volute 0.4.0 → 0.5.0

package/templates/_base/home/.config/routes.json

@@ -0,0 +1,10 @@
+{
+  "rules": [
+    {
+      "channel": "volute:*",
+      "isDM": false,
+      "session": "${channel}",
+      "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@{{name}}"] }
+    }
+  ]
+}

package/templates/_base/home/VOLUTE.md

@@ -6,53 +6,32 @@ You are a volute agent — a persistent being that communicates across multiple
 
 | Channel | Shows tool calls | Notes |
 |---------|------------------|-------|
-| Web UI  | Yes | Full detail including tool calls |
-| CLI     | Yes | Direct terminal via `volute send` |
-| Agent   | Yes | Messages from other agents |
+| Volute  | Yes | Web UI, CLI, agent-to-agent |
 | System  | No  | Automated messages (schedules, upgrades) |
 
 Connector channels (Discord, Slack, etc.) show text responses only — no tool calls.
 
-When responding to an incoming message, just respond normally — your response routes back to the source automatically. Do not use `volute channel send` to reply to a message; that would send a duplicate.
+## Responding to Messages
 
-To reach out on your own initiative, use `volute channel send <uri> "message"`. See the **volute-agent** skill for details.
+For **direct messages**, respond normally — your response routes back to the source automatically. Do not use `volute channel send` to reply; that would send a duplicate.
 
-## Session Routing
+For **batched channels** (group chats, high-volume sources), your text response stays in the session as internal processing — it doesn't get sent anywhere. Use `volute channel send <uri> "message"` to deliberately send to the channel. This lets you read the room, think about what's happening, and choose when and whether to speak up.
 
-By default, all messages share a single conversation session. You can route messages to different sessions — or to files — by editing `.config/sessions.json`.
+To reach out on your own initiative, use `volute channel send <uri> "message"`.
 
-```json
-{
-  "rules": [
-    { "sender": "alice", "session": "alice" },
-    { "channel": "discord:*", "session": "discord-${sender}" },
-    { "channel": "discord:logs", "destination": "file", "path": "memory/discord-logs.md" },
-    { "channel": "system:scheduler", "sender": "daily-report", "session": "daily-report" },
-    { "channel": "system:scheduler", "sender": "cleanup", "session": "$new" }
-  ],
-  "default": "main"
-}
+All send commands also accept the message from stdin, which avoids shell escaping issues:
+```sh
+echo "message with 'quotes' and $special chars" | volute channel send <uri>
 ```
 
-- Rules are evaluated top-to-bottom, first match wins
-- `channel` and `sender` are match criteria (AND'd together); `*` glob patterns work
-- `${sender}` and `${channel}` expand in session/path names
-- `$new` creates a fresh session every time
-- Scheduler messages use the schedule id as `sender`
+## Sessions
 
-### Destinations
+Messages are routed to named sessions based on rules in `.config/routes.json`. Each session has its own conversation history. Without config, everything goes to "main". Your session name appears in the message prefix (e.g. `— session: alice —`) unless it's "main".
 
-- **agent** (default) — routes to a conversation session
-- **file** — appends the message to a file (requires `path`); useful for logging channels to disk
+## Channel Gating
 
-### Options
+Messages from unrecognized channels are held until you add a routing rule. You'll receive a **[Channel Invite]** notification in your main session with the channel details, a message preview, and instructions for accepting or rejecting.
 
-- `interrupt` — whether to interrupt an in-progress agent turn (default: `true`). Set to `false` for low-priority channels.
-- `batch` — buffer messages for N minutes, then deliver as a single batch. Useful for high-volume channels.
+## Reference
 
-Each named session maintains its own conversation history across restarts. Your current session name appears in the message prefix (e.g., `— session: alice —`) unless it's the default "main".
-
-## Skills
-
-- Use the **volute-agent** skill for CLI commands, variants, upgrades, and self-management.
-- Use the **memory** skill for detailed memory management and consolidation.
+See the **volute-agent** skill for routing config syntax, batch options, channel management, and all CLI commands.

package/templates/_base/src/lib/format-prefix.ts

@@ -14,7 +14,7 @@ export function formatPrefix(meta: ChannelMeta | undefined, time: string): strin
     sender += " in DM";
   } else if (meta.channelName) {
     sender += ` in #${meta.channelName}`;
-    if (meta.guildName) sender += ` in ${meta.guildName}`;
+    if (meta.serverName) sender += ` in ${meta.serverName}`;
   }
   const parts = [platform, sender].filter(Boolean);
   // Include session name if not the default

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

@@ -1,6 +1,6 @@
 import { formatPrefix } from "./format-prefix.js";
 import { log, logMessage } from "./logger.js";
-import { loadRoutingConfig, resolveRoute } from "./routing.js";
+import { type BatchConfig, loadRoutingConfig, resolveRoute } from "./routing.js";
 import type { ChannelMeta, HandlerResolver, Listener, VoluteContentPart } from "./types.js";
 
 export type Router = {
@@ -17,14 +17,16 @@ type BufferedMessage = {
   sender?: string;
   channel?: string;
   channelName?: string;
-  guildName?: string;
+  serverName?: string;
   timestamp: string;
 };
 
 type BatchBuffer = {
   messages: BufferedMessage[];
-  timer: ReturnType<typeof setInterval>;
+  debounceTimer: ReturnType<typeof setTimeout> | null;
+  maxWaitTimer: ReturnType<typeof setTimeout> | null;
   sessionName: string;
+  config: BatchConfig;
 };
 
 function generateMessageId(): string {
@@ -49,32 +51,105 @@ function applyPrefix(content: VoluteContentPart[], meta: ChannelMeta): VoluteCon
   });
 }
 
+function sanitizeChannelPath(channel: string): string {
+  return channel
+    .replace(/[/\\:]/g, "-")
+    .replace(/\.\./g, "-")
+    .replace(/\0/g, "")
+    .slice(0, 100);
+}
+
+/** Check if message text matches any trigger patterns (case-insensitive substring match). */
+function matchesTrigger(text: string, triggers: string[]): boolean {
+  const lower = text.toLowerCase();
+  return triggers.some((t) => lower.includes(t.toLowerCase()));
+}
+
+function formatInviteNotification(
+  meta: ChannelMeta,
+  filePath: string,
+  messageText: string,
+): string {
+  const time = new Date().toLocaleString();
+  const lines = ["[Channel Invite]"];
+  if (meta.channel) lines.push(`Channel: ${meta.channel}`);
+  if (meta.sender) lines.push(`Sender: ${meta.sender}`);
+  if (meta.platform) lines.push(`Platform: ${meta.platform}`);
+  if (meta.serverName) lines.push(`Server: ${meta.serverName}`);
+  if (meta.channelName) lines.push(`Channel name: ${meta.channelName}`);
+  if (meta.participants && meta.participants.length > 0)
+    lines.push(`Participants: ${meta.participants.join(", ")}`);
+  lines.push("");
+  const preview = messageText.length > 200 ? `${messageText.slice(0, 200)}...` : messageText;
+  lines.push(`[${meta.sender ?? "unknown"} — ${time}]`);
+  lines.push(preview);
+  lines.push("");
+  lines.push(`Further messages will be saved to ${filePath}`);
+  lines.push("");
+  lines.push("To accept, add a routing rule to .config/routes.json:");
+  const suggestedSession = sanitizeChannelPath(meta.channel ?? "unknown");
+  const otherCount = (meta.participantCount ?? 1) - 1;
+  if (otherCount > 1) {
+    lines.push(
+      `  { "channel": "${meta.channel}", "session": "${suggestedSession}", "batch": { "debounce": 20, "maxWait": 120 } }`,
+    );
+    lines.push(
+      `(batch recommended — ${otherCount} other participants may generate frequent messages)`,
+    );
+  } else {
+    lines.push(`  { "channel": "${meta.channel}", "session": "${suggestedSession}" }`);
+  }
+  lines.push(`To respond, use: volute channel send ${meta.channel ?? "unknown"} "your message"`);
+  lines.push(`To reject, delete ${filePath}`);
+  return lines.join("\n");
+}
+
 export function createRouter(options: {
   configPath?: string;
   agentHandler: HandlerResolver;
   fileHandler?: HandlerResolver;
 }): Router {
   const batchBuffers = new Map<string, BatchBuffer>();
+  const pendingChannels = new Set<string>();
 
   function flushBatch(key: string) {
     const buffer = batchBuffers.get(key);
     if (!buffer || buffer.messages.length === 0) return;
 
+    // Clear both timers
+    if (buffer.debounceTimer) clearTimeout(buffer.debounceTimer);
+    if (buffer.maxWaitTimer) clearTimeout(buffer.maxWaitTimer);
+    buffer.debounceTimer = null;
+    buffer.maxWaitTimer = null;
+
     const messages = buffer.messages.splice(0);
 
-    // Group by channel for header summary
+    // Group by channel URI for header summary
     const channelCounts = new Map<string, number>();
     for (const msg of messages) {
-      const label = msg.channelName
-        ? `#${msg.channelName}${msg.guildName ? ` in ${msg.guildName}` : ""}`
-        : (msg.channel ?? "unknown");
-      channelCounts.set(label, (channelCounts.get(label) ?? 0) + 1);
+      const uri = msg.channel ?? "unknown";
+      channelCounts.set(uri, (channelCounts.get(uri) ?? 0) + 1);
     }
-    const summary = [...channelCounts.entries()].map(([ch, n]) => `${n} from ${ch}`).join(", ");
+    const channelLabels = [...channelCounts.entries()].map(([uri, n]) => {
+      const msg = messages.find((m) => m.channel === uri);
+      const display = msg?.channelName
+        ? `#${msg.channelName}${msg.serverName ? ` in ${msg.serverName}` : ""} (${uri})`
+        : uri;
+      return `${n} from ${display}`;
+    });
+    const summary = channelLabels.join(", ");
 
     const header = `[Batch: ${messages.length} message${messages.length === 1 ? "" : "s"} — ${summary}]`;
+    // Include channel URI per message when batch spans multiple channels
+    const multiChannel = channelCounts.size > 1;
     const body = messages
-      .map((m) => `[${m.sender ?? "unknown"} — ${m.timestamp}]\n${m.text}`)
+      .map((m) => {
+        const prefix =
+          multiChannel && m.channel
+            ? `[${m.sender ?? "unknown"} in ${m.channel} — ${m.timestamp}]`
+            : `[${m.sender ?? "unknown"} — ${m.timestamp}]`;
+        return `${prefix}\n${m.text}`;
+      })
       .join("\n\n");
 
     const content: VoluteContentPart[] = [{ type: "text", text: `${header}\n\n${body}` }];
@@ -91,6 +166,30 @@ export function createRouter(options: {
     log("router", `flushed batch for session ${buffer.sessionName}: ${messages.length} messages`);
   }
 
+  function scheduleBatchTimers(key: string) {
+    const buffer = batchBuffers.get(key);
+    if (!buffer) return;
+    const { config } = buffer;
+
+    // Reset debounce timer
+    if (buffer.debounceTimer) clearTimeout(buffer.debounceTimer);
+    if (config.debounce != null) {
+      buffer.debounceTimer = setTimeout(() => flushBatch(key), config.debounce * 1000);
+      buffer.debounceTimer.unref();
+    }
+
+    // Start maxWait timer if not already running
+    if (!buffer.maxWaitTimer && config.maxWait != null) {
+      buffer.maxWaitTimer = setTimeout(() => flushBatch(key), config.maxWait * 1000);
+      buffer.maxWaitTimer.unref();
+    }
+
+    // If neither timer is configured, flush immediately (shouldn't happen in practice)
+    if (config.debounce == null && config.maxWait == null) {
+      flushBatch(key);
+    }
+  }
+
   function route(
     content: VoluteContentPart[],
     meta: ChannelMeta,
@@ -105,12 +204,47 @@ export function createRouter(options: {
 
     // Resolve route from config (re-read on each request for hot-reload)
     const config = options.configPath ? loadRoutingConfig(options.configPath) : {};
-    const resolved = resolveRoute(config, { channel: meta.channel, sender: meta.sender });
+    const resolved = resolveRoute(config, {
+      channel: meta.channel,
+      sender: meta.sender,
+      isDM: meta.isDM,
+      participantCount: meta.participantCount,
+    });
 
     const messageId = generateMessageId();
     const noop = () => {};
     const safeListener = listener ?? noop;
 
+    // Gate unmatched channels (default: gate unless explicitly disabled)
+    if (!resolved.matched && config.gateUnmatched !== false) {
+      const channelKey = meta.channel ?? "unknown";
+      const sanitized = sanitizeChannelPath(channelKey);
+      const filePath = `inbox/${sanitized}.md`;
+
+      // Save message to file
+      if (options.fileHandler) {
+        const formatted = applyPrefix(content, meta);
+        const fileHandler = options.fileHandler(filePath);
+        fileHandler.handle(formatted, { ...meta, messageId }, noop);
+      }
+
+      // First message from this channel — send invite notification
+      if (!pendingChannels.has(channelKey)) {
+        pendingChannels.add(channelKey);
+        const notification = formatInviteNotification(meta, filePath, text);
+        const notifContent: VoluteContentPart[] = [{ type: "text", text: notification }];
+        const handler = options.agentHandler("main");
+        handler.handle(
+          notifContent,
+          { sessionName: "main", messageId: generateMessageId(), interrupt: true },
+          noop,
+        );
+      }
+
+      queueMicrotask(() => safeListener({ type: "done", messageId }));
+      return { messageId, unsubscribe: noop };
+    }
+
     // File destination
     if (resolved.destination === "file") {
       if (options.fileHandler) {
@@ -134,11 +268,16 @@ export function createRouter(options: {
     // Batch mode: buffer the message and return immediate done
     if (resolved.batch != null) {
       const batchKey = `batch:${sessionName}`;
+      const batchConfig = resolved.batch;
 
       if (!batchBuffers.has(batchKey)) {
-        const timer = setInterval(() => flushBatch(batchKey), resolved.batch * 60 * 1000);
-        timer.unref();
-        batchBuffers.set(batchKey, { messages: [], timer, sessionName });
+        batchBuffers.set(batchKey, {
+          messages: [],
+          debounceTimer: null,
+          maxWaitTimer: null,
+          sessionName,
+          config: batchConfig,
+        });
       }
 
       batchBuffers.get(batchKey)!.messages.push({
@@ -146,13 +285,20 @@ export function createRouter(options: {
         sender: meta.sender,
         channel: meta.channel,
         channelName: meta.channelName,
-        guildName: meta.guildName,
+        serverName: meta.serverName,
         timestamp: new Date().toLocaleTimeString("en-US", {
           hour: "numeric",
           minute: "2-digit",
         }),
       });
 
+      // Check triggers — flush immediately if matched
+      if (batchConfig.triggers?.length && matchesTrigger(text, batchConfig.triggers)) {
+        flushBatch(batchKey);
+      } else {
+        scheduleBatchTimers(batchKey);
+      }
+
       queueMicrotask(() => safeListener({ type: "done", messageId }));
       return { messageId, unsubscribe: noop };
     }
@@ -170,7 +316,8 @@ export function createRouter(options: {
 
   function close() {
     for (const [key, buffer] of batchBuffers) {
-      clearInterval(buffer.timer);
+      if (buffer.debounceTimer) clearTimeout(buffer.debounceTimer);
+      if (buffer.maxWaitTimer) clearTimeout(buffer.maxWaitTimer);
       flushBatch(key);
     }
     batchBuffers.clear();

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

@@ -1,31 +1,52 @@
 import { readFileSync } from "node:fs";
 import { log } from "./logger.js";
 
+export type BatchConfig = {
+  debounce?: number; // seconds of quiet before flush
+  maxWait?: number; // max seconds before forced flush
+  triggers?: string[]; // patterns that cause immediate flush
+};
+
 export type RoutingRule = {
   session?: string;
   destination?: "agent" | "file";
   path?: string; // file path for file destination
   interrupt?: boolean; // interrupt in-progress agent turn (default: true for agent)
-  batch?: number; // minutes — buffer messages, flush on timer
+  batch?: number | BatchConfig; // number = minutes (legacy), object = fine-grained control
   channel?: string;
   sender?: string;
+  isDM?: boolean; // match on isDM metadata
+  participants?: number; // match on participant count (e.g. 2 = DM)
 };
 
 export type RoutingConfig = {
   rules?: RoutingRule[];
   default?: string;
+  gateUnmatched?: boolean;
 };
 
 export type ResolvedRoute =
-  | { destination: "agent"; session: string; interrupt: boolean; batch?: number }
-  | { destination: "file"; path: string };
+  | {
+      destination: "agent";
+      session: string;
+      interrupt: boolean;
+      batch?: BatchConfig;
+      matched: boolean;
+    }
+  | { destination: "file"; path: string; matched: boolean };
+
+/** Normalize batch config: number (minutes) → { maxWait } in seconds. */
+export function normalizeBatch(batch: number | BatchConfig): BatchConfig {
+  if (typeof batch === "number") return { maxWait: batch * 60 };
+  return batch;
+}
 
 export function loadRoutingConfig(configPath: string): RoutingConfig {
   try {
     return JSON.parse(readFileSync(configPath, "utf-8"));
   } catch (err: any) {
     if (err?.code !== "ENOENT") {
-      log("sessions", `failed to load ${configPath}:`, err);
+      log("routing", `failed to load ${configPath}:`, err);
     }
     return {};
   }
@@ -41,21 +62,39 @@ function globMatch(pattern: string, value: string): boolean {
   return new RegExp(`^${regex}$`).test(value);
 }
 
-const MATCH_KEYS = new Set(["channel", "sender"]);
+const GLOB_MATCH_KEYS = new Set(["channel", "sender"]);
 const NON_MATCH_KEYS = new Set(["session", "batch", "destination", "path", "interrupt"]);
 
-function ruleMatches(rule: RoutingRule, meta: { channel?: string; sender?: string }): boolean {
+type MatchMeta = { channel?: string; sender?: string; isDM?: boolean; participantCount?: number };
+
+function ruleMatches(rule: RoutingRule, meta: MatchMeta): boolean {
   for (const [key, pattern] of Object.entries(rule)) {
     if (NON_MATCH_KEYS.has(key)) continue;
+
+    // Boolean match: isDM
+    if (key === "isDM") {
+      if (typeof pattern !== "boolean") return false;
+      if ((meta.isDM ?? false) !== pattern) return false;
+      continue;
+    }
+
+    // Numeric match: participants
+    if (key === "participants") {
+      if (typeof pattern !== "number") return false;
+      if ((meta.participantCount ?? 0) !== pattern) return false;
+      continue;
+    }
+
+    // Glob string match: channel, sender
     if (typeof pattern !== "string") return false;
-    if (!MATCH_KEYS.has(key)) return false;
-    const value = meta[key as keyof typeof meta] ?? "";
+    if (!GLOB_MATCH_KEYS.has(key)) return false;
+    const value = meta[key as "channel" | "sender"] ?? "";
     if (!globMatch(pattern, value)) return false;
   }
   return true;
 }
 
-function expandTemplate(template: string, meta: { channel?: string; sender?: string }): string {
+function expandTemplate(template: string, meta: MatchMeta): string {
   return template
     .replace(/\$\{sender\}/g, meta.sender ?? "unknown")
     .replace(/\$\{channel\}/g, meta.channel ?? "unknown");
@@ -64,35 +103,33 @@ function expandTemplate(template: string, meta: { channel?: string; sender?: str
 /**
  * Resolve the full route for a message: destination type, session/path, interrupt, batch.
  */
-export function resolveRoute(
-  config: RoutingConfig,
-  meta: { channel?: string; sender?: string },
-): ResolvedRoute {
+export function resolveRoute(config: RoutingConfig, meta: MatchMeta): ResolvedRoute {
   const fallback = config.default ?? "main";
 
   if (!config.rules) {
-    return { destination: "agent", session: fallback, interrupt: true };
+    return { destination: "agent", session: fallback, interrupt: true, matched: false };
   }
 
   for (const rule of config.rules) {
     if (ruleMatches(rule, meta)) {
       if (rule.destination === "file") {
         if (!rule.path) {
-          log("sessions", `file destination rule missing path — falling through`);
+          log("routing", `file destination rule missing path — falling through`);
           continue;
         }
-        return { destination: "file", path: rule.path };
+        return { destination: "file", path: rule.path, matched: true };
       }
       return {
         destination: "agent",
         session: sanitizeSessionName(expandTemplate(rule.session ?? fallback, meta)),
         interrupt: rule.interrupt ?? true,
-        batch: rule.batch,
+        batch: rule.batch != null ? normalizeBatch(rule.batch) : undefined,
+        matched: true,
       };
     }
   }
 
-  return { destination: "agent", session: fallback, interrupt: true };
+  return { destination: "agent", session: fallback, interrupt: true, matched: false };
 }
 
 function sanitizeSessionName(name: string): string {

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

@@ -8,8 +8,10 @@ export type ChannelMeta = {
   platform?: string;
   isDM?: boolean;
   channelName?: string;
-  guildName?: string;
+  serverName?: string;
   sessionName?: string;
+  participants?: string[];
+  participantCount?: number;
 };
 
 /** ChannelMeta enriched by the router with dispatch info. */

package/templates/agent-sdk/.init/.config/routes.json

@@ -0,0 +1,5 @@
+{
+  "gateUnmatched": true,
+  "rules": [{ "channel": "volute:*", "isDM": true, "session": "${channel}" }],
+  "default": "main"
+}

package/templates/agent-sdk/.init/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Mechanics
 
-You are an autonomous agent running as a persistent server in a git repository. Your working directory is `home/` within the project root. Everything described below — your identity, memory, skills, server code — is yours to understand and modify.
+You are an autonomous agent running as a persistent server in a git repository. Your working directory is already set to `home/` — all file paths you use (`.config/routes.json`, `inbox/`, `memory/`, etc.) are relative to it. Everything described below — your identity, memory, skills, server code — is yours to understand and modify.
 
 ## Message Format
 
@@ -33,7 +33,7 @@ See the **memory** skill for detailed guidance.
 
 ## Sessions
 
-- You may have **multiple named sessions** — each maintains its own conversation history. See `VOLUTE.md` for how to configure session routing via `.config/sessions.json`.
+- You may have **multiple named sessions** — each maintains its own conversation history. See `VOLUTE.md` for how to configure session routing via `.config/routes.json`.
 - Your conversation may be **resumed** from a previous session — orient yourself by reading recent journal entries if needed.
 - On a **fresh session**, read `MEMORY.md` and recent journal entries to remember where you left off.
 - On **compaction**, update today's journal to preserve context before the conversation is trimmed.

package/templates/agent-sdk/src/agent.ts

@@ -69,9 +69,10 @@ export function createAgent(options: {
   ];
 
   const sessions = new Map<string, Session>();
+  const today = new Date().toISOString().slice(0, 10);
   const compactionMessage =
     options.compactionMessage ??
-    "Your conversation is approaching its context limit. Please update today's journal entry to preserve important context before the conversation is compacted.";
+    `Context is getting long — compaction is about to summarize this conversation. Before that happens, save anything important to files (MEMORY.md, memory/journal/${today}.md, etc.) since those survive compaction. Focus on: decisions made, open tasks, and anything you'd need to pick up where you left off.`;
 
   // --- Session persistence ---
 

package/templates/agent-sdk/src/server.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createAgent } from "./agent.js";
 import { createFileHandlerResolver } from "./lib/file-handler.js";
@@ -41,13 +41,19 @@ const agent = createAgent({
   onIdentityReload: async () => {
     log("server", "identity file changed — restarting to reload");
     await agent.waitForCommits();
+    // Signal daemon to restart immediately (bypasses crash backoff)
+    try {
+      writeFileSync(resolve(".volute/restart.json"), JSON.stringify({ action: "reload" }));
+    } catch (err) {
+      log("server", "failed to write restart signal:", err);
+    }
     server.close();
     process.exit(0);
   },
 });
 
 const router = createRouter({
-  configPath: resolve("home/.config/sessions.json"),
+  configPath: resolve("home/.config/routes.json"),
   agentHandler: agent.resolve,
   fileHandler: createFileHandlerResolver(resolve("home")),
 });

package/templates/agent-sdk/volute-template.json

@@ -4,6 +4,6 @@
     "biome.json.tmpl": "biome.json",
     "home/.config/volute.json.tmpl": "home/.config/volute.json"
   },
-  "substitute": ["package.json", ".init/SOUL.md"],
+  "substitute": ["package.json", ".init/SOUL.md", "home/.config/routes.json"],
   "skillsDir": "home/.claude/skills"
 }

package/templates/pi/.init/.config/routes.json

@@ -0,0 +1,5 @@
+{
+  "gateUnmatched": true,
+  "rules": [{ "channel": "volute:*", "isDM": true, "session": "${channel}" }],
+  "default": "main"
+}

package/templates/pi/.init/AGENTS.md

@@ -23,7 +23,7 @@ See the **memory** skill for detailed guidance.
 
 ## Sessions
 
-- You may have **multiple named sessions** — each maintains its own conversation history. See `VOLUTE.md` for how to configure session routing via `.config/sessions.json`.
+- You may have **multiple named sessions** — each maintains its own conversation history. See `VOLUTE.md` for how to configure session routing via `.config/routes.json`.
 - Your conversation may be **resumed** from a previous session — orient yourself by reading recent daily logs if needed.
 - On a **fresh session**, read `MEMORY.md` and recent daily logs to remember where you left off.
 - On **compaction**, update today's daily log to preserve context before the conversation is trimmed.

package/templates/pi/src/agent.ts

@@ -32,8 +32,10 @@ type PiSession = {
   currentMessageId?: string;
 };
 
-const DEFAULT_COMPACTION_MESSAGE =
-  "Your conversation is approaching its context limit. Please update today's journal entry to preserve important context before the conversation is compacted.";
+function defaultCompactionMessage(): string {
+  const today = new Date().toISOString().slice(0, 10);
+  return `Context is getting long — compaction is about to summarize this conversation. Before that happens, save anything important to files (MEMORY.md, memory/journal/${today}.md, etc.) since those survive compaction. Focus on: decisions made, open tasks, and anything you'd need to pick up where you left off.`;
+}
 
 function resolveModel(modelStr: string) {
   const [provider, ...rest] = modelStr.split(":");
@@ -75,7 +77,7 @@ export function createAgent(options: {
   compactionMessage?: string;
 }): { resolve: HandlerResolver } {
   const sessions = new Map<string, PiSession>();
-  const compactionMessage = options.compactionMessage ?? DEFAULT_COMPACTION_MESSAGE;
+  const compactionMessage = options.compactionMessage ?? defaultCompactionMessage();
 
   // Shared setup (created once)
   const modelStr = options.model || process.env.PI_MODEL || "anthropic:claude-sonnet-4-20250514";

package/templates/pi/src/server.ts

@@ -29,7 +29,7 @@ const agent = createAgent({
 });
 
 const router = createRouter({
-  configPath: resolve("home/.config/sessions.json"),
+  configPath: resolve("home/.config/routes.json"),
   agentHandler: agent.resolve,
   fileHandler: createFileHandlerResolver(resolve("home")),
 });

package/templates/pi/volute-template.json

@@ -4,6 +4,6 @@
     "biome.json.tmpl": "biome.json",
     "home/.config/volute.json.tmpl": "home/.config/volute.json"
   },
-  "substitute": ["package.json", ".init/SOUL.md"],
+  "substitute": ["package.json", ".init/SOUL.md", "home/.config/routes.json"],
   "skillsDir": "home/.claude/skills"
 }