@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/index.js

@@ -1,50 +1,152 @@
+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, withLines } from "./tool-execution/file-tracking.js";
+import { GuidanceNotices } from "./tool-execution/guidance-notices.js";
+import { registerApplyPatch } from "./tool-execution/apply-patch/tool.js";
+import { applyToolExecutionTools } from "./tool-execution/tools.js";
+import {
+  BackgroundJobs,
+  MONITOR_PER_MINUTE,
+  MONITOR_TYPE,
+  freeflowNotice,
+  NOTICE_TYPE,
+  registerBackgroundTools,
+} from "./tool-execution/background.js";
+import { Inbound, renderNotice } from "./host/inbound.js";
+import { currentSections, headSections, keepSections } from "./host/section-keeper.js";
+import { backgroundRefusal } from "./tool-execution/bash-guard.js";
+import { CompactionController, RECOVERY_TYPE, USER_REQUEST } from "./compaction/controller.js";
+import { applyCompactionTools, registerCompactionTool } from "./compaction/tool.js";
+import { strictest } from "./compaction/thresholds.js";
+import { SNAPSHOT_TYPE, TASK_ENTRY, TaskMemory } from "./task-memory/runtime.js";
+import { applyTaskMemoryTools, registerTaskMemoryTool } from "./task-memory/tool.js";
+import { freeflowHome } from "./task-memory/registry.js";
+import { DEFAULT_INBOUND_POLICY } from "./messaging/config.js";
+import { MESSAGE_TYPE, Messaging } from "./messaging/messaging.js";
+import { applyMessagingTools, registerMessagingTools } from "./messaging/tools.js";
+import { renderMessage } from "./messaging/render.js";
+import { renderSnapshotMessage } from "./task-memory/render.js";
+import { applyAskUserTool, registerAskUserTool } from "./ask-user/tool.js";
+import { confirmWithUser } from "./ask-user/ask.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,
+  freeflowSkillPath,
+  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";
+// The user's /freeflow compact, delivered as Freeflow's message.
+const COMPACT_REQUEST_TYPE = "freeflow-compaction-request";
+/** 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. */
+/** The sections Freeflow sets: its own, and Pi's rules and docs, which Tool Execution changes. */
+const OWN_SECTION_NAMES = ["freeflow_guidance", "environment", "tool_execution", "rules", "docs"];
+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,
+      );
+  }
+  const counted =
+    tokens ??
+    (manager.buildSessionProjection()?.messages ?? []).reduce((sum, message) => sum + estimateTokens(message), 0);
+  historyEstimate.set(manager, { branch, tokens: counted });
+  return counted + system;
+}
+/**
+ * Send a skill command's prompt as the user's message. A command can run while Pi is busy, which from Pi 1.2.0 includes
+ * the start of a run (before_agent_start); Pi then refuses a user message without `deliverAs`, so it is queued to
+ * follow the current work instead.
+ */
+function sendSkillPrompt(pi, skill, args) {
+  pi.sendUserMessage(skillPrompt(skill, args), { expandPromptTemplates: true, deliverAs: "followUp" });
+}
 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 });
+    sendSkillPrompt(pi, skill, args);
     return;
   }
   if (!state.configured || !state.enabled) {
     ctx.ui.notify("Run /setup-freeflow or enable Freeflow before dispatching this skill.", "warning");
     return;
   }
+  if (state.skills?.off?.includes(skill)) {
+    ctx.ui.notify(`${skill} is turned off in /freeflow settings (Skills).`, "warning");
+    return;
+  }
   const prompts = await getRuntimeContext(state);
   if (!hasUsableMandatoryPrompts(prompts)) {
     ctx.ui.notify("Freeflow core prompts are unavailable; the requested skill cannot be dispatched.", "warning");
     return;
   }
-  await pi.sendUserMessage(skillPrompt(skill, args), { expandPromptTemplates: true });
+  sendSkillPrompt(pi, skill, args);
 }
 function freeflowCompletions(prefix, routingAvailable) {
   const query = prefix ?? "";
@@ -54,51 +156,117 @@ function freeflowCompletions(prefix, routingAvailable) {
         ["settings local", "local", "Edit personal overrides for this repository"],
         ["settings repo", "repo", "Edit shared repository settings"],
       ]
-    : query.startsWith("profile ") && routingAvailable
+    : query.startsWith("task ")
       ? [
-          ["profile coordinator", "coordinator", "Hold Coordinator manually"],
-          ["profile helper", "helper", "Hold Helper manually when enabled"],
-          ["profile executor", "executor", "Hold Executor manually when enabled"],
-          ["profile auto", "auto", "Return to automatic Coordinator reconciliation"],
-          ["profile history", "history", "Read routing observations"],
+          ["task list", "list", "This repository's records, or a project's tasks"],
+          ["task new", "new", "Create a task in this repository's project and attach it"],
+          ["task attach", "attach", "Attach a record by task ID or path"],
+          ["task focus", "focus", "Move the focus to an attached record"],
+          ["task detach", "detach", "Detach a record"],
+          ["task confirm", "confirm", "Make held records writable here"],
+          ["task fanout", "fanout", "Create a child of the focused task with its own worktree"],
+          ["task child", "child", "Create a child of a task and attach it here"],
+          ["task import", "import", "Move a repository record into a project"],
+          ["task remove", "remove", "Move a task and its children to the trash"],
         ]
-      : query.startsWith("context ")
+      : query.startsWith("project ")
         ? [
-            ["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"],
+            ["project list", "list", "Every project"],
+            ["project new", "new", "Create a project and link this repository"],
+            ["project link", "link", "Link this repository to a project"],
+            ["project remove", "remove", "Move a project and its tasks to the trash"],
           ]
-        : [
-            ["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"],
-          ];
+        : query.startsWith("profile ") && routingAvailable
+          ? [
+              ["profile coordinator", "coordinator", "Hold Coordinator manually"],
+              ["profile helper", "helper", "Hold Helper manually when enabled"],
+              ["profile executor", "executor", "Hold Executor manually when enabled"],
+              ["profile auto", "auto", "Return to automatic Coordinator reconciliation"],
+              ["profile history", "history", "Read routing observations"],
+            ]
+          : [
+              ["settings", "settings", "Open settings; Tab switches Session, Personal and Repository"],
+              ["status", "status", "Show effective Freeflow state"],
+              ["compact", "compact", "Prepare, compact and recover now"],
+              ["task", "task", "Attach, focus, detach or confirm Working Records (task memory)"],
+              ["project", "project", "Create or link a task-memory project"],
+              ["trash", "trash", "Removed tasks and projects; trash empty deletes them for good"],
+              ...(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;
+  // The system sections of the last prompt's run, while Freeflow sets sections; see keepSections.
+  let ownSections;
+  let ownSectionsVersion = 0;
+  let ownHead;
+  // The sections Freeflow sets, and whether the current run is one a prompt started (so its requests carry them), or
+  // one an extension's message started that Freeflow still set its sections for (Pi 1.2.0 and later).
+  let ownNames = [];
+  let promptRun = false;
+  let messageRun = false;
+  // Whether the session has had a prompt. Pi before 1.2.0 builds the system prompt only for prompts, so until then a
+  // turn Freeflow started for a notice would reach the model with none: notices wait for the user's first prompt.
+  let prompted = false;
+  const files = new FileTracking();
+  const toolExecutionEffective = () => capability?.toolExecution?.effective === true;
+  const guidance = new GuidanceNotices(packageRoot);
+  const guidanceNoticesEffective = () =>
+    toolExecutionEffective() && capability?.toolExecution?.guidanceNotices !== false;
+  const compactionEffective = () => capability?.compaction?.effective === true;
+  const taskMemoryEffective = () => capability?.taskMemory?.effective === true;
+  const askUserEffective = () => capability?.askUser?.effective === true;
+  const messagingEffective = () => capability?.messaging?.effective === true;
+  const cacheHealth = new CacheHealth();
   let prompts;
-  let context;
-  let virtualization;
-  let history;
   let refreshState = true;
-  let sessionContext;
+  // Skills already read, as the Runtime State lists them: taken only where the state refreshes anyway (run
+  // boundaries, settings changes, compaction, navigation), so a skill read mid-run adds no state message.
+  let stateSkills = [];
+  // 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 +275,786 @@ 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());
+    applyTaskMemoryTools(api, taskMemoryEffective());
+    applyAskUserTool(api, askUserEffective());
+    applyMessagingTools(api, messagingEffective());
+    syncMessaging(ctx);
     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;
+    // The Coordinator's projected view may lack reads the full history holds, and every profile shares the state.
+    stateSkills = toolExecutionEffective() && !routing.projectionEnabled ? files.loadedSkills(ctx) : [];
+  }
+  /**
+   * 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 },
+  registerAskUserTool(api, {
+    // Under automatic routing only the Coordinator talks to the user; a worker returns the choice in its report.
+    refusal: () => {
+      const scope = routing.observationScope();
+      return scope.control === "automatic" && (scope.profile === "helper" || scope.profile === "executor")
+        ? "A Cognitive Routing worker does not ask the user. Put the choice, its options and your recommendation in your report (return_work); the Coordinator asks."
+        : undefined;
+    },
+  });
+  registerApplyPatch(api, {
+    effective: toolExecutionEffective,
+    files: (ctx) => files.forPatch(ctx),
+    written: (paths, ctx) => files.written(paths, ctx),
+  });
+  // Content arriving from outside the turn (host/inbound.ts): background exits now, later monitors and messages.
+  const inbound = new Inbound({
+    sendMessage: (message, options) => api.sendMessage(message, options),
+    sendUserMessage: (content) => api.sendUserMessage(content),
+    isIdle: () => liveHost?.isIdle?.(),
+    canWake: () => prompted,
+  });
+  api.registerMessageRenderer?.(NOTICE_TYPE, renderNotice("Background"));
+  api.registerMessageRenderer?.(MONITOR_TYPE, renderNotice("Monitor"));
+  api.registerMessageRenderer?.(COMPACT_REQUEST_TYPE, renderNotice("Compaction"));
+  // Compaction's warnings and its recovery message, and the changed-file notice: one line each, the rest on expand.
+  api.registerMessageRenderer?.(COMPACTION_NOTICE_TYPE, renderNotice("Compaction"));
+  api.registerMessageRenderer?.(RECOVERY_TYPE, renderNotice("Compaction"));
+  api.registerMessageRenderer?.("freeflow-files", renderNotice("Files"));
+  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) =>
+      inbound.deliver({ customType: NOTICE_TYPE, content, details, wake: triggerTurn }),
+    // A monitor's lines wake an idle agent (spec O-6); the rate limit bounds what that costs.
+    event: (id, line, join, onLimit) =>
+      inbound.deliver(
+        { customType: MONITOR_TYPE, content: line, details: { id }, wake: true },
+        {
+          key: `monitor:${id}`,
+          perMinute: MONITOR_PER_MINUTE,
+          onLimit,
+          join: (notices) => join(notices.map((notice) => notice.content)),
+        },
+      ),
+    endEvents: (id) => {
+      inbound.flush(`monitor:${id}`);
+      inbound.close(`monitor:${id}`);
+    },
+    discardEvents: (id) => inbound.close(`monitor:${id}`),
+  };
+  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 })),
+    notice: (text) => freeflowNotice("compaction", text),
+    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);
+  const sendSnapshot = (content, record) =>
+    void Promise.resolve(
+      api.sendMessage({ customType: SNAPSHOT_TYPE, content, display: true, details: { record } }),
+    ).catch(() => {});
+  const taskMemory = new TaskMemory({
+    effective: taskMemoryEffective,
+    append: (data) => api.appendEntry(TASK_ENTRY, data),
+    send: sendSnapshot,
+    owner: () => ({
+      session: liveHost?.sessionManager?.getSessionId?.() ?? "unknown",
+      ...(liveHost?.sessionManager?.getSessionFile?.() ? { file: liveHost.sessionManager.getSessionFile() } : {}),
+      since: new Date().toISOString(),
+    }),
+    confirm: async (title, message) => (liveHost?.hasUI ? confirmWithUser(liveHost, title, message) : false),
+    cwd: () => liveHost?.cwd ?? process.cwd(),
+    packageRoot,
+  });
+  // Messaging between live Pi sessions (Task 002 D-005). Its tools are deferred: tool_search loads them.
+  // Read from the event context that last synced messaging, while it was current: a captured context goes stale when
+  // Pi replaces the session, so later asynchronous work uses these values, not the context.
+  let messagingSeen;
+  let agentRunning = false;
+  const live = (read, fallback) => {
+    try {
+      return read();
+    } catch {
+      return fallback;
+    }
+  };
+  const messaging = new Messaging(
+    {
+      identity: async () => {
+        const seen = messagingSeen ?? { sessionId: `pid-${process.pid}`, cwd: process.cwd() };
+        const project = await taskMemory.registry.projectFor(seen.cwd).catch(() => undefined);
+        const focus = taskMemory.state().focus;
+        const task = focus ? await taskMemory.registry.byRecord(focus).catch(() => undefined) : undefined;
+        // The tasks this session owns, so a child finds its parent's session in list_sessions (Task 002 D-009).
+        const tasks = await taskMemory.registry
+          .read()
+          .then((data) => data.tasks)
+          .catch(() => ({}));
+        const owns = Object.entries(tasks)
+          .filter(([, each]) => each?.owner?.session === seen.sessionId)
+          .map(([id]) => id);
+        return {
+          ...seen,
+          ...(project ? { project: project.slug } : {}),
+          ...(task ? { task: task.id } : {}),
+          ...(owns.length ? { owns } : {}),
+        };
+      },
+      policy: () => capability?.messaging?.inbound ?? DEFAULT_INBOUND_POLICY,
+      busy: () => agentRunning,
+      deliver: (content, details) => {
+        inbound.deliver({ customType: MESSAGE_TYPE, content, details, wake: true });
+        if (!prompted && details.kind === "message")
+          live(
+            () =>
+              liveHost?.ui?.notify?.(
+                `A message from ${String(details.name ?? "another session")} is waiting: the agent reads it with your next prompt.`,
+                "info",
+              ),
+            undefined,
+          );
+      },
+      canWake: () => prompted,
+      canAsk: () => live(() => liveHost?.hasUI === true, false),
+      // The same dialog as ask_user, with a countdown (Task 002 D-008).
+      confirm: async (title, message, timeout) =>
+        (await Promise.resolve(
+          live(
+            () => confirmWithUser(liveHost, title, message, { timeoutMs: timeout, yes: "Deliver", no: "Refuse" }),
+            false,
+          ),
+        ).catch(() => false)) === true,
+    },
+    freeflowHome(),
   );
+  registerMessagingTools(api, messaging, messagingEffective);
+  api.registerMessageRenderer?.(MESSAGE_TYPE, renderMessage);
+  // Start or stop listening as messaging's effective state changes; a running session refreshes its registry entry.
+  let messagingSync = Promise.resolve();
+  function syncMessaging(ctx) {
+    const effective = messagingEffective();
+    if (effective)
+      messagingSeen = live(() => {
+        const manager = ctx.sessionManager;
+        const name = manager?.getSessionName?.();
+        return {
+          sessionId: manager?.getSessionId?.() ?? `pid-${process.pid}`,
+          ...(name ? { name } : {}),
+          cwd: ctx.cwd ?? process.cwd(),
+        };
+      }, messagingSeen);
+    messagingSync = messagingSync
+      .then(() => (effective ? messaging.start() : messaging.running() ? messaging.stop() : undefined))
+      .catch(() => {});
+  }
+  // A delivered resume view shows as one line naming the task; expanding shows the view the model received.
+  api.registerMessageRenderer?.(SNAPSHOT_TYPE, (message, options, theme) =>
+    renderSnapshotMessage(message, options, theme),
+  );
+  registerTaskMemoryTool(api, {
+    memory: taskMemory,
+    // Under automatic routing only the Coordinator proposes task memory actions; workers do not talk to the user.
+    refusal: () => {
+      const scope = routing.observationScope();
+      return scope.control === "automatic" && (scope.profile === "helper" || scope.profile === "executor")
+        ? "A Cognitive Routing worker may only read task memory (projects, list, view, search, env). Put the action you would propose in your report (return_work); the Coordinator proposes it."
+        : undefined;
+    },
+    // Proposals in groups the user allowed run without the dialog (Task 004 D-002).
+    autoApproved: (group) => capability?.taskMemory?.autoApprove?.[group] === true,
+    changed: (ctx) => {
+      refreshState = true;
+      status(ctx);
+    },
+  });
+  // /freeflow project: the user creates projects and links repositories to them; the model never does (D-015).
+  // Where the user can browse the project's records, when the project link was made (Task 004 D-003).
+  async function browseNote(cwd) {
+    const link = await taskMemory.registry.linkHere(cwd).catch(() => undefined);
+    return link && !link.error ? ` Browse its records in ${link.link}.` : "";
+  }
+  // Removal asks even from the user's own command: it moves records out of every session that holds them (Task 006).
+  async function removeWithConfirmation(ctx, target, title) {
+    const { question, error } = await taskMemory.removalQuestion(target);
+    if (!question) return { ok: false, text: error ?? "Nothing to remove." };
+    if (!ctx.hasUI || !(await confirmWithUser(ctx, title, question))) return { ok: false, text: "Not removed." };
+    return taskMemory.remove(target);
+  }
+  // The trash holds removed tasks and projects. Only this command empties it, so only the user can (Task 006).
+  async function trashCommand(rest, ctx) {
+    const where = await taskMemory.registry.trashPath();
+    const entries = await taskMemory.registry.trashEntries();
+    if (rest.trim().toLowerCase() !== "empty") {
+      ctx.ui.notify(
+        entries.length
+          ? `Trash (${where}):\n${entries.map((entry) => `- ${entry}`).join("\n")}\n/freeflow trash empty deletes them for good.`
+          : "The trash is empty.",
+        "info",
+      );
+      return;
+    }
+    if (!entries.length) {
+      ctx.ui.notify("The trash is empty.", "info");
+      return;
+    }
+    const yes =
+      ctx.hasUI &&
+      (await confirmWithUser(
+        ctx,
+        "Empty the trash?",
+        `Delete ${entries.length} removed item(s) in ${where} for good? This cannot be undone.`,
+      ));
+    if (!yes) {
+      ctx.ui.notify("The trash was not emptied.", "info");
+      return;
+    }
+    const deleted = await taskMemory.registry.emptyTrash();
+    ctx.ui.notify(`Deleted ${deleted.length} item(s) from the trash.`, "info");
+  }
+  async function projectCommand(rest, ctx) {
+    if (!taskMemoryEffective()) {
+      ctx.ui.notify("Task memory is off. Turn it on in /freeflow settings (Task Memory).", "warning");
+      return;
+    }
+    const [sub, ...words] = rest.trim().split(/\s+/).filter(Boolean);
+    // --worktrees <dir>: where fan-out puts this project's child worktrees.
+    const at = words.indexOf("--worktrees");
+    const worktrees = at >= 0 ? words.splice(at, 2)[1] : undefined;
+    const name = words.join(" ");
+    try {
+      if (sub === "new" && name) {
+        const slug = await taskMemory.registry.createProject(name, ctx.cwd, worktrees);
+        ctx.ui.notify(`Project ${slug} created and linked to this repository.${await browseNote(ctx.cwd)}`, "info");
+      } else if (sub === "link" && name) {
+        const slug = await taskMemory.registry.linkProject(name, ctx.cwd, worktrees);
+        ctx.ui.notify(`This repository is linked to project ${slug}.${await browseNote(ctx.cwd)}`, "info");
+      } else if (sub === "remove" && name) {
+        const result = await removeWithConfirmation(ctx, { project: name }, "Remove project?");
+        ctx.ui.notify(result.text, result.ok ? "info" : "warning");
+        refreshState = true;
+        status(ctx);
+      } else if (sub === "list") {
+        const result = await taskMemory.projects(ctx.cwd);
+        ctx.ui.notify(result.text, result.ok ? "info" : "warning");
+      } else {
+        const found = await taskMemory.registry.projectFor(ctx.cwd);
+        ctx.ui.notify(
+          found
+            ? `Project ${found.project.name} (${found.slug}), store ${found.project.store}.${await browseNote(ctx.cwd)}\n${await taskMemory.list(ctx.cwd)}`
+            : "This repository is not linked to a project. Use /freeflow project new <name> or link <name>.",
+          "info",
+        );
+      }
+    } catch (error) {
+      ctx.ui.notify(error?.message ?? String(error), "warning");
+    }
+  }
+  // /freeflow task: the user's own attach, focus, detach and confirm, and a picker over this repository's records.
+  async function taskCommand(rest, ctx) {
+    if (!taskMemoryEffective()) {
+      ctx.ui.notify("Task memory is off. Turn it on in /freeflow settings (Task Memory).", "warning");
+      return;
+    }
+    const [sub, ...words] = rest.trim().split(/\s+/).filter(Boolean);
+    let action = sub?.toLowerCase();
+    let target = words.join(" ");
+    if (!action || action === "pick") {
+      const records = await taskMemory.records(ctx.cwd);
+      if (!records.length || !ctx.hasUI) {
+        ctx.ui.notify(await taskMemory.list(ctx.cwd), "info");
+        return;
+      }
+      const labels = records.map((record) => `${taskMemory.name(record)} — ${record}`);
+      const chosen = await ctx.ui.select("Task records", labels);
+      if (!chosen) return;
+      target = records[labels.indexOf(chosen)];
+      action = taskMemory.state().attached.includes(target) ? "focus" : "attach";
+    }
+    let result;
+    if (action === "list") result = { ok: true, text: await taskMemory.list(ctx.cwd, target) };
+    else if (action === "new") {
+      // The user's own command: create the task in this repository's project and attach it, with no dialog.
+      const created = await taskMemory.create(target, target, ctx.cwd);
+      result = created.ok && created.id ? await taskMemory.attach(created.id, ctx.cwd) : created;
+    } else if (action === "attach") result = await taskMemory.attach(target, ctx.cwd);
+    else if (action === "focus") result = await taskMemory.focus(target, ctx.cwd);
+    else if (action === "detach") result = await taskMemory.detach(target, ctx.cwd);
+    else if (action === "confirm") result = await taskMemory.confirm(target, ctx.cwd);
+    else if (action === "child") {
+      // From the new session: create a child of the named parent and attach it here.
+      const [parent, ...title] = words;
+      const created = await taskMemory.child(title.join(" "), title.join(" "), parent);
+      const id = /Created child (\S+)/.exec(created.text)?.[1];
+      result = created.ok && id ? await taskMemory.attach(id, ctx.cwd) : created;
+    } else if (action === "fanout") {
+      const title = words.join(" ");
+      result = await taskMemory.fanout(title, title);
+    } else if (action === "import") {
+      const [path, ...project] = words;
+      const yes = ctx.hasUI
+        ? await confirmWithUser(ctx, "Import record?", `Move ${path} into the ${project.join(" ")} project's store?`)
+        : false;
+      result = yes
+        ? await taskMemory.importRecord(path, project.join(" "), ctx.cwd)
+        : { ok: false, text: "Not imported." };
+    } else if (action === "remove") {
+      result = await removeWithConfirmation(ctx, { task: target }, "Remove task?");
+    } else
+      result = {
+        ok: false,
+        text: "Use /freeflow task [list [project]|new <title>|attach <id or record>|focus <id or record>|detach <id or record>|confirm [record]|child <parent-id> <title>|fanout <title>|import <record> <project>|remove <id>].",
+      };
+    if (result.snapshot) {
+      sendSnapshot(result.text, result.snapshot);
+      ctx.ui.notify(
+        `Task memory: ${(await taskMemory.brief(result.snapshot)).label} is the focus. ${taskMemory.attachedText()}`,
+        "info",
+      );
+    } else if (result.command)
+      ctx.ui.notify(`${result.headline ?? result.text}\nRun in a new terminal:\n  ${result.command}`, "info");
+    else ctx.ui.notify(result.text, result.ok ? "info" : "warning");
+    refreshState = true;
+    status(ctx);
+  }
+  // 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);
+    // Freeflow's message saying the user asked, not text in the user's name (Task 002 D-008); the run it starts keeps
+    // Freeflow's system sections (host/section-keeper.ts).
+    const index = compaction.indexText(ctx);
+    const text = freeflowNotice(
+      "compaction",
+      `The user ran /freeflow compact. ${USER_REQUEST}${index ? `\n\n${index}` : ""}`,
+    );
+    await Promise.resolve(
+      api.sendMessage(
+        { customType: COMPACT_REQUEST_TYPE, content: text, display: true, details: {} },
+        { triggerTurn: true, deliverAs: "steer" },
+      ),
+    ).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 {
+      // Only what this configuration can use (Task 003 D-002): capability skills only while their capability is
+      // effective, and while Freeflow is inactive (disabled, unconfigured, or its prompts missing) only Setup Freeflow,
+      // so /setup-freeflow still works.
+      skillPaths:
+        state?.enabled === true && hasUsableMandatoryPrompts(prompts)
+          ? freeflowModelSkillPaths(state)
+          : [freeflowSkillPath("setup-freeflow")],
+    };
   });
+  /** Sections recorded on another session or branch are not this one's; whether this branch had a prompt is its own. */
+  const forgetSections = (ctx) => {
+    ownSections = undefined;
+    ownHead = undefined;
+    ownSectionsVersion++;
+    prompted = (cachedBranch(ctx.sessionManager) ?? []).some(
+      (entry) =>
+        entry?.type === "message" &&
+        (entry.message?.role === "user" || (entry.message?.role === "system" && entry.message.sections)),
+    );
+  };
   pi.on("session_start", async (event, ctx) => {
+    liveHost = ctx;
+    // Sections recorded for another session (after /new or /resume) are not this one's.
+    forgetSections(ctx);
+    promptRun = false;
+    messageRun = false;
     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();
+    stateSkills = [];
+    compaction.reset();
     await routing.bind(ctx, capability.cognitiveRouting, event?.reason !== "reload");
-    contextTools();
+    taskMemory.rebuild(cachedBranch(ctx.sessionManager));
+    if (taskMemoryEffective()) {
+      await taskMemory.load();
+      // The project link for the user to browse records in the editor, made again if missing (Task 004 D-003). Not
+      // awaited: it runs Git, and nothing at startup reads it.
+      void taskMemory.registry.linkHere(ctx.cwd).catch(() => undefined);
+      // A fork or clone copies the branch's attachments; they stay held until the user confirms them here.
+      if (event?.reason === "fork") {
+        const held = taskMemory.holdInherited();
+        if (held.length)
+          ctx.ui?.notify?.(
+            `Task memory: ${held.length} inherited record(s) are held, not writable. Release with /freeflow task confirm.`,
+            "info",
+          );
+      }
+      await taskMemory.deliver(cachedBranch(ctx.sessionManager));
+      // A session started in a task's directory with nothing attached offers that task (D-017). Not awaited, so
+      // startup finishes first and the user answers when the dialog appears; a decline is kept on the branch.
+      const suggested = ctx.hasUI ? await taskMemory.suggestion(cachedBranch(ctx.sessionManager)) : undefined;
+      if (suggested)
+        void (async () => {
+          const yes = await confirmWithUser(
+            ctx,
+            `Attach ${suggested.id}?`,
+            `This directory belongs to ${suggested.title} (${suggested.id}). Attach it to this session?`,
+          );
+          if (generation !== surfaceGeneration) return;
+          if (!yes) {
+            taskMemory.decline(suggested.record);
+            return;
+          }
+          const result = await taskMemory.attach(suggested.id, ctx.cwd);
+          if (result.snapshot) sendSnapshot(result.text, result.snapshot);
+          ctx.ui.notify(
+            result.ok ? `Task memory: ${suggested.id} attached.` : result.text,
+            result.ok ? "info" : "warning",
+          );
+          refreshState = true;
+          status(ctx);
+        })().catch(() => {});
+    }
     status(ctx);
   });
   pi.on("session_shutdown", async () => {
     surfaceGeneration++;
-    requestHistory.reset();
+    // Leave the live registry and close the socket, after any start still queued; sessions waiting for this one learn
+    // that it ended.
+    messagingSync = messagingSync.then(() => messaging.stop()).catch(() => {});
+    await messagingSync;
+    // Background processes belong to this extension instance; none may report into the next session.
+    await background.stopAll();
+    inbound.reset();
+    files.reset();
+    stateSkills = [];
+    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) => {
+    // Pi 1.2.0 and later fire this for a run an extension's message starts too (messageType "custom").
+    const fromMessage = event.messageType === "custom";
     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, fromMessage ? "message" : "prompt");
+    } 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];
+      // Nothing of Freeflow while it is disabled or unconfigured (Task 003 D-002).
+      if (capability?.enabled === true && hasUsableMandatoryPrompts(prompts))
+        sections.freeflow_guidance = stableRuntimeContext(prompts, {
+          routing: capability?.cognitiveRouting?.effective === true,
+          prompts: capability?.prompts,
+        });
+      if (toolExecution)
+        Object.assign(sections, toolExecutionTail(api.getSettings?.()?.shellPath, prompts?.toolExecutionPrompt));
+      // What Freeflow set, so requests of runs an extension's message starts keep it (host/section-keeper.ts).
+      ownNames = OWN_SECTION_NAMES.filter(
+        (name) => (toolExecution || (name !== "rules" && name !== "docs")) && typeof sections[name] === "string",
+      );
+      promptRun = !fromMessage;
+      messageRun = fromMessage;
+      prompted = true;
+    }
+    // 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: freeflowNotice("files", changed), display: true } };
+  });
+  pi.on("agent_start", () => {
+    routing.runStarted();
+    guidance.runStarted();
+    agentRunning = true;
+    if (messaging.running()) void messaging.setBusy(true).catch(() => {});
   });
-  pi.on("message_end", (event) => routing.messageEnd(event.message));
-  pi.on("tool_call", (event, ctx) => {
+  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.
+    // Pi 1.2.0 and later prepare it through before_agent_start; this covers earlier Pi, which skips that event there.
+    if (routing.startedByMessage(event.message)) {
+      await update(ctx);
+      try {
+        await routing.beforeRun(ctx, "late");
+      } finally {
+        writeStagedControl(ctx);
+        status(ctx);
+      }
+    }
+  });
+  pi.on("tool_call", async (event, ctx) => {
+    const recordGate = await taskMemory.gate(event.toolName, event.input, ctx.cwd);
+    if (recordGate) return recordGate;
+    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) => {
+    if (!toolExecutionEffective()) return undefined;
+    const shaped = await files.toolResult(event, ctx);
+    // The push retriever's notice joins the result before it is delivered, after anything Tool Execution added.
+    const executeWorkUnread = () =>
+      !(capability?.skills?.off ?? []).includes("execute-work") && !files.loadedSkills(ctx).includes("execute-work");
+    const lines = guidanceNoticesEffective() ? await guidance.toolResult(event, ctx.cwd, executeWorkUnread) : [];
+    return lines.length ? { content: withLines(shaped?.content ?? event.content ?? [], lines) } : shaped;
   });
   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) {
+      // The focused record arrives after the summary, so recovery starts from it rather than a path to look up.
+      const snapshot = await taskMemory.snapshotEntry();
+      if (snapshot) compacting.entries.push(snapshot);
+      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;
+    // File state first, so the state restore refreshes lists no skill from before the compaction.
+    await files.compacted(compacted.carriedFiles, ctx);
+    await restore(ctx, false);
   });
   pi.on("agent_settled", async (_event, ctx) => {
+    promptRun = false;
+    messageRun = false;
+    agentRunning = false;
+    if (messaging.running()) await messaging.setBusy(false).catch(() => {});
     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);
-    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);
+    // Entry identity lets attribution and request history skip hashing unchanged native history.
+    tagProjectedMessages(
+      event.messages,
+      ctx.sessionManager?.buildSessionProjection?.(),
+      cachedBranch(ctx.sessionManager) ?? [],
+    );
+    // A run an extension's message starts keeps the prompt of the last prompt's run: every section, as Pi rendered it,
+    // so the sections other extensions set only for prompts (Pi's own MCP servers, for one) are not removed either; on
+    // Pi 1.2.0 and later Freeflow's own follow what it set for that run. Recorded only while Freeflow sets sections;
+    // with Freeflow off, Pi's prompt passes through unchanged.
+    const strings = (current) =>
+      Object.fromEntries(Object.entries(current).filter((entry) => typeof entry[1] === "string"));
+    if (promptRun) {
+      const own = ownNames.length ? strings(currentSections(event.messages)) : {};
+      if (
+        !ownSections ||
+        Object.keys(own).length !== Object.keys(ownSections).length ||
+        Object.entries(own).some(([name, value]) => ownSections[name] !== value)
+      ) {
+        ownSections = own;
+        ownSectionsVersion++;
+      }
+      ownHead = headSections(event.messages);
+    } else if (messageRun && ownSections) {
+      // Pi 1.2.0 and later give a run an extension's message starts the sections Freeflow set for it, so Freeflow's
+      // follow this run, while every other section keeps the last prompt's value (its extension may set it only for
+      // prompts). The head stays the one recorded, so a head Pi rebuilds here still gets the recorded sections.
+      const current = currentSections(event.messages);
+      const next = { ...ownSections };
+      for (const name of OWN_SECTION_NAMES) {
+        const value = current[name];
+        if (typeof value === "string") next[name] = value;
+        else delete next[name];
+      }
+      if (OWN_SECTION_NAMES.some((name) => next[name] !== ownSections[name])) {
+        ownSections = next;
+        ownSectionsVersion++;
+      }
+    } else if (!ownSections) {
+      // A run Pi started before any prompt of this process (a resumed session messaged while idle): the transcript
+      // still carries the last prompt's sections, when Freeflow's guidance is among them.
+      const current = currentSections(event.messages);
+      if (typeof current.freeflow_guidance === "string") {
+        ownSections = strings(current);
+        ownHead = headSections(event.messages);
+        ownSectionsVersion++;
+      }
     }
+    let messages = keepSections(event.messages, ownSections, ownSectionsVersion, ownHead)
+      .map(filterBootstrapMessage)
+      .filter(Boolean);
     messages = withFreeflowRuntimeState(messages, capability, routing.state(), prompts, {
       force: refreshState,
+      anchor: runtimeStateAnchor,
       projectionFailure: routing.state().projectionFailure,
+      taskMemory: taskMemory.runtimeLines(),
+      skills: stateSkills,
     });
     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 +1063,41 @@ 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.on("session_tree", async (_event, ctx) => {
+    // A run Pi starts on this branch keeps this branch's last prompt's sections, not the branch left behind.
+    forgetSections(ctx);
+    // Task memory follows the branch: the records attached at this point of the conversation.
+    const before = taskMemory.state();
+    const changed = taskMemory.rebuild(cachedBranch(ctx.sessionManager));
+    if (taskMemoryEffective()) await taskMemory.load();
+    await restore(ctx);
+    if (!taskMemoryEffective()) return;
+    if (changed) {
+      const focus = taskMemory.state().focus;
+      ctx.ui?.notify?.(
+        `Task memory follows this branch: focus ${before.focus ? taskMemory.name(before.focus) : "none"} -> ${focus ? taskMemory.name(focus) : "none"}. ${taskMemory.attachedText()} Change it with /freeflow task.`,
+        "info",
+      );
+    }
+    await taskMemory.deliver(cachedBranch(ctx.sessionManager));
+  });
+  // 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) => {
+    files.piCompacted();
+    await restore(ctx, false);
+    background.restate();
+    await taskMemory.deliver(cachedBranch(ctx.sessionManager));
+  });
   pi.on("session_compact_failed", async (_event, ctx) => {
     refreshState = true;
     status(ctx);
@@ -305,26 +1110,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);
       },
@@ -333,15 +1138,6 @@ export default function freeflow(pi) {
   for (const { command, skill } of WORKFLOW_COMMANDS)
     pi.registerCommand(command, {
       description: command === skill ? `Run Freeflow ${skill}` : `Run Freeflow ${skill} via ${command}`,
-      ...(command === "bypass"
-        ? {
-            getArgumentCompletions: (prefix) =>
-              [
-                { value: "next", label: "next", description: "Skip one optional step" },
-                { value: "task", label: "task", description: "Reduce optional pressure for the current task" },
-              ].filter((item) => item.value.startsWith(prefix ?? "")),
-          }
-        : {}),
       handler: (args, ctx) => sendSkillCommand(pi, ctx, skill, args),
     });
   for (const skill of CONTRIBUTOR_COMMANDS)
@@ -350,7 +1146,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 +1155,42 @@ export default function freeflow(pi) {
           typeof api.setThinkingLevel === "function",
       ),
     handler: async (args, ctx) => {
-      if (await routing.command(args ?? "", ctx)) {
-        await update(ctx);
+      const task = /^task(?:\s+(.*))?$/i.exec((args ?? "").trim());
+      if (task) {
+        await taskCommand(task[1] ?? "", 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,
-        );
+      const trash = /^trash(?:\s+(.*))?$/i.exec((args ?? "").trim());
+      if (trash) {
+        await trashCommand(trash[1] ?? "", ctx);
+        return;
+      }
+      const project = /^project(?:\s+(.*))?$/i.exec((args ?? "").trim());
+      if (project) {
+        await projectCommand(project[1] ?? "", ctx);
+        return;
+      }
+      if ((args ?? "").trim().toLowerCase() === "compact") {
+        await compactNow(ctx);
+        return;
+      }
+      // 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),
+          taskMemory: taskMemory.attachedText(),
+          messaging: messaging.self()
+            ? `this session is ${messaging.self().name}${messaging.heldCount() ? `, ${messaging.heldCount()} held` : ""}`
+            : undefined,
+        }),
+      });
     },
   });
 }