@hassangameryt/freeflow 0.7.2 → 0.7.3

package/pi-extension/src/provider-support/astra/history.ts

@@ -0,0 +1,145 @@
+import { createHash, randomUUID } from "node:crypto";
+
+export const ENTRY_TYPE = "freeflow-astra-effort-v1";
+export const EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type Effort = (typeof EFFORTS)[number];
+export interface Attempt {
+  version: 1;
+  id: string;
+  basis: string | null;
+  key: string;
+  generation: string;
+  envelope: string;
+  baseline: Effort;
+  effective: Effort;
+  parent: string | null;
+  length: number;
+  inputHash: string;
+  update?: { at: number; prefixHash: string; effort: Effort };
+}
+export const hash = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const digest = (x: unknown): x is string => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
+const effort = (x: unknown): x is Effort => EFFORTS.includes(x as Effort);
+const identity = (x: unknown): x is string => typeof x === "string" && x.length > 0 && x.length <= 1024;
+export function parseAttempt(value: any): Attempt {
+  if (
+    !value ||
+    value.version !== 1 ||
+    !identity(value.id) ||
+    !(value.basis === null || identity(value.basis)) ||
+    !identity(value.key) ||
+    !identity(value.generation) ||
+    !digest(value.envelope) ||
+    !digest(value.inputHash) ||
+    !effort(value.baseline) ||
+    !effort(value.effective) ||
+    !(value.parent === null || identity(value.parent)) ||
+    !Number.isSafeInteger(value.length) ||
+    value.length < 0 ||
+    (value.update !== undefined &&
+      (!value.update ||
+        !Number.isSafeInteger(value.update.at) ||
+        value.update.at < 0 ||
+        value.update.at > value.length ||
+        !digest(value.update.prefixHash) ||
+        !effort(value.update.effort))) ||
+    Object.keys(value).some(
+      (k) =>
+        ![
+          "version",
+          "id",
+          "basis",
+          "key",
+          "generation",
+          "envelope",
+          "baseline",
+          "effective",
+          "parent",
+          "length",
+          "inputHash",
+          "update",
+        ].includes(k),
+    )
+  )
+    throw new Error("Invalid Astra effort history");
+  return value;
+}
+
+// Hash complete serialized items, including opaque reasoning; never persist their bodies.
+export function prefixHashes(input: readonly unknown[]): string[] {
+  const result = [hash([])];
+  for (const item of input) result.push(hash([result.at(-1), item]));
+  return result;
+}
+export function envelopeHash(payload: any): string {
+  const { input: _input, prompt_cache_key: _key, max_output_tokens: _max, stream: _stream, ...rest } = payload;
+  const { effort: _effort, ...reasoning } = rest.reasoning;
+  return hash({ ...rest, reasoning });
+}
+export function assemble(payload: any, key: string, generation: string, basis: string | null, records: Attempt[]) {
+  const hashes = prefixHashes(payload.input),
+    envelope = envelopeHash(payload);
+  const applicable = records.filter((r) => r.key === key && r.generation === generation);
+  const compatible = applicable.filter((r) => r.envelope === envelope && hashes[r.length] === r.inputHash);
+  const prior = compatible.reduce<Attempt | undefined>(
+    (best, r) => (!best || r.length >= best.length ? r : best),
+    undefined,
+  );
+  const baseline = prior?.baseline ?? applicable[0]?.baseline ?? (payload.reasoning.effort as Effort);
+  const desired = payload.reasoning.effort as Effort;
+  const byId = new Map(records.map((r) => [r.id, r]));
+  const updates: NonNullable<Attempt["update"]>[] = [];
+  const seen = new Set<string>();
+  let cursor = prior;
+  while (cursor) {
+    if (seen.has(cursor.id)) throw new Error("Cyclic Astra history");
+    seen.add(cursor.id);
+    if (cursor.update) {
+      if (hashes[cursor.update.at] !== cursor.update.prefixHash) throw new Error("Astra anchor changed");
+      updates.unshift(cursor.update);
+    }
+    if (cursor.parent === null) break;
+    const parent = byId.get(cursor.parent);
+    if (!parent || parent.key !== key || parent.generation !== generation || parent.baseline !== baseline)
+      throw new Error("Astra history parent unavailable");
+    cursor = parent;
+  }
+  let update: Attempt["update"];
+  if (desired !== (prior?.effective ?? baseline)) {
+    // Only insert before a new user item. Within a tool loop, append after all completed exchanges.
+    const last = payload.input.length - 1;
+    const at = payload.input[last]?.role === "user" && last >= (prior?.length ?? 0) ? last : payload.input.length;
+    update = { at, prefixHash: hashes[at], effort: desired };
+    if (updates.at(-1)?.at === at) throw new Error("Adjacent Astra effort updates");
+    updates.push(update);
+  }
+  if (updates.some((u, i) => i > 0 && u.at <= updates[i - 1].at)) throw new Error("Invalid Astra update order");
+  const output = structuredClone(payload);
+  output.input = [];
+  let nextUpdate = 0;
+  for (let i = 0; i <= payload.input.length; i++) {
+    if (updates[nextUpdate]?.at === i) {
+      output.input.push({ type: "configuration_update", reasoning: { effort: updates[nextUpdate++].effort } });
+    }
+    if (i < payload.input.length) output.input.push(structuredClone(payload.input[i]));
+  }
+  output.reasoning.effort = baseline;
+  const identical = prior?.length === payload.input.length && prior.effective === desired;
+  const record: Attempt | undefined = identical
+    ? undefined
+    : {
+        version: 1,
+        id: randomUUID(),
+        basis,
+        key,
+        generation,
+        envelope,
+        baseline,
+        effective: desired,
+        parent: prior?.id ?? null,
+        length: payload.input.length,
+        inputHash: hashes.at(-1)!,
+        ...(update ? { update } : {}),
+      };
+  return { payload: output, record, baseline, effective: desired, rebased: !prior && applicable.length > 0 };
+}

package/pi-extension/src/provider-support/astra/index.ts

@@ -0,0 +1,12 @@
+import { AstraAdapter } from "./adapter.js";
+
+export function registerAstraSupport(pi: any): void {
+  const adapter = new AstraAdapter(pi);
+  pi.on("session_start", (_event: any, ctx: any) => adapter.reset(ctx));
+  pi.on("session_shutdown", (_event: any, ctx: any) => adapter.reset(ctx));
+  pi.on("session_tree", (_event: any, ctx: any) => adapter.reset(ctx));
+  pi.on("session_before_compact", () => adapter.setCompacting(true));
+  pi.on("session_compact", (_event: any, ctx: any) => adapter.reset(ctx));
+  pi.on("session_compact_failed", () => adapter.setCompacting(false));
+  pi.on("before_provider_request", (event: any, ctx: any) => adapter.adapt(event.payload, ctx));
+}

package/pi-extension/src/provider-support/astra/session-state.ts

@@ -0,0 +1,113 @@
+import { activeReadOnlySessionBranch, readOnlySessionSnapshot } from "../../session-sources/read-only-session.js";
+import { ENTRY_TYPE, parseAttempt, type Attempt } from "./history.js";
+
+export class SessionState {
+  private acknowledged = new Map<string, string>();
+  private fault?: string;
+  constructor(
+    private readonly pi: any,
+    private readonly reader: any,
+  ) {}
+  private branch(): any[] {
+    const entries = this.reader.getBranch();
+    let parent: string | null = null;
+    const seen = new Set<string>();
+    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(): Promise<Attempt[]> {
+    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<string, { epoch: string; legacy: string }>();
+    let epoch = "root",
+      legacy = "root",
+      model: string | undefined;
+    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<string, Attempt>();
+    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(): string {
+    let generation = "root";
+    for (const entry of this.branch()) {
+      if (entry.type === "compaction" || entry.type === "branch_summary") generation = entry.id;
+    }
+    return generation;
+  }
+  append(record: Attempt): void {
+    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/src/provider-support/index.ts

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

package/pi-extension/src/runtime/request-history.ts

@@ -0,0 +1,243 @@
+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: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function fingerprint(message: any): string {
+  const { usage: _usage, timestamp: _timestamp, details: _details, ...body } = message;
+  return hash(body);
+}
+interface Injection {
+  at: number;
+  message: any;
+}
+interface Frame {
+  version: 1;
+  id: string;
+  basis: string | null;
+  view: string;
+  generation: string;
+  length: number;
+  prefix: string;
+  parent: string | null;
+  states: Record<string, string>;
+  retained: string[];
+  additions: Injection[];
+}
+function prefixes(messages: any[]) {
+  const result = [hash([])];
+  for (const message of messages) result.push(hash([result.at(-1), fingerprint(message)]));
+  return result;
+}
+function owned(message: any): boolean {
+  return message?.role === "custom" && TRANSIENT.has(message.customType);
+}
+function parse(value: any): Frame {
+  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: any) => typeof x === "string") ||
+    !Array.isArray(value.additions) ||
+    !value.additions.every(
+      (x: any) => 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 {
+  private acknowledged = new Map<string, string>();
+  private identity?: string;
+  private fault = false;
+  private serial: Promise<unknown> = Promise.resolve();
+  private revision = 0;
+  constructor(private readonly pi: any) {}
+  reset() {
+    this.revision++;
+    this.acknowledged.clear();
+    this.identity = undefined;
+    this.fault = false;
+  }
+  async assemble(messages: any[], view: string, ctx: any, notice?: (messages: any[]) => any): Promise<any[]> {
+    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;
+  }
+  private async prepare(
+    messages: any[],
+    view: string,
+    ctx: any,
+    revision: number,
+    notice?: (messages: any[]) => any,
+  ): Promise<any[]> {
+    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: string | null = null,
+      generation = "root";
+    const ids = new Set<string>();
+    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: any) => e.type === "custom" && e.customType === ENTRY);
+    if (
+      entries.some((e: any) => this.acknowledged.get(e.id) !== hash(e)) &&
+      reader.getSessionFile?.() &&
+      branch.some((e: any) => 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: Frame[] = [],
+      byId = new Map<string, Frame>();
+    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<Frame | undefined>(
+      (best, f) => (!best || f.length >= best.length ? f : best),
+      undefined,
+    );
+    const states = { ...prior?.states },
+      additions: Injection[] = [];
+    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: Injection[] = [];
+    const chain: Frame[] = [];
+    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: any[] = [];
+    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: 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: any) => 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/src/runtime/runtime-context.ts

@@ -55,6 +55,13 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "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) {
@@ -559,11 +566,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") {
@@ -603,6 +606,7 @@ type CognitiveRoutingRuntimeSnapshot = {
   runtimeStatus?: "active" | "inactive" | "blocked";
   runtimeReason?: unknown;
   activeProfile?: unknown;
+  delegation?: unknown;
   controlMode?: unknown;
 };
 
@@ -615,13 +619,13 @@ type FreeflowContextMessage = {
 
 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) {
@@ -644,9 +648,7 @@ function publicCognitiveRoutingProjectionMode(
 ): CognitiveRoutingProjectionMode {
   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";
@@ -700,6 +702,7 @@ export function freeflowRuntimeStateMessage(
       "Cognitive Routing:",
       `- Control: \`${control}\``,
       `- Profile: \`${profile}\``,
+      `- Delegation: \`${capabilityState?.cognitiveRouting?.delegation ?? "executor"}\``,
       `- Projection: \`${projectionMode}\``,
     ].join("\n"),
     display: false,
@@ -760,6 +763,25 @@ export function withFreeflowRuntimeState(
   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/src/session-sources/events.ts

@@ -100,6 +100,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<string, { value: string; eventId: string; entryId: string }>();
+        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);