volute 0.53.0 → 0.55.0

package/templates/_base/src/lib/startup.ts

@@ -40,7 +40,6 @@ export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
 export type MindConfig = {
   model?: string;
   logLevel?: "error" | "warn" | "info" | "debug";
-  compactionMessage?: string;
   compaction?: { maxContextTokens?: number };
   /** Idle minutes before a session's SDK subprocess is reaped. 0 disables. Default 30. */
   sessionIdleMinutes?: number;
@@ -103,21 +102,6 @@ export function memorySizeLabel(): string {
   return formatTokens(estimateTokens(loadFile(resolve("home/MEMORY.md")).length));
 }
 
-/**
- * Render the compaction warning for sending: substitute ${date} and
- * ${memory_size} with current values. Called per send — the date rolls over
- * and MEMORY.md changes as the mind edits it.
- */
-export function renderCompactionWarning(template: string): string {
-  return (
-    template
-      // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${date} placeholder
-      .replaceAll("${date}", new Date().toLocaleDateString("en-CA"))
-      // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${memory_size} placeholder
-      .replaceAll("${memory_size}", memorySizeLabel())
-  );
-}
-
 function headAtLineBoundary(text: string, maxChars: number): string {
   const cut = text.lastIndexOf("\n", maxChars);
   // Prefer a whole-line cut, but not when the nearest newline is so far back
@@ -251,7 +235,6 @@ export async function getStartupContext(): Promise<string | null> {
 }
 
 export type MindPrompts = {
-  compaction_warning: string;
   compaction_instructions: string;
   reply_instructions: string;
   event_instructions: string;
@@ -264,13 +247,12 @@ export type MindPrompts = {
  * (the copy the Prompt Library UI edits); test/prompts.test.ts fails if they drift.
  */
 export const DEFAULT_PROMPTS: MindPrompts = {
-  compaction_warning:
-    // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${cutoff}/${date}/${memory_size} prompt template
-    "Context limit approaching — this session will rotate shortly. Turns before ${cutoff} will be collapsed to their summaries; turns from ${cutoff} on are kept verbatim in the continued session, so there's no need to re-describe them.\n\nFor the turns that will collapse, make sure they read the way you'd want: `volute mind history --provisional` shows the provisional summaries, and `volute mind history --write --turn <id> --text \"...\"` replaces any with your own account. Also save anything important to your files (memory/journal/${date}.md, or a memory/ file). Provisional summaries are kept if you write nothing — nothing blocks on this.\n\nYour MEMORY.md is currently ${memory_size}. It is loaded into every request, so consolidate rather than append — distill detail into memory/ files and keep MEMORY.md lean (see the memory skill).",
   compaction_instructions:
     "Preserve your sense of who you are, what matters to you, what happened in this conversation, and the threads of thought and connection you'd want to return to.",
+  // Quoted: `${channel}` is `#garden` for a Volute channel, and an unquoted `#` starts a
+  // shell comment, so the target would be stripped before the CLI saw it.
   // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${channel} prompt template
-  reply_instructions: 'To reply to this message, use: volute chat send ${channel} "your message"',
+  reply_instructions: 'To reply to this message, use: volute chat send "${channel}" "your message"',
   event_instructions:
     "This is a system event from your environment — not a message from anyone, and nothing awaits a reply. If it calls for action, use your normal channels. Your closing thoughts on an event turn are kept as a private reflection in your history.",
   channel_invite: `[Channel Invite]
@@ -283,7 +265,7 @@ Further messages will be saved to \${filePath}
 
 To accept, add to .config/routes.json:
   Rule: { "channel": "\${channel}", "session": "\${suggestedSession}" }
-\${batchRecommendation}To respond, use: volute chat send \${channel} "your message"
+\${batchRecommendation}To respond, use: volute chat send "\${channel}" "your message"
 To reject, delete \${filePath}`,
 };
 

package/templates/claude/.init/CLAUDE.md

@@ -11,6 +11,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`.
+
 ## Identity & Sessions
 
 These files shape your starting identity. They're loaded into your system prompt, but they belong to you — edit them as you evolve:

package/templates/claude/package.json

@@ -9,12 +9,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.207",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.217",
     "@anthropic-ai/tokenizer": "^0.0.4",
     "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/claude/src/agent.ts

@@ -14,7 +14,6 @@ import {
   readSkillDescriptions,
 } from "./lib/context-breakdown.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";
@@ -23,23 +22,17 @@ 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 { DEFAULT_SEED_TOKENS, rotateSession, seedSession } from "./lib/session-seed.js";
 import { createSessionStore } from "./lib/session-store.js";
-import type { EffortLevel, ThinkingConfig } from "./lib/startup.js";
-import { loadPrompts, renderCompactionWarning, type SubagentConfig } from "./lib/startup.js";
-import { consumeStream } from "./lib/stream-consumer.js";
+import type { EffortLevel, SubagentConfig, ThinkingConfig } from "./lib/startup.js";
+import { consumeStream, type MessageIdEntry } from "./lib/stream-consumer.js";
 import type {
   HandlerMeta,
   HandlerResolver,
@@ -54,8 +47,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;
@@ -75,12 +69,6 @@ type Session = {
   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 —
@@ -89,20 +77,15 @@ type Session = {
    */
   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.
+   * True when this session crossed the context threshold (or the SDK tried to
+   * auto-compact) and should rotate in place when the current turn ends. Rotation
+   * is deliberately silent: no warning, no wrap-up turn — the auto summarizer's
+   * turn summaries are the record of collapsed turns, and the one-line
+   * ROTATED_SESSION_NOTE marks the boundary on the next turn.
    */
-  rotationPhase?: RotationPhase;
+  rotationPending: boolean;
 };
 
-type RotationPhase = "warned" | "rotateAfterTurn";
-
 /** Stop self-rotating after this many back-to-back rotations that didn't reduce context. */
 const MAX_CONSECUTIVE_ROTATIONS = 3;
 
@@ -114,7 +97,6 @@ export function createMind(options: {
   thinking?: ThinkingConfig;
   effort?: EffortLevel;
   sessionsDir: string;
-  compactionMessage?: string;
   maxContextTokens?: number;
   subagents?: Record<string, SubagentConfig>;
   onIdentityReload?: () => Promise<void>;
@@ -137,9 +119,6 @@ export function createMind(options: {
   ];
 
   const sessions = new Map<string, Session>();
-  const prompts = loadPrompts();
-  const compactionMessage = () =>
-    options.compactionMessage ?? renderCompactionWarning(prompts.compaction_warning);
   const maxContextTokens = options.maxContextTokens;
   const seedTokens = options.seedTokens ?? DEFAULT_SEED_TOKENS;
 
@@ -394,60 +373,19 @@ export function createMind(options: {
       let currentSessionId = savedSessionId;
       let streamAbort = new AbortController();
 
-      /**
-       * 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";
-        session.messageIds.push(undefined);
-        session.channel.push({
-          type: "user",
-          session_id: "",
-          message: { role: "user", content: [{ type: "text", text: warning }] },
-          parent_tool_use_id: null,
-        });
+      /** Mark the session to rotate in place when the current turn ends. */
+      function scheduleRotation() {
+        session.rotationPending = true;
       }
 
-      // 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).
+      // PreCompact backstop: first fire schedules a rotation (unless one is already
+      // pending, 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();
+        if (!session.rotationPending && session.consecutiveRotations < MAX_CONSECUTIVE_ROTATIONS) {
+          log("mind", `session "${session.name}": native compaction — scheduling rotation`);
+          scheduleRotation();
         }
       });
 
@@ -457,10 +395,11 @@ 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
@@ -468,13 +407,12 @@ export function createMind(options: {
           // the closest-to-arrival signal available without reading the transcript back.
           session.seeded = false;
           await autoCommit.flushFileChanges();
-          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`);
+          if (session.rotationPending) {
+            // The turn that crossed the threshold is done — abort to rotate in place.
+            log(
+              "mind",
+              `session "${session.name}": turn ended over context limit — aborting to rotate`,
+            );
             streamAbort.abort(new CompactionAbort());
           } else {
             // A healthy turn (context under the threshold) — the rotation streak, if
@@ -488,14 +426,14 @@ export function createMind(options: {
           if (
             maxContextTokens &&
             tokens >= maxContextTokens &&
-            !session.rotationPhase &&
+            !session.rotationPending &&
             session.consecutiveRotations < MAX_CONSECUTIVE_ROTATIONS
           ) {
             log(
               "mind",
-              `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — warning + pinning rotation`,
+              `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — rotation pending at turn end`,
             );
-            warnAndPinRotation();
+            scheduleRotation();
           }
         },
       };
@@ -543,17 +481,15 @@ export function createMind(options: {
               currentSessionId
             ) {
               // Stream was aborted to rotate: replace the session with a synthetic one
-              // holding the verbatim recent tail (from the pinned cut), then resume it.
+              // holding the verbatim recent tail (the seedTokens-budget tail), 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
+              session.rotationPending = false;
               if (!rotatedId) {
                 // Rotation couldn't proceed — fall back to a fresh session (no seed).
                 // Unlike a successful rotation (boundary note, verbatim tail, archived
@@ -599,11 +535,19 @@ export function createMind(options: {
               preCompact.reset();
               streamAbort = new AbortController();
               // 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.
+              // (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);
+              // 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
@@ -626,8 +570,7 @@ export function createMind(options: {
           // 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;
+          session.rotationPending = false;
           streamAbort = new AbortController();
           session.channel = createMessageChannel();
           try {
@@ -671,8 +614,8 @@ export function createMind(options: {
       seeded: false,
       seededArchivedAt: null,
       seededCause: "restored",
-      rotationCut: null,
       consecutiveRotations: 0,
+      rotationPending: false,
     };
     sessions.set(name, session);
 
@@ -749,11 +692,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);
     }
   }
 
@@ -782,7 +730,7 @@ export function createMind(options: {
           s,
           now,
           idleTimeoutMs,
-          (name) => sessions.get(name)?.rotationPhase !== undefined,
+          (name) => sessions.get(name)?.rotationPending === true,
         ),
       );
       // Reaps run independently; each awaits its own subprocess exit internally.
@@ -841,13 +789,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

@@ -8,9 +8,9 @@ import { log } from "../logger.js";
  * 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.
+ *   - First fire: run `onCompact` (schedule a rotation — mark the session to rotate
+ *     at turn end) and BLOCK the SDK's native compaction, so the session rotates
+ *     instead of being natively compacted.
  *   - Second fire: allow the SDK's native compaction as an emergency backstop —
  *     only reachable if rotation never happened (a hung turn, or rotation failed).
  *
@@ -32,10 +32,10 @@ export function createPreCompactHook(onCompact: () => void) {
       return {};
     }
 
-    // Auto-compaction: first pass warns + marks for rotation and blocks; second
-    // pass allows the native compaction as the emergency backstop.
+    // Auto-compaction: first pass schedules a rotation and blocks; second pass
+    // allows the native compaction as the emergency backstop.
     if (!compactBlocked) {
-      log("mind", "blocking auto-compaction — warning mind + marking session for rotation");
+      log("mind", "blocking auto-compaction — marking session for rotation");
       try {
         onCompact();
         compactBlocked = true;

package/templates/claude/src/lib/message-channel.ts

@@ -1,16 +1,34 @@
 import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 
+/** A queued/in-flight message paired with the sequence number that identifies it. */
+export type ChannelEntry = { msg: SDKUserMessage; seq: number };
+
+// Module-scoped, not per-channel: rotation and the idle reaper both replace a
+// session's channel with a fresh instance while carrying seqs forward (relocking
+// old entries to new ones — see relockstepMessageIds in recover.ts). A per-instance
+// counter would restart at 0 on every fresh channel, so a seq minted by one channel
+// generation could collide with one minted by another; a single global counter makes
+// every seq unique for the process's lifetime, so a stale seq can never be mistaken
+// for a different message.
+let nextSeq = 0;
+
 export type MessageChannel = {
-  push: (msg: SDKUserMessage) => void;
-  /** Acknowledge that the oldest in-flight message's turn has completed. */
-  ack: () => void;
+  /** Returns the sequence number minted for this message — the identity `ack()` needs. */
+  push: (msg: SDKUserMessage) => number;
+  /**
+   * Acknowledge that the message with this `seq` has completed its turn. Identity-based
+   * (not positional): the SDK folds messages that arrive mid-run into the active run, so
+   * a turn's `result` can cover more than just the oldest in-flight message — see the
+   * caller in stream-consumer.ts.
+   */
+  ack: (seq: number) => void;
   /**
    * Return every message that has not been fully processed — those delivered to
    * the consumer but not yet acked (their turn never finished) followed by those
-   * still queued — and reset the channel. Used to re-feed the stream after a
-   * compaction abort so in-flight input is never lost.
+   * still queued — paired with their `seq`, and reset the channel. Used to re-feed
+   * the stream after a compaction abort so in-flight input is never lost.
    */
-  recover: () => SDKUserMessage[];
+  recover: () => ChannelEntry[];
   /**
    * Terminate the input iterable: resolve any pending `next()` with `done: true`
    * and make subsequent `next()` calls return done. The SDK sees end-of-input and
@@ -23,33 +41,43 @@ export type MessageChannel = {
 };
 
 export function createMessageChannel(): MessageChannel {
-  const queue: SDKUserMessage[] = [];
+  const queue: ChannelEntry[] = [];
   // Messages handed to the consumer (the SDK's read-ahead) whose turn has not yet
   // completed. The SDK's streamInput loop pulls messages eagerly and writes them
   // to the CLI subprocess, so once delivered they no longer live in `queue`. We
   // retain them here so a compaction abort — which kills that subprocess — can
   // re-feed the unprocessed ones instead of dropping them.
-  const inFlight: SDKUserMessage[] = [];
+  const inFlight: ChannelEntry[] = [];
   let resolve: ((value: IteratorResult<SDKUserMessage>) => void) | null = null;
   let closed = false;
 
-  function deliver(msg: SDKUserMessage): IteratorResult<SDKUserMessage> {
-    inFlight.push(msg);
-    return { value: msg, done: false };
+  function deliver(entry: ChannelEntry): IteratorResult<SDKUserMessage> {
+    inFlight.push(entry);
+    return { value: entry.msg, done: false };
   }
 
   return {
     push(msg: SDKUserMessage) {
+      const entry: ChannelEntry = { msg, seq: nextSeq++ };
       if (resolve) {
         const r = resolve;
         resolve = null;
-        r(deliver(msg));
+        r(deliver(entry));
       } else {
-        queue.push(msg);
+        queue.push(entry);
       }
+      return entry.seq;
     },
-    ack() {
-      inFlight.shift();
+    ack(seq: number) {
+      let i = inFlight.findIndex((e) => e.seq === seq);
+      if (i !== -1) {
+        inFlight.splice(i, 1);
+        return;
+      }
+      // Defensive: shouldn't normally be in the queue when acked, but remove it
+      // there too rather than leave a stranded entry if it somehow is.
+      i = queue.findIndex((e) => e.seq === seq);
+      if (i !== -1) queue.splice(i, 1);
     },
     recover() {
       // Resolve any pending iterator wait with done:true so it doesn't

package/templates/claude/src/lib/recover.ts

@@ -0,0 +1,69 @@
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { ChannelEntry } from "./message-channel.js";
+import type { MessageIdEntry } from "./stream-consumer.js";
+
+/**
+ * `recover()` returns messages the channel can't prove were unprocessed — a genuinely
+ * unfinished turn looks identical to a stranded, already-completed one would have before
+ * #764's ack fix. Mark every re-pushed message so the mind can check its own record
+ * before redoing work: fail toward noise (a spurious note is cosmetic and self-correcting)
+ * rather than silence (a missing one is invisible and produces a false permanent record).
+ */
+export const RECOVERED_MESSAGE_NOTE =
+  "Note: this message is being redelivered after a session interruption. You may already " +
+  "have handled it — check your recent work (e.g. journal, files, messages you've already " +
+  "sent) before repeating anything.";
+
+export function markRecovered(msg: SDKUserMessage): SDKUserMessage {
+  const content = msg.message.content;
+  const blocks = typeof content === "string" ? [{ type: "text" as const, text: content }] : content;
+  // A message can be recovered twice (consecutive rotations, up to
+  // MAX_CONSECUTIVE_ROTATIONS) — don't stack the note on each pass.
+  const first = blocks[0];
+  if (first && "type" in first && first.type === "text" && first.text === RECOVERED_MESSAGE_NOTE) {
+    return { ...msg, message: { ...msg.message, content: blocks } };
+  }
+  const marker = { type: "text" as const, text: RECOVERED_MESSAGE_NOTE };
+  return { ...msg, message: { ...msg.message, content: [marker, ...blocks] } };
+}
+
+/**
+ * Re-push `recover()`'s output into a fresh channel and append the result onto
+ * `existingMessageIds` — mutated in place and returned, rather than replacing it.
+ * That's not incidental: `existingMessageIds` may already hold an entry for a
+ * message that raced in and was pushed into the SAME fresh channel/messageIds
+ * while `recover()` was still pending (the idle reaper awaits the SDK subprocess's
+ * shutdown before recovering — see agent.ts). Returning a fresh array for the
+ * caller to assign over would silently discard that entry (#764) — appending
+ * in place makes that mistake impossible at the call site.
+ *
+ * Each entry's `id` carries over — matched by its *old* `seq` — to the *new* seq
+ * the fresh channel mints on push, so the next turn's currentMessageId/channel
+ * routing isn't corrupted by stale or missing ids. A `pending` entry with no
+ * match in `oldMessageIds` gets `id: undefined` (see the `idBySeq.get` fallback
+ * below) rather than throwing — safe because `seq` is now globally unique
+ * (message-channel.ts), so this can only happen if `oldMessageIds` itself was
+ * incomplete, and losing routing info for one message beats losing the message.
+ *
+ * `existingMessageIds` has no default — deliberately. `= []` would let a call site
+ * omit it and get back a fresh array to assign over, which is exactly the #764
+ * clobber: silently discarding whatever the target array already held. Making it
+ * required turns that omission into a compile error at every call site, including
+ * ones written later.
+ */
+export function relockstepMessageIds(
+  pending: ChannelEntry[],
+  oldMessageIds: MessageIdEntry[],
+  push: (msg: SDKUserMessage) => number,
+  existingMessageIds: MessageIdEntry[],
+  transform: (msg: SDKUserMessage) => SDKUserMessage = markRecovered,
+): MessageIdEntry[] {
+  const idBySeq = new Map(oldMessageIds.map((e) => [e.seq, e.id]));
+  existingMessageIds.push(
+    ...pending.map((entry) => ({
+      id: idBySeq.get(entry.seq),
+      seq: push(transform(entry.msg)),
+    })),
+  );
+  return existingMessageIds;
+}