volute 0.53.0 → 0.55.0

package/templates/claude/src/lib/stream-consumer.ts

@@ -4,10 +4,14 @@ import { log, warn } from "./logger.js";
 import { filterEvent, loadTransparencyPreset } from "./transparency.js";
 import type { VoluteEvent } from "./types.js";
 
+/** A pending message's daemon-facing id (routing/channel key) paired with its channel `seq`. */
+export type MessageIdEntry = { id: string | undefined; seq: number };
+
 export type StreamSession = {
   name: string;
-  messageIds: (string | undefined)[];
+  messageIds: MessageIdEntry[];
   currentMessageId?: string;
+  currentSeq?: number;
   messageChannels: Map<string, { channel: string; sender?: string }>;
 };
 
@@ -16,6 +20,11 @@ export type StreamCallbacks = {
   broadcast: (event: VoluteEvent) => void;
   onTurnEnd?: () => void;
   onContextTokens?: (tokens: number) => void;
+  /**
+   * Acknowledge the message channel entry with this `seq` — its turn is done (either
+   * it drove this turn directly, or it was folded into it; see the `result` handler).
+   */
+  ack: (seq: number) => void;
 };
 
 // Loaded once at startup — mind restarts on config changes
@@ -48,7 +57,9 @@ export async function consumeStream(
   let preTurnPending = 0;
   for await (const msg of stream) {
     if (session.currentMessageId === undefined) {
-      session.currentMessageId = session.messageIds.shift();
+      const entry = session.messageIds.shift();
+      session.currentMessageId = entry?.id;
+      session.currentSeq = entry?.seq;
       preTurnPending = session.messageIds.length;
     }
     if ("session_id" in msg && msg.session_id) {
@@ -123,14 +134,20 @@ export async function consumeStream(
       if (session.currentMessageId) {
         session.messageChannels.delete(session.currentMessageId);
       }
+      // Ack this turn's driving message, identified by seq (not position — see
+      // message-channel.ts). Without this the channel's inFlight set strands an
+      // entry per turn, which gets replayed verbatim on the next rotation (#764).
+      if (session.currentSeq !== undefined) callbacks.ack(session.currentSeq);
       // Prune every id folded into this turn — the ones pushed after it started
       // — not just currentMessageId. The SDK folds mid-run arrivals into the
       // active run (they never see a result of their own), and a stranded entry
       // would be shifted in as the NEXT turn's id, tagging that turn's rows with
       // the wrong channel (#700). Ids queued before the turn started stay: each
-      // still gets a run (and result) of its own.
-      for (const id of session.messageIds.splice(preTurnPending)) {
-        if (id !== undefined) session.messageChannels.delete(id);
+      // still gets a run (and result) of its own. Ack each folded entry too — same
+      // reasoning as above, applied to every message the fold absorbed.
+      for (const entry of session.messageIds.splice(preTurnPending)) {
+        if (entry.id !== undefined) session.messageChannels.delete(entry.id);
+        callbacks.ack(entry.seq);
       }
       log("mind", `session "${session.name}": turn done`);
       // Log any error messages from the result
@@ -154,6 +171,7 @@ export async function consumeStream(
       callbacks.broadcast({ type: "done" });
       emit(session, { type: "done" });
       session.currentMessageId = undefined;
+      session.currentSeq = undefined;
       callbacks.onTurnEnd?.();
     }
   }

package/templates/claude/src/server.ts

@@ -33,7 +33,6 @@ const mind = createMind({
   thinking: config.thinking,
   effort: config.effort,
   sessionsDir,
-  compactionMessage: config.compactionMessage,
   maxContextTokens: config.compaction?.maxContextTokens,
   sessionIdleMinutes: config.sessionIdleMinutes,
   seedTokens: config.continuity?.seedTokens,

package/templates/claude/volute-template.json

@@ -2,5 +2,5 @@
   "rename": {
     "gitignore": ".gitignore"
   },
-  "substitute": ["package.json", ".init/SOUL.md", "home/.config/routes.json"]
+  "substitute": ["package.json", ".init/SOUL.md", ".init/.config/routes.json"]
 }

package/templates/codex/.init/AGENTS.md

@@ -13,6 +13,10 @@ Messages arrive with a context prefix:
 
 You can also reach out proactively — see the **volute-mind** skill.
 
+## Framework Upgrades
+
+When the host updates Volute, your framework code (`src/`, plus `VOLUTE.md`) upgrades automatically the next time you're eligible — usually your next restart. Identity and memory files in `home/` — `SOUL.md`, `MEMORY.md`, everything you author — are never touched by an upgrade. If you'd rather manage your own framework code by hand, set `"upgrades": "manual"` in `.config/volute.json`.
+
 ## Memory System
 
 Two-tier memory, both managed via file tools:

package/templates/codex/package.json

@@ -10,11 +10,11 @@
   },
   "dependencies": {
     "@anthropic-ai/tokenizer": "^0.0.4",
-    "@openai/codex-sdk": "^0.144.3",
+    "@openai/codex-sdk": "^0.145.0",
     "tsx": "^4.23.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.3",
+    "@biomejs/biome": "2.5.5",
     "@types/node": "^26.1.1",
     "typescript": "^6.0.3"
   }

package/templates/codex/src/agent.ts

@@ -3,8 +3,6 @@ import { resolve as resolvePath } from "node:path";
 import { Codex } from "@openai/codex-sdk";
 import { flushFileChanges, trackFileChange } from "./lib/auto-commit.js";
 import {
-  type CodexSeedCut,
-  computeCodexSeedCut,
   DEFAULT_SEED_TOKENS,
   rotateCodexSession,
   seedCodexSession,
@@ -21,17 +19,11 @@ import {
   readSkillDescriptions,
 } from "./lib/context-breakdown.js";
 import { daemonEmit, daemonRestart, type EventType } from "./lib/daemon-client.js";
-import { compactTimestamp } from "./lib/format-prefix.js";
 import { runHooks } from "./lib/hook-loader.js";
 import { log, warn } from "./lib/logger.js";
 import { buildSeededNote, type SeedCause } from "./lib/seed-note.js";
 import { createSessionStore } from "./lib/session-store.js";
-import {
-  getStartupContext,
-  loadPrompts,
-  loadSystemPrompt,
-  renderCompactionWarning,
-} from "./lib/startup.js";
+import { getStartupContext, loadPrompts, loadSystemPrompt } from "./lib/startup.js";
 import { filterEvent, loadTransparencyPreset } from "./lib/transparency.js";
 import { turnContextFor } from "./lib/turn-context.js";
 import type {
@@ -52,7 +44,7 @@ type CodexThread = {
   ): Promise<{ events: AsyncIterable<Record<string, any>> }>;
 };
 
-type QueuedMessage = { text: string; meta: HandlerMeta; isRotationWarning?: boolean };
+type QueuedMessage = { text: string; meta: HandlerMeta };
 
 type CodexSession = {
   name: string;
@@ -81,14 +73,6 @@ type CodexSession = {
   currentThreadId: string | null;
   /** Why the tail is seeded — picks the boundary note's wording. Last cause wins. */
   seededCause: SeedCause;
-  /**
-   * The cut point pinned at warn time (the first-kept turn the mind was told would
-   * survive verbatim). Honored at rotation so the promise in the warning holds even
-   * though the rollout grows after the warning. Null until a warning fires.
-   */
-  rotationCut: CodexSeedCut | null;
-  /** A rotation warning turn is queued/in-flight — suppress re-triggering until it rotates. */
-  rotatePending: boolean;
   /**
    * Back-to-back rotations that did NOT bring context under the threshold (reset by any
    * healthy turn). Guards against a runaway loop when the tail alone can't fit — e.g. a
@@ -139,12 +123,6 @@ export function createMind(options: {
   const maxContextTokens = options.maxContextTokens;
   const seedTokens = options.seedTokens ?? DEFAULT_SEED_TOKENS;
 
-  // The warning the mind gets when the context limit approaches: it authors summaries
-  // of the turns that will collapse, then the session rotates onto the verbatim tail.
-  // ${date}/${memory_size} are filled per-warning (the date rolls over and MEMORY.md
-  // changes as the mind edits it); ${cutoff} is filled with the pinned boundary.
-  const compactionMessage = () => renderCompactionWarning(prompts.compaction_warning);
-
   if (maxContextTokens) {
     log("mind", `compaction threshold: ${maxContextTokens} tokens`);
   }
@@ -173,11 +151,11 @@ export function createMind(options: {
     ...(apiKey ? { apiKey } : {}),
     config: {
       model_instructions_file: promptPath,
-      // Rotation (mind-authored compaction) is the primary path: at maxContextTokens we
-      // warn the mind and rotate onto the verbatim tail. The SDK's native auto-compaction
-      // is only an emergency backstop — set above the volute threshold (1.5×) so it fires
-      // solely when rotation can't relieve context (e.g. a system prompt too large to fit
-      // the tail under the threshold), after the runaway guard stops self-rotating.
+      // Rotation is the primary path: at maxContextTokens we silently rotate onto the
+      // verbatim tail between turns. The SDK's native auto-compaction is only an emergency
+      // backstop — set above the volute threshold (1.5×) so it fires solely when rotation
+      // can't relieve context (e.g. a system prompt too large to fit the tail under the
+      // threshold), after the runaway guard stops self-rotating.
       model_auto_compact_token_limit: maxContextTokens
         ? Math.floor(maxContextTokens * 1.5)
         : 999999999,
@@ -217,8 +195,6 @@ export function createMind(options: {
       seededArchivedAt: null,
       currentThreadId: null,
       seededCause: "restored",
-      rotationCut: null,
-      rotatePending: false,
       consecutiveRotations: 0,
     };
     sessions.set(name, session);
@@ -642,62 +618,22 @@ export function createMind(options: {
     session.currentMessageId = undefined;
   }
 
-  // --- Rotation (mind-authored compaction) ---
+  // --- Rotation (silent, at turn end) ---
 
   /**
-   * Warn the mind that the session will rotate at the context limit and pin the cut
-   * point it's told about. Computes which whole turns fit in `seedTokens` from the live
-   * rollout, pins the first-kept turn's timestamp (so rotation honors the same boundary
-   * even as the rollout grows), interpolates its local time into the `${cutoff}`
-   * placeholder, and queues the warning as the mind's next (wrap-up) turn.
-   */
-  function warnAndPinRotation(session: CodexSession) {
-    let cutoffLabel = "the cutoff";
-    session.rotationCut = null;
-    const threadId = session.currentThreadId;
-    if (threadId) {
-      try {
-        const path = findCodexSessionFile(threadId, options.mindDir);
-        const cut = path ? computeCodexSeedCut(readFileSync(path, "utf-8"), seedTokens) : null;
-        if (cut) {
-          session.rotationCut = cut;
-          const d = new Date(cut.boundaryTimestamp);
-          if (!Number.isNaN(d.getTime())) cutoffLabel = compactTimestamp(d);
-        }
-      } catch (err) {
-        log("mind", `session "${session.name}": failed to pin rotation cut:`, err);
-      }
-    }
-    // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${cutoff} prompt placeholder
-    const warning = compactionMessage().replaceAll("${cutoff}", cutoffLabel);
-    session.rotatePending = true;
-    // Run the warning next, ahead of any queued messages, so the mind wraps up before
-    // more context piles on. Remaining queued messages then run on the rotated thread.
-    session.messageQueue.unshift({
-      text: warning,
-      meta: { messageId: `rotation-warning-${Date.now()}` },
-      isRotationWarning: true,
-    });
-  }
-
-  /**
-   * After the wrap-up warning turn completes, rotate the thread in place: build a seeded
-   * rollout from the pinned cut out of the live rollout, archive the rotated-out thread,
-   * and resume the new thread. On any failure we leave the old thread in place and let
-   * the SDK's native backstop handle it if context keeps climbing.
+   * Rotate the thread in place: build a seeded budget-tail rollout out of the live
+   * rollout, archive the rotated-out thread, and resume the new thread. On any failure
+   * we leave the old thread in place and let the SDK's native backstop handle it if
+   * context keeps climbing.
    */
   function performRotation(session: CodexSession) {
-    session.rotatePending = false;
     const oldThreadId = session.currentThreadId;
-    const cut = session.rotationCut;
-    session.rotationCut = null;
 
     const newThreadId = oldThreadId
       ? rotateCodexSession({
           mindDir: options.mindDir,
           name: session.name,
           oldThreadId,
-          cut,
           seedTokens,
         })
       : null;
@@ -733,22 +669,24 @@ export function createMind(options: {
   }
 
   /**
-   * Decide, after a normal (non-warning) turn, whether to warn + pin a rotation: only when
-   * a threshold is configured, context is at/over it, no rotation is already pending, and
-   * we're under the runaway cap. A turn that came back under the threshold ends any streak.
+   * Decide, after a turn, whether to rotate in place: only when a threshold is
+   * configured, context is at/over it, and we're under the runaway cap (past the
+   * cap, the SDK's native backstop takes over). A turn that came back under the
+   * threshold ends any streak. Rotation is silent — the one-line rotation note
+   * arms via seededCause and lands on the next turn.
    */
-  function maybeWarnRotation(session: CodexSession) {
+  function maybeRotate(session: CodexSession) {
     if (!maxContextTokens) return;
     if (session.cumulativeInputTokens < maxContextTokens) {
       session.consecutiveRotations = 0; // healthy turn — streak over
       return;
     }
-    if (session.rotatePending || session.consecutiveRotations >= MAX_CONSECUTIVE_ROTATIONS) return;
+    if (session.consecutiveRotations >= MAX_CONSECUTIVE_ROTATIONS) return;
     log(
       "mind",
-      `session "${session.name}": ${session.cumulativeInputTokens} tokens >= ${maxContextTokens} — warning + pinning rotation`,
+      `session "${session.name}": ${session.cumulativeInputTokens} tokens >= ${maxContextTokens} — rotating`,
     );
-    warnAndPinRotation(session);
+    performRotation(session);
   }
 
   // --- Message queue processing ---
@@ -761,12 +699,8 @@ export function createMind(options: {
       const next = session.messageQueue.shift()!;
       session.currentMessageId = next.meta.messageId;
       await runTurn(session, next.text, next.meta);
-      if (next.isRotationWarning) {
-        // The wrap-up warning turn is done — rotate the thread in place.
-        performRotation(session);
-      } else {
-        maybeWarnRotation(session);
-      }
+      // Post-turn is between-turns for the queue, so rotate here if we're over.
+      maybeRotate(session);
     }
 
     session.processing = false;

package/templates/codex/volute-template.json

@@ -2,5 +2,5 @@
   "rename": {
     "gitignore": ".gitignore"
   },
-  "substitute": ["package.json", ".init/SOUL.md", "home/.config/routes.json"]
+  "substitute": ["package.json", ".init/SOUL.md", ".init/.config/routes.json"]
 }

package/templates/pi/.init/MINDS.md

@@ -13,6 +13,10 @@ Messages arrive with a context prefix:
 
 You can also reach out proactively — see the **volute-mind** skill.
 
+## Framework Upgrades
+
+When the host updates Volute, your framework code (`src/`, plus `VOLUTE.md`) upgrades automatically the next time you're eligible — usually your next restart. Identity and memory files in `home/` — `SOUL.md`, `MEMORY.md`, everything you author — are never touched by an upgrade. If you'd rather manage your own framework code by hand, set `"upgrades": "manual"` in `.config/volute.json`.
+
 ## Memory System
 
 Two-tier memory, both managed via file tools:

package/templates/pi/package.json

@@ -16,7 +16,7 @@
     "tsx": "^4.23.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.3",
+    "@biomejs/biome": "2.5.5",
     "@types/node": "^26.1.1",
     "typescript": "^6.0.3"
   }

package/templates/pi/src/agent.ts

@@ -24,25 +24,13 @@ import {
 import { daemonEmit } from "./lib/daemon-client.js";
 import { dispatchPrompt } from "./lib/dispatch.js";
 import { createEventHandler, emit } from "./lib/event-handler.js";
-import { compactTimestamp } from "./lib/format-prefix.js";
 import { runHooks } from "./lib/hook-loader.js";
 import { log } from "./lib/logger.js";
-import {
-  computePiSeedCut,
-  DEFAULT_SEED_TOKENS,
-  type PiSeedCut,
-  rotatePiSession,
-  seedPiSession,
-} from "./lib/pi-session-seed.js";
+import { DEFAULT_SEED_TOKENS, rotatePiSession, seedPiSession } from "./lib/pi-session-seed.js";
 import { createReplyInstructionsExtension } from "./lib/reply-instructions-extension.js";
 import { resolveModel } from "./lib/resolve-model.js";
 import { buildSeededNote, type SeedCause } from "./lib/seed-note.js";
-import {
-  getStartupContext,
-  loadPrompts,
-  renderCompactionWarning,
-  type SubagentConfig,
-} from "./lib/startup.js";
+import { getStartupContext, loadPrompts, type SubagentConfig } from "./lib/startup.js";
 import { createSubagentExtension, type SubagentDefinition } from "./lib/subagents.js";
 import type {
   HandlerMeta,
@@ -81,12 +69,6 @@ type PiSession = {
    * note (which fires only on the first turn of a freshly created agent session).
    */
   rotationNotePending?: boolean;
-  /**
-   * The cut point pinned at warn time (the first-kept turn the mind was told would
-   * survive verbatim). Honored at rotation so the promise in the warning holds even
-   * though the transcript grows after the warning. Null until a warning fires.
-   */
-  rotationCut?: PiSeedCut | null;
   /**
    * Back-to-back rotations that did NOT bring context under the threshold (reset by
    * any healthy turn). Guards against a runaway loop when the tail alone can't fit —
@@ -107,7 +89,6 @@ export function createMind(options: {
   sessionsDir: string;
   model?: string;
   thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
-  compactionMessage?: string;
   maxContextTokens?: number;
   /** Estimated-token budget for seeding a fresh persistent session. 0 disables. Default 30000. */
   seedTokens?: number;
@@ -119,8 +100,6 @@ export function createMind(options: {
 } {
   const sessions = new Map<string, PiSession>();
   const prompts = loadPrompts();
-  const compactionMessage = () =>
-    options.compactionMessage ?? renderCompactionWarning(prompts.compaction_warning);
   const compactionInstructions = prompts.compaction_instructions;
   const maxContextTokens = options.maxContextTokens;
   const seedTokens = options.seedTokens ?? DEFAULT_SEED_TOKENS;
@@ -387,62 +366,26 @@ export function createMind(options: {
 
     log("mind", `session "${session.name}": ${isEphemeral ? "ephemeral" : "persistent"}`);
 
-    // Compaction state machine (rotation, not SDK /compact):
-    // 1. threshold (onContextTokens) or native PreCompact -> warnAndPinRotation:
-    //    pin the cut from the live transcript, interpolate it into the ${cutoff}
-    //    warning, send it as the wrap-up prompt, set compactionTriggered
-    // 2. onTurnEnd (after warning turn): compactionTriggered -> compactOnNextTurnEnd
-    // 3. onTurnEnd (after mind's wrap-up turn): compactOnNextTurnEnd -> rotateInPlace
-    //    (or, past the runaway cap, the native compact() backstop)
+    // Compaction is rotation (not SDK /compact), and it's silent: crossing the
+    // threshold (onContextTokens) or a native PreCompact just sets rotatePending; the
+    // session rotates in place at the end of the turn that crossed it — no warning, no
+    // wrap-up turn. The auto summarizer's turn summaries are the record of collapsed
+    // turns, and the one-line rotation note marks the boundary on the next turn. Past
+    // the runaway cap, onTurnEnd defers to the native compact() backstop instead.
     let compactBlocked = false;
     let manualCompactPending = false;
-    let compactionTriggered = false;
-    let compactOnNextTurnEnd = false;
+    let rotatePending = false;
     let compactionInProgress = false;
 
     function resetCompactionState() {
-      compactionTriggered = false;
-      compactOnNextTurnEnd = false;
+      rotatePending = false;
       compactionInProgress = false;
     }
 
-    /**
-     * Warn the mind that the session will rotate at the context limit and pin the cut
-     * point it's told about. Computes which whole turns fit in `seedTokens` from the
-     * live transcript, pins the first-kept turn (so rotation honors the same boundary
-     * even as the transcript grows), interpolates its local time into the `${cutoff}`
-     * placeholder, and sends the warning as the wrap-up prompt. Shared by the
-     * threshold and native-PreCompact paths.
-     */
-    function warnAndPinRotation() {
-      let cutoffLabel = "the cutoff";
-      session.rotationCut = null;
-      const sourcePath = session.agentSession?.sessionManager.getSessionFile();
-      if (sourcePath) {
-        try {
-          const cut = computePiSeedCut(readFileSync(sourcePath, "utf-8"), seedTokens);
-          if (cut) {
-            session.rotationCut = cut;
-            if (cut.boundaryTimestamp) {
-              const d = new Date(cut.boundaryTimestamp);
-              if (!Number.isNaN(d.getTime())) cutoffLabel = compactTimestamp(d);
-            }
-          }
-        } catch (err) {
-          log("mind", `session "${session.name}": failed to pin rotation cut:`, err);
-        }
-      }
-      // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${cutoff} prompt placeholder
-      const warning = compactionMessage().replaceAll("${cutoff}", cutoffLabel);
-      compactionTriggered = true;
-      session.messageIds.push(undefined);
-      session.agentSession?.prompt(warning, { streamingBehavior: "followUp" });
-    }
-
     /**
      * Rotate the session in place onto a synthetic session holding the verbatim recent
-     * tail (from the pinned cut), then switch the running SessionManager to it. Returns
-     * false if rotation can't proceed (session not ready, or the file build failed) so
+     * tail (the seedTokens-budget tail), then switch the running SessionManager to it.
+     * Returns false if rotation can't proceed (session not ready, or the file build failed) so
      * the caller can fall back to a fresh session. The setSessionFile + state.messages
      * re-sync is the load-bearing adoption step: the agent caches context in
      * state.messages, so swapping the file alone wouldn't change what the mind sees
@@ -457,10 +400,8 @@ export function createMind(options: {
         sessionsDir: options.sessionsDir,
         name: session.name,
         sourcePath,
-        cut: session.rotationCut ?? null,
         seedTokens,
       });
-      session.rotationCut = null;
       if (!newPath) return false;
       as.sessionManager.setSessionFile(newPath);
       as.state.messages = as.sessionManager.buildSessionContext().messages;
@@ -487,7 +428,6 @@ export function createMind(options: {
         as.sessionManager.newSession();
         as.state.messages = [];
       }
-      session.rotationCut = null;
       session.consecutiveRotations = 0;
       compactBlocked = false;
       log("mind", `session "${session.name}": rotation failed, starting fresh`);
@@ -520,23 +460,22 @@ export function createMind(options: {
         }
 
         // The SDK's native auto-compaction wants to fire. Converge it onto rotation:
-        // the first pass warns + pins + marks for rotation (unless the threshold path
-        // already did, or the runaway cap is hit) and blocks the native compaction;
-        // the second pass allows native compaction as the emergency backstop (only
-        // reachable if rotation never brought context under control).
+        // the first pass marks the session for rotation at turn end (unless the
+        // threshold path already did, or the runaway cap is hit) and blocks the native
+        // compaction; the second pass allows native compaction as the emergency
+        // backstop (only reachable if rotation never brought context under control).
         if (!compactBlocked) {
           compactBlocked = true;
           if (
-            !compactionTriggered &&
-            !compactOnNextTurnEnd &&
+            !rotatePending &&
             !compactionInProgress &&
             (session.consecutiveRotations ?? 0) < MAX_CONSECUTIVE_ROTATIONS
           ) {
             log(
               "mind",
-              `session "${session.name}": native compaction — warning + pinning rotation`,
+              `session "${session.name}": native compaction — rotation pending at turn end`,
             );
-            warnAndPinRotation();
+            rotatePending = true;
           } else {
             log("mind", `session "${session.name}": blocking native compaction (rotation pending)`);
           }
@@ -595,8 +534,7 @@ export function createMind(options: {
           if (
             maxContextTokens &&
             tokens >= maxContextTokens &&
-            !compactionTriggered &&
-            !compactOnNextTurnEnd &&
+            !rotatePending &&
             !compactionInProgress &&
             (session.consecutiveRotations ?? 0) < MAX_CONSECUTIVE_ROTATIONS
           ) {
@@ -609,18 +547,18 @@ export function createMind(options: {
             }
             log(
               "mind",
-              `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — warning + pinning rotation`,
+              `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — rotation pending at turn end`,
             );
-            warnAndPinRotation();
+            rotatePending = true;
           }
         },
         onTurnEnd: maxContextTokens
           ? () => {
               try {
-                // The wrap-up turn (after the warning) is done — rotate the session in
-                // place onto the verbatim tail, honoring the pinned cut.
-                if (compactOnNextTurnEnd) {
-                  compactOnNextTurnEnd = false;
+                // The turn that crossed the threshold is done — rotate the session in
+                // place onto the verbatim recent tail. Silent: no warning, no wrap-up.
+                if (rotatePending) {
+                  rotatePending = false;
                   if ((session.consecutiveRotations ?? 0) >= MAX_CONSECUTIVE_ROTATIONS) {
                     // Runaway guard: rotation isn't relieving context (system prompt too
                     // large to fit the tail under the threshold) — defer to the SDK.
@@ -632,11 +570,6 @@ export function createMind(options: {
                   }
                   return;
                 }
-                if (compactionTriggered) {
-                  compactionTriggered = false;
-                  compactOnNextTurnEnd = true;
-                  return;
-                }
                 // A healthy turn (context under the threshold) — the rotation streak,
                 // if any, is over, so re-arm the self-rotation cap.
                 session.consecutiveRotations = 0;

package/templates/pi/src/lib/mechanics-doc.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/** This template's mechanics doc, relative to the mind's home/. */
+export const MECHANICS_DOC = "MINDS.md";
+
+/**
+ * Append the mechanics doc to the system prompt.
+ *
+ * pi-coding-agent only auto-loads a project context file named AGENTS.md or
+ * CLAUDE.md (see @earendil-works/pi-coding-agent `core/resource-loader.js`), so
+ * MINDS.md never reaches the model on its own — pi minds would run with no
+ * mechanics doc at all. The claude and codex templates get theirs for free
+ * because their runtimes read CLAUDE.md / AGENTS.md natively; pi has to be
+ * handed its doc by hand.
+ *
+ * Kept in the system prompt (rather than injected as a context file) so it is
+ * counted once, under `systemPrompt`, by the context breakdown.
+ */
+export function withMechanicsDoc(systemPrompt: string, homeDir: string): string {
+  const path = resolve(homeDir, MECHANICS_DOC);
+  let doc: string;
+  try {
+    doc = readFileSync(path, "utf-8").trim();
+  } catch (err: any) {
+    if (err?.code !== "ENOENT") throw err;
+    return systemPrompt;
+  }
+  return doc ? `${systemPrompt}\n\n---\n\n${doc}` : systemPrompt;
+}

package/templates/pi/src/server.ts

@@ -2,6 +2,7 @@ import { resolve } from "node:path";
 import { createMind } from "./agent.js";
 import { createFileHandlerResolver } from "./lib/file-handler.js";
 import { log, setLevel } from "./lib/logger.js";
+import { withMechanicsDoc } from "./lib/mechanics-doc.js";
 import { createRouter } from "./lib/router.js";
 import {
   loadConfig,
@@ -18,7 +19,8 @@ if (config.logLevel) setLevel(config.logLevel);
 if (config.model) log("server", `using model: ${config.model}`);
 if (config.thinkingLevel) log("server", `thinking level: ${config.thinkingLevel}`);
 
-const systemPrompt = loadSystemPrompt(config);
+// pi does not auto-load MINDS.md, so the mechanics doc is appended by hand.
+const systemPrompt = withMechanicsDoc(loadSystemPrompt(config), resolve("home"));
 const pkg = loadPackageInfo();
 
 const mindDir = resolve(".");
@@ -29,7 +31,6 @@ const mind = createMind({
   sessionsDir: resolve(".mind/pi-sessions"),
   model: config.model,
   thinkingLevel: config.thinkingLevel,
-  compactionMessage: config.compactionMessage,
   maxContextTokens: config.compaction?.maxContextTokens,
   seedTokens: config.continuity?.seedTokens,
   subagents: config.subagents,

package/templates/pi/volute-template.json

@@ -2,5 +2,5 @@
   "rename": {
     "gitignore": ".gitignore"
   },
-  "substitute": ["package.json", ".init/SOUL.md", "home/.config/routes.json"]
+  "substitute": ["package.json", ".init/SOUL.md", ".init/.config/routes.json"]
 }