@mnemom/mnemom 0.17.25 → 0.17.26

package/dist/lib/slack-router.js

@@ -6,15 +6,37 @@
  * connection per session would silently drop messages). For every channel
  * message it asks lib/slack-route.ts who is addressed and appends the message to
  * each addressed session's inbox (lib/slack-state.ts); each session's listener
- * delivers from there. The router never writes to a session, never runs a tool,
- * and holds no state beyond an in-memory user-name cache.
+ * delivers from there. A routing made by address (mention, handle, alias) is
+ * recorded so later replies in that thread stick to the same session. The router
+ * never writes to a session, never runs a tool, and holds no state beyond an
+ * in-memory user-name cache.
  */
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { fetchThread, formatThread, messageBody, slackCall, } from "./slack.js";
-import { buildThreadIndex, routeMessage, stripAddressing, } from "./slack-route.js";
-import { appendInbox, liveSessions, readPosts, slackDir } from "./slack-state.js";
+import { buildThreadIndex, normSession, routeHits, stripAddressing, } from "./slack-route.js";
+import { appendInbox, inboxSize, listAliases, liveSessions, PENDING_TTL_MS, readAliases, readPosts, readThreadRecords, recordPending, recordRoute, settlePending, slackDir, } from "./slack-state.js";
+/** How often the router settles held messages (delivered / expired). */
+export const PENDING_SWEEP_MS = 30_000;
+const ttlText = () => `${Math.round(PENDING_TTL_MS / 60_000)} min`;
+/**
+ * Settle the held messages (see settlePending) and tell the sender of each expired
+ * one, in its thread, that it was not delivered. Best effort: a failed post is
+ * logged, never retried (the message is already dropped from the queue).
+ */
+export async function sweepPending(opts) {
+    const r = settlePending(opts.now ?? Date.now());
+    for (const p of r.expired) {
+        const res = await slackCall("chat.postMessage", opts.botToken, {
+            channel: p.channel,
+            thread_ts: p.thread_ts,
+            text: `<@${p.user}> not delivered: \`${p.session}\` did not pick this up within ${ttlText()}. Send it again once that session is running, or address another one.`,
+        }, opts.fetchImpl ?? fetch).catch((e) => ({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+        opts.log?.(`undelivered ${p.channel}/${p.ts} → ${p.session}${res.ok ? "" : ` (notice failed: ${String(res.error)})`}`);
+    }
+    return { delivered: r.delivered.length, expired: r.expired.length, held: r.held.length };
+}
 const routerPidFile = () => join(slackDir(), "router.pid");
 function pidAlive(pid) {
     try {
@@ -53,6 +75,8 @@ export function ensureRouter(argv = [process.execPath, process.argv[1] ?? "mnemo
 }
 /** Run the router until the process is killed. Reconnects on disconnect. */
 export async function runRouter(opts) {
+    const aliasesOn = opts.aliases === true;
+    const stickyOn = opts.stickyThreads === true;
     // Lines carry Slack-supplied values (channel, handles, disconnect reason);
     // strip CR/LF so a crafted message cannot forge extra log lines.
     const log = opts.log ?? ((l) => console.error(`[slack-router] ${l.replace(/\n|\r/g, "")}`));
@@ -69,6 +93,14 @@ export async function runRouter(opts) {
         throw new Error(`a router is already running (pid ${other}).`);
     mkdirSync(slackDir(), { recursive: true, mode: 0o700 });
     writeFileSync(routerPidFile(), String(process.pid), { mode: 0o600 });
+    log(`aliases ${aliasesOn ? "on" : "off"}, sticky threads ${stickyOn ? "on" : "off"}`);
+    if (aliasesOn) {
+        const sweep = setInterval(() => {
+            sweepPending({ botToken: opts.botToken, fetchImpl, log }).catch((e) => log(`pending sweep failed: ${e instanceof Error ? e.message : e}`));
+        }, opts.sweepMs ?? PENDING_SWEEP_MS);
+        sweep.unref();
+        opts.signal?.addEventListener("abort", () => clearInterval(sweep));
+    }
     const names = new Map();
     const userName = async (id) => {
         if (names.has(id))
@@ -99,12 +131,14 @@ export async function runRouter(opts) {
         if (!ev.user || !opts.allow.includes(ev.user))
             return;
         const live = liveSessions();
-        const threads = buildThreadIndex(readPosts());
-        const targets = routeMessage(ev, { botUserId, liveSessions: live, threads });
-        if (!targets.length) {
+        const aliases = aliasesOn ? readAliases() : new Map();
+        const threads = buildThreadIndex(stickyOn ? readThreadRecords(Date.now(), { live, aliases }) : readPosts());
+        const hits = routeHits(ev, { botUserId, liveSessions: live, threads, aliases });
+        if (!hits.length) {
             if (ev.text?.includes(`<@${botUserId}>`) && !ev.bot_id) {
-                const hint = live.length
-                    ? `No live session matched. Address one as \`@<app> <session>: …\` — live now: ${live.map((s) => `\`${s}\``).join(", ")}.`
+                const handles = aliasesOn ? listAliases().map((a) => `\`@${a.handle}\``) : [];
+                const hint = live.length || handles.length
+                    ? `No live session matched. Address one as \`@<app> <session>: …\` — live now: ${live.length ? live.map((s) => `\`${s}\``).join(", ") : "none"}${handles.length ? `; handles: ${handles.join(", ")}` : ""}.`
                     : "No agent session is listening right now.";
                 // Ephemeral: only the sender sees the hint, so a mistyped address never
                 // leaves a permanent post in the thread for everyone else.
@@ -119,7 +153,7 @@ export async function runRouter(opts) {
         const user_name = await userName(user);
         const text = messageBody({
             ts,
-            text: stripAddressing(ev.text ?? "", botUserId, live),
+            text: stripAddressing(ev.text ?? "", botUserId, live, aliases),
             files: ev.files,
         });
         // A thread reply carries the thread so far: "review this" means nothing
@@ -143,12 +177,24 @@ export async function runRouter(opts) {
                 log(`thread context unavailable for ${channel}/${ev.thread_ts}: ${e instanceof Error ? e.message : e}`);
             }
         }
-        for (const session of targets) {
+        const mentioned = (ev.text ?? "").includes(`<@${botUserId}>`);
+        // Which sessions THIS message addresses (as opposed to inherits from the thread).
+        const addressed = new Map(routeHits({ ...ev, thread_ts: undefined }, { botUserId, liveSessions: live, threads, aliases }).map((h) => [h.session, h]));
+        const liveNow = new Set(live.map(normSession));
+        const waitingFor = [];
+        for (const { session, for: handle } of hits) {
+            // Not listening: hold it (aliases on) so it is delivered when the session
+            // reads its inbox, or reported undelivered — never left unread in silence.
+            const held = aliasesOn && !liveNow.has(normSession(session));
+            const at = new Date().toISOString();
+            const start = held ? inboxSize(session) : 0;
             const via = [];
             if (inThread?.has(session))
                 via.push("thread");
-            if ((ev.text ?? "").includes(`<@${botUserId}>`))
+            if (mentioned)
                 via.push("mention");
+            if (addressed.get(session)?.for)
+                via.push("alias");
             if (!via.length)
                 via.push("handle");
             appendInbox(session, {
@@ -159,9 +205,48 @@ export async function runRouter(opts) {
                 user_name,
                 text,
                 via,
+                ...(handle ? { for: handle } : {}),
                 ...(context ? { context } : {}),
+                ...(held ? { queued_at: at } : {}),
             });
-            log(`routed ${ev.channel}/${ev.ts} → ${session} (${via.join("+")})`);
+            if (held) {
+                recordPending({
+                    session,
+                    channel,
+                    ts,
+                    thread_ts: ev.thread_ts ?? ts,
+                    user,
+                    start,
+                    end: inboxSize(session),
+                    at,
+                });
+                waitingFor.push(session);
+            }
+            // Addressed here (not merely inherited from the thread) → the thread sticks.
+            // The address is kept so later replies re-resolve it (see reresolveRoutes).
+            const addr = addressed.get(session)?.addr;
+            if (stickyOn && addressed.has(session) && !inThread?.has(session)) {
+                recordRoute({
+                    session,
+                    channel,
+                    ts,
+                    thread_ts: ev.thread_ts,
+                    ...(handle ? { for: handle } : {}),
+                    ...(addr ? { addr } : {}),
+                    at,
+                });
+            }
+            log(`routed ${ev.channel}/${ev.ts} → ${session} (${via.join("+")}${handle ? ` for @${handle}` : ""}${held ? ", held" : ""})`);
+        }
+        if (waitingFor.length) {
+            // Ephemeral: the sender is looking now; the durable answer is the
+            // not-delivered reply sweepPending posts if the session never reads it.
+            await slackCall("chat.postEphemeral", opts.botToken, {
+                channel,
+                user,
+                thread_ts: ev.thread_ts ?? ts,
+                text: `Waiting for ${waitingFor.map((s) => `\`${s}\``).join(", ")}: not listening right now. It gets this when it next reads Slack; if it has not within ${ttlText()}, I will reply here that it was not delivered.`,
+            }, fetchImpl).catch(() => undefined);
         }
     };
     for (;;) {

package/dist/lib/slack-state.d.ts

@@ -2,16 +2,47 @@
  * lib/slack-state.ts — the local, per-operator state behind `mnemom agent slack`.
  *
  *   ~/.mnemom/slack/posts.jsonl          every post a session made (routes thread replies)
+ *   ~/.mnemom/slack/routes.jsonl         every addressed routing the router made (sticky threads)
  *   ~/.mnemom/slack/live/<session>.json  a session currently listening (pid)
+ *   ~/.mnemom/slack/aliases/<handle>.json an operator-registered handle → session
  *   ~/.mnemom/slack/inbox/<session>.jsonl messages the router routed to a session
+ *   ~/.mnemom/slack/offsets/<session>.off how far into its inbox a session has read
+ *   ~/.mnemom/slack/pending.jsonl        messages held for a session that was not
+ *                                        listening (slack_aliases on): delivered when its
+ *                                        offset passes them, else reported undelivered
  *
- * The router (one per operator machine) is the only writer of inboxes; each
- * session's listener is the only reader of its own. No secret is stored here.
+ * The router (one per operator machine) is the only writer of inboxes and routes;
+ * each session's listener is the only reader of its own inbox. No secret is
+ * stored here.
  */
-import { type PostRecord } from "./slack-route.js";
+import { type PostRecord, type StickyRoute } from "./slack-route.js";
 export declare function slackDir(): string;
+/** A sticky-thread route stops routing replies this long after it was made. */
+export declare const STICKY_TTL_MS: number;
+/**
+ * A message held for a session that was not listening is dropped (and its sender
+ * told it was not delivered) this long after it arrived.
+ */
+export declare const PENDING_TTL_MS: number;
 export declare function recordPost(p: PostRecord): void;
 export declare function readPosts(): PostRecord[];
+/** A routing the router made by address (mention/handle/alias), kept so the thread sticks. */
+export interface RouteRecord extends StickyRoute {
+    /** ISO time the routing was made; the record expires STICKY_TTL_MS later. */
+    at: string;
+}
+export declare function recordRoute(r: RouteRecord): void;
+/** Sticky routes still within their TTL at `now`, oldest first (capped like posts). */
+export declare function readRoutes(now?: number): RouteRecord[];
+/**
+ * The records that route thread replies: posts plus unexpired sticky routes. With
+ * `resolve`, each sticky route is re-resolved against who is live and which aliases
+ * exist now (reresolveRoutes), so a thread follows a restarted or replaced session.
+ */
+export declare function readThreadRecords(now?: number, resolve?: {
+    live: Iterable<string>;
+    aliases: Map<string, string>;
+}): PostRecord[];
 /**
  * The post `session` itself made at `ts` (optionally in `channel`), from the local
  * post index — the ownership check behind delete: a session may only remove its
@@ -26,13 +57,66 @@ export interface InboxMessage {
     user: string;
     user_name?: string;
     text: string;
-    /** How it was addressed: thread | mention | handle. */
+    /** How it was addressed: thread | mention | handle | alias. */
     via: string[];
+    /** The alias handle it was addressed to (the session may front for several). */
+    for?: string;
     /** The thread so far (parent + recent replies), when the message is a thread reply. */
     context?: string;
+    /**
+     * Set (ISO time) when the router held the message because the session was not
+     * listening. A held message older than PENDING_TTL_MS is never delivered: its
+     * sender was already told it was not.
+     */
+    queued_at?: string;
 }
+/** `messages` without the held ones that have expired (see InboxMessage.queued_at). */
+export declare function freshInbox(messages: InboxMessage[], now?: number): InboxMessage[];
 export declare function appendInbox(session: string, msg: InboxMessage): void;
 export declare function inboxPath(session: string): string;
+/** The inbox's size in bytes (0 when absent): the offset just past its last message. */
+export declare function inboxSize(session: string): number;
+/** How far into its inbox `session` has read (0 when it never saved an offset). */
+export declare function readOffset(session: string): number;
+/** `session` has read its inbox up to byte `offset`. */
+export declare function writeOffset(session: string, offset: number): void;
+/** True when `session` has saved an offset at all (it has read its inbox before). */
+export declare function hasOffset(session: string): boolean;
+/** A held message: where it came from, and the inbox offset just past it. */
+export interface PendingRecord {
+    session: string;
+    channel: string;
+    ts: string;
+    /** The thread to answer in (the message's own ts when it was not in a thread). */
+    thread_ts: string;
+    user: string;
+    /** Inbox byte offset where the held message starts. */
+    start: number;
+    /** Inbox byte offset just past the held message: read once the offset reaches it. */
+    end: number;
+    /** ISO time it was held. */
+    at: string;
+}
+export declare function recordPending(p: PendingRecord): void;
+export declare function readPending(): PendingRecord[];
+/**
+ * Where `session`'s listener must start reading to deliver what is held for it:
+ * the start of its earliest held message it has not read, or undefined when
+ * nothing unread is held (the listener then starts at the end of its inbox and
+ * reads nothing). Cost: a read of pending.jsonl, which is absent with aliases off.
+ */
+export declare function heldFrom(session: string): number | undefined;
+/**
+ * Settle the held messages at `now`: one whose session has read past it is
+ * delivered; one older than PENDING_TTL_MS that is still unread is expired; the
+ * rest stay held. Rewrites pending.jsonl with the ones still held. The router is
+ * the only caller (and the only writer of pending.jsonl).
+ */
+export declare function settlePending(now?: number): {
+    delivered: PendingRecord[];
+    expired: PendingRecord[];
+    held: PendingRecord[];
+};
 /** Messages appended after byte `offset`, and the new offset. */
 export declare function readInboxFrom(session: string, offset: number): {
     messages: InboxMessage[];
@@ -40,5 +124,22 @@ export declare function readInboxFrom(session: string, offset: number): {
 };
 export declare function registerLive(session: string, pid?: number): void;
 export declare function unregisterLive(session: string): void;
+export interface AliasRecord {
+    handle: string;
+    session: string;
+    since: string;
+}
+/**
+ * Register `handle` → `session` (idempotent; re-running with the same pair keeps the
+ * first `since`). The session need not be live: an alias is how a handle reaches a
+ * session that is launched later or restarts.
+ */
+export declare function setAlias(handle: string, session: string): AliasRecord;
+/** Remove `handle`; true when something was removed. */
+export declare function removeAlias(handle: string): boolean;
+/** Every registered alias, by handle (sorted). Corrupt files are ignored, not fatal. */
+export declare function listAliases(): AliasRecord[];
+/** normalised handle → session, the shape routeHits takes. */
+export declare function readAliases(): Map<string, string>;
 /** Sessions with a running listener; stale entries (dead pid) are pruned. */
 export declare function liveSessions(): string[];

package/dist/lib/slack-state.js

@@ -2,24 +2,42 @@
  * lib/slack-state.ts — the local, per-operator state behind `mnemom agent slack`.
  *
  *   ~/.mnemom/slack/posts.jsonl          every post a session made (routes thread replies)
+ *   ~/.mnemom/slack/routes.jsonl         every addressed routing the router made (sticky threads)
  *   ~/.mnemom/slack/live/<session>.json  a session currently listening (pid)
+ *   ~/.mnemom/slack/aliases/<handle>.json an operator-registered handle → session
  *   ~/.mnemom/slack/inbox/<session>.jsonl messages the router routed to a session
+ *   ~/.mnemom/slack/offsets/<session>.off how far into its inbox a session has read
+ *   ~/.mnemom/slack/pending.jsonl        messages held for a session that was not
+ *                                        listening (slack_aliases on): delivered when its
+ *                                        offset passes them, else reported undelivered
  *
- * The router (one per operator machine) is the only writer of inboxes; each
- * session's listener is the only reader of its own. No secret is stored here.
+ * The router (one per operator machine) is the only writer of inboxes and routes;
+ * each session's listener is the only reader of its own inbox. No secret is
+ * stored here.
  */
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { MNEMOM_DIR } from "./config.js";
-import { normSession } from "./slack-route.js";
+import { normHandle, normSession, reresolveRoutes, } from "./slack-route.js";
 export function slackDir() {
     return join(MNEMOM_DIR, "slack");
 }
 const postsFile = () => join(slackDir(), "posts.jsonl");
+const routesFile = () => join(slackDir(), "routes.jsonl");
 const liveDir = () => join(slackDir(), "live");
+const aliasDir = () => join(slackDir(), "aliases");
 const inboxDir = () => join(slackDir(), "inbox");
+const offsetDir = () => join(slackDir(), "offsets");
+const pendingFile = () => join(slackDir(), "pending.jsonl");
 /** Only the most recent posts matter for thread routing; cap what we read. */
 const MAX_POSTS = 5000;
+/** A sticky-thread route stops routing replies this long after it was made. */
+export const STICKY_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * A message held for a session that was not listening is dropped (and its sender
+ * told it was not delivered) this long after it arrived.
+ */
+export const PENDING_TTL_MS = 60 * 60 * 1000;
 function ensure(dir) {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
@@ -46,6 +64,31 @@ export function recordPost(p) {
 export function readPosts() {
     return readJsonl(postsFile()).slice(-MAX_POSTS);
 }
+export function recordRoute(r) {
+    ensure(slackDir());
+    appendFileSync(routesFile(), JSON.stringify(r) + "\n", { mode: 0o600 });
+}
+/** Sticky routes still within their TTL at `now`, oldest first (capped like posts). */
+export function readRoutes(now = Date.now()) {
+    return readJsonl(routesFile())
+        .filter((r) => {
+        const at = Date.parse(r.at);
+        return Number.isFinite(at) && now - at <= STICKY_TTL_MS && now >= at;
+    })
+        .slice(-MAX_POSTS);
+}
+/**
+ * The records that route thread replies: posts plus unexpired sticky routes. With
+ * `resolve`, each sticky route is re-resolved against who is live and which aliases
+ * exist now (reresolveRoutes), so a thread follows a restarted or replaced session.
+ */
+export function readThreadRecords(now = Date.now(), resolve) {
+    const routes = readRoutes(now);
+    return [
+        ...readPosts(),
+        ...(resolve ? reresolveRoutes(routes, resolve.live, resolve.aliases) : routes),
+    ];
+}
 /**
  * The post `session` itself made at `ts` (optionally in `channel`), from the local
  * post index — the ownership check behind delete: a session may only remove its
@@ -57,6 +100,15 @@ export function findOwnPost(session, ts, channel) {
         .reverse()
         .find((p) => p.ts === ts && normSession(p.session) === me && (!channel || p.channel === channel));
 }
+/** `messages` without the held ones that have expired (see InboxMessage.queued_at). */
+export function freshInbox(messages, now = Date.now()) {
+    return messages.filter((m) => {
+        if (!m.queued_at)
+            return true;
+        const at = Date.parse(m.queued_at);
+        return Number.isFinite(at) && now - at <= PENDING_TTL_MS;
+    });
+}
 const fileFor = (session) => `${normSession(session)}`;
 export function appendInbox(session, msg) {
     ensure(inboxDir());
@@ -67,15 +119,117 @@ export function appendInbox(session, msg) {
 export function inboxPath(session) {
     return join(inboxDir(), `${fileFor(session)}.jsonl`);
 }
+/** The inbox's size in bytes (0 when absent): the offset just past its last message. */
+export function inboxSize(session) {
+    try {
+        return statSync(inboxPath(session)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+// Normalised like the inbox file name, so a session name can never escape offsets/.
+const offsetFile = (session) => join(offsetDir(), `${fileFor(session)}.off`);
+/** How far into its inbox `session` has read (0 when it never saved an offset). */
+export function readOffset(session) {
+    try {
+        return Number(readFileSync(offsetFile(session), "utf8")) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** `session` has read its inbox up to byte `offset`. */
+export function writeOffset(session, offset) {
+    ensure(offsetDir());
+    writeFileSync(offsetFile(session), String(offset), { mode: 0o600 });
+}
+/** True when `session` has saved an offset at all (it has read its inbox before). */
+export function hasOffset(session) {
+    return existsSync(offsetFile(session));
+}
+export function recordPending(p) {
+    ensure(slackDir());
+    appendFileSync(pendingFile(), JSON.stringify(p) + "\n", { mode: 0o600 });
+}
+export function readPending() {
+    return readJsonl(pendingFile());
+}
+/**
+ * Where `session`'s listener must start reading to deliver what is held for it:
+ * the start of its earliest held message it has not read, or undefined when
+ * nothing unread is held (the listener then starts at the end of its inbox and
+ * reads nothing). Cost: a read of pending.jsonl, which is absent with aliases off.
+ */
+export function heldFrom(session) {
+    if (!existsSync(pendingFile()))
+        return undefined;
+    const me = normSession(session);
+    const read = readOffset(session);
+    const size = inboxSize(session);
+    let from;
+    for (const p of readPending()) {
+        if (normSession(p.session) !== me || !(p.end > read) || p.end > size)
+            continue;
+        const s = Number.isFinite(p.start) ? Math.max(p.start, read) : read;
+        from = from === undefined ? s : Math.min(from, s);
+    }
+    return from;
+}
+/**
+ * Settle the held messages at `now`: one whose session has read past it is
+ * delivered; one older than PENDING_TTL_MS that is still unread is expired; the
+ * rest stay held. Rewrites pending.jsonl with the ones still held. The router is
+ * the only caller (and the only writer of pending.jsonl).
+ */
+export function settlePending(now = Date.now()) {
+    const delivered = [];
+    const expired = [];
+    const held = [];
+    const all = readPending();
+    if (!all.length)
+        return { delivered, expired, held };
+    for (const p of all) {
+        const at = Date.parse(p.at);
+        if (readOffset(p.session) >= p.end)
+            delivered.push(p);
+        else if (!Number.isFinite(at) || now - at > PENDING_TTL_MS)
+            expired.push(p);
+        else
+            held.push(p);
+    }
+    writeFileSync(pendingFile(), held.map((p) => JSON.stringify(p) + "\n").join(""), {
+        mode: 0o600,
+    });
+    return { delivered, expired, held };
+}
 /** Messages appended after byte `offset`, and the new offset. */
 export function readInboxFrom(session, offset) {
-    const path = inboxPath(session);
-    if (!existsSync(path))
-        return { messages: [], offset: 0 };
-    const buf = readFileSync(path);
-    if (buf.length < offset)
-        offset = 0; // truncated/rotated
-    const chunk = buf.subarray(offset).toString("utf8");
+    // Open, don't check-then-open: the router appends concurrently. Read only the
+    // bytes after `offset`, never the whole history.
+    let fd;
+    try {
+        fd = openSync(inboxPath(session), "r");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { messages: [], offset: 0 };
+        throw e;
+    }
+    let chunk;
+    try {
+        const size = fstatSync(fd).size;
+        if (size < offset)
+            offset = 0; // truncated/rotated
+        const buf = Buffer.alloc(size - offset);
+        // One positional read. A short read (the file shrank under us) is safe: the
+        // offset only advances past complete lines, so the rest is read next poll.
+        const got = buf.length ? readSync(fd, buf, 0, buf.length, offset) : 0;
+        chunk = buf.subarray(0, got).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
     const end = chunk.lastIndexOf("\n") + 1; // leave a partial trailing line for next read
     const messages = [];
     for (const line of chunk.slice(0, end).split("\n")) {
@@ -106,6 +260,71 @@ function pidAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/**
+ * Register `handle` → `session` (idempotent; re-running with the same pair keeps the
+ * first `since`). The session need not be live: an alias is how a handle reaches a
+ * session that is launched later or restarts.
+ */
+export function setAlias(handle, session) {
+    const h = normHandle(handle);
+    const s = session.trim();
+    if (!h)
+        throw new Error(`alias: '${handle}' is not a usable handle (letters, digits, dashes).`);
+    if (!normSession(s))
+        throw new Error(`alias: '${session}' is not a usable session name.`);
+    ensure(aliasDir());
+    const path = join(aliasDir(), `${h}.json`);
+    const prev = readAlias(path);
+    const rec = {
+        handle: h,
+        session: s,
+        since: prev && prev.session === s ? prev.since : new Date().toISOString(),
+    };
+    writeFileSync(path, JSON.stringify(rec), { mode: 0o600 });
+    return rec;
+}
+/** Remove `handle`; true when something was removed. */
+export function removeAlias(handle) {
+    const h = normHandle(handle);
+    if (!h)
+        return false;
+    const path = join(aliasDir(), `${h}.json`);
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}
+function readAlias(path) {
+    try {
+        const rec = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof rec.handle === "string" && typeof rec.session === "string" && rec.session) {
+            return { handle: rec.handle, session: rec.session, since: String(rec.since ?? "") };
+        }
+    }
+    catch {
+        /* corrupt → absent */
+    }
+    return undefined;
+}
+/** Every registered alias, by handle (sorted). Corrupt files are ignored, not fatal. */
+export function listAliases() {
+    if (!existsSync(aliasDir()))
+        return [];
+    const out = [];
+    for (const f of readdirSync(aliasDir()).sort()) {
+        if (!f.endsWith(".json"))
+            continue;
+        const rec = readAlias(join(aliasDir(), f));
+        // The file name is the normalised handle; a record whose handle disagrees is ignored.
+        if (rec && `${normHandle(rec.handle)}.json` === f)
+            out.push(rec);
+    }
+    return out;
+}
+/** normalised handle → session, the shape routeHits takes. */
+export function readAliases() {
+    return new Map(listAliases().map((a) => [normHandle(a.handle), a.session]));
+}
 /** Sessions with a running listener; stale entries (dead pid) are pruned. */
 export function liveSessions() {
     if (!existsSync(liveDir()))

package/dist/lib/subscription-login.d.ts

@@ -57,10 +57,19 @@ export interface MnemomKeyDeps {
     say(line: string): void;
 }
 /**
- * The Mnemom key a subscription launch sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored
- * key, else mint one (gateway scope only) and store it. The key is never printed.
+ * The Mnemom key this machine already has — MNEMOM_AGENT_MNEMOM_KEY, else the stored key — or
+ * undefined. NEVER mints. An unpinned api-key launch sends it (`x-mnemom-api-key`) alongside its
+ * Anthropic key when there is one, so the gateway can serve the key owner's claimed agent of that
+ * name instead of a fresh one per rotated Anthropic key; with none it launches exactly as before.
  */
-export declare function resolveSubscriptionMnemomKey(deps: MnemomKeyDeps): Promise<string>;
+export declare function readMnemomKey(deps: Pick<MnemomKeyDeps, "env" | "readStored">): string | undefined;
+/**
+ * The Mnemom key a subscription launch (or a pinned launch, which the gateway honours only with
+ * a verified Mnemom key) sends: MNEMOM_AGENT_MNEMOM_KEY, else the stored key, else mint one
+ * (gateway scope only) and store it. The key is never printed. `purpose` names why in the
+ * one-line notes ("subscription login" by default).
+ */
+export declare function resolveSubscriptionMnemomKey(deps: MnemomKeyDeps, purpose?: string): Promise<string>;
 /**
  * Remote Control on a subscription login is open to accounts entitled to Remote Control
  * (internal Mnemom accounts): the RC proxy then forwards the user's own OAuth bearer to the