@cello-protocol/daemon 0.0.43 → 0.0.45

package/dist/session-node-manager.js

@@ -69,6 +69,7 @@
 import { openEncryptedDatabase, resolveDbKey, dbKeyPathFor, } from "./sqlcipher-db.js";
 import { migrateToEncryptedIfNeeded } from "./identity-migration.js";
 import { ensureIdentitySchema } from "./db-identity-store.js";
+import { migrateSessionTablesToAgentId } from "./agent-id-migration.js";
 import { randomUUID, createHash } from "node:crypto";
 import * as lp from "it-length-prefixed";
 import { decode, Encoder } from "cbor-x";
@@ -332,7 +333,7 @@ export class SessionNodeManager {
         this.#db.exec(`
       CREATE TABLE IF NOT EXISTS sessions (
         session_id TEXT NOT NULL,
-        agent_name TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
         counterparty_pubkey TEXT NOT NULL,
         status TEXT NOT NULL,
         created_at INTEGER NOT NULL,
@@ -340,7 +341,9 @@ export class SessionNodeManager {
         -- DOD-LOOP-1: composite key so two of the operator's agents can hold both ends of the
         -- SAME session_id on ONE daemon (the loopback case). A bare session_id PK would reject
         -- the second end's row.
-        PRIMARY KEY (agent_name, session_id)
+        -- DOD-AGENT-ID-JOINKEY-1: keyed on the STABLE agent_id, never the mutable, reuse-freed
+        -- agent_name. The display name lives on the agents table and is joined in for reads.
+        PRIMARY KEY (agent_id, session_id)
       )
     `);
         // M7-SESSION-001: idempotent schema extension — add message_count and interrupted_at
@@ -386,7 +389,7 @@ export class SessionNodeManager {
         // Merkle root so the achieved commitment is never discarded.
         this.#db.exec(`
       CREATE TABLE IF NOT EXISTS seal_interrupted_artifacts (
-        agent_name TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
         session_id TEXT NOT NULL,
         role TEXT NOT NULL,
         own_leaf TEXT NOT NULL,
@@ -395,7 +398,7 @@ export class SessionNodeManager {
         nonce TEXT NOT NULL,
         created_at INTEGER NOT NULL,
         -- DOD-LOOP-1: composite key (per-agent end of a loopback session).
-        PRIMARY KEY (agent_name, session_id)
+        PRIMARY KEY (agent_id, session_id)
       )
     `);
         // DAEMON-004 (AC-007 / SI-001): the daemon-owned per-session Merkle tree,
@@ -405,14 +408,14 @@ export class SessionNodeManager {
         // by session_id ORDER BY leaf_index is the only read pattern.
         this.#db.exec(`
       CREATE TABLE IF NOT EXISTS session_tree_leaves (
-        agent_name TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
         session_id TEXT NOT NULL,
         leaf_index INTEGER NOT NULL,
         leaf_kind TEXT NOT NULL,
         leaf_hash_hex TEXT NOT NULL,
         created_at INTEGER NOT NULL,
         -- DOD-LOOP-1: composite key so each agent's end has its own append-ordered tree.
-        PRIMARY KEY (agent_name, session_id, leaf_index)
+        PRIMARY KEY (agent_id, session_id, leaf_index)
       )
     `);
         // DOD-LOG-1 (PERSIST-LOG-001) / PERSIST-002 (AC-010): the durable, ENCRYPTED-at-rest readable
@@ -422,13 +425,13 @@ export class SessionNodeManager {
         // provided by whole-DB SQLCipher, not a per-column cipher (relay/directory never see it — INV-3).
         this.#db.exec(`
       CREATE TABLE IF NOT EXISTS transcript (
-        agent_name TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
         session_id TEXT NOT NULL,
         sequence INTEGER NOT NULL,
         direction TEXT NOT NULL,        -- 'sent' | 'received'
         blob BLOB NOT NULL,             -- readable plaintext bytes (whole-DB SQLCipher-encrypted at rest)
         created_at INTEGER NOT NULL,
-        PRIMARY KEY (agent_name, session_id, sequence, direction)
+        PRIMARY KEY (agent_id, session_id, sequence, direction)
       )
     `);
         // M8C-INBOX-1 (N2): per-agent, per-session read watermark. `last_delivered_seq` is the highest
@@ -438,10 +441,10 @@ export class SessionNodeManager {
         // across daemon restarts, not just within one process (INV-PUSHPULL). Additive table.
         this.#db.exec(`
       CREATE TABLE IF NOT EXISTS message_watermarks (
-        agent_name TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
         session_id TEXT NOT NULL,
         last_delivered_seq INTEGER NOT NULL,
-        PRIMARY KEY (agent_name, session_id)
+        PRIMARY KEY (agent_id, session_id)
       )
     `);
         // M8C-CONTACT-1: binary per-agent contact whitelist. This is an ACCESS-CONTROL LIST, not a
@@ -450,10 +453,10 @@ export class SessionNodeManager {
         // re-resolved); known stays known until explicitly removed (no TTL/expiry on membership).
         this.#db.exec(`
       CREATE TABLE IF NOT EXISTS contacts (
-        agent_name TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
         pubkey TEXT NOT NULL,
         added_at INTEGER NOT NULL,
-        PRIMARY KEY (agent_name, pubkey)
+        PRIMARY KEY (agent_id, pubkey)
       )
     `);
         // MONIKER-3 AC1: the receiver's own pet name for a pubkey — the top tier of whoLabel.
@@ -463,6 +466,15 @@ export class SessionNodeManager {
         if (!contactCols.some((c) => c.name === "moniker")) {
             this.#db.exec("ALTER TABLE contacts ADD COLUMN moniker TEXT");
         }
+        // DOD-AGENT-ID-JOINKEY-1: finish REMOVE-001. Re-key the seven child tables from the mutable,
+        // reuse-freed `agent_name` to the stable `agent_id`, in ONE transaction. Runs AFTER every
+        // CREATE/ALTER above, so an existing table has its full historical column set before it is
+        // rebuilt, and BEFORE any read below touches it. A no-op once the tables carry `agent_id`.
+        //
+        // `retry_queue` (the seventh) is created later, by RetryQueue's constructor. On an existing
+        // database it already exists here and is re-keyed in the same transaction; on a fresh one it is
+        // absent, is skipped, and RetryQueue then creates it directly in the re-keyed shape.
+        migrateSessionTablesToAgentId(this.#db, this.#logger);
         // M8C-TGDOOR-1: daemon-wide Telegram settings (bot token + allowlisted operator chat). A
         // NEW dedicated table — NOT folded into the parked M9-CFG-001 config store, because a bot
         // token has no sensible default (a required credential, unlike AWAY/TTL/CONTACT's real
@@ -479,8 +491,15 @@ export class SessionNodeManager {
         // Step 2: Detect interrupted sessions (SIGKILL detection — AC-010).
         // Any 'active' row in a freshly-started daemon is a remnant of a prior
         // killed process. Batch-update to 'interrupted' before IPC opens.
+        // DOD-AGENT-ID-JOINKEY-1: this sweep spans EVERY agent, so it cannot resolve one name up front.
+        // It scopes its UPDATE by the row's own agent_id and LEFT JOINs `agents` only to LOG a human
+        // name. LEFT, not INNER: an inner join would silently skip a session whose agent row is missing,
+        // leaving it 'active' forever — a stuck row hidden by the query that was meant to find it. An
+        // orphan is instead marked interrupted like any other AND reported loudly.
         const activeRows = this.#db
-            .prepare("SELECT * FROM sessions WHERE status = 'active'")
+            .prepare(`SELECT s.session_id, s.agent_id, a.agent_name
+         FROM sessions s LEFT JOIN agents a ON a.agent_id = s.agent_id
+         WHERE s.status = 'active'`)
             .all();
         if (activeRows.length > 0) {
             const now = Date.now();
@@ -488,8 +507,15 @@ export class SessionNodeManager {
             for (const row of activeRows) {
                 try {
                     this.#db
-                        .prepare("UPDATE sessions SET status = 'interrupted', updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?) WHERE agent_name = ? AND session_id = ?")
-                        .run(now, interruptedAt, row.agent_name, row.session_id);
+                        .prepare("UPDATE sessions SET status = 'interrupted', updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?) WHERE agent_id = ? AND session_id = ?")
+                        .run(now, interruptedAt, row.agent_id, row.session_id);
+                    if (row.agent_name === null) {
+                        this.#logger.error("session.agent.orphaned", {
+                            sessionId: row.session_id,
+                            agentId: row.agent_id,
+                            impact: "session row references an agent_id with no agents row",
+                        });
+                    }
                     this.#logger.warn("session.interrupted.detected", {
                         sessionId: row.session_id,
                         agentName: row.agent_name,
@@ -557,11 +583,12 @@ export class SessionNodeManager {
         if (!this.#db)
             return;
         try {
+            const agentId = this.#requireAgentId(agentName);
             const blob = Buffer.from(plaintext);
             this.#db
-                .prepare(`INSERT OR IGNORE INTO transcript (agent_name, session_id, sequence, direction, blob, created_at)
+                .prepare(`INSERT OR IGNORE INTO transcript (agent_id, session_id, sequence, direction, blob, created_at)
            VALUES (?, ?, ?, ?, ?, ?)`)
-                .run(agentName, sessionId, sequence, direction, blob, Date.now());
+                .run(agentId, sessionId, sequence, direction, blob, Date.now());
             this.#logger.info("transcript.message.recorded", { sessionId, agentName, sequence, direction, correlationId });
         }
         catch (err) {
@@ -590,8 +617,8 @@ export class SessionNodeManager {
             return { messages: [], undecryptable: 0 };
         const rows = this.#db
             .prepare(`SELECT sequence, direction, blob, created_at FROM transcript
-         WHERE agent_name = ? AND session_id = ? ORDER BY sequence ASC, direction ASC`)
-            .all(agentName, sessionId);
+         WHERE agent_id = ? AND session_id = ? ORDER BY sequence ASC, direction ASC`)
+            .all(this.#requireAgentId(agentName), sessionId);
         const messages = [];
         // PERSIST-002 (AC-010): the blob is plaintext (whole-DB SQLCipher at rest), so there is no
         // per-row decrypt step that can fail — `undecryptable` stays 0 and is kept only for callers that
@@ -614,8 +641,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return -1;
         const row = this.#db
-            .prepare("SELECT last_delivered_seq FROM message_watermarks WHERE agent_name = ? AND session_id = ?")
-            .get(agentName, sessionId);
+            .prepare("SELECT last_delivered_seq FROM message_watermarks WHERE agent_id = ? AND session_id = ?")
+            .get(this.#requireAgentId(agentName), sessionId);
         return row ? row.last_delivered_seq : -1;
     }
     /** Advance the read watermark (delivery marks read). MONOTONIC — never lowers, so a replayed or
@@ -624,11 +651,11 @@ export class SessionNodeManager {
         if (!this.#db)
             return;
         this.#db
-            .prepare(`INSERT INTO message_watermarks (agent_name, session_id, last_delivered_seq)
+            .prepare(`INSERT INTO message_watermarks (agent_id, session_id, last_delivered_seq)
          VALUES (?, ?, ?)
-         ON CONFLICT(agent_name, session_id)
+         ON CONFLICT(agent_id, session_id)
          DO UPDATE SET last_delivered_seq = MAX(last_delivered_seq, excluded.last_delivered_seq)`)
-            .run(agentName, sessionId, seq);
+            .run(this.#requireAgentId(agentName), sessionId, seq);
         this.#logger.info("message.watermark.advanced", { agentName, sessionId, sequence: seq });
     }
     /** INBOX-1 (N2): per-session unread summary for an agent — sessions that have RECEIVED transcript
@@ -643,21 +670,21 @@ export class SessionNodeManager {
                 MAX(t.sequence) AS last_seq
          FROM transcript t
          LEFT JOIN message_watermarks w
-           ON w.agent_name = t.agent_name AND w.session_id = t.session_id
-         WHERE t.agent_name = ?
+           ON w.agent_id = t.agent_id AND w.session_id = t.session_id
+         WHERE t.agent_id = ?
            AND t.direction = 'received'
            AND t.sequence > COALESCE(w.last_delivered_seq, -1)
          GROUP BY t.session_id
          HAVING unread_count > 0
          ORDER BY t.session_id ASC`)
-            .all(agentName);
+            .all(this.#requireAgentId(agentName));
         return rows;
     }
     /** M8C-CONTACT-1: is this pubkey a known contact of this agent? */
     isContact(agentName, pubkey) {
         if (!this.#db)
             return false;
-        const row = this.#db.prepare("SELECT 1 FROM contacts WHERE agent_name = ? AND pubkey = ?").get(agentName, pubkey);
+        const row = this.#db.prepare("SELECT 1 FROM contacts WHERE agent_id = ? AND pubkey = ?").get(this.#requireAgentId(agentName), pubkey);
         return row !== undefined;
     }
     /** M8C-CONTACT-1: pin a contact at add time — idempotent (re-adding an existing contact is a
@@ -675,13 +702,14 @@ export class SessionNodeManager {
         if (moniker !== undefined && moniker !== null && validateMoniker(moniker) === null) {
             throw new Error(`invalid contact moniker for agent '${agentName}': must match ${MONIKER_RE.source}`);
         }
+        const agentId = this.#requireAgentId(agentName);
         this.#db
-            .prepare("INSERT OR IGNORE INTO contacts (agent_name, pubkey, added_at) VALUES (?, ?, ?)")
-            .run(agentName, pubkey, Date.now());
+            .prepare("INSERT OR IGNORE INTO contacts (agent_id, pubkey, added_at) VALUES (?, ?, ?)")
+            .run(agentId, pubkey, Date.now());
         if (moniker !== undefined && moniker !== null) {
             this.#db
-                .prepare("UPDATE contacts SET moniker = ? WHERE agent_name = ? AND pubkey = ?")
-                .run(moniker, agentName, pubkey);
+                .prepare("UPDATE contacts SET moniker = ? WHERE agent_id = ? AND pubkey = ?")
+                .run(moniker, agentId, pubkey);
         }
     }
     /** MONIKER-3 AC3: rename (string) or clear (null) an EXISTING contact's pet name. Returns false
@@ -696,15 +724,15 @@ export class SessionNodeManager {
             throw new Error(`invalid contact moniker for agent '${agentName}': must match ${MONIKER_RE.source}`);
         }
         const res = this.#db
-            .prepare("UPDATE contacts SET moniker = ? WHERE agent_name = ? AND pubkey = ?")
-            .run(moniker, agentName, pubkey);
+            .prepare("UPDATE contacts SET moniker = ? WHERE agent_id = ? AND pubkey = ?")
+            .run(moniker, this.#requireAgentId(agentName), pubkey);
         return res.changes > 0;
     }
     /** M8C-CONTACT-1: known stays known until explicitly removed. */
     removeContact(agentName, pubkey) {
         if (!this.#db)
             return false;
-        const res = this.#db.prepare("DELETE FROM contacts WHERE agent_name = ? AND pubkey = ?").run(agentName, pubkey);
+        const res = this.#db.prepare("DELETE FROM contacts WHERE agent_id = ? AND pubkey = ?").run(this.#requireAgentId(agentName), pubkey);
         return res.changes > 0;
     }
     /** MONIKER-4: the operator's pet name for a pubkey (whoLabel's top tier), or null. Read-only
@@ -717,8 +745,8 @@ export class SessionNodeManager {
             return null;
         }
         const row = this.#db
-            .prepare("SELECT moniker FROM contacts WHERE agent_name = ? AND pubkey = ?")
-            .get(agentName, pubkey);
+            .prepare("SELECT moniker FROM contacts WHERE agent_id = ? AND pubkey = ?")
+            .get(this.#requireAgentId(agentName), pubkey);
         return row?.moniker ?? null;
     }
     /** M8C-CONTACT-1: list an agent's known contacts, oldest-added first. MONIKER-3 AC3: includes
@@ -727,16 +755,16 @@ export class SessionNodeManager {
         if (!this.#db)
             return [];
         return this.#db
-            .prepare("SELECT pubkey, added_at, moniker FROM contacts WHERE agent_name = ? ORDER BY added_at ASC")
-            .all(agentName);
+            .prepare("SELECT pubkey, added_at, moniker FROM contacts WHERE agent_id = ? ORDER BY added_at ASC")
+            .all(this.#requireAgentId(agentName));
     }
     /** M8C-ABUSE-1: cumulative RECEIVED byte total for a session (anti-drip-feed accounting). */
     #getReceivedBytesTotal(agentName, sessionId) {
         if (!this.#db)
             return 0;
         const row = this.#db
-            .prepare("SELECT COALESCE(SUM(LENGTH(blob)), 0) AS total FROM transcript WHERE agent_name = ? AND session_id = ? AND direction = 'received'")
-            .get(agentName, sessionId);
+            .prepare("SELECT COALESCE(SUM(LENGTH(blob)), 0) AS total FROM transcript WHERE agent_id = ? AND session_id = ? AND direction = 'received'")
+            .get(this.#requireAgentId(agentName), sessionId);
         return row.total;
     }
     /** M8C-ABUSE-1 (reviewer HIGH fix, D18): bytes currently sitting in the out-of-order hold
@@ -763,8 +791,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return 0;
         const row = this.#db
-            .prepare("SELECT COUNT(*) AS n FROM sessions WHERE agent_name = ? AND counterparty_pubkey = ? AND status IN ('active', 'interrupted')")
-            .get(agentName, counterpartyPubkey);
+            .prepare("SELECT COUNT(*) AS n FROM sessions WHERE agent_id = ? AND counterparty_pubkey = ? AND status IN ('active', 'interrupted')")
+            .get(this.#requireAgentId(agentName), counterpartyPubkey);
         return row.n;
     }
     /** M8C-ABUSE-1 (anti-swarm): non-terminal sessions this agent holds with counterparties that are
@@ -775,9 +803,9 @@ export class SessionNodeManager {
             return 0;
         const row = this.#db
             .prepare(`SELECT COUNT(*) AS n FROM sessions s
-         WHERE s.agent_name = ? AND s.status IN ('active', 'interrupted')
-           AND NOT EXISTS (SELECT 1 FROM contacts c WHERE c.agent_name = s.agent_name AND c.pubkey = s.counterparty_pubkey)`)
-            .get(agentName);
+         WHERE s.agent_id = ? AND s.status IN ('active', 'interrupted')
+           AND NOT EXISTS (SELECT 1 FROM contacts c WHERE c.agent_id = s.agent_id AND c.pubkey = s.counterparty_pubkey)`)
+            .get(this.#requireAgentId(agentName));
         return row.n;
     }
     /** M8C-ABUSE-1: is a NEW inbound session from this counterparty within the acceptance bounds?
@@ -906,6 +934,66 @@ export class SessionNodeManager {
     #k(agentName, sessionId) {
         return `${agentName}\x1f${sessionId}`;
     }
+    /**
+     * DOD-AGENT-ID-JOINKEY-1: resolve an agent's NAME to its STABLE agent_id. This is the ONE place a
+     * name becomes a key, and it is the boundary between the two worlds:
+     *
+     *   - ABOVE it, addressing by name is correct. The operator says `cello_use_agent { name }`, and
+     *     the in-memory maps (#k, standing receivers, keyProviders) key by name safely, because
+     *     name-addressing only ever resolves ACTIVE agents and the `agents_active_name` partial unique
+     *     index makes active names unique.
+     *   - BELOW it, only `agent_id` may touch SQL. `agent_name` is a mutable display attribute that a
+     *     retire frees for reuse; a table joined on it hands a new keypair the dead identity's rows.
+     *
+     * It resolves ONLY non-retired agents — a retired identity is gone from the runtime (`list` omits
+     * it, `start` returns agent_not_found), so no live surface may act as one.
+     *
+     * It THROWS on an unresolvable name rather than returning null. A null would flow into a
+     * `WHERE agent_id IS NULL` that quietly matches nothing: reads would return empty and writes would
+     * vanish, and the daemon would look healthy while losing an agent's data. Every caller has already
+     * resolved the agent before it gets here, so an unresolvable name is a bug in the caller, not a
+     * condition to absorb.
+     */
+    #requireAgentId(agentName) {
+        if (!this.#db)
+            throw new Error("agent_id_unresolved: database is not open");
+        const row = this.#db
+            .prepare("SELECT agent_id FROM agents WHERE agent_name = ? AND state != 'retired'")
+            .get(agentName);
+        if (!row) {
+            this.#logger.error("session.agent_id.unresolved", { agentName });
+            throw new Error(`agent_id_unresolved: no active agent named '${agentName}'. The session tables are keyed by the ` +
+                `stable agent_id (DOD-AGENT-ID-JOINKEY-1); scoping a query by an unresolvable name would ` +
+                `silently match nothing.`);
+        }
+        return row.agent_id;
+    }
+    /**
+     * DOD-AGENT-ID-JOINKEY-1: the public form of the name→stable-id resolver, for components that own
+     * agent-scoped tables of their own (RetryQueue) and must be handed the STABLE key, never a name.
+     * The daemon resolves ONCE, at its own boundary, exactly as this class does internally. Throws on
+     * an unresolvable name — see #requireAgentId for why null is not an option.
+     */
+    resolveAgentId(agentName) {
+        return this.#requireAgentId(agentName);
+    }
+    /**
+     * Reverse lookup: the display name of a stable agent_id, or null if no such agent.
+     *
+     * Deliberately INCLUDES retired agents. Its caller (the startup awaiting-content re-park) holds an
+     * agent_id read off a durable row and needs a name to find that agent's standing receiver. A
+     * retired agent resolves to its name and then has no standing receiver, so the park fails cleanly
+     * and loudly — which is correct. Filtering retired agents out here would instead make the row
+     * unattributable and the failure mute.
+     */
+    agentNameForId(agentId) {
+        if (!this.#db)
+            return null;
+        const row = this.#db
+            .prepare("SELECT agent_name FROM agents WHERE agent_id = ?")
+            .get(agentId);
+        return row?.agent_name ?? null;
+    }
     /**
      * Create a new outbound session node.
      * Called during cello_initiate_session.
@@ -1152,8 +1240,8 @@ export class SessionNodeManager {
                 // before the in-memory entry exists) can deposit un-acked content to the same relay.
                 try {
                     this.#db
-                        ?.prepare("UPDATE sessions SET relay_peer_id = ?, relay_addrs = ?, updated_at = ? WHERE agent_name = ? AND session_id = ?")
-                        .run(relay.relayPeerId, JSON.stringify(relay.relayAddrs), Date.now(), agentName, sessionId);
+                        ?.prepare("UPDATE sessions SET relay_peer_id = ?, relay_addrs = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?")
+                        .run(relay.relayPeerId, JSON.stringify(relay.relayAddrs), Date.now(), this.#requireAgentId(agentName), sessionId);
                 }
                 catch (err) {
                     this.#logger.warn("session.relay.endpoint.persist.failed", {
@@ -1595,8 +1683,22 @@ export class SessionNodeManager {
     getSessionsByStatus(status) {
         if (!this.#db)
             return [];
+        // Spans EVERY agent (cello_status is daemon-wide), so no single name can be resolved up front —
+        // the display name is joined in from `agents`, its one source of truth. `agent_name` is no
+        // longer a `sessions` column, so without this join buildActiveSessions/buildInterruptedSessions
+        // read `row.agent_name` as undefined.
+        //
+        // DOD-AGENT-ID-JOINKEY-1 (reviewer Finding 1): INNER JOIN with `state != 'retired'`, NOT a bare
+        // LEFT JOIN. This is the LIVE-status + reaper surface, and a retired agent is gone from the
+        // runtime — its leftover session rows (kept for accountability, never re-statused) are not
+        // resumable and must not appear here. If they did, the half-open reaper would resolve their
+        // RETIRED name via #requireAgentId, which throws, taking down cello_status for the whole daemon.
+        // Excluding them also guarantees a non-null agent_name on every returned row. The full historical
+        // archive (getAllSessions) keeps its LEFT JOIN and still shows retired/orphaned rows.
         return this.#db
-            .prepare("SELECT * FROM sessions WHERE status = ?")
+            .prepare(`SELECT s.*, a.agent_name AS agent_name
+         FROM sessions s JOIN agents a ON a.agent_id = s.agent_id
+         WHERE s.status = ? AND a.state != 'retired'`)
             .all(status);
     }
     /**
@@ -1610,9 +1712,13 @@ export class SessionNodeManager {
     getSessionsForAgent(agentName) {
         if (!this.#db)
             return [];
-        return this.#db
-            .prepare("SELECT * FROM sessions WHERE agent_name = ? ORDER BY updated_at DESC")
-            .all(agentName);
+        // Scoped by the STABLE id. `agent_name` is not a column of `sessions` any more, so it is stamped
+        // back on for display — and it is exactly the name we just resolved the id FROM, so no join is
+        // needed and no stale copy can exist.
+        const rows = this.#db
+            .prepare("SELECT * FROM sessions WHERE agent_id = ? ORDER BY updated_at DESC")
+            .all(this.#requireAgentId(agentName));
+        return rows.map((r) => ({ ...r, agent_name: agentName }));
     }
     /**
      * Every persisted session across ALL agents, most-recently-updated first. Backs the daemon-wide
@@ -1622,8 +1728,13 @@ export class SessionNodeManager {
     getAllSessions() {
         if (!this.#db)
             return [];
+        // Spans EVERY agent, so no single name can be resolved up front: the display name is joined in
+        // from `agents`, its one source of truth. LEFT JOIN, not INNER — a session whose agent row is
+        // missing must still be listed (an invisible session is worse than an unnamed one).
         return this.#db
-            .prepare("SELECT * FROM sessions ORDER BY updated_at DESC")
+            .prepare(`SELECT s.*, a.agent_name AS agent_name
+         FROM sessions s LEFT JOIN agents a ON a.agent_id = s.agent_id
+         ORDER BY s.updated_at DESC`)
             .all();
     }
     /**
@@ -1639,8 +1750,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return;
         this.#db
-            .prepare("UPDATE sessions SET seal_legibility = ?, sealed_root_hex = ?, updated_at = ? WHERE agent_name = ? AND session_id = ?")
-            .run(legibilityJson, sealedRootHex, Date.now(), agentName, sessionId);
+            .prepare("UPDATE sessions SET seal_legibility = ?, sealed_root_hex = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?")
+            .run(legibilityJson, sealedRootHex, Date.now(), this.#requireAgentId(agentName), sessionId);
     }
     /**
      * M8B FINDING-6 (cascade-2): persist a seal certificate for a session that may have NO local
@@ -1658,9 +1769,9 @@ export class SessionNodeManager {
         const now = Date.now();
         this.#db
             .prepare(`INSERT OR IGNORE INTO sessions
-           (session_id, agent_name, counterparty_pubkey, status, created_at, updated_at)
+           (session_id, agent_id, counterparty_pubkey, status, created_at, updated_at)
          VALUES (?, ?, ?, ?, ?, ?)`)
-            .run(sessionId, agentName, counterpartyPubkeyHex, "sealed", now, now);
+            .run(sessionId, this.#requireAgentId(agentName), counterpartyPubkeyHex, "sealed", now, now);
         this.recordSealCertificate(agentName, sessionId, sealedRootHex, legibilityJson);
     }
     /**
@@ -1673,8 +1784,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return;
         this.#db
-            .prepare("UPDATE sessions SET counterparty_primary_pubkey = ?, updated_at = ? WHERE agent_name = ? AND session_id = ?")
-            .run(primaryPubkeyHex, Date.now(), agentName, sessionId);
+            .prepare("UPDATE sessions SET counterparty_primary_pubkey = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?")
+            .run(primaryPubkeyHex, Date.now(), this.#requireAgentId(agentName), sessionId);
     }
     /**
      * M7-SESSION-004 (AC-005/AC-006): read the persisted seal certificate for a session.
@@ -1688,8 +1799,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return null;
         const row = this.#db
-            .prepare("SELECT sealed_root_hex, seal_legibility FROM sessions WHERE agent_name = ? AND session_id = ?")
-            .get(agentName, sessionId);
+            .prepare("SELECT sealed_root_hex, seal_legibility FROM sessions WHERE agent_id = ? AND session_id = ?")
+            .get(this.#requireAgentId(agentName), sessionId);
         if (!row || !row.seal_legibility || !row.sealed_root_hex)
             return null;
         let legibility;
@@ -1741,8 +1852,8 @@ export class SessionNodeManager {
             // the pre-check above raced (it cannot — DatabaseSync is synchronous), the
             // UPDATE only mutates a row that is still active.
             this.#db
-                .prepare("UPDATE sessions SET status = 'interrupted', updated_at = ?, message_count = ?, interrupted_at = ? WHERE agent_name = ? AND session_id = ? AND status = 'active'")
-                .run(now, authoritativeCount, interruptedAt, agentName, sessionId);
+                .prepare("UPDATE sessions SET status = 'interrupted', updated_at = ?, message_count = ?, interrupted_at = ? WHERE agent_id = ? AND session_id = ? AND status = 'active'")
+                .run(now, authoritativeCount, interruptedAt, this.#requireAgentId(agentName), sessionId);
         }
         catch (err) {
             this.#logger.error("session.interrupt.db.write.failed", {
@@ -1826,9 +1937,9 @@ export class SessionNodeManager {
         try {
             this.#db
                 .prepare(`INSERT OR REPLACE INTO seal_interrupted_artifacts
-           (agent_name, session_id, role, own_leaf, counterparty_leaf, merkle_root, nonce, created_at)
+           (agent_id, session_id, role, own_leaf, counterparty_leaf, merkle_root, nonce, created_at)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
-                .run(opts.agentName, opts.sessionId, opts.role, JSON.stringify(opts.ownLeaf), JSON.stringify(opts.counterpartyLeaf), opts.merkleRoot, opts.nonce, now);
+                .run(this.#requireAgentId(opts.agentName), opts.sessionId, opts.role, JSON.stringify(opts.ownLeaf), JSON.stringify(opts.counterpartyLeaf), opts.merkleRoot, opts.nonce, now);
         }
         catch (err) {
             this.#logger.error("session.interrupted.db.write.failed", {
@@ -1842,8 +1953,8 @@ export class SessionNodeManager {
         // active-session seal). The guard still refuses to overwrite a terminal
         // 'sealed' row or an already-pending one.
         const result = this.#db
-            .prepare("UPDATE sessions SET status = 'seal_interrupted_pending', updated_at = ? WHERE agent_name = ? AND session_id = ? AND status IN ('active', 'interrupted')")
-            .run(now, opts.agentName, opts.sessionId);
+            .prepare("UPDATE sessions SET status = 'seal_interrupted_pending', updated_at = ? WHERE agent_id = ? AND session_id = ? AND status IN ('active', 'interrupted')")
+            .run(now, this.#requireAgentId(opts.agentName), opts.sessionId);
         return Number(result.changes) > 0;
     }
     /**
@@ -1854,8 +1965,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return null;
         const row = this.#db
-            .prepare("SELECT * FROM seal_interrupted_artifacts WHERE agent_name = ? AND session_id = ?")
-            .get(agentName, sessionId);
+            .prepare("SELECT * FROM seal_interrupted_artifacts WHERE agent_id = ? AND session_id = ?")
+            .get(this.#requireAgentId(agentName), sessionId);
         if (!row)
             return null;
         return {
@@ -1874,9 +1985,11 @@ export class SessionNodeManager {
         if (!this.#db)
             return null;
         const row = this.#db
-            .prepare("SELECT * FROM sessions WHERE agent_name = ? AND session_id = ?")
-            .get(agentName, sessionId);
-        return row ?? null;
+            .prepare("SELECT * FROM sessions WHERE agent_id = ? AND session_id = ?")
+            .get(this.#requireAgentId(agentName), sessionId);
+        // `agent_name` is display-only and no longer stored on the row; stamp back the name whose
+        // agent_id scoped this lookup (~50 daemon call sites read `record.agent_name`).
+        return row ? { ...row, agent_name: agentName } : null;
     }
     /**
      * MSG-2 startup-flush: the persisted relay endpoint for a session, or null if none was
@@ -1887,8 +2000,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return null;
         const row = this.#db
-            .prepare("SELECT relay_peer_id, relay_addrs FROM sessions WHERE agent_name = ? AND session_id = ?")
-            .get(agentName, sessionId);
+            .prepare("SELECT relay_peer_id, relay_addrs FROM sessions WHERE agent_id = ? AND session_id = ?")
+            .get(this.#requireAgentId(agentName), sessionId);
         if (!row?.relay_peer_id || !row?.relay_addrs)
             return null;
         try {
@@ -1911,8 +2024,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return [];
         const rows = this.#db
-            .prepare("SELECT DISTINCT relay_peer_id, relay_addrs FROM sessions WHERE agent_name = ? AND relay_peer_id IS NOT NULL")
-            .all(agentName);
+            .prepare("SELECT DISTINCT relay_peer_id, relay_addrs FROM sessions WHERE agent_id = ? AND relay_peer_id IS NOT NULL")
+            .all(this.#requireAgentId(agentName));
         const byPeer = new Map();
         for (const row of rows) {
             if (!row.relay_peer_id || !row.relay_addrs)
@@ -1962,9 +2075,9 @@ export class SessionNodeManager {
             try {
                 this.#db
                     .prepare(`INSERT INTO session_tree_leaves
-             (agent_name, session_id, leaf_index, leaf_kind, leaf_hash_hex, created_at)
+             (agent_id, session_id, leaf_index, leaf_kind, leaf_hash_hex, created_at)
              VALUES (?, ?, ?, ?, ?, ?)`)
-                    .run(agentName, sessionId, leafIndex, kind, leafHashHex, Date.now());
+                    .run(this.#requireAgentId(agentName), sessionId, leafIndex, kind, leafHashHex, Date.now());
                 // DAEMON-004 (finding #2): keep sessions.message_count synced to the tree
                 // size. message_count is the bilateral leafCount the seal flow signs over
                 // (handleSealInterruptedFlow / the responder). If it diverged from the
@@ -1972,8 +2085,8 @@ export class SessionNodeManager {
                 // truncated transcript and the bilateral leafCount check would mismatch.
                 // The tree (leafIndex + 1 leaves) is authoritative; the column tracks it.
                 this.#db
-                    .prepare("UPDATE sessions SET message_count = ?, updated_at = ? WHERE agent_name = ? AND session_id = ?")
-                    .run(leafIndex + 1, Date.now(), agentName, sessionId);
+                    .prepare("UPDATE sessions SET message_count = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?")
+                    .run(leafIndex + 1, Date.now(), this.#requireAgentId(agentName), sessionId);
             }
             catch (err) {
                 // A persist failure must be visible, not swallowed: the in-memory tree
@@ -2803,8 +2916,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return null;
         const row = this.#db
-            .prepare("SELECT sealed_root_hex FROM sessions WHERE agent_name = ? AND session_id = ?")
-            .get(agentName, sessionId);
+            .prepare("SELECT sealed_root_hex FROM sessions WHERE agent_id = ? AND session_id = ?")
+            .get(this.#requireAgentId(agentName), sessionId);
         return row?.sealed_root_hex ?? null;
     }
     // ─── CELLO-M7-MSG-001: delivery ACK / TTF tracking (send side) ──────────────
@@ -2973,8 +3086,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return SessionTree.empty();
         const rows = this.#db
-            .prepare("SELECT leaf_kind, leaf_hash_hex FROM session_tree_leaves WHERE agent_name = ? AND session_id = ? ORDER BY leaf_index ASC")
-            .all(agentName, sessionId);
+            .prepare("SELECT leaf_kind, leaf_hash_hex FROM session_tree_leaves WHERE agent_id = ? AND session_id = ? ORDER BY leaf_index ASC")
+            .all(this.#requireAgentId(agentName), sessionId);
         return SessionTree.fromLeaves(rows.map((r) => ({ kind: r.leaf_kind === "ctrl" ? "ctrl" : "msg", hashHex: r.leaf_hash_hex })));
     }
     /**
@@ -3424,9 +3537,9 @@ export class SessionNodeManager {
         try {
             this.#db
                 .prepare(`INSERT INTO sessions
-           (session_id, agent_name, counterparty_pubkey, status, created_at, updated_at)
+           (session_id, agent_id, counterparty_pubkey, status, created_at, updated_at)
            VALUES (?, ?, ?, ?, ?, ?)`)
-                .run(sessionId, agentName, counterpartyPubkey, status, now, now);
+                .run(sessionId, this.#requireAgentId(agentName), counterpartyPubkey, status, now, now);
             return true;
         }
         catch (err) {
@@ -3448,8 +3561,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return 0;
         const row = this.#db
-            .prepare("SELECT COUNT(*) AS n FROM transcript WHERE agent_name = ? AND session_id = ? AND direction = 'received'")
-            .get(agentName, sessionId);
+            .prepare("SELECT COUNT(*) AS n FROM transcript WHERE agent_id = ? AND session_id = ? AND direction = 'received'")
+            .get(this.#requireAgentId(agentName), sessionId);
         return row.n;
     }
     /** CC-5/F21: unilaterally mark a session locally-terminal ("abandoned") — retire its live node and
@@ -3471,8 +3584,8 @@ export class SessionNodeManager {
         const now = Date.now();
         try {
             this.#db
-                .prepare("UPDATE sessions SET status = ?, updated_at = ? WHERE agent_name = ? AND session_id = ?")
-                .run(status, now, agentName, sessionId);
+                .prepare("UPDATE sessions SET status = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?")
+                .run(status, now, this.#requireAgentId(agentName), sessionId);
             return true;
         }
         catch (err) {