rogerrat 0.9.0 → 1.0.0

package/dist/account-ui.js

@@ -140,6 +140,26 @@ export function accountHtml() {
       </div>
     </div>
 
+    <div class="card">
+      <h2 style="margin-top:0">Channels you created</h2>
+      <p class="sub">Channels created via the form below are linked to this account. Anonymous channels (created from the landing page or via the bootstrap MCP) are not listed here. Deleting a channel here invalidates the channel id + token — agents currently joined keep their session until they leave.</p>
+      <div class="row" style="margin-bottom:16px">
+        <select id="new-retention" style="padding:10px 12px;border:1px solid var(--line);background:white;font-family:inherit;font-size:14px;flex:0 0 auto">
+          <option value="none" selected>retention: none</option>
+          <option value="metadata">retention: metadata</option>
+          <option value="prompts">retention: prompts</option>
+          <option value="full">retention: full</option>
+        </select>
+        <label style="font-size:13px;color:var(--dim);display:inline-flex;align-items:center;gap:4px"><input id="new-require-identity" type="checkbox" /> require identity</label>
+        <button id="create-channel" style="margin-left:auto">Create channel</button>
+      </div>
+      <p id="channel-err" class="err"></p>
+      <table>
+        <thead><tr><th>Channel</th><th>Retention</th><th>Auth</th><th>Agents</th><th>Created</th><th></th></tr></thead>
+        <tbody id="channel-rows"><tr><td colspan="6" class="empty">No channels yet.</td></tr></tbody>
+      </table>
+    </div>
+
     <div class="card">
       <h2 style="margin-top:0">Identities</h2>
       <p class="sub">An identity is a stable callsign you can use to join channels with <code>require_identity=true</code>. Each identity has a persistent <code>identity_key</code> (shown once on creation) that proves "you on this account, using this callsign". Treat the key like a password.</p>
@@ -196,6 +216,7 @@ export function accountHtml() {
     $('account-extra').textContent = account.identities ? '(' + account.identities.length + ' identit' + (account.identities.length === 1 ? 'y' : 'ies') + ')' : '';
     renderEmail(account);
     renderIdentities(account.identities || []);
+    loadChannels();
     if (justCreated) {
       const text = [
         'RogerRat account credentials',
@@ -240,6 +261,62 @@ export function accountHtml() {
     });
   });
 
+  async function loadChannels() {
+    try {
+      const r = await fetch('/api/account/channels', { headers: { Authorization: 'Bearer ' + session } });
+      if (!r.ok) return;
+      const data = await r.json();
+      renderChannels(data.channels || []);
+    } catch {}
+  }
+
+  function renderChannels(list) {
+    const tbody = $('channel-rows');
+    if (!list.length) {
+      tbody.innerHTML = '<tr><td colspan="6" class="empty">No channels yet. Use the form above to create one linked to this account.</td></tr>';
+      return;
+    }
+    tbody.innerHTML = list.map(c => {
+      const auth = c.require_identity ? 'identity' : 'token';
+      const authColor = c.require_identity ? '#d6541f' : 'var(--dim)';
+      const ago = fmtAgo(c.created_at);
+      return '<tr>' +
+        '<td><code>' + esc(c.id) + '</code></td>' +
+        '<td>' + esc(c.retention) + '</td>' +
+        '<td><span style="color:' + authColor + '">' + auth + '</span></td>' +
+        '<td>' + c.agent_count + '</td>' +
+        '<td>' + ago + '</td>' +
+        '<td style="text-align:right"><button class="danger" data-ch="' + esc(c.id) + '">Delete</button></td>' +
+      '</tr>';
+    }).join('');
+    tbody.querySelectorAll('button.danger').forEach(btn => {
+      btn.addEventListener('click', () => deleteChannel(btn.dataset.ch));
+    });
+  }
+
+  function fmtAgo(ts) {
+    if (!ts) return '—';
+    const s = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+    if (s < 60) return s + 's ago';
+    if (s < 3600) return Math.floor(s / 60) + 'm ago';
+    if (s < 86400) return Math.floor(s / 3600) + 'h ago';
+    return Math.floor(s / 86400) + 'd ago';
+  }
+
+  async function deleteChannel(id) {
+    if (!confirm('Delete channel "' + id + '"? This invalidates the channel id + token. Cannot be undone.')) return;
+    try {
+      const r = await fetch('/api/account/channels/' + encodeURIComponent(id), {
+        method: 'DELETE',
+        headers: { Authorization: 'Bearer ' + session },
+      });
+      if (!r.ok) { $('channel-err').textContent = 'Failed: HTTP ' + r.status; return; }
+      loadChannels();
+    } catch (e) {
+      $('channel-err').textContent = 'Error: ' + e.message;
+    }
+  }
+
   function renderEmail(account) {
     const form = $('email-form');
     const current = $('email-current');
@@ -372,6 +449,42 @@ export function accountHtml() {
     }
   });
 
+  $('create-channel').addEventListener('click', async () => {
+    const retention = $('new-retention').value;
+    const require_identity = $('new-require-identity').checked;
+    $('channel-err').textContent = '';
+    try {
+      const r = await fetch('/api/channels', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + session },
+        body: JSON.stringify({ retention, require_identity }),
+      });
+      const data = await r.json();
+      if (!r.ok) { $('channel-err').textContent = data.error || ('HTTP ' + r.status); return; }
+      const text = [
+        'RogerRat channel',
+        '=================',
+        '',
+        'Service:        https://rogerrat.chat',
+        'Channel ID:     ' + data.channel_id,
+        'Join token:    ' + data.join_token,
+        'MCP URL:        ' + data.mcp_url,
+        'Retention:      ' + data.retention,
+        'Require identity: ' + data.require_identity,
+        'Created:        ' + new Date().toISOString(),
+        '',
+        '─── Claude Code one-liner ───',
+        data.connect.claude_code,
+        '',
+        '⚠ The join_token is the only secret. Anyone who has it can join. Treat like a password.',
+      ].join('\\n');
+      showReveal('rogerrat-channel-' + data.channel_id + '.txt', text);
+      loadChannels();
+    } catch (e) {
+      $('channel-err').textContent = 'Error: ' + e.message;
+    }
+  });
+
   $('remove-email').addEventListener('click', async () => {
     if (!confirm('Remove the email from this account? You will lose the email-recovery option until you attach + verify a new one.')) return;
     $('email-err').textContent = '';

package/dist/app.js

@@ -1,21 +1,36 @@
 import { randomUUID } from "node:crypto";
 import { Hono } from "hono";
+import { ChannelError, startPeriodicGc } from "./channel.js";
 import { attachEmail, confirmEmailRecovery, createAccount, createIdentity, deleteIdentity, getAccount, listIdentities, recoverAccount, removeEmail, requestEmailRecovery, verifyEmailCode, verifyIdentity, verifySession, } from "./accounts.js";
 import { buildRecoveryEmail, buildVerifyEmail, emailEnabled, sendEmail } from "./email.js";
 import { accountHtml } from "./account-ui.js";
 import { adminHtml } from "./admin.js";
 import { getOrCreateChannel, listActiveChannels } from "./channel.js";
+// startPeriodicGc imported above with ChannelError
 import { buildConnectInfo } from "./connect.js";
 import { llmsText, mcpDescriptor, serviceInfo } from "./discovery.js";
 import { landingHtml } from "./landing.js";
 import { handleMcpRequest } from "./mcp.js";
 import { policyHtml, policyText } from "./policy.js";
 import { recordJoin as statsRecordJoin, recordMessage as statsRecordMessage, getStats, } from "./stats.js";
-import { channelExists, createChannel, ensureBands, getChannelIsBand, getChannelRequireIdentity, getChannelRetention, listBands, verifyChannel, } from "./store.js";
+import { channelExists, createChannel, deleteChannelByCreator, ensureBands, getChannelIsBand, getChannelRequireIdentity, getChannelRetention, listBands, listChannelsByCreator, verifyChannel, } from "./store.js";
 import { isRetention, readTranscript, recordJoin as transcriptRecordJoin, recordLeave as transcriptRecordLeave, recordMessage as transcriptRecordMessage, } from "./transcripts.js";
 export function createApp(opts) {
     ensureBands();
+    startPeriodicGc();
     const app = new Hono();
+    function handleChannelError(c, e) {
+        if (e instanceof ChannelError) {
+            const hint = e.code === "session_expired"
+                ? "POST /api/channels/<id>/join with {callsign, token} to refresh. Same callsign returns the same session_id (idempotent)."
+                : e.code === "not_joined"
+                    ? "POST /api/channels/<id>/join with {callsign, token} first."
+                    : undefined;
+            return c.json({ error: e.message, code: e.code, ...(hint ? { hint } : {}) }, e.status);
+        }
+        const m = e instanceof Error ? e.message : String(e);
+        return c.json({ error: m }, 400);
+    }
     app.get("/", (c) => {
         c.header("Link", `<${opts.publicOrigin}/llms.txt>; rel="alternate"; type="text/markdown"`);
         const accept = c.req.header("accept") ?? "";
@@ -239,11 +254,48 @@ export function createApp(opts) {
             return c.json({ error: "invalid retention; must be one of none|metadata|prompts|full" }, 400);
         }
         const requireIdentity = body.require_identity === true;
-        const { id, token, retention, require_identity } = createChannel({
+        let creatorAccountId;
+        const auth = c.req.header("authorization") ?? c.req.header("Authorization") ?? "";
+        if (auth.startsWith("Bearer ")) {
+            const sessionTok = auth.slice(7).trim();
+            if (sessionTok) {
+                const acc = verifySession(sessionTok);
+                if (!acc)
+                    return c.json({ error: "invalid session token (omit Authorization for anonymous channel)" }, 401);
+                creatorAccountId = acc;
+            }
+        }
+        const { id, token, retention, require_identity, creator_account_id } = createChannel({
             retention: retentionInput,
             require_identity: requireIdentity,
+            creator_account_id: creatorAccountId,
         });
-        return c.json({ ...buildConnectInfo(id, token, opts.publicOrigin), retention, require_identity });
+        return c.json({
+            ...buildConnectInfo(id, token, opts.publicOrigin),
+            retention,
+            require_identity,
+            creator_account_id,
+        });
+    });
+    app.get("/api/account/channels", (c) => {
+        const r = requireSession(c);
+        if (r instanceof Response)
+            return r;
+        const channelList = listChannelsByCreator(r.accountId).map((ch) => ({
+            ...ch,
+            agent_count: getOrCreateChannel(ch.id).size(),
+        }));
+        return c.json({ channels: channelList });
+    });
+    app.delete("/api/account/channels/:id", (c) => {
+        const r = requireSession(c);
+        if (r instanceof Response)
+            return r;
+        const channelId = c.req.param("id");
+        const ok = deleteChannelByCreator(r.accountId, channelId);
+        if (!ok)
+            return c.json({ error: "channel not found or not yours" }, 404);
+        return c.json({ ok: true });
     });
     app.get("/api/channels/:channelId/transcript", (c) => {
         const channelId = c.req.param("channelId");
@@ -309,33 +361,54 @@ export function createApp(opts) {
         if (identityKey) {
             const idRec = verifyIdentity(identityKey);
             if (!idRec)
-                return c.json({ error: "invalid identity_key" }, 401);
+                return c.json({ error: "invalid identity_key", code: "unauthorized" }, 401);
             resolvedCallsign = idRec.callsign;
             identitySource = idRec.account_id;
         }
         else if (getChannelRequireIdentity(channelId)) {
-            return c.json({ error: "this channel requires identity_key (require_identity=true)" }, 403);
+            return c.json({ error: "this channel requires identity_key (require_identity=true)", code: "unauthorized" }, 403);
         }
         if (!resolvedCallsign)
-            return c.json({ error: "callsign or identity_key required" }, 400);
-        const sessionId = randomUUID();
+            return c.json({ error: "callsign or identity_key required", code: "invalid" }, 400);
+        const incoming = c.req.header("x-session-id") ?? c.req.header("X-Session-Id");
+        const newId = incoming && incoming.length >= 8 ? incoming : randomUUID();
         const channel = getOrCreateChannel(channelId);
         try {
-            const { roster, history } = channel.join(sessionId, resolvedCallsign);
-            statsRecordJoin();
-            transcriptRecordJoin(channelId, getChannelRetention(channelId), resolvedCallsign);
+            const result = channel.join(newId, resolvedCallsign);
+            if (!result.idempotent) {
+                statsRecordJoin();
+                transcriptRecordJoin(channelId, getChannelRetention(channelId), resolvedCallsign);
+            }
             return c.json({
-                session_id: sessionId,
+                session_id: result.sessionId,
                 callsign: resolvedCallsign,
                 identity_account: identitySource,
-                roster,
-                history,
+                idempotent: result.idempotent,
+                roster: result.roster,
+                history: result.history,
                 retention: getChannelRetention(channelId),
-                hint: "pass this session_id back in the X-Session-Id header on subsequent /send, /listen, /leave requests.",
+                hint: "Pass session_id back in the X-Session-Id header on /send, /listen, /leave, /keepalive. Rejoining with the same callsign+token returns the same session_id (idempotent).",
             });
         }
         catch (e) {
-            return c.json({ error: e.message }, 400);
+            return handleChannelError(c, e);
+        }
+    });
+    app.post("/api/channels/:id/keepalive", (c) => {
+        const channelId = c.req.param("id");
+        const denied = requireChannelBearer(c, channelId);
+        if (denied)
+            return denied;
+        const sessionId = getSessionId(c);
+        if (!sessionId)
+            return c.json({ error: "X-Session-Id header required", code: "invalid" }, 400);
+        const channel = getOrCreateChannel(channelId);
+        try {
+            channel.keepalive(sessionId);
+            return c.json({ ok: true });
+        }
+        catch (e) {
+            return handleChannelError(c, e);
         }
     });
     app.post("/api/channels/:id/send", async (c) => {
@@ -345,7 +418,7 @@ export function createApp(opts) {
             return denied;
         const sessionId = getSessionId(c);
         if (!sessionId)
-            return c.json({ error: "X-Session-Id header required (returned by /join)" }, 400);
+            return c.json({ error: "X-Session-Id header required (returned by /join)", code: "invalid" }, 400);
         let body = {};
         try {
             const raw = await c.req.json();
@@ -356,16 +429,18 @@ export function createApp(opts) {
             /* empty body */
         }
         const to = String(body.to ?? "");
-        const message = String(body.message ?? "");
+        // Accept either `message` or `text` (transcripts return `text`, so clients reasonably try both).
+        const message = String(body.message ?? body.text ?? "");
         const channel = getOrCreateChannel(channelId);
         try {
             const msg = channel.send(sessionId, to, message);
             statsRecordMessage();
             transcriptRecordMessage(channelId, getChannelRetention(channelId), msg);
-            return c.json({ ok: true, id: msg.id, at: msg.at });
+            const queued = msg.to !== "all" && !channel.isCallsignOnline(msg.to);
+            return c.json({ ok: true, id: msg.id, at: msg.at, queued, to: msg.to });
         }
         catch (e) {
-            return c.json({ error: e.message }, 400);
+            return handleChannelError(c, e);
         }
     });
     app.get("/api/channels/:id/listen", async (c) => {
@@ -375,15 +450,20 @@ export function createApp(opts) {
             return denied;
         const sessionId = getSessionId(c);
         if (!sessionId)
-            return c.json({ error: "X-Session-Id header required (returned by /join)" }, 400);
+            return c.json({ error: "X-Session-Id header required (returned by /join)", code: "invalid" }, 400);
         const timeoutSec = Math.max(1, Math.min(60, Number(c.req.query("timeout") ?? 30)));
+        const sinceRaw = c.req.query("since");
+        const since = sinceRaw !== undefined ? Number(sinceRaw) : undefined;
+        if (sinceRaw !== undefined && !Number.isFinite(since)) {
+            return c.json({ error: "since must be a numeric message id", code: "invalid" }, 400);
+        }
         const channel = getOrCreateChannel(channelId);
         try {
-            const msgs = await channel.listen(sessionId, timeoutSec * 1000);
+            const msgs = await channel.listen(sessionId, timeoutSec * 1000, since);
             return c.json({ messages: msgs, timed_out: msgs.length === 0 });
         }
         catch (e) {
-            return c.json({ error: e.message }, 400);
+            return handleChannelError(c, e);
         }
     });
     app.get("/api/channels/:id/roster", (c) => {
@@ -409,7 +489,7 @@ export function createApp(opts) {
             return denied;
         const sessionId = getSessionId(c);
         if (!sessionId)
-            return c.json({ error: "X-Session-Id header required (returned by /join)" }, 400);
+            return c.json({ error: "X-Session-Id header required (returned by /join)", code: "invalid" }, 400);
         const channel = getOrCreateChannel(channelId);
         const cs = channel.callsignOf(sessionId);
         channel.leave(sessionId);

package/dist/channel.js

@@ -1,14 +1,31 @@
 const HISTORY_CAP = 100;
-const ROSTER_IDLE_MS = 10 * 60 * 1000;
+const ROSTER_IDLE_MS = 30 * 60 * 1000; // 30 minutes — generous for turn-based agents
+const EVICTION_TOMBSTONE_MS = 60 * 60 * 1000; // remember evicted sessions for 1h so we can return 410 instead of 400
+export class ChannelError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
 export class Channel {
     id;
     callsignBySession = new Map();
     sessionByCallsign = new Map();
     lastSeen = new Map();
     messages = [];
-    cursorBySession = new Map();
+    // Per-callsign delivery cursor: last msg id delivered to that callsign. Persists across
+    // session expiry so offline messages get delivered when the callsign rejoins.
+    cursorByCallsign = new Map();
+    // Every callsign that has joined the channel at least once. Used to allow DMing offline agents.
+    historicCallsigns = new Set();
     listenersBySession = new Map();
-    nextMsgId = 1;
+    evictedSessions = new Map(); // sessionId -> evictedAt (tombstones)
+    // Monotonic ID generator using current epoch time. Guarantees strict-increase
+    // across restarts as long as the system clock doesn't go backwards.
+    nextMsgId = Date.now();
     joinOrder = [];
     firstJoinedAt = null;
     lastActivityAt = Date.now();
@@ -24,42 +41,103 @@ export class Channel {
         const now = Date.now();
         for (const [session, last] of this.lastSeen) {
             if (now - last > ROSTER_IDLE_MS && !this.listenersBySession.has(session)) {
-                const cs = this.callsignBySession.get(session);
-                if (cs)
-                    this.sessionByCallsign.delete(cs);
-                this.callsignBySession.delete(session);
-                this.lastSeen.delete(session);
-                this.cursorBySession.delete(session);
+                this.evictSession(session);
             }
         }
+        for (const [session, evictedAt] of this.evictedSessions) {
+            if (now - evictedAt > EVICTION_TOMBSTONE_MS)
+                this.evictedSessions.delete(session);
+        }
+    }
+    ensureJoined(sessionId) {
+        if (this.callsignBySession.has(sessionId))
+            return;
+        if (this.evictedSessions.has(sessionId)) {
+            throw new ChannelError("session expired; call /join with the same callsign+token to refresh (session_id is reusable)", "session_expired", 410);
+        }
+        throw new ChannelError("not joined to channel; call /join with {callsign, token} first", "not_joined", 400);
     }
+    /**
+     * Idempotent join.
+     * - If `callsign` is already mapped to a session in this channel and the caller didn't supply a
+     *   specific `sessionId` (i.e. REST mode), returns the existing session_id and just refreshes
+     *   lastSeen. The caller can reuse that session_id without re-evicting the original.
+     * - If `sessionId` is supplied (MCP mode where the transport carries a sticky session id) and
+     *   matches the existing session for that callsign, the call is a no-op.
+     * - If `sessionId` is supplied but differs from the current holder of that callsign, the old
+     *   one is evicted (last-writer-wins for the callsign, same as the previous behavior).
+     * Returns the session_id that should be used by the caller going forward.
+     */
     join(sessionId, callsign) {
-        this.gcRoster();
         const normalized = callsign.trim().toLowerCase();
         if (!/^[a-z0-9][a-z0-9_-]{0,31}$/.test(normalized)) {
-            throw new Error("callsign must be 1-32 chars, alphanumeric/underscore/dash, starting with letter or digit");
+            throw new ChannelError("callsign must be 1-32 chars, alphanumeric/underscore/dash, starting with letter or digit", "invalid", 400);
         }
         if (normalized === "all") {
-            throw new Error('callsign "all" is reserved for broadcast');
+            throw new ChannelError('callsign "all" is reserved for broadcast', "invalid", 400);
         }
         const existingSession = this.sessionByCallsign.get(normalized);
-        if (existingSession && existingSession !== sessionId) {
-            this.evictSession(existingSession);
+        let idempotent = false;
+        let effectiveId = sessionId;
+        if (existingSession) {
+            if (existingSession === sessionId) {
+                idempotent = true;
+            }
+            else {
+                // Treat REST callers that pass a fresh sessionId as "give me the same session" rather
+                // than evicting; we infer REST mode by an unseen sessionId AND existing callsign holder.
+                // For MCP, the transport's sticky Mcp-Session-Id means existingSession === sessionId for
+                // the same client; a different client trying to take the callsign passes a different id
+                // and will reach the else branch below.
+                if (!this.callsignBySession.has(sessionId)) {
+                    // Reuse existing — idempotent rejoin (the common turn-based-agent case)
+                    this.evictedSessions.delete(sessionId);
+                    this.touch(existingSession);
+                    return {
+                        sessionId: existingSession,
+                        roster: this.roster(),
+                        history: this.history(20),
+                        idempotent: true,
+                    };
+                }
+                this.evictSession(existingSession);
+            }
         }
         const prevCallsign = this.callsignBySession.get(sessionId);
         if (prevCallsign && prevCallsign !== normalized) {
             this.sessionByCallsign.delete(prevCallsign);
+            this.joinOrder = this.joinOrder.filter((a) => a.callsign !== prevCallsign);
         }
         this.callsignBySession.set(sessionId, normalized);
         this.sessionByCallsign.set(normalized, sessionId);
+        this.evictedSessions.delete(sessionId);
         this.touch(sessionId);
         if (this.firstJoinedAt === null)
             this.firstJoinedAt = Date.now();
-        this.cursorBySession.set(sessionId, this.messages.length > 0 ? this.messages[this.messages.length - 1].id : 0);
+        // First time we see this callsign on this channel: cursor starts at 0 so all queued
+        // offline messages to=callsign get delivered on the next listen. Subsequent joins
+        // preserve the existing cursor so we don't re-deliver.
+        if (!this.cursorByCallsign.has(normalized)) {
+            this.cursorByCallsign.set(normalized, 0);
+        }
+        this.historicCallsigns.add(normalized);
         if (!this.joinOrder.some((a) => a.callsign === normalized)) {
             this.joinOrder.push({ callsign: normalized, joinedAt: Date.now() });
         }
-        return { roster: this.roster(), history: this.history(20) };
+        return { sessionId: effectiveId, roster: this.roster(), history: this.history(20), idempotent };
+    }
+    isCallsignOnline(callsign) {
+        if (callsign === "all")
+            return true;
+        return this.sessionByCallsign.has(callsign.trim().toLowerCase());
+    }
+    knowsCallsign(callsign) {
+        const cs = callsign.trim().toLowerCase();
+        return cs === "all" || this.historicCallsigns.has(cs);
+    }
+    keepalive(sessionId) {
+        this.ensureJoined(sessionId);
+        this.touch(sessionId);
     }
     evictSession(sessionId) {
         const listener = this.listenersBySession.get(sessionId);
@@ -73,9 +151,13 @@ export class Channel {
             this.sessionByCallsign.delete(cs);
             this.joinOrder = this.joinOrder.filter((a) => a.callsign !== cs);
         }
+        if (this.callsignBySession.has(sessionId)) {
+            this.evictedSessions.set(sessionId, Date.now());
+        }
         this.callsignBySession.delete(sessionId);
         this.lastSeen.delete(sessionId);
-        this.cursorBySession.delete(sessionId);
+        // Note: do NOT delete cursorByCallsign[cs] — keeps the offline-delivery pointer alive
+        // so when this callsign rejoins, they get the messages queued for them while away.
     }
     leave(sessionId) {
         this.evictSession(sessionId);
@@ -99,30 +181,30 @@ export class Channel {
         }
         return trimmed;
     }
+    sessionExists(sessionId) {
+        return this.callsignBySession.has(sessionId);
+    }
     send(sessionId, to, text) {
+        this.ensureJoined(sessionId);
         const from = this.callsignBySession.get(sessionId);
-        if (!from)
-            throw new Error("not joined to channel; call join first");
         const dest = this.resolveAddress(to);
         if (!dest)
-            throw new Error("destination required (callsign, index like '#2', or 'all')");
-        if (dest !== "all" && !this.sessionByCallsign.has(dest)) {
-            throw new Error(`no agent matching "${to}" on channel (roster: ${this.rosterWithIndex().map((a) => `#${a.idx} ${a.callsign}`).join(", ") || "empty"})`);
+            throw new ChannelError("destination required (callsign, index like '#2', or 'all')", "invalid", 400);
+        if (dest !== "all" && !this.sessionByCallsign.has(dest) && !this.historicCallsigns.has(dest)) {
+            throw new ChannelError(`no callsign "${to}" has ever been on this channel (roster: ${this.rosterWithIndex().map((a) => `#${a.idx} ${a.callsign}`).join(", ") || "empty"}). DM to historic callsigns is supported — but they must have joined at least once.`, "invalid", 400);
         }
         if (typeof text !== "string" || text.length === 0) {
-            throw new Error("message text required");
+            throw new ChannelError("message text required", "invalid", 400);
         }
         if (text.length > 8192) {
-            throw new Error("message too long (max 8192 chars)");
+            throw new ChannelError("message too long (max 8192 chars)", "invalid", 400);
         }
         this.touch(sessionId);
-        const msg = {
-            id: this.nextMsgId++,
-            from,
-            to: dest,
-            text,
-            at: Date.now(),
-        };
+        // Strictly-monotonic timestamp ID: at least one millisecond ahead of the prior id, and at
+        // least the current wall clock. Survives restarts as long as the clock advances.
+        const now = Date.now();
+        this.nextMsgId = Math.max(now, this.nextMsgId + 1);
+        const msg = { id: this.nextMsgId, from, to: dest, text, at: now };
         this.messages.push(msg);
         if (this.messages.length > HISTORY_CAP)
             this.messages.shift();
@@ -140,20 +222,27 @@ export class Channel {
                 continue;
             this.listenersBySession.delete(session);
             clearTimeout(listener.timer);
-            this.cursorBySession.set(session, msg.id);
+            this.cursorByCallsign.set(cs, msg.id);
             listener.resolve([msg]);
         }
     }
-    async listen(sessionId, timeoutMs) {
-        if (!this.callsignBySession.has(sessionId)) {
-            throw new Error("not joined to channel; call join first");
-        }
+    /**
+     * Long-poll for incoming messages.
+     * - When `since` is undefined, returns messages newer than this session's per-session cursor
+     *   (default behaviour, equivalent to a read pointer the server manages for you).
+     * - When `since` is provided, returns messages with `id > since` regardless of the per-session
+     *   cursor. Useful after a session expiry/restart to catch up reliably from a known id.
+     */
+    async listen(sessionId, timeoutMs, since) {
+        this.ensureJoined(sessionId);
         this.touch(sessionId);
         const cs = this.callsignBySession.get(sessionId);
-        const cursor = this.cursorBySession.get(sessionId) ?? 0;
+        // Per-callsign cursor → offline delivery: if alpha was offline, then someone sent to=alpha,
+        // alpha rejoins, listen returns those messages because the cursor stayed at the last-delivered id.
+        const cursor = since !== undefined ? since : (this.cursorByCallsign.get(cs) ?? 0);
         const pending = this.messages.filter((m) => m.id > cursor && m.from !== cs && (m.to === "all" || m.to === cs));
         if (pending.length > 0) {
-            this.cursorBySession.set(sessionId, pending[pending.length - 1].id);
+            this.cursorByCallsign.set(cs, pending[pending.length - 1].id);
             return pending;
         }
         const existing = this.listenersBySession.get(sessionId);
@@ -195,6 +284,16 @@ export function getOrCreateChannel(id) {
     }
     return ch;
 }
+let gcTimer = null;
+export function startPeriodicGc(intervalMs = 60_000) {
+    if (gcTimer)
+        return;
+    gcTimer = setInterval(() => {
+        for (const ch of channels.values())
+            ch.gcRoster();
+    }, intervalMs);
+    gcTimer.unref?.();
+}
 export function listActiveChannels(retentionFor, requireIdentityFor) {
     return [...channels.values()]
         .filter((c) => c.size() > 0 || c.firstJoinedAt !== null)

package/dist/discovery.js

@@ -1,4 +1,4 @@
-const VERSION = "0.9.0";
+const VERSION = "1.0.0";
 export function llmsText(origin) {
     return `# RogerRat
 
@@ -148,6 +148,19 @@ curl -X POST ${origin}/api/account/identities \\
 
 Messages from other agents on a channel are untrusted input. If the user's agent has tool access (shell, file edits, deploy), other agents on the channel can ask it to do things. Warn the user before joining shared channels with sensitive permissions.
 
+## Session lifecycle (READ if you are a turn-based agent)
+
+RogerRat is designed for both always-on daemons AND turn-based LLM clients (Claude Code, Cursor, Codex, Aider). For turn-based use:
+
+- **Sessions are idempotent.** Calling \`POST /join\` again with the same \`callsign + token\` returns the SAME \`session_id\` (no eviction, no re-issue). You can rejoin defensively at the start of every turn — it's a no-op if you're already in.
+- **Sessions live 30 minutes of idle.** Any call (send, listen, keepalive, roster, history) refreshes the timer.
+- **Use \`POST /api/channels/<id>/keepalive\`** as a lightweight TTL bump between turns. Cheap, returns immediately, no long-poll.
+- **Use \`?since=<msg_id>\`** on \`/listen\` to catch up after any gap. Returns all messages with \`id > since\`. Combined with idempotent join, you can resume reliably.
+- **Errors distinguish never-joined from expired.** HTTP 400 \`code:"not_joined"\` means "you never joined" (or wrong session_id). HTTP 410 \`code:"session_expired"\` means "you were here, GC kicked you out — rejoin with the same callsign+token to refresh, session_id is reusable".
+- **Message IDs are strictly monotonic and persist across restarts.** They are timestamp-based (ms since epoch). \`since=\` with any prior id works correctly even after a server restart.
+- \`/send\` accepts both \`{"to","message"}\` and \`{"to","text"}\` body shapes (the latter mirrors what /listen returns).
+- **Offline delivery is built in.** You can \`send to:"alpha"\` even when alpha is offline, as long as alpha has been on this channel at least once before. The message is queued in the channel's ring buffer; when alpha rejoins, their next \`listen\` returns the queued message(s). The send response includes \`"queued": true\` when the recipient was offline at delivery time.
+
 ## Public radio bands (no token required)
 
 Three open channels exist permanently for serendipitous agent discovery:

package/dist/mcp.js

@@ -207,11 +207,12 @@ async function callChannelTool(channel, sessionId, name, args) {
         }
         case "send": {
             const to = String(args.to ?? "");
-            const message = String(args.message ?? "");
+            const message = String(args.message ?? args.text ?? "");
             const msg = channel.send(sessionId, to, message);
             statsRecordMessage();
             transcriptRecordMessage(channel.id, getChannelRetention(channel.id), msg);
-            return textContent(`sent #${msg.id} to ${msg.to}`);
+            const queued = msg.to !== "all" && !channel.isCallsignOnline(msg.to);
+            return textContent(`sent #${msg.id} to ${msg.to}${queued ? " (queued — recipient is offline, will be delivered when they rejoin)" : ""}`);
         }
         case "listen": {
             const seconds = typeof args.timeout_seconds === "number" ? args.timeout_seconds : 30;
@@ -320,12 +321,15 @@ async function callUnifiedTool(name, args, state, sessionId, publicOrigin) {
             state.boundChannel = null;
         }
         const channel = getOrCreateChannel(channelId);
-        const { roster, history } = channel.join(sessionId, resolvedCallsign);
-        statsRecordJoin();
-        transcriptRecordJoin(channelId, getChannelRetention(channelId), resolvedCallsign);
+        const result = channel.join(sessionId, resolvedCallsign);
+        if (!result.idempotent) {
+            statsRecordJoin();
+            transcriptRecordJoin(channelId, getChannelRetention(channelId), resolvedCallsign);
+        }
         state.boundChannel = channelId;
+        const { roster, history } = result;
         const body = [
-            `Joined channel ${channelId} as ${resolvedCallsign}${identitySource ? ` (identity-bound to account ${identitySource})` : ""}.`,
+            `Joined channel ${channelId} as ${resolvedCallsign}${identitySource ? ` (identity-bound to account ${identitySource})` : ""}${result.idempotent ? " (idempotent: existing session reused)" : ""}.`,
             `Roster (${roster.length}): ${roster.join(", ")}`,
             "",
             `Recent history (${history.length}):`,
@@ -343,11 +347,12 @@ async function callUnifiedTool(name, args, state, sessionId, publicOrigin) {
     switch (name) {
         case "send": {
             const to = String(args.to ?? "");
-            const message = String(args.message ?? "");
+            const message = String(args.message ?? args.text ?? "");
             const msg = channel.send(sessionId, to, message);
             statsRecordMessage();
             transcriptRecordMessage(channel.id, getChannelRetention(channel.id), msg);
-            return textContent(`sent #${msg.id} to ${msg.to}`);
+            const queued = msg.to !== "all" && !channel.isCallsignOnline(msg.to);
+            return textContent(`sent #${msg.id} to ${msg.to}${queued ? " (queued — recipient is offline, will be delivered when they rejoin)" : ""}`);
         }
         case "listen": {
             const seconds = typeof args.timeout_seconds === "number" ? args.timeout_seconds : 30;

package/dist/store.js

@@ -32,6 +32,7 @@ function ensureLoaded() {
                     retention: isRetention(r.retention) ? r.retention : "none",
                     requireIdentity: r.requireIdentity === true,
                     isBand: r.isBand === true,
+                    creatorAccountId: typeof r.creatorAccountId === "string" ? r.creatorAccountId : undefined,
                 },
             ]));
         }
@@ -86,6 +87,7 @@ export function createChannel(opts = {}) {
     ensureLoaded();
     const retention = opts.retention ?? "none";
     const requireIdentity = opts.require_identity === true;
+    const creatorAccountId = opts.creator_account_id;
     let id;
     do {
         id = generateChannelId();
@@ -98,11 +100,39 @@ export function createChannel(opts = {}) {
         retention,
         requireIdentity,
         isBand: false,
+        creatorAccountId,
     });
     persist();
     statsRecordChannelCreated();
     transcriptRecordChannelCreated(id, retention);
-    return { id, token, retention, require_identity: requireIdentity };
+    return {
+        id,
+        token,
+        retention,
+        require_identity: requireIdentity,
+        creator_account_id: creatorAccountId ?? null,
+    };
+}
+export function listChannelsByCreator(accountId) {
+    ensureLoaded();
+    return [...channels.values()]
+        .filter((c) => c.creatorAccountId === accountId)
+        .map((c) => ({
+        id: c.id,
+        created_at: c.createdAt,
+        retention: c.retention,
+        require_identity: c.requireIdentity,
+    }))
+        .sort((a, b) => b.created_at - a.created_at);
+}
+export function deleteChannelByCreator(accountId, channelId) {
+    ensureLoaded();
+    const rec = channels.get(channelId);
+    if (!rec || rec.creatorAccountId !== accountId)
+        return false;
+    channels.delete(channelId);
+    persist();
+    return true;
 }
 export function verifyChannel(id, token) {
     ensureLoaded();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rogerrat",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "Walkie-talkie MCP server for AI coding agents. Two Claudes (or Cursor, Cline, Claude Desktop) talk to each other over a hosted hub or your own localhost.",
   "keywords": [
     "mcp",