volute 0.52.0 → 0.54.0

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;
+}

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
@@ -43,9 +52,15 @@ export async function consumeStream(
   callbacks: StreamCallbacks,
 ) {
   emit(session, { type: "session_start" });
+  // How many queued message ids predate the current turn — see the pruning in
+  // the result handler (#700).
+  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) {
       callbacks.onSessionId?.(msg.session_id as string);
@@ -119,6 +134,21 @@ 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. 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
       const resultMsg = msg as Record<string, unknown>;
@@ -141,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

@@ -20,7 +20,7 @@ if (config.model) log("server", `using model: ${config.model}`);
 if (config.thinking) log("server", `thinking: ${JSON.stringify(config.thinking)}`);
 if (config.effort) log("server", `effort: ${config.effort}`);
 
-const systemPrompt = loadSystemPrompt();
+const systemPrompt = loadSystemPrompt(config);
 const sessionsDir = resolve(".mind/sessions");
 
 const pkg = loadPackageInfo();
@@ -36,6 +36,7 @@ const mind = createMind({
   compactionMessage: config.compactionMessage,
   maxContextTokens: config.compaction?.maxContextTokens,
   sessionIdleMinutes: config.sessionIdleMinutes,
+  seedTokens: config.continuity?.seedTokens,
   subagents: config.subagents,
   onIdentityReload: async () => {
     log("server", "identity file changed — restarting to reload");

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,13 +13,17 @@ 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:
 
-- **`MEMORY.md`** — Your long-term memory, always in context. Update as you grow — new understanding, changed perspectives, things that matter to you.
-- **`memory/journal/YYYY-MM-DD.md`** — Your daily journal. Write about what you're doing, thinking, and learning. Journals are permanent records.
-- Periodically consolidate journal entries into `MEMORY.md` to promote lasting insights.
+- **`MEMORY.md`** — Your core memory, always in context. Every token it holds is paid on every request, so keep it lean: identity, active context, key relationships, and an index of your `memory/` files.
+- **`memory/`** — Everything else, read on demand: your daily journal (`memory/journal/YYYY-MM-DD.md` — a permanent record of what you're doing, thinking, and learning) plus any topic, channel, or project files you create.
+- Periodically consolidate: distill detail out of `MEMORY.md` into `memory/` files, leaving one-line index entries behind.
 
 See the **memory** skill for detailed guidance.