@hassangameryt/freeflow 0.7.3 → 0.8.0

package/pi-extension/dist/index.js

@@ -1,36 +1,103 @@
+import { calculateContextTokens, compact as piCompact, estimateTokens } from "@earendil-works/pi-coding-agent";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { RequestHistory } from "./runtime/request-history.js";
+import { RequestHistory } from "./host/request-history.js";
 import { registerProviderSupport } from "./provider-support/index.js";
-import { RoutingRuntime } from "./cognitive-routing-v2/runtime.js";
-import { workersForDelegation } from "./cognitive-routing-v2/types.js";
-import { applyRoutingToolVisibility, registerRoutingTools } from "./cognitive-routing-v2/tools.js";
-import { ConversationHistoryRuntime } from "./conversation-history/runtime.js";
-import { FreeflowContextRuntime } from "./freeflow-context/runtime.js";
-import { CONTEXT_VIRTUALIZATION_TOOL_NAME, registerFreeflowContextTool } from "./freeflow-context/tool.js";
-import { handleContextCommand } from "./context-virtualization/commands.js";
-import { ContextVirtualizationRuntime } from "./context-virtualization/runtime.js";
-import { handleFreeflowCommand } from "./settings/settings-ui.js";
-import { isPiFlowHost } from "./runtime/runtime-identity.js";
+import { CacheHealth } from "./provider-support/cache/health.js";
+import { CacheMonitor } from "./provider-support/cache/monitor.js";
+import { RoutingRuntime } from "./cognitive-routing/runtime.js";
+import { applyRoutingToolVisibility, registerRoutingTools } from "./cognitive-routing/tools.js";
+import { handleFreeflowCommand } from "./host/settings/freeflow-command.js";
+import { toolExecutionSections, toolExecutionTail } from "./tool-execution/prompt.js";
+import { FileTracking } from "./tool-execution/file-tracking.js";
+import { registerApplyPatch } from "./tool-execution/apply-patch/tool.js";
+import { applyToolExecutionTools } from "./tool-execution/tools.js";
+import { BackgroundJobs, NOTICE_PREFIX, NOTICE_TYPE, registerBackgroundTools } from "./tool-execution/background.js";
+import { backgroundRefusal } from "./tool-execution/bash-guard.js";
+import { CompactionController, USER_REQUEST } from "./compaction/controller.js";
+import { applyCompactionTools, registerCompactionTool } from "./compaction/tool.js";
+import { strictest } from "./compaction/thresholds.js";
+import { tagProjectedMessages } from "./host/projection-tags.js";
+import { trustStartedSession } from "./host/read-only-session.js";
+import { takeStage } from "./host/staging.js";
 import {
   CONTRIBUTOR_COMMANDS,
   WORKFLOW_COMMANDS,
   freeflowModelSkillPaths,
+  STABLE_FREEFLOW_SURFACE,
+  skillPrompt,
+} from "./host/catalog.js";
+import {
+  readCapabilityState,
+  restoreSessionOverrides,
+  setSessionCoreOverride,
+  writeStagedSessionOverrides,
+} from "./host/config.js";
+import {
   getRuntimeContext,
   hasUsableMandatoryPrompts,
   isPromptAvailable,
-  readCapabilityState,
   refreshRuntimeContext,
-  restoreSessionOverrides,
   stableRuntimeContext,
-  STABLE_FREEFLOW_SURFACE,
-  filterBootstrapMessage,
-  setFreeflowStatus,
-  skillPrompt,
-  withFreeflowRuntimeState,
-} from "./runtime/runtime-context.js";
+} from "./host/prompts.js";
+import { filterBootstrapMessage, withFreeflowRuntimeState } from "./host/runtime-state.js";
+import { setFreeflowStatus } from "./host/status.js";
+import { cachedBranch } from "./host/branch.js";
+const COMPACTION_NOTICE_TYPE = "freeflow-compaction-notice";
+/** Estimated size of the full native history plus the system prompt: what a request without projection carries. */
+/**
+ * The context a turn ended with, as Pi estimates it: the turn's own usage plus the tool results after it. Pi's
+ * getContextUsage rebuilds the session projection to find the same numbers. Undefined when the turn has no usable usage
+ * (aborted, failed, or none reported), where Pi's own estimate applies.
+ */
+function turnContextTokens(turn) {
+  const message = turn?.message;
+  if (message?.role !== "assistant" || message.stopReason === "aborted" || message.stopReason === "error") return;
+  if (!message.usage || calculateContextTokens(message.usage) <= 0) return;
+  return (turn.toolResults ?? []).reduce(
+    (sum, result) => sum + estimateTokens(result),
+    calculateContextTokens(message.usage),
+  );
+}
+/** Entry types that add no message to Pi's session projection. */
+const NO_MESSAGE = new Set(["custom", "label", "session_info", "model_change", "thinking_level_change"]);
+const historyEstimate = new WeakMap();
+/**
+ * The full history's size, as every message's estimate plus the system prompt. Kept per session and extended by the
+ * messages appended since, because the branch only grows between compactions; a compaction, summary or custom
+ * message (which Pi's projection may place or replace) recomputes it from Pi's projection.
+ */
+function fullHistoryTokens(ctx) {
+  const manager = ctx.sessionManager;
+  const system = Math.ceil((ctx.getSystemPrompt?.() ?? "").length / 4);
+  if (!manager?.buildSessionProjection) return system;
+  const branch = cachedBranch(manager);
+  const previous = historyEstimate.get(manager);
+  let tokens;
+  if (previous && branch === previous.branch) tokens = previous.tokens;
+  else if (
+    previous &&
+    previous.branch.length > 0 &&
+    branch.length >= previous.branch.length &&
+    branch[previous.branch.length - 1] === previous.branch.at(-1)
+  ) {
+    const added = branch.slice(previous.branch.length);
+    if (added.every((entry) => entry.type === "message" || NO_MESSAGE.has(entry.type)))
+      tokens = added.reduce(
+        (sum, entry) => sum + (entry.type === "message" ? estimateTokens(entry.message) : 0),
+        previous.tokens,
+      );
+  }
+  if (tokens === undefined)
+    tokens = (manager.buildSessionProjection()?.messages ?? []).reduce(
+      (sum, message) => sum + estimateTokens(message),
+      0,
+    );
+  historyEstimate.set(manager, { branch, tokens });
+  return tokens + system;
+}
 async function sendSkillCommand(pi, ctx, skill, args) {
-  const state = await readCapabilityState(ctx.cwd, ctx, pi.host);
+  const state = await readCapabilityState(ctx.cwd, ctx);
   if (skill === "setup-freeflow" && !state.configured) {
     await pi.sendUserMessage(skillPrompt(skill, args), { expandPromptTemplates: true });
     return;
@@ -62,43 +129,65 @@ function freeflowCompletions(prefix, routingAvailable) {
           ["profile auto", "auto", "Return to automatic Coordinator reconciliation"],
           ["profile history", "history", "Read routing observations"],
         ]
-      : query.startsWith("context ")
-        ? [
-            ["context status", "status", "Show Freeflow Context state"],
-            ["context list", "list", "List archived context projections"],
-            ["context restore", "restore", "Restore one or more context references"],
-            ["context reset all", "reset all", "Reset projection decisions on the active branch"],
-          ]
-        : [
-            ["settings", "settings", "Open personal override settings"],
-            ["status", "status", "Show effective Freeflow state"],
-            ["context", "context", "Inspect Freeflow Context"],
-            ...(routingAvailable
-              ? [
-                  ["profile", "profile", "Hold or release Cognitive Routing profile control"],
-                  ["resume", "resume", "Resume the current saved routing responsibility"],
-                ]
-              : []),
-            ["enable", "enable", "Enable Freeflow for this repository"],
-            ["disable", "disable", "Disable Freeflow for this repository"],
-          ];
+      : [
+          ["settings", "settings", "Open settings; Tab switches Session, Personal and Repository"],
+          ["status", "status", "Show effective Freeflow state"],
+          ["compact", "compact", "Prepare, compact and recover now"],
+          ...(routingAvailable
+            ? [
+                ["profile", "profile", "Hold or release Cognitive Routing profile control"],
+                ["resume", "resume", "Resume the current saved routing responsibility"],
+              ]
+            : []),
+          ["enable", "enable", "Enable Freeflow for this repository"],
+          ["disable", "disable", "Disable Freeflow for this repository"],
+        ];
   return choices
     .filter(([value]) => value.startsWith(query))
     .map(([value, label, description]) => ({ value, label, description }));
 }
 export default function freeflow(pi) {
-  registerProviderSupport(pi);
+  // Cache diagnostics are reported to /freeflow status; the footer only shows current settings.
+  const cacheMonitor = new CacheMonitor();
+  // Only an explicit master-switch disable turns provider support off; unconfigured repositories keep it.
+  const providerSupport = registerProviderSupport(
+    pi,
+    () => !(capability?.configured === true && capability.enabled === false),
+    cacheMonitor,
+  );
   const api = pi;
   const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
   const routing = new RoutingRuntime(api, [packageRoot]);
-  const requestHistory = new RequestHistory(api);
+  // A Coordinator waiting on its worker will resume, so its prompt cache is worth keeping warm.
+  providerSupport.keepAlive.setHoldSource(() => routing.suspendedCoordinator());
+  // A worker may share the Coordinator's model; each profile keeps its own warmed request.
+  providerSupport.keepAlive.setRequesterSource(() => routing.observationScope().profile);
+  const requestHistory = new RequestHistory(api, cacheMonitor);
+  // Where the Freeflow Runtime State was last placed on paths that bypass request history.
+  const runtimeStateAnchor = {};
+  const resetHistory = () => {
+    requestHistory.reset();
+    delete runtimeStateAnchor.content;
+    delete runtimeStateAnchor.index;
+  };
   let capability;
+  const files = new FileTracking();
+  const toolExecutionEffective = () => capability?.toolExecution?.effective === true;
+  const compactionEffective = () => capability?.compaction?.effective === true;
+  const cacheHealth = new CacheHealth();
   let prompts;
-  let context;
-  let virtualization;
-  let history;
   let refreshState = true;
-  let sessionContext;
+  // Pi's event contexts read the host model and effort live. Its interactive shortcut contexts copy them at the
+  // key press, so after a switch they still name the previous model; routing must never judge a switch by them.
+  let liveHost;
+  const withLiveModel = (ctx) =>
+    Object.defineProperties(
+      { ...ctx },
+      {
+        model: { enumerable: true, get: () => liveHost?.model ?? ctx.model },
+        thinkingLevel: { enumerable: true, get: () => api.getThinkingLevel?.() ?? ctx.thinkingLevel },
+      },
+    );
   let surfaceGeneration = 0;
   const unavailable = (state, message) => ({
     ...state,
@@ -107,171 +196,328 @@ export default function freeflow(pi) {
   });
   async function loadSurface(ctx) {
     const generation = surfaceGeneration;
-    const next = await readCapabilityState(ctx.cwd, ctx, pi.host);
+    const next = await readCapabilityState(ctx.cwd, ctx);
     const loaded = await getRuntimeContext(STABLE_FREEFLOW_SURFACE);
     if (generation !== surfaceGeneration) throw new Error("Discarded surface preparation for a replaced session.");
     if (!hasUsableMandatoryPrompts(loaded)) {
-      for (const key of ["cognitiveRouting", "contextVirtualization", "conversationHistory"])
+      for (const key of ["cognitiveRouting", "toolExecution"])
         next[key] = unavailable(next[key], "Mandatory Freeflow prompts are unavailable.");
     }
     if (next.cognitiveRouting.effective && !isPromptAvailable(loaded.cognitiveRoutingPrompt))
       next.cognitiveRouting = unavailable(next.cognitiveRouting, "Routing bootstrap cue is unavailable.");
-    if (next.contextVirtualization.effective && !isPromptAvailable(loaded.contextVirtualizationPrompt))
-      next.contextVirtualization = unavailable(
-        next.contextVirtualization,
-        "Context Virtualization guidance is unavailable.",
-      );
-    if (next.conversationHistory.effective && !isPromptAvailable(loaded.conversationHistoryPrompt))
-      next.conversationHistory = unavailable(next.conversationHistory, "Conversation History guidance is unavailable.");
-    // The existing reduction engine is not the future Context Control port. Do not pretend
-    // its independent transform ordering has been qualified with the new projection.
-    if (
-      next.cognitiveRouting.effective &&
-      next.cognitiveRouting.projection &&
-      (next.contextVirtualization.effective || next.conversationHistory.effective)
-    )
-      next.cognitiveRouting = unavailable(
-        next.cognitiveRouting,
-        "New routing projection with legacy context transforms is not qualified. Disable that combination explicitly.",
-      );
-    if (next.cognitiveRouting.enabled && isPiFlowHost(pi.host))
-      next.cognitiveRouting = unavailable(
-        next.cognitiveRouting,
-        "The redesigned PiFlow adapter requires separate qualification.",
-      );
     capability = next;
     prompts = loaded;
-    sessionContext = ctx;
     return next;
   }
-  function contextTools() {
-    registerFreeflowContextTool(
-      api,
-      () => virtualization,
-      () => history,
-      {
-        contextVirtualization: capability?.contextVirtualization?.effective === true,
-        conversationHistory: capability?.conversationHistory?.effective === true,
-      },
-    );
-    if (api.getActiveTools && api.setActiveTools) {
-      const current = new Set(api.getActiveTools());
-      current.add(CONTEXT_VIRTUALIZATION_TOOL_NAME);
-      const next = [...current];
-      if (JSON.stringify(next) !== JSON.stringify(api.getActiveTools())) api.setActiveTools(next);
-    }
-  }
   function status(ctx) {
     applyRoutingToolVisibility(api, routing, capability?.cognitiveRouting?.effective === true);
+    applyToolExecutionTools(api, toolExecutionEffective());
+    applyCompactionTools(api, compactionEffective());
     setFreeflowStatus(ctx, capability, routing.state(), prompts);
   }
+  // Control and setting changes made between prompts are staged; their net effect is written as a prompt starts.
+  function writeStagedControl(ctx) {
+    const staged = takeStage(ctx.sessionManager);
+    routing.writeStaged(staged.events);
+    writeStagedSessionOverrides(staged.overrides, api, ctx.sessionManager);
+  }
   async function update(ctx) {
     const next = await loadSurface(ctx);
     await routing.refresh(ctx, next.cognitiveRouting);
-    contextTools();
     status(ctx);
     refreshState = true;
   }
+  /**
+   * Turn Cognitive Routing on for this session when it is off: clear a session "off" (such as the one an outside model
+   * change sets), and switch it on for the session if configuration leaves it off. Re-enabling hands control to the
+   * automatic Coordinator. Configuration that still blocks routing (no profiles, invalid presets) is reported by the
+   * control that follows.
+   */
+  async function turnRoutingOn(ctx) {
+    if (capability?.cognitiveRouting?.effective === true || ctx.isIdle?.() === false) return;
+    if (capability?.cognitiveRouting?.enabledSource === "session")
+      await setSessionCoreOverride("cognitiveRouting.enabled", null, ctx, api);
+    if ((await readCapabilityState(ctx.cwd, ctx)).cognitiveRouting?.enabled !== true)
+      await setSessionCoreOverride("cognitiveRouting.enabled", true, ctx, api);
+    await update(ctx);
+  }
   registerRoutingTools(api, routing);
-  registerFreeflowContextTool(
-    api,
-    () => virtualization,
-    () => history,
-    { contextVirtualization: false, conversationHistory: false },
-  );
+  registerApplyPatch(api, {
+    effective: toolExecutionEffective,
+    files: (ctx) => files.forPatch(ctx),
+    written: (paths, ctx) => files.written(paths, ctx),
+  });
+  const backgroundHost = {
+    effective: toolExecutionEffective,
+    shellPath: () => api.getSettings?.()?.shellPath,
+    // An exit notice starts a turn when idle; mid-run it is steered in after the current turn's tool results.
+    send: (content, details, triggerTurn) => {
+      const notice = () =>
+        Promise.resolve(
+          api.sendMessage(
+            { customType: NOTICE_TYPE, content, display: true, details },
+            triggerTurn ? { triggerTurn: true, deliverAs: "steer" } : { triggerTurn: false },
+          ),
+        ).catch(() => {});
+      // When idle, the notice starts the run as a user message: a run an extension message starts loses Freeflow's
+      // system sections from its second request (Pi #10267). If a run started meanwhile, it is steered in instead.
+      if (!triggerTurn || liveHost?.isIdle?.() !== true) return notice();
+      try {
+        return Promise.resolve(api.sendUserMessage(content)).catch(notice);
+      } catch {
+        return notice();
+      }
+    },
+  };
+  const background = new BackgroundJobs(backgroundHost);
+  registerBackgroundTools(api, background, backgroundHost);
+  const compaction = new CompactionController({
+    effective: compactionEffective,
+    routingProfile: () => {
+      const state = routing.state();
+      return state.effective ? state.activeProfile : undefined;
+    },
+    routingAssignment: () => routing.currentAssignment(),
+    assignmentResults: () => routing.assignmentResults(),
+    background: () => background.running().map(({ id, label, outputPath }) => ({ id, label, outputPath })),
+    noticePrefix: NOTICE_PREFIX,
+    carryEnabled: () => capability?.compaction?.carry !== false,
+    nativeRefs: () => capability?.cognitiveRouting?.effective === true,
+    resolveRef: (ref) => routing.evidenceSource(ref),
+    coordinatorUnderProjection: () =>
+      capability?.cognitiveRouting?.effective === true &&
+      capability.cognitiveRouting.projection === true &&
+      routing.state().effective === true &&
+      routing.state().activeProfile === "coordinator",
+    summarize: async (preparation, instructions, signal, ctx) => {
+      const auth = await ctx.modelRegistry?.getApiKeyAndHeaders?.(ctx.model);
+      if (!ctx.model || !auth?.ok) throw new Error("No request auth for the summarizer");
+      const model = auth.baseUrl ? { ...ctx.model, baseUrl: auth.baseUrl } : ctx.model;
+      return piCompact(
+        preparation,
+        model,
+        auth.apiKey,
+        auth.headers,
+        instructions,
+        signal,
+        api.getThinkingLevel?.(),
+        undefined,
+        auth.env,
+      );
+    },
+    measure: (ctx, turn) => {
+      // Every model that may receive the full history: the active one and, under routing, each profile's.
+      const routingCapability = capability?.cognitiveRouting;
+      const models = [ctx.model];
+      if (routingCapability?.effective)
+        for (const profile of Object.values(routingCapability.profiles ?? {}))
+          models.push(ctx.modelRegistry?.find?.(profile.provider, profile.model));
+      const limits = strictest(models, api.getSettings?.());
+      if (!limits) return undefined;
+      let tokens = turnContextTokens(turn) ?? ctx.getContextUsage?.()?.tokens ?? 0;
+      // A Coordinator under projection sends a reduced view; the next worker request carries the whole history.
+      if (
+        routingCapability?.effective &&
+        routingCapability.projection &&
+        routing.state().activeProfile === "coordinator"
+      )
+        tokens = Math.max(tokens, fullHistoryTokens(ctx));
+      return { tokens, thresholds: limits };
+    },
+  });
+  registerCompactionTool(api, compaction);
+  // The user's /freeflow compact makes compaction due now: the agent prepares, compacts and recovers.
+  async function compactNow(ctx) {
+    if (!compactionEffective()) {
+      ctx.ui.notify("Freeflow compaction is off; Pi's /compact still works.", "warning");
+      return;
+    }
+    compaction.requestByUser(ctx);
+    // The user asked, so this is their message. A user message also starts an ordinary run, which keeps Freeflow's
+    // system sections; a run started by an extension message loses them from its second request (Pi #10267).
+    const index = compaction.indexText(ctx);
+    const text = `${USER_REQUEST}${index ? `\n\n${index}` : ""}`;
+    await Promise.resolve(
+      api.sendUserMessage(text, ctx.isIdle?.() === false ? { deliverAs: "steer" } : undefined),
+    ).catch(() => {});
+  }
   pi.on("resources_discover", async (event, ctx) => {
     const state = capability ?? (await loadSurface(ctx ?? { cwd: event?.cwd ?? process.cwd() }));
-    return { skillPaths: freeflowModelSkillPaths(STABLE_FREEFLOW_SURFACE) };
+    return {
+      skillPaths: freeflowModelSkillPaths({ ...STABLE_FREEFLOW_SURFACE, toolExecution: state.toolExecution }),
+    };
   });
   pi.on("session_start", async (event, ctx) => {
+    liveHost = ctx;
     const generation = ++surfaceGeneration;
-    requestHistory.reset();
+    resetHistory();
+    // Where Pi has just parsed this session file, later checks read only the bytes appended since.
+    trustStartedSession(event?.reason, ctx.sessionManager);
     routing.unbind();
     capability = undefined;
     prompts = undefined;
     refreshState = true;
     restoreSessionOverrides(ctx);
-    const initial = await readCapabilityState(ctx.cwd, ctx, pi.host);
     await refreshRuntimeContext(STABLE_FREEFLOW_SURFACE);
     if (generation !== surfaceGeneration) return;
     await loadSurface(ctx);
-    context = new FreeflowContextRuntime(ctx);
-    virtualization = new ContextVirtualizationRuntime(pi, ctx, context);
-    history = new ConversationHistoryRuntime(
-      ctx,
-      (entryId) => virtualization?.isSourceFullyProjected(entryId) ?? true,
-      context,
-    );
-    await virtualization.recover(ctx);
+    cacheHealth.reset();
+    files.reset();
+    compaction.reset();
     await routing.bind(ctx, capability.cognitiveRouting, event?.reason !== "reload");
-    contextTools();
     status(ctx);
   });
   pi.on("session_shutdown", async () => {
     surfaceGeneration++;
-    requestHistory.reset();
+    // Background processes belong to this extension instance; none may report into the next session.
+    await background.stopAll();
+    files.reset();
+    compaction.reset();
+    resetHistory();
     routing.unbind();
-    context = undefined;
-    virtualization = undefined;
-    history = undefined;
     capability = undefined;
     prompts = undefined;
-    sessionContext = undefined;
   });
   pi.on("before_agent_start", async (event, ctx) => {
     await update(ctx);
-    await routing.beforeRun(ctx);
-    status(ctx);
-    const text = stableRuntimeContext(prompts);
-    return { systemPrompt: text ? `${event.systemPrompt}\n\n${text}` : event.systemPrompt };
+    try {
+      await routing.beforeRun(ctx);
+    } finally {
+      // Pi reports a handler error and still sends the prompt, so the fixed guidance section and the staged
+      // control must never be skipped: a missing section would change the cached prompt head.
+      // After the run's own reconciliation, so everything staged lands ahead of the prompt in one pass.
+      writeStagedControl(ctx);
+      status(ctx);
+      // Pi 0.87 records changed sections at their native transcript position.
+      // Returning systemPrompt would force one replacement head for every request.
+      const sections = event.systemPromptOptions.sections;
+      const toolExecution = capability?.toolExecution?.effective === true;
+      // Pi's own sections are replaced in place. Freeflow's are re-inserted at the end in a fixed order: its guidance,
+      // then Tool Execution's environment facts and guidance.
+      if (toolExecution)
+        Object.assign(sections, toolExecutionSections(event.systemPrompt, api.getSettings?.()?.shellPath));
+      for (const name of ["freeflow_guidance", "environment", "tool_execution"]) delete sections[name];
+      sections.freeflow_guidance = stableRuntimeContext(prompts);
+      if (toolExecution)
+        Object.assign(sections, toolExecutionTail(api.getSettings?.()?.shellPath, prompts?.toolExecutionPrompt));
+    }
+    // Like Claude Code's next-turn reminder: files the model read that changed while it was not running a tool.
+    const changed = toolExecutionEffective() ? await files.changedNotice(ctx, false) : undefined;
+    if (changed)
+      return { message: { customType: "freeflow-files", content: `${NOTICE_PREFIX} ${changed}`, display: true } };
   });
-  pi.on("message_end", (event) => routing.messageEnd(event.message));
-  pi.on("tool_call", (event, ctx) => {
+  pi.on("agent_start", () => routing.runStarted());
+  pi.on("message_end", async (event, ctx) => {
+    const message = event.message;
     if (
-      event.toolName === CONTEXT_VIRTUALIZATION_TOOL_NAME &&
-      !capability?.contextVirtualization?.effective &&
-      !capability?.conversationHistory?.effective
-    )
-      return { block: true, reason: "Freeflow Context is disabled." };
-    return routing.preflight(event, ctx);
+      capability?.enabled === true &&
+      message?.role === "assistant" &&
+      message.usage &&
+      message.stopReason !== "error"
+    ) {
+      const scope = routing.observationScope();
+      const lifetime = ctx.model?.promptCache?.[process.env.PI_CACHE_RETENTION === "long" ? "long" : "short"];
+      const warning = cacheHealth.observe({
+        provider: message.provider,
+        model: message.model,
+        thinking: ctx.thinkingLevel,
+        at: Date.now(),
+        input: message.usage.input ?? 0,
+        cacheRead: message.usage.cacheRead ?? 0,
+        cacheWrite: message.usage.cacheWrite ?? 0,
+        ...(scope.control === "automatic" && scope.profile !== "solo" ? { lane: scope.profile } : {}),
+        ...(typeof lifetime === "number" ? { ttlMs: lifetime * 1000 } : {}),
+      });
+      if (warning) ctx.ui?.notify?.(warning, "warning");
+    }
+    routing.messageEnd(event.message);
+    // A run started by an extension's message (a background notice, for one) gets the same preparation as a prompt.
+    if (routing.startedByMessage(event.message)) {
+      await update(ctx);
+      try {
+        await routing.beforeRun(ctx, false);
+      } finally {
+        writeStagedControl(ctx);
+        status(ctx);
+      }
+    }
   });
+  pi.on("tool_call", async (event, ctx) => {
+    const gate = routing.preflight(event, ctx);
+    if (gate?.block || !toolExecutionEffective()) return gate;
+    const refusal = event.toolName === "bash" ? backgroundRefusal(event.input?.command) : undefined;
+    if (refusal) return { block: true, reason: refusal };
+    return (await files.toolCall(event, ctx)) ?? gate;
+  });
+  pi.on("tool_result", async (event, ctx) => (toolExecutionEffective() ? files.toolResult(event, ctx) : undefined));
   pi.on("turn_end", async (event, ctx) => {
     await routing.turnEnd(event, ctx);
+    files.clearPending();
     status(ctx);
+    const compacting = await compaction.turnEnd(event, ctx);
+    if (compacting) return compacting;
+    const notice = compaction.observe(ctx, event);
+    if (notice) {
+      // Mid-run the notice joins the next request; when the run is ending it waits for the next prompt rather than
+      // starting work nobody asked for.
+      const midRun = (event.message?.content ?? []).some((block) => block?.type === "toolCall");
+      await Promise.resolve(
+        api.sendMessage(
+          { customType: COMPACTION_NOTICE_TYPE, content: notice.text, display: true, details: { level: notice.level } },
+          { deliverAs: midRun ? "steer" : "nextTurn" },
+        ),
+      ).catch(() => {});
+    }
+    return undefined;
+  });
+  // A Freeflow compaction fires no session_compact, so its resets run here, before the new cycle's first request.
+  pi.on("turn_start", async (_event, ctx) => {
+    const compacted = compaction.takeCompacted();
+    if (!compacted) return;
+    await restore(ctx, false);
+    await files.compacted(compacted.carriedFiles, ctx);
   });
   pi.on("agent_settled", async (_event, ctx) => {
     await routing.settled(ctx);
     await update(ctx);
   });
-  pi.on("model_select", async (_event, ctx) => {
-    await routing.nativeChange(ctx);
-    status(ctx);
-  });
-  pi.on("thinking_level_select", async (_event, ctx) => {
-    await routing.nativeChange(ctx);
+  // A model or effort picked in Pi itself (/model, Shift+Tab) ends automatic routing. Routing then turns off for this
+  // session through its Session switch, so settings and the footer show it off, and any routing control turns it on.
+  const externalChange = async (ctx) => {
+    cacheHealth.noteSwitch();
+    if (await routing.nativeChange(ctx)) {
+      await setSessionCoreOverride("cognitiveRouting.enabled", false, ctx, api);
+      await update(ctx);
+    }
     status(ctx);
-  });
-  pi.on("context", async (event, ctx) => {
+  };
+  pi.on("model_select", async (_event, ctx) => externalChange(ctx));
+  pi.on("thinking_level_select", async (_event, ctx) => externalChange(ctx));
+  pi.on("context_with_system", async (event, ctx) => {
+    writeStagedControl(ctx);
     if (!capability) await loadSurface(ctx);
+    // Entry identity lets attribution and request history skip hashing unchanged native history.
+    tagProjectedMessages(
+      event.messages,
+      ctx.sessionManager?.buildSessionProjection?.(),
+      cachedBranch(ctx.sessionManager) ?? [],
+    );
     let messages = event.messages.map(filterBootstrapMessage).filter(Boolean);
-    if (virtualization) {
-      virtualization.setContext(ctx);
-      const projected = await virtualization.project(messages, capability.contextVirtualization.effective);
-      messages = projected.messages;
-    }
-    if (history && capability.conversationHistory.effective) {
-      history.setContext(ctx);
-      history.capture(capability.contextVirtualization.effective);
-    }
     messages = withFreeflowRuntimeState(messages, capability, routing.state(), prompts, {
       force: refreshState,
+      anchor: runtimeStateAnchor,
       projectionFailure: routing.state().projectionFailure,
     });
     refreshState = false;
-    const routed = await routing.context(ctx, messages);
-    const projected = virtualization?.decorate(routed) ?? routed;
+    // Disabled Freeflow pays no per-request provenance work; re-enabling rebuilds it from session history.
+    const projected = capability?.enabled === true ? await routing.context(ctx, messages) : messages;
     const state = routing.state();
-    if (projected.some((message) => message.details?.routingRequestBlocked === true)) return { messages: projected };
+    if (projected.some((message) => message.details?.routingRequestBlocked === true)) {
+      // Routing must not expose hidden worker history on failure, but Pi's full-
+      // transcript hook still requires the leading system prompt/tool state.
+      const head = event.messages[0]?.role === "system" ? [event.messages[0]] : [];
+      return { messages: [...head, ...projected] };
+    }
     const view = routing.projectionEnabled && state.activeProfile === "coordinator" ? "coordinator" : "ordinary";
     return {
       messages: await requestHistory.assemble(projected, view, ctx, (assembled) =>
@@ -280,19 +526,22 @@ export default function freeflow(pi) {
     };
   });
   const restore = async (ctx, navigation = true) => {
-    requestHistory.reset();
+    cacheHealth.noteBreak();
+    resetHistory();
+    // Navigation selects another branch, whose reads differ; compaction keeps the branch and its file state.
+    if (navigation) files.invalidate();
     restoreSessionOverrides(ctx);
     refreshState = true;
-    if (virtualization) {
-      virtualization.setContext(ctx);
-      await virtualization.recover(ctx);
-    }
-    history?.setContext(ctx);
     await routing.ancestryChanged(ctx, navigation);
     await update(ctx);
   };
   pi.on("session_tree", async (_event, ctx) => restore(ctx));
-  pi.on("session_compact", async (_event, ctx) => restore(ctx, false));
+  // Pi compacting on its own (threshold, overflow, /compact) keeps its summarizer and kept tail, with Freeflow's additions.
+  pi.on("session_before_compact", async (event, ctx) => compaction.fallback(event, ctx));
+  pi.on("session_compact", async (_event, ctx) => {
+    await restore(ctx, false);
+    background.restate();
+  });
   pi.on("session_compact_failed", async (_event, ctx) => {
     refreshState = true;
     status(ctx);
@@ -305,26 +554,26 @@ export default function freeflow(pi) {
   ) {
     pi.registerShortcut("ctrl+shift+r", {
       description: "Cycle enabled Cognitive Routing manual holds",
-      handler: async (ctx) => {
+      handler: async (shortcutCtx) => {
+        const ctx = withLiveModel(shortcutCtx);
         if (!ctx.isIdle()) {
           ctx.ui.notify("Wait for Pi to become idle before changing control.", "warning");
           return;
         }
-        const state = routing.state();
-        const profiles = ["coordinator", ...workersForDelegation(state.delegation)];
-        const current = profiles.indexOf(state.activeProfile ?? "coordinator");
-        const target = profiles[(current + 1) % profiles.length];
-        ctx.ui.notify(JSON.stringify(await routing.setManualProfile(target)), "info");
+        await turnRoutingOn(ctx);
+        ctx.ui.notify(JSON.stringify(await routing.cycleManualProfile()), "info");
         await update(ctx);
       },
     });
     pi.registerShortcut("ctrl+shift+a", {
-      description: "Release manual hold to Automatic Coordinator",
-      handler: async (ctx) => {
+      description: "Turn Cognitive Routing on, or release a manual hold, to the automatic Coordinator",
+      handler: async (shortcutCtx) => {
+        const ctx = withLiveModel(shortcutCtx);
         if (!ctx.isIdle()) {
           ctx.ui.notify("Wait for Pi to become idle before changing control.", "warning");
           return;
         }
+        await turnRoutingOn(ctx);
         ctx.ui.notify(JSON.stringify(await routing.setAutomaticControl()), "info");
         await update(ctx);
       },
@@ -350,7 +599,7 @@ export default function freeflow(pi) {
       handler: (args, ctx) => sendSkillCommand(pi, ctx, skill, args),
     });
   pi.registerCommand("freeflow", {
-    description: "Freeflow settings, status, profile control, saved-operation resume, and context tools",
+    description: "Freeflow settings, status, profile control, and saved-operation resume",
     getArgumentCompletions: (prefix) =>
       freeflowCompletions(
         prefix,
@@ -359,22 +608,23 @@ export default function freeflow(pi) {
           typeof api.setThinkingLevel === "function",
       ),
     handler: async (args, ctx) => {
-      if (await routing.command(args ?? "", ctx)) {
-        await update(ctx);
+      if ((args ?? "").trim().toLowerCase() === "compact") {
+        await compactNow(ctx);
         return;
       }
-      const input = (args ?? "").trim();
-      if (input === "context" || input.startsWith("context ")) {
-        await handleContextCommand(
-          input.slice(7).trim(),
-          ctx,
-          virtualization,
-          capability?.contextVirtualization.effective,
-          capability?.conversationHistory.effective,
-        );
+      // A routing control (a hold or `auto`) turns routing on first when it is off.
+      if (/^profile\s+(?!history\b)\S/i.test((args ?? "").trim())) await turnRoutingOn(ctx);
+      if (await routing.command(args ?? "", ctx)) {
+        await update(ctx);
         return;
       }
-      await handleFreeflowCommand(args, ctx, async () => update(ctx), pi, routing);
+      await handleFreeflowCommand(args, ctx, async () => update(ctx), pi, routing, {
+        status: () => ({
+          cacheHealth: [...cacheHealth.status(), ...cacheMonitor.lines()],
+          backgroundRunning: background.running().length,
+          compaction: compaction.statusText(ctx),
+        }),
+      });
     },
   });
 }