volute 0.52.0 → 0.54.0

package/templates/claude/src/agent.ts

@@ -13,7 +13,8 @@ import {
   readSdkInstructions,
   readSkillDescriptions,
 } from "./lib/context-breakdown.js";
-import { daemonEmit } from "./lib/daemon-client.js";
+import { daemonEmit, daemonNotice } from "./lib/daemon-client.js";
+import { compactTimestamp } from "./lib/format-prefix.js";
 import { runHooks } from "./lib/hook-loader.js";
 import { createAutoCommitHook } from "./lib/hooks/auto-commit.js";
 import { createIdentityReloadHook } from "./lib/hooks/identity-reload.js";
@@ -22,15 +23,24 @@ import { createPreCompactHook } from "./lib/hooks/pre-compact.js";
 import { createReplyInstructionsHook } from "./lib/hooks/reply-instructions.js";
 import { log } from "./lib/logger.js";
 import { createMessageChannel } from "./lib/message-channel.js";
+import { relockstepMessageIds } from "./lib/recover.js";
+import { buildSeededNote, type SeedCause } from "./lib/seed-note.js";
 import {
   isSessionReapable,
   reapSessionQuery,
   reapSessionsForShutdown,
 } from "./lib/session-reaper.js";
+import {
+  computeSeedCut,
+  DEFAULT_SEED_TOKENS,
+  rotateSession,
+  type SeedCut,
+  seedSession,
+} from "./lib/session-seed.js";
 import { createSessionStore } from "./lib/session-store.js";
 import type { EffortLevel, ThinkingConfig } from "./lib/startup.js";
-import { loadPrompts, type SubagentConfig } from "./lib/startup.js";
-import { consumeStream } from "./lib/stream-consumer.js";
+import { loadPrompts, renderCompactionWarning, type SubagentConfig } from "./lib/startup.js";
+import { consumeStream, type MessageIdEntry } from "./lib/stream-consumer.js";
 import type {
   HandlerMeta,
   HandlerResolver,
@@ -45,8 +55,9 @@ type Session = {
   name: string;
   channel: ReturnType<typeof createMessageChannel>;
   listeners: Set<Listener>;
-  messageIds: (string | undefined)[];
+  messageIds: MessageIdEntry[];
   currentMessageId?: string;
+  currentSeq?: number;
   currentQuery?: ReturnType<typeof query>;
   messageChannels: Map<string, { channel: string; sender?: string }>;
   replyInstructionsFired: boolean;
@@ -56,8 +67,47 @@ type Session = {
   contextTokens: number;
   /** Last inbound message or completed turn — drives idle reaping. */
   lastActivityAt: number;
+  /**
+   * True when this session was seeded from the previous session's transcript.
+   * Injects the honest-boundary note on each prompt until a turn resolves (see
+   * the pre-prompt hook and onTurnEnd), so an interrupted first turn re-offers it.
+   */
+  seeded: boolean;
+  /** When the seeded-from session was archived (epoch ms), for the gap note; null if unknown. */
+  seededArchivedAt: number | 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 transcript grows after the warning. Null until a warning fires.
+   */
+  rotationCut: SeedCut | 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 —
+   * e.g. a system prompt (large MEMORY.md) that already fills most of the window, which
+   * rotation can't trim. Past the cap we stop rotating and defer to native compaction.
+   */
+  consecutiveRotations: number;
+  /**
+   * Rotation state machine (undefined = idle). The warning is pushed and the mind
+   * takes a wrap-up turn — with FULL context of the turns it's summarizing — before
+   * the session rotates:
+   *   - "warned": a turn was mid-flight when we warned; it must finish before the
+   *     wrap-up turn (which consumes the warning) runs.
+   *   - "rotateAfterTurn": the wrap-up turn is the current/next turn; rotate when it ends.
+   * Lives on the session (not a map) so it can't leak into a resumed session if the
+   * stream dies mid-flight — a fresh session starts idle.
+   */
+  rotationPhase?: RotationPhase;
 };
 
+type RotationPhase = "warned" | "rotateAfterTurn";
+
+/** Stop self-rotating after this many back-to-back rotations that didn't reduce context. */
+const MAX_CONSECUTIVE_ROTATIONS = 3;
+
 export function createMind(options: {
   systemPrompt: string;
   cwd: string;
@@ -72,6 +122,8 @@ export function createMind(options: {
   onIdentityReload?: () => Promise<void>;
   /** Idle minutes before a session's SDK subprocess is reaped. 0 disables. Default 30. */
   sessionIdleMinutes?: number;
+  /** Estimated-token budget for seeding a fresh persistent session. 0 disables. Default 30000. */
+  seedTokens?: number;
 }): {
   resolve: HandlerResolver;
   waitForCommits: () => Promise<void>;
@@ -88,20 +140,15 @@ export function createMind(options: {
 
   const sessions = new Map<string, Session>();
   const prompts = loadPrompts();
-  const today = new Date().toLocaleDateString("en-CA");
-  const compactionMessage =
-    // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${date} in prompt template
-    options.compactionMessage ?? prompts.compaction_warning.replace("${date}", today);
-  const compactionInstructions = prompts.compaction_instructions;
+  const compactionMessage = () =>
+    options.compactionMessage ?? renderCompactionWarning(prompts.compaction_warning);
   const maxContextTokens = options.maxContextTokens;
+  const seedTokens = options.seedTokens ?? DEFAULT_SEED_TOKENS;
 
   if (maxContextTokens) {
     log("mind", `compaction threshold: ${maxContextTokens} tokens`);
   }
 
-  // Per-session compaction state
-  const compactionTriggered = new Map<string, boolean>();
-
   // --- Subagents (config-driven) ---
 
   type SDKAgent = {
@@ -242,11 +289,43 @@ export function createMind(options: {
           }
         }
         // Only UserPromptSubmit hooks can inject additionalContext into the conversation
-        if (event !== "pre-prompt" || !result.additionalContext) return {};
+        if (event !== "pre-prompt") return {};
+        let additionalContext = result.additionalContext;
+        // On a seeded session, prepend the honest-boundary note. Deliberately NOT
+        // cleared here: this hook only hands the note to the SDK at *dispatch*, and
+        // the SDK cancels UserPromptSubmit hooks when an interrupt arrives (a
+        // `hook_cancelled` transcript entry). That's most likely on the seeded first
+        // turn post-wake, when queued inbound messages flood in — exactly when we'd
+        // lose the note. Clearing on a mere injection attempt could drop it forever
+        // and silently. So the flag is cleared only when a turn actually resolves
+        // (onTurnEnd); an interrupted turn re-offers the note next prompt. Worst case
+        // it fires twice (cosmetic) instead of zero times (unrecoverable, invisible).
+        if (session.seeded) {
+          const note = buildSeededNote({
+            cause: session.seededCause,
+            archivedAtMs: session.seededArchivedAt,
+          });
+          additionalContext = additionalContext ? `${note}\n\n${additionalContext}` : note;
+          // Also surface the note as its own context event (matching codex/pi) so it
+          // isn't delivered only in the same low-salience container as routine
+          // per-prompt hooks. Once per injection attempt; a duplicate on re-offer is fine.
+          const channel = session.currentMessageId
+            ? session.messageChannels.get(session.currentMessageId)?.channel
+            : undefined;
+          daemonEmit({
+            type: "context",
+            content: note,
+            metadata: { source: "seeded-session" },
+            session: session.name,
+            channel,
+            messageId: session.currentMessageId,
+          }).catch((err) => log("mind", "seeded-session context emit failed:", err));
+        }
+        if (!additionalContext) return {};
         return {
           hookSpecificOutput: {
             hookEventName: "UserPromptSubmit" as const,
-            additionalContext: result.additionalContext,
+            additionalContext,
           },
         };
       } catch (err) {
@@ -317,17 +396,61 @@ export function createMind(options: {
       let currentSessionId = savedSessionId;
       let streamAbort = new AbortController();
 
-      const preCompact = createPreCompactHook(() => {
-        session.messageIds.push(undefined);
-        session.channel.push({
+      /**
+       * 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 time into the
+       * `${cutoff}` placeholder, enters the rotation state machine, and pushes the
+       * warning as the wrap-up prompt. Shared by the threshold and PreCompact paths.
+       *
+       * Crucially it does NOT abort here: the mind takes a wrap-up turn (reading the
+       * pinned cutoff and authoring `volute mind history` summaries with full context
+       * of the turns being collapsed) before rotation. The entry phase depends on
+       * whether a turn is mid-flight: if one is (threshold path fires on an assistant
+       * message), it must finish before the queued warning runs, so we start "warned";
+       * if we're between turns (PreCompact fired at a boundary), the warning IS the
+       * next turn, so we start "rotateAfterTurn".
+       */
+      function warnAndPinRotation() {
+        let cutoffLabel = "the cutoff";
+        session.rotationCut = null;
+        if (currentSessionId) {
+          try {
+            const path = findClaudeSessionFile(options.cwd, currentSessionId);
+            const cut = path ? computeSeedCut(readFileSync(path, "utf-8"), seedTokens) : null;
+            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);
+        session.rotationPhase =
+          session.currentMessageId !== undefined ? "warned" : "rotateAfterTurn";
+        const seq = session.channel.push({
           type: "user",
           session_id: "",
-          message: {
-            role: "user",
-            content: [{ type: "text", text: compactionMessage }],
-          },
+          message: { role: "user", content: [{ type: "text", text: warning }] },
           parent_tool_use_id: null,
         });
+        session.messageIds.push({ id: undefined, seq });
+      }
+
+      // PreCompact backstop: first fire warns + pins + enters the rotation machine
+      // (unless already warned, or the rotation cap is hit) and blocks; second fire
+      // allows the SDK's native compaction — the emergency backstop when rotation never
+      // intervened (a hung turn, or a system prompt too large for rotation to relieve).
+      const preCompact = createPreCompactHook(() => {
+        if (!session.rotationPhase && session.consecutiveRotations < MAX_CONSECUTIVE_ROTATIONS) {
+          warnAndPinRotation();
+        }
       });
 
       const callbacks = {
@@ -336,20 +459,31 @@ export function createMind(options: {
           if (!session.name.startsWith("new-")) sessionStore.save(session.name, id);
         },
         broadcast: (event: VoluteEvent) => broadcastToSession(session, event),
+        // Identity-based ack — stream-consumer.ts calls this once per message the
+        // just-finished turn covers (its own driving message, plus any folded in
+        // mid-run) so none of them strand in the channel's in-flight set (#764).
+        ack: (seq: number) => session.channel.ack(seq),
         onTurnEnd: async () => {
-          // This turn's message is fully processed — drop it from the channel's
-          // in-flight set so a later compaction abort won't re-feed it.
-          session.channel.ack();
           session.lastActivityAt = Date.now();
+          // A turn resolved — the seeded note's injection had its chance to land
+          // (the pre-prompt hook ran and wasn't cancelled by an interrupt), so stop
+          // re-offering it. This is the honest place to clear: a completed turn is
+          // the closest-to-arrival signal available without reading the transcript back.
+          session.seeded = false;
           await autoCommit.flushFileChanges();
-          const wasCompacting = compactionTriggered.get(session.name);
-          compactionTriggered.set(session.name, false);
-          if (wasCompacting) {
-            // Mind's turn after compaction warning is done — abort the stream to run /compact
-            log("mind", `session "${session.name}": aborting stream for compaction`);
+          if (session.rotationPhase === "warned") {
+            // The mid-flight turn finished; the queued warning runs next as the wrap-up
+            // turn. Advance — do NOT abort yet, so the mind summarizes with full context.
+            session.rotationPhase = "rotateAfterTurn";
+          } else if (session.rotationPhase === "rotateAfterTurn") {
+            // The wrap-up turn is done (summaries authored) — abort to rotate in place.
+            log("mind", `session "${session.name}": wrap-up turn done — aborting to rotate`);
             streamAbort.abort(new CompactionAbort());
-          } else if (identityReload.shouldRequestReload()) {
-            options.onIdentityReload?.();
+          } else {
+            // A healthy turn (context under the threshold) — the rotation streak, if
+            // any, is over, so re-arm the self-rotation cap.
+            session.consecutiveRotations = 0;
+            if (identityReload.shouldRequestReload()) options.onIdentityReload?.();
           }
         },
         onContextTokens: (tokens: number) => {
@@ -357,64 +491,18 @@ export function createMind(options: {
           if (
             maxContextTokens &&
             tokens >= maxContextTokens &&
-            !compactionTriggered.get(session.name)
+            !session.rotationPhase &&
+            session.consecutiveRotations < MAX_CONSECUTIVE_ROTATIONS
           ) {
-            compactionTriggered.set(session.name, true);
             log(
               "mind",
-              `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — triggering compaction`,
+              `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — warning + pinning rotation`,
             );
-            session.messageIds.push(undefined);
-            session.channel.push({
-              type: "user",
-              session_id: "",
-              message: {
-                role: "user",
-                content: [{ type: "text", text: compactionMessage }],
-              },
-              parent_tool_use_id: null,
-            });
+            warnAndPinRotation();
           }
         },
       };
 
-      async function runCompact(sessionId: string) {
-        log("mind", `session "${session.name}": compacting with custom instructions`);
-        const compactAbort = new AbortController();
-        // Forward mind-level abort to the compact query
-        options.abortController.signal.addEventListener("abort", () => compactAbort.abort(), {
-          once: true,
-        });
-        const compactQuery = query({
-          prompt: `/compact ${compactionInstructions}`,
-          options: {
-            systemPrompt: options.systemPrompt,
-            permissionMode: "bypassPermissions",
-            allowDangerouslySkipPermissions: true,
-            settingSources: ["project", "user"],
-            skills: installedSkills(),
-            env: sdkEnv,
-            cwd: options.cwd,
-            abortController: compactAbort,
-            model: options.model,
-            resume: sessionId,
-          },
-        });
-        let gotResult = false;
-        for await (const msg of compactQuery) {
-          if ("session_id" in msg && msg.session_id) {
-            currentSessionId = msg.session_id as string;
-            if (!session.name.startsWith("new-")) {
-              sessionStore.save(session.name, currentSessionId);
-            }
-          }
-          if (msg.type === "result") gotResult = true;
-        }
-        if (!gotResult)
-          log("mind", `session "${session.name}": compaction stream ended without result`);
-        log("mind", `session "${session.name}": compaction complete`);
-      }
-
       /** Emit done to both local listeners and the daemon (best-effort with retries). */
       function emitDone() {
         broadcastToSession(session, { type: "done" });
@@ -457,30 +545,77 @@ export function createMind(options: {
               streamAbort.signal.reason instanceof CompactionAbort &&
               currentSessionId
             ) {
-              // Stream was aborted for compaction — run /compact, then loop to resume
-              try {
-                await runCompact(currentSessionId);
-              } catch (compactErr) {
-                log(
-                  "mind",
-                  `session "${session.name}": custom compaction failed, starting fresh:`,
-                  compactErr,
+              // Stream was aborted to rotate: replace the session with a synthetic one
+              // holding the verbatim recent tail (from the pinned cut), then resume it.
+              const rotatedId = rotateSession({
+                cwd: options.cwd,
+                sessionsDir: options.sessionsDir,
+                name: session.name,
+                oldSessionId: currentSessionId,
+                cut: session.rotationCut,
+                seedTokens,
+              });
+              session.rotationCut = null;
+              session.rotationPhase = undefined; // state machine consumed
+              if (!rotatedId) {
+                // Rotation couldn't proceed — fall back to a fresh session (no seed).
+                // Unlike a successful rotation (boundary note, verbatim tail, archived
+                // transcript), this genuinely loses the live context — say so (#367).
+                log("mind", `session "${session.name}": rotation failed, starting fresh`);
+                daemonNotice({
+                  kind: "context_lost",
+                  thread: session.name,
+                  message:
+                    "Session rotation failed at the context limit and this thread was " +
+                    "reset — conversation context before this point was lost. Your turn " +
+                    "summaries survive in `volute mind history`; check your journal for " +
+                    "where you left off.",
+                }).catch((err) =>
+                  log("mind", `session "${session.name}": failed to record notice:`, err),
                 );
                 sessionStore.delete(session.name);
                 currentSessionId = undefined;
+                session.seeded = false;
                 streamAbort = new AbortController();
                 session.channel = createMessageChannel();
                 break;
               }
+              // Point the live pointer at the rotated session and arm the boundary
+              // note (rotation cause — no gap). Ephemeral `new-*` keep no pointer.
+              if (!session.name.startsWith("new-")) sessionStore.save(session.name, rotatedId);
+              currentSessionId = rotatedId;
+              session.seeded = true;
+              session.seededCause = "rotation";
+              session.seededArchivedAt = null;
+              // Count this rotation; a healthy turn resets it. If back-to-back rotations
+              // don't reduce context (system prompt too large to fit the tail under the
+              // threshold), the cap stops the loop and defers to native compaction.
+              session.consecutiveRotations++;
+              if (session.consecutiveRotations >= MAX_CONSECUTIVE_ROTATIONS) {
+                log(
+                  "mind",
+                  `session "${session.name}": ${session.consecutiveRotations} rotations without relief — deferring further compaction to the SDK (system prompt likely too large)`,
+                );
+              }
+              // Re-arm the PreCompact backstop so a future auto-compact blocks + rotates
+              // again rather than falling straight through to native compaction.
+              preCompact.reset();
               streamAbort = new AbortController();
-              // Recover input the aborted stream had already pulled but not
-              // finished (the compaction wrap-up plus any messages that arrived
-              // mid-turn) alongside anything queued during /compact, so nothing
-              // is dropped when the killed subprocess takes its buffer with it.
+              // Recover input the aborted stream had already pulled but not finished
+              // (the wrap-up warning plus anything that arrived mid-turn) so nothing is
+              // dropped when the killed subprocess takes its buffer with it.
               const pending = session.channel.recover();
+              const oldMessageIds = session.messageIds;
               session.channel = createMessageChannel();
-              for (const msg of pending) session.channel.push(msg);
-              continue; // restart the stream loop
+              // Starts from [] — nothing can race into this fresh channel/messageIds
+              // before the next line runs (single-threaded, no await in between).
+              session.messageIds = relockstepMessageIds(
+                pending,
+                oldMessageIds,
+                session.channel.push,
+                [],
+              );
+              continue; // restart the stream loop on the rotated session
             }
             throw err; // rethrow non-compaction errors
           }
@@ -489,8 +624,21 @@ export function createMind(options: {
         session.messageChannels.clear();
         if (currentSessionId) {
           log("mind", `session "${session.name}": resume failed, starting fresh:`, err);
+          daemonNotice({
+            kind: "context_lost",
+            thread: session.name,
+            message:
+              "Your session couldn't be resumed after an error, so you're starting fresh. " +
+              "Recent context may be in memory/journal/.",
+          }).catch((e) => log("mind", `session "${session.name}": failed to record notice:`, e));
           sessionStore.delete(session.name);
           currentSessionId = undefined;
+          // We fell back to a truly empty session — don't tell the mind its
+          // conversation continued when the seeded transcript failed to resume,
+          // and don't let a half-entered rotation leak into the fresh session.
+          session.seeded = false;
+          session.rotationPhase = undefined;
+          session.rotationCut = null;
           streamAbort = new AbortController();
           session.channel = createMessageChannel();
           try {
@@ -531,6 +679,11 @@ export function createMind(options: {
       eventNoteFired: false,
       contextTokens: 0,
       lastActivityAt: Date.now(),
+      seeded: false,
+      seededArchivedAt: null,
+      seededCause: "restored",
+      rotationCut: null,
+      consecutiveRotations: 0,
     };
     sessions.set(name, session);
 
@@ -542,9 +695,41 @@ export function createMind(options: {
       log("mind", `session "${name}": stored session ${savedSessionId} not found, starting fresh`);
       sessionStore.delete(name);
       savedSessionId = undefined;
+      // Worded so it stays true whether or not transcript seeding (below) partially
+      // restores context: the live session is gone either way.
+      daemonNotice({
+        kind: "context_lost",
+        thread: name,
+        message:
+          "Your previous session couldn't be restored (session file missing), so this " +
+          "thread was reset. Recent context may be in memory/journal/.",
+      }).catch((err) => log("mind", `session "${name}": failed to record notice:`, err));
     }
     if (savedSessionId) {
       log("mind", `session "${name}": resuming ${savedSessionId}`);
+    } else if (!isEphemeral) {
+      // Fresh persistent session — seed it from the previous session's archived
+      // transcript so the mind experiences the conversation continuing rather
+      // than waking into an empty context. Ephemeral `new-*` sessions never seed.
+      const seeded = seedSession({
+        cwd: options.cwd,
+        sessionsDir: options.sessionsDir,
+        name,
+        seedTokens: options.seedTokens ?? DEFAULT_SEED_TOKENS,
+      });
+      if (seeded) {
+        sessionStore.save(name, seeded.sessionId);
+        savedSessionId = seeded.sessionId;
+        session.seeded = true;
+        session.seededArchivedAt = seeded.archivedAt;
+        session.seededCause = "restored";
+        log(
+          "mind",
+          `session "${name}": seeded from previous transcript, resuming ${seeded.sessionId}`,
+        );
+      } else {
+        log("mind", `session "${name}": starting fresh`);
+      }
     } else {
       log("mind", `session "${name}": starting fresh`);
     }
@@ -565,7 +750,6 @@ export function createMind(options: {
     // Delete first so a racing inbound message spins up a fresh resumed session
     // instead of reusing the one we're tearing down.
     sessions.delete(session.name);
-    compactionTriggered.delete(session.name);
     // End the input iterable so the stream consumer unwinds (its finally block
     // also deletes from the map, now a no-op), then await the SDK's graceful
     // shutdown via query.return() — unlike the fire-and-forget close(), this
@@ -576,11 +760,16 @@ export function createMind(options: {
       log("mind", `session "${session.name}": error reaping SDK subprocess:`, err),
     );
     // Nothing should have raced in (isSessionReapable checked isEmpty), but if it
-    // did, re-dispatch into a fresh session so no input is dropped.
+    // did, re-dispatch into a fresh session so no input is dropped. Same marker
+    // treatment as the rotation path (#764) — see relockstepMessageIds above.
+    // getOrCreateSession() can return a session an inbound message already raced
+    // into during the reapSessionQuery() await above (it pushed its own entry into
+    // fresh.messageIds via the normal handler path) — relockstepMessageIds appends
+    // onto fresh.messageIds rather than replacing it, so that entry survives.
     const pending = session.channel.recover();
     if (pending.length > 0) {
       const fresh = getOrCreateSession(session.name);
-      for (const msg of pending) fresh.channel.push(msg);
+      relockstepMessageIds(pending, session.messageIds, fresh.channel.push, fresh.messageIds);
     }
   }
 
@@ -605,7 +794,12 @@ export function createMind(options: {
     const reaper = setInterval(() => {
       const now = Date.now();
       const stale = [...sessions.values()].filter((s) =>
-        isSessionReapable(s, now, idleTimeoutMs, (name) => !!compactionTriggered.get(name)),
+        isSessionReapable(
+          s,
+          now,
+          idleTimeoutMs,
+          (name) => sessions.get(name)?.rotationPhase !== undefined,
+        ),
       );
       // Reaps run independently; each awaits its own subprocess exit internally.
       for (const session of stale) {
@@ -663,13 +857,13 @@ export function createMind(options: {
 
         // Push message into SDK
         session.lastActivityAt = Date.now();
-        session.messageIds.push(meta.messageId);
-        session.channel.push({
+        const seq = session.channel.push({
           type: "user",
           session_id: "",
           message: { role: "user", content: toSDKContent(content) },
           parent_tool_use_id: null,
         });
+        session.messageIds.push({ id: meta.messageId, seq });
 
         return () => {
           if (filteredListener) session.listeners.delete(filteredListener);

package/templates/claude/src/lib/hooks/pre-compact.ts

@@ -1,21 +1,41 @@
 import type { HookCallback, PreCompactHookInput } from "@anthropic-ai/claude-agent-sdk";
 import { log } from "../logger.js";
 
+/**
+ * PreCompact hook: the backstop for SDK-initiated auto-compaction.
+ *
+ * The primary compaction path is volute's own token threshold, which rotates the
+ * session in place. This hook covers the case where the SDK decides to auto-compact
+ * before (or instead of) that threshold firing:
+ *
+ *   - First fire: run `onCompact` (warn the mind + pin the rotation boundary, same
+ *     as the threshold path) and BLOCK the SDK's native compaction. The wrap-up
+ *     turn then ends and the session rotates.
+ *   - Second fire: allow the SDK's native compaction as an emergency backstop —
+ *     only reachable if rotation never happened (a hung turn, or rotation failed).
+ *
+ * `reset()` re-arms the first-fire behavior; the agent calls it after a successful
+ * rotation so a later auto-compact blocks + rotates again instead of falling
+ * straight through to native compaction.
+ *
+ * Manual `/compact` with custom instructions is always allowed through untouched.
+ */
 export function createPreCompactHook(onCompact: () => void) {
   let compactBlocked = false;
 
   const hook: HookCallback = async (input) => {
     const { trigger, custom_instructions } = input as PreCompactHookInput;
 
-    // Our custom compaction (via /compact with instructions) — allow through without the two-pass block
+    // Manual compaction with custom instructions — allow through without the block.
     if (trigger === "manual" && custom_instructions) {
       log("mind", "allowing manual compaction with custom instructions");
       return {};
     }
 
-    // Auto-compaction: two-pass block (first pass warns mind, second pass allows)
+    // Auto-compaction: first pass warns + marks for rotation and blocks; second
+    // pass allows the native compaction as the emergency backstop.
     if (!compactBlocked) {
-      log("mind", "blocking compaction — asking mind to update daily log first");
+      log("mind", "blocking auto-compaction — warning mind + marking session for rotation");
       try {
         onCompact();
         compactBlocked = true;
@@ -26,9 +46,14 @@ export function createPreCompactHook(onCompact: () => void) {
       return { decision: "block" };
     }
     compactBlocked = false;
-    log("mind", "allowing compaction");
+    log("mind", "allowing native compaction (rotation did not intervene)");
     return {};
   };
 
-  return { hook };
+  /** Re-arm the first-fire block/rotate behavior (called after a rotation). */
+  function reset() {
+    compactBlocked = false;
+  }
+
+  return { hook, reset };
 }