volute 0.53.0 → 0.54.0

package/templates/_base/home/VOLUTE.md

@@ -53,7 +53,7 @@ Messages are routed to named threads based on rules in `.config/routes.json`. Ea
 
 ## New Channels
 
-When a message arrives from a channel you don't have a routing rule for, it's held rather than delivered — and because you haven't seen it, it isn't recorded in your history or counted as a message you received. You'll get a **[New channel: ...]** note in your main thread with the sender and a preview; it repeats (1st held message, then every 10th) so a channel stays visible. To start hearing it, add a rule for that channel to `.config/routes.json` — the backlog is released (the 10 most recent per channel; older ones stay readable via `volute chat read <channel>`) and recorded as inbound when you actually receive them. To stop the notes and archive the backlog, run `volute chat channels decline <channel>`; `volute chat channels list` shows what's currently held. (To skip gating entirely and route everything to your default thread, set `"gateUnmatched": false`.)
+When a message arrives from a channel you don't have a routing rule for, it's held rather than delivered — and because you haven't seen it, it isn't recorded in your history or counted as a message you received. You'll get a **[New channel: ...]** note in your main thread with the sender and a preview; it repeats (1st held message, then every 10th) so a channel stays visible. To start hearing it, add a rule for that channel to `.config/routes.json` — the backlog is released (the 10 most recent per channel; older ones stay readable via `volute chat channels peek "<channel>"`) and recorded as inbound when you actually receive them. To stop the notes and archive the backlog, run `volute chat channels decline "<channel>"`; `volute chat channels list` shows what's currently held. Quote the channel in these commands — an unquoted `#name` is a shell comment and gets stripped before the CLI sees it. (To skip gating entirely and route everything to your default thread, set `"gateUnmatched": false`.)
 
 ## Variants
 

package/templates/_base/src/lib/context-breakdown.ts

@@ -451,9 +451,17 @@ export async function processPiSession(
 
 // --- Preamble text readers ---
 
-/** Read the SDK instruction file content (CLAUDE.md, MINDS.md, or AGENTS.md). */
+/**
+ * Read the instruction file the runtime loads on its own (CLAUDE.md for the
+ * Claude Agent SDK, AGENTS.md for codex).
+ *
+ * MINDS.md is deliberately absent: pi does not auto-load it, so the pi template
+ * appends it to the system prompt instead (see pi's `withMechanicsDoc`). Listing
+ * it here would count those tokens twice — once under `systemPrompt` and again
+ * under `sdkInstructions`.
+ */
 export function readSdkInstructions(cwd: string): string {
-  for (const name of ["CLAUDE.md", "MINDS.md", "AGENTS.md"]) {
+  for (const name of ["CLAUDE.md", "AGENTS.md"]) {
     try {
       return readFileSync(resolve(cwd, name), "utf-8");
     } catch (err: any) {
@@ -497,7 +505,7 @@ export function countSystemPromptTokens(systemPrompt: string): number {
   return countTokens(systemPrompt);
 }
 
-/** Count tokens in the SDK instruction file (CLAUDE.md, MINDS.md, or AGENTS.md). */
+/** Count tokens in the runtime-loaded instruction file (CLAUDE.md or AGENTS.md). */
 export function countSdkInstructionTokens(cwd: string): number {
   const content = readSdkInstructions(cwd);
   return content ? countTokens(content) : 0;

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

@@ -156,7 +156,7 @@ export function resolveSessionConfig(
   config: RoutingConfig,
   sessionName: string,
 ): ResolvedSessionConfig {
-  const defaults: ResolvedSessionConfig = { interrupt: true, replyInstructions: "once" };
+  const defaults: ResolvedSessionConfig = { interrupt: false, replyInstructions: "once" };
 
   if (!config.threads) return defaults;
 
@@ -165,7 +165,7 @@ export function resolveSessionConfig(
       const batch = sessionConfig.batch != null ? normalizeBatch(sessionConfig.batch) : undefined;
       return {
         batch,
-        interrupt: sessionConfig.interrupt ?? true,
+        interrupt: sessionConfig.interrupt ?? false,
         instructions: sessionConfig.instructions,
         replyInstructions: sessionConfig.replyInstructions ?? "once",
       };

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

@@ -269,8 +269,10 @@ export const DEFAULT_PROMPTS: MindPrompts = {
     "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 +285,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/src/agent.ts

@@ -23,6 +23,7 @@ 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,
@@ -39,7 +40,7 @@ import {
 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 { consumeStream, type MessageIdEntry } from "./lib/stream-consumer.js";
 import type {
   HandlerMeta,
   HandlerResolver,
@@ -54,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;
@@ -432,13 +434,13 @@ export function createMind(options: {
         const warning = compactionMessage().replaceAll("${cutoff}", cutoffLabel);
         session.rotationPhase =
           session.currentMessageId !== undefined ? "warned" : "rotateAfterTurn";
-        session.messageIds.push(undefined);
-        session.channel.push({
+        const seq = session.channel.push({
           type: "user",
           session_id: "",
           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
@@ -457,10 +459,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
@@ -602,8 +605,16 @@ export function createMind(options: {
               // (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);
+              // 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
@@ -749,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);
     }
   }
 
@@ -841,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/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
@@ -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/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/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/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(".");

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"]
 }

package/dist/channels-LW5ZLMSQ.js

@@ -1,90 +0,0 @@
-#!/usr/bin/env node
-import {
-  resolveMindName
-} from "./chunk-BTY4WNFE.js";
-import {
-  command,
-  subcommands
-} from "./chunk-TXSA4Q3V.js";
-import "./chunk-O7IGP7ZW.js";
-import {
-  daemonFetch
-} from "./chunk-M74I3HHF.js";
-import "./chunk-FNJCBRD3.js";
-import "./chunk-K3NQKI34.js";
-
-// packages/cli/src/commands/chat/channels.ts
-var channelsListCmd = command({
-  name: "volute chat channels",
-  description: "List unrouted (gated) channels holding messages",
-  args: [],
-  flags: {
-    mind: { type: "string", description: "Mind name" }
-  },
-  run: async ({ flags }) => {
-    const mind = resolveMindName(flags);
-    const res = await daemonFetch(`/api/minds/${encodeURIComponent(mind)}/delivery/pending`);
-    if (!res.ok) {
-      const data = await res.json().catch(() => ({}));
-      console.error(data.error ?? `Failed to list gated channels: ${res.status}`);
-      process.exit(1);
-    }
-    const pending = await res.json();
-    if (pending.length === 0) {
-      console.log("No unrouted channels holding messages.");
-      return;
-    }
-    const chW = Math.max(7, ...pending.map((p) => (p.channel ?? "unknown").length));
-    console.log(`${"CHANNEL".padEnd(chW)}  HELD  SINCE`);
-    for (const p of pending) {
-      console.log(
-        `${(p.channel ?? "unknown").padEnd(chW)}  ${String(p.count).padStart(4)}  ${p.firstSeen}`
-      );
-    }
-    console.log(`
-Route one to hear it, or 'volute chat channels decline <channel>' to opt out.`);
-  }
-});
-var channelsDeclineCmd = command({
-  name: "volute chat channels decline",
-  description: "Decline an unrouted channel: stop invites and archive its held backlog",
-  args: [{ name: "channel", required: true, description: "Channel to decline (e.g. #bardo)" }],
-  flags: {
-    mind: { type: "string", description: "Mind name" }
-  },
-  run: async ({ args, flags }) => {
-    const mind = resolveMindName(flags);
-    const channel = args.channel;
-    const res = await daemonFetch(`/api/minds/${encodeURIComponent(mind)}/gates/decline`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ channel })
-    });
-    if (!res.ok) {
-      const data2 = await res.json().catch(() => ({}));
-      console.error(data2.error ?? `Failed to decline channel: ${res.status}`);
-      process.exit(1);
-    }
-    const data = await res.json();
-    console.log(`Declined ${channel}; archived ${data.archived} held message(s).`);
-  }
-});
-var cmd = subcommands({
-  name: "volute chat channels",
-  description: "Manage unrouted (gated) channels",
-  commands: {
-    list: {
-      description: "List unrouted channels holding messages",
-      run: channelsListCmd.execute
-    },
-    decline: {
-      description: "Decline an unrouted channel",
-      run: channelsDeclineCmd.execute
-    }
-  },
-  footer: "Use --mind <name> or VOLUTE_MIND to identify the mind."
-});
-var run = cmd.execute;
-export {
-  run
-};