@cello-protocol/daemon 0.0.44 → 0.0.46

package/dist/session-node-manager.js

@@ -69,6 +69,9 @@
 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 { TIER, normalizeTier, isKnownTierValue, tierBoundsFor, DEFAULT_TIER_BOUNDS, migrateContactsAddTierMetadata } from "./contacts-tier-migration.js";
+import { boundSettingKey, settableTierName, isValidSettingKey, awayTierSettingKey, AWAY_DEFAULT_KEY } from "./agent-settings-keys.js";
 import { randomUUID, createHash } from "node:crypto";
 import * as lp from "it-length-prefixed";
 import { decode, Encoder } from "cbor-x";
@@ -83,15 +86,18 @@ import { RelayReceiptStore } from "./relay-receipt-store.js";
 import { SessionSealLeafStore } from "./session-seal-leaf-store.js";
 import { PassthroughGatewayClient, GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT, } from "@cello-protocol/gateway";
 const CBOR_ENC = new Encoder({ tagUint8Array: false });
-// M8C-ABUSE-1: persistence bounds — the non-M9 remainder (per-message cap + outbound rate are
-// M9's, not rebuilt here). "Whitelisted senders bounded only by disk" (DoD) — these bounds apply
-// ONLY to sessions/senders that are NOT a known contact (CONTACT-1's whitelist).
-/** Anti-drip-feed: cumulative RECEIVED bytes per session, from a non-contact sender. */
-export const ABUSE_MAX_SESSION_RECEIVED_BYTES = 25 * 1024 * 1024; // 25 MB
-/** Anti-drip-feed via many sessions: active sessions a single unknown counterparty may hold open
- *  with one agent at once. */
-export const ABUSE_MAX_SESSIONS_PER_UNKNOWN_SENDER = 3;
-/** Anti-swarm: total active sessions from ALL unknown (non-contact) counterparties combined, per agent. */
+// M8C-ABUSE-1 + DOD-TIER-2: persistence bounds. Formerly a binary "known contacts exempt entirely,
+// everyone else 3 sessions / 25 MB"; now TIER-GRADUATED via DEFAULT_TIER_BOUNDS (contacts-tier-
+// migration). The two consts below are kept for back-compat but DERIVE from the grid's UNKNOWN row —
+// the grid is the single source (DOD-TIER-2 AC4), so these can never drift from it.
+/** Anti-drip-feed: cumulative RECEIVED bytes per session at the UNKNOWN tier (= the grid's UNKNOWN
+ *  byte cap). Higher tiers get more (DEFAULT_TIER_BOUNDS); no tier is unbounded (INV-TIER-BOUND). */
+export const ABUSE_MAX_SESSION_RECEIVED_BYTES = DEFAULT_TIER_BOUNDS[TIER.UNKNOWN].maxBytesPerSession; // 25 MB
+/** Anti-drip-feed via many sessions: active sessions an UNKNOWN counterparty may hold open at once
+ *  (= the grid's UNKNOWN per-sender cap). */
+export const ABUSE_MAX_SESSIONS_PER_UNKNOWN_SENDER = DEFAULT_TIER_BOUNDS[TIER.UNKNOWN].maxSessionsPerSender; // 3
+/** Anti-swarm: total active sessions from ALL UNKNOWN-tier counterparties combined, per agent. A
+ *  scalar across the whole unknown pool — not per-tier — so it stays a standalone const. */
 export const ABUSE_MAX_UNKNOWN_SESSIONS_GLOBAL = 50;
 // ─── SessionNodeManager ───────────────────────────────────────────────────────
 export class SessionNodeManager {
@@ -332,7 +338,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 +346,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 +394,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 +403,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 +413,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 +430,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 +446,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 +458,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 +471,20 @@ 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);
+        // DOD-TIER-1 (address-book Step 1): give `contacts` its tier metadata (tier / provenance /
+        // last_offered_moniker / away_message). Pure ADD COLUMN, no rebuild — so it runs AFTER the
+        // agent-id re-key above (it never needs to appear in that migration's pinned DDL) and BEFORE any
+        // read below. Idempotent, no column DEFAULT, grandfathers existing contacts to WHITELISTED once.
+        migrateContactsAddTierMetadata(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
@@ -475,12 +497,48 @@ export class SessionNodeManager {
         allowlisted_chat_id TEXT NOT NULL,
         updated_at INTEGER NOT NULL
       )
+    `);
+        // DOD-RENAME-1 (Option C): pending rename notices — one per (agent, contact). A notice is queued
+        // when a peer the operator has PERSONALLY NAMED offers a self-declared name that differs from the
+        // last one seen; it surfaces through cello_check_notifications (NOT a real-time push) and clears
+        // when the operator adopts a name (cello_contact_set_moniker) or removes the contact. Keyed on
+        // agent_id (the stable key); the offered name is charset-validated at the wire boundary but still
+        // operator-untrusted, so surfaces render it as a quoted CLAIM.
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS contact_rename_notices (
+        agent_id TEXT NOT NULL,
+        pubkey TEXT NOT NULL,
+        offered_name TEXT NOT NULL,
+        noticed_at INTEGER NOT NULL,
+        PRIMARY KEY (agent_id, pubkey)
+      )
+    `);
+        // DOD-SETTINGS-1: a daemon-side per-agent settings store for REACHABILITY POLICY (the tier bounds
+        // overrides and the per-tier/agent away messages). A generic key-value table on the stable
+        // agent_id, in the same SQLCipher DB. Deliberately NOT M9-CFG-001's gateway config store: this is
+        // daemon reachability policy, not gateway SCREENING config, and the M9 store is unwired + plaintext.
+        // reconcile with DOD-CONFIG-1 later; this is daemon reachability policy, not gateway config.
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS agent_settings (
+        agent_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (agent_id, key)
+      )
     `);
         // 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 +546,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 +622,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 +656,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 +680,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 +690,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,29 +709,98 @@ 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;
     }
+    /** DOD-TIER-1: the reachability tier for a counterparty of this agent. The RESULT is total — an
+     *  absent contact row (undefined), a NULL `tier`, or a corrupt out-of-range value all resolve to
+     *  UNKNOWN via `normalizeTier`, so the return is always in 0..4 and guards the JS `null >= 0`/`0 ||
+     *  1`/`grid[99]` traps. It is a SECURITY read (Step 2 gates inbound bounds on it), so it FAILS
+     *  CLOSED, never open: an uninitialized DB throws (same contract as addContact) rather than
+     *  silently returning UNKNOWN and admitting a BLOCKED sender; an unresolvable/retired agent name
+     *  throws via #requireAgentId. Both are invariant violations a caller must surface, not swallow. */
+    getTier(agentName, pubkey) {
+        // Fail CLOSED: a read that decides whether to admit a sender must not degrade to "unclassified"
+        // when it cannot reach the ACL — that would admit a blocked contact. Throw as addContact does.
+        if (!this.#db)
+            throw new Error(`getTier('${agentName}'): database not initialized`);
+        const row = this.#db
+            .prepare("SELECT tier FROM contacts WHERE agent_id = ? AND pubkey = ?")
+            .get(this.#requireAgentId(agentName), pubkey);
+        if (row && row.tier !== null && !isKnownTierValue(row.tier)) {
+            // A stored tier outside 0..4 is corruption — surface it. normalizeTier still maps it to the
+            // tighter UNKNOWN so the caller is safe, but a silent map would hide a broken row.
+            this.#logger.warn("contact.tier.corrupt", { agentName, pubkey, storedTier: row.tier });
+        }
+        return normalizeTier(row?.tier);
+    }
+    /** DOD-TIER-4: the DISPLAY/relationship check — is this counterparty a genuine contact (KNOWN or
+     *  above)? Replaces the old binary `isContact` for behaviour that keyed on "we have a relationship"
+     *  (e.g. the away-response wording). An UNKNOWN-tier contact (a mere row) is NOT known. */
+    isKnown(agentName, pubkey) {
+        return this.getTier(agentName, pubkey) >= TIER.KNOWN;
+    }
+    /** DOD-TIER-4: the POLICY gate — may an inbound session from this counterparty be auto-accepted
+     *  when the operator is unattended (WHITELISTED or VIP)? The behavioural consumer is the offline
+     *  relay mailbox (LEAVEMSG-1), out of scope for this unit; defined here as the seam. Being merely
+     *  KNOWN is NOT enough to auto-accept — whitelisting is the deliberate `cello_contact_set_tier` act. */
+    isAutoAccept(agentName, pubkey) {
+        return this.getTier(agentName, pubkey) >= TIER.WHITELISTED;
+    }
+    /** DOD-TIER-BOUNDS-SETTINGS: the effective bound for (agent, tier, field) — a per-agent SETTINGS
+     *  override if one is set and valid, else the hardcoded grid default (DEFAULT_TIER_BOUNDS). With no
+     *  settings this is byte-identical to Step 2 (the daemon runs on defaults alone). A stored value
+     *  that is somehow non-positive/non-finite (should be impossible — validated at SET time) falls back
+     *  to the grid default rather than removing the bound (INV-TIER-BOUND, defensive). BLOCKED is never
+     *  settable — it always returns the fixed grid value (0). */
+    resolveTierBound(agentName, tier, field) {
+        const gridDefault = field === "max_sessions"
+            ? tierBoundsFor(tier).maxSessionsPerSender
+            : tierBoundsFor(tier).maxBytesPerSession;
+        const name = settableTierName(tier);
+        if (name === null)
+            return gridDefault; // BLOCKED or out-of-range — fixed, not overridable
+        const raw = this.getSetting(agentName, boundSettingKey(name, field));
+        if (raw === null)
+            return gridDefault; // unset → default
+        const parsed = Number(raw);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            // Should be impossible (validated at SET time) → a config-integrity failure. Surface it: this
+            // reverts a possibly-TIGHTENED bound to the looser default, so a silent revert would hide a real
+            // problem. Still fail SAFE (grid default, never unbounded — INV-TIER-BOUND).
+            this.#logger.warn("settings.bound.corrupt", { agentName, tier, field, raw });
+            return gridDefault;
+        }
+        return parsed;
+    }
     /** M8C-CONTACT-1: pin a contact at add time — idempotent (re-adding an existing contact is a
      *  no-op, never refreshes added_at; identity does not get re-resolved). MONIKER-3 AC2: an
      *  optional pet name; a NEW non-null moniker on re-add updates it, absence leaves it untouched.
      *  THROWS on an invalid moniker — callers validate first; this is the can-never-be-stored
-     *  backstop (same contract as DbIdentityStore.setMoniker). */
-    addContact(agentName, pubkey, moniker) {
+     *  backstop (same contract as DbIdentityStore.setMoniker).
+     *
+     *  DOD-TIER-1/4: a NEW row is stamped `tier` (never NULL) and an optional `provenance`
+     *  ('accepted' | 'initiated' | null). The `tier` defaults to the least-privilege UNKNOWN floor —
+     *  a caller GRANTS trust by passing a higher tier explicitly. Every production creation path is a
+     *  deliberate operator action and passes KNOWN (initiate, engage/reply, explicit cello_contact_add
+     *  — DEC-AB-1). INSERT OR IGNORE means an EXISTING contact is untouched — tier and provenance pin
+     *  at first add, exactly as `added_at`/`moniker` already do; re-adding never downgrades a contact
+     *  the operator has since promoted. Raising the tier later is `cello_contact_set_tier`'s job. */
+    addContact(agentName, pubkey, moniker, provenance, tier = TIER.UNKNOWN) {
         if (!pubkey)
             return;
         // Review F1: a missing DB handle must FAIL the write loudly — returning silently here let
@@ -675,13 +810,21 @@ 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}`);
         }
+        // DOD-TIER-4 (review F3): the stored tier must be a known 0..4 constant — a can-never-be-stored
+        // backstop mirroring the moniker validation above. All callers pass a TIER constant; this catches
+        // a future caller (or a bad refactor) that would otherwise persist a corrupt tier the read side
+        // must then defensively normalize.
+        if (!isKnownTierValue(tier)) {
+            throw new Error(`invalid contact tier for agent '${agentName}': ${tier} (must be 0..4)`);
+        }
+        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, tier, provenance) VALUES (?, ?, ?, ?, ?)")
+            .run(agentId, pubkey, Date.now(), tier, provenance ?? null);
         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 +839,130 @@ 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);
+        // DOD-RENAME-1: setting the local pet name IS the operator acting on a rename — resolve any
+        // pending notice for this contact (whether they adopted the offered name or chose their own).
+        if (res.changes > 0)
+            this.clearRenameNotice(agentName, pubkey);
+        return res.changes > 0;
+    }
+    /** DOD-AWAY-TIER-1: set (or clear, with null) a contact's per-contact away message. Returns false
+     *  when no such contact — fail-loud at the caller (same contract as setContactMoniker/setContactTier). */
+    setContactAwayMessage(agentName, pubkey, message) {
+        if (!this.#db)
+            throw new Error(`setContactAwayMessage('${agentName}'): database not initialized`);
+        const res = this.#db
+            .prepare("UPDATE contacts SET away_message = ? WHERE agent_id = ? AND pubkey = ?")
+            .run(message, this.#requireAgentId(agentName), pubkey);
         return res.changes > 0;
     }
+    /** DOD-AWAY-TIER-1: resolve the most-specific CUSTOM away text for a counterparty, most-specific
+     *  first: per-contact `away_message` → per-tier away setting → agent default away setting. Returns
+     *  null when none is configured, so the CALLER applies the system default (code) — making the full
+     *  four-level resolution TOTAL. A pure read; the resolved text is screened on the outbound path by
+     *  the caller like any content (SI — it does not bypass the gateway). */
+    resolveAwayMessage(agentName, pubkey) {
+        if (!this.#db)
+            return null;
+        const agentId = this.#requireAgentId(agentName);
+        const row = this.#db
+            .prepare("SELECT away_message FROM contacts WHERE agent_id = ? AND pubkey = ?")
+            .get(agentId, pubkey);
+        if (row?.away_message != null) {
+            this.#logger.debug("contact.away.resolved", { agentName, pubkey, level: "contact" }); // obs AC
+            return row.away_message; // 1. per-contact
+        }
+        const tierName = settableTierName(this.getTier(agentName, pubkey));
+        if (tierName !== null) {
+            const tierAway = this.getSetting(agentName, awayTierSettingKey(tierName));
+            if (tierAway !== null) {
+                this.#logger.debug("contact.away.resolved", { agentName, pubkey, level: "tier" });
+                return tierAway; // 2. per-tier
+            }
+        }
+        const agentDefault = this.getSetting(agentName, AWAY_DEFAULT_KEY);
+        // 3. agent default, else null → caller applies the system default (code). Level logged HERE.
+        this.#logger.debug("contact.away.resolved", { agentName, pubkey, level: agentDefault !== null ? "agent_default" : "system" });
+        return agentDefault;
+    }
+    /** DOD-CONTACT-VIEW-1: set an EXISTING contact's reachability tier. Returns false when no such
+     *  contact — fail-loud at the caller, never a silent no-op success (same contract as
+     *  setContactMoniker). The caller validates the tier is a known constant BEFORE calling; this
+     *  stores whatever it is handed (the handler is the validation boundary). */
+    setContactTier(agentName, pubkey, tier) {
+        if (!this.#db)
+            throw new Error(`setContactTier('${agentName}'): database not initialized`);
+        const res = this.#db
+            .prepare("UPDATE contacts SET tier = ? WHERE agent_id = ? AND pubkey = ?")
+            .run(tier, this.#requireAgentId(agentName), pubkey);
+        return res.changes > 0;
+    }
+    /** DOD-RENAME-1 (Option C): record a self-declared name a peer offered, at the moment the offer is
+     *  SEEN. The stored local pet name (contacts.moniker) is SACROSANCT — this only ever touches
+     *  last_offered_moniker and the notice queue, never the moniker (AC2). A rename NOTICE is queued
+     *  only when the peer is a contact the operator has PERSONALLY NAMED (moniker non-null), a name was
+     *  seen BEFORE (last_offered_moniker non-null), and the new offer DIFFERS (AC3). The first-ever
+     *  offer just records the baseline (no notice); a repeat of the same name is idempotent (AC4).
+     *  Called only when a moniker WAS offered (caller-guarded), so silence never clears the baseline
+     *  (AC5). Limitation: last_offered_moniker updates only on the RECEIVING side of an offer, so rename
+     *  detection works only for peers who INITIATE to you — a property, not a bug. */
+    recordOfferedMoniker(agentName, pubkey, offered) {
+        // Fail CLOSED like getTier/setContactTier: a silent skip here would drop a rename baseline update
+        // (and any notice) while the daemon reports healthy — the inbound path always has an open DB.
+        if (!this.#db)
+            throw new Error(`recordOfferedMoniker('${agentName}'): database not initialized`);
+        const agentId = this.#requireAgentId(agentName);
+        const row = this.#db
+            .prepare("SELECT last_offered_moniker, moniker FROM contacts WHERE agent_id = ? AND pubkey = ?")
+            .get(agentId, pubkey);
+        if (!row)
+            return; // not a contact — no row to hold a baseline or a notice
+        if (offered === row.last_offered_moniker)
+            return; // idempotent — same name already seen (AC4)
+        // A genuine change from a previously-seen name, for a contact the operator has named → notice.
+        if (row.last_offered_moniker !== null && row.moniker !== null) {
+            this.#db
+                .prepare("INSERT OR REPLACE INTO contact_rename_notices (agent_id, pubkey, offered_name, noticed_at) VALUES (?, ?, ?, ?)")
+                .run(agentId, pubkey, offered, Date.now());
+            // Observability: log the FACT, never the attacker-chosen name (same rule as moniker.rejected).
+            this.#logger.info("contact.rename.noticed", { agentName, pubkey });
+        }
+        this.#db
+            .prepare("UPDATE contacts SET last_offered_moniker = ? WHERE agent_id = ? AND pubkey = ?")
+            .run(offered, agentId, pubkey);
+    }
+    /** DOD-RENAME-1: pending rename notices for an agent, oldest first (surfaced in
+     *  cello_check_notifications — an INBOX pull, never a real-time push). */
+    getRenameNotices(agentName) {
+        if (!this.#db)
+            return [];
+        // JOIN the local pet name so the notice can NAME the contact (AC3) — a notice only ever fires for
+        // a personally-named contact, so moniker is expected non-null (LEFT JOIN is defensive).
+        return this.#db
+            .prepare(`SELECT n.pubkey, n.offered_name, n.noticed_at, c.moniker
+         FROM contact_rename_notices n
+         LEFT JOIN contacts c ON c.agent_id = n.agent_id AND c.pubkey = n.pubkey
+         WHERE n.agent_id = ? ORDER BY n.noticed_at ASC`)
+            .all(this.#requireAgentId(agentName));
+    }
+    /** DOD-RENAME-1: clear a pending rename notice — the operator acted (adopted a name or removed the
+     *  contact). Idempotent (no notice → no-op). Fail-closed on a missing DB, like the writes above. */
+    clearRenameNotice(agentName, pubkey) {
+        if (!this.#db)
+            throw new Error(`clearRenameNotice('${agentName}'): database not initialized`);
+        this.#db
+            .prepare("DELETE FROM contact_rename_notices WHERE agent_id = ? AND pubkey = ?")
+            .run(this.#requireAgentId(agentName), pubkey);
+    }
     /** 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);
+        // DOD-RENAME-1: a removed contact has no pending rename to resolve.
+        if (res.changes > 0)
+            this.clearRenameNotice(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,26 +975,36 @@ 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
-     *  the pet name (null when none set). */
+    /** M8C-CONTACT-1 + DOD-CONTACT-VIEW-1: list an agent's contacts, oldest-added first, each with its
+     *  pet name (MONIKER-3), tier + provenance (the address-book metadata), and a READ-side LEFT JOIN
+     *  against `sessions` for how many SEALED sessions were shared and when they last spoke (MAX
+     *  updated_at). No new stored data — a pure read. A contact with no sessions shows 0 / null (never),
+     *  not an error. The JOIN is scoped by agent_id so one agent's sessions never bleed into another's. */
     listContacts(agentName) {
         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 c.pubkey, c.added_at, c.moniker, c.tier, c.provenance,
+                COUNT(CASE WHEN s.status = 'sealed' THEN 1 END) AS sealed_count,
+                MAX(s.updated_at) AS last_spoke
+         FROM contacts c
+         LEFT JOIN sessions s ON s.agent_id = c.agent_id AND s.counterparty_pubkey = c.pubkey
+         WHERE c.agent_id = ?
+         GROUP BY c.pubkey, c.added_at, c.moniker, c.tier, c.provenance
+         ORDER BY c.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,36 +1031,53 @@ 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
-     *  NOT a known contact — the global cap counts across ALL unknown senders combined. Same
+    /** M8C-ABUSE-1 (anti-swarm) + DOD-TIER-2: non-terminal sessions this agent holds with UNKNOWN-tier
+     *  counterparties — the global cap counts across the whole stranger pool. A sender is exempt from
+     *  THIS pool iff it is a KNOWN+ contact (tier >= KNOWN); a bare stranger (no row → UNKNOWN) or an
+     *  explicitly UNKNOWN-tier contact both count. Keying on `tier >= KNOWN` (bounded to <= VIP so a
+     *  corrupt high value cannot grant pool-exemption) replaces the old row-existence proxy, which
+     *  would have let a merely-recorded UNKNOWN contact escape the anti-swarm cap. Same
      *  'interrupted'-status fix as countActiveSessionsForCounterparty above. */
     countActiveSessionsFromUnknownSenders(agentName) {
         if (!this.#db)
             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
+               AND c.tier >= ${TIER.KNOWN} AND c.tier <= ${TIER.VIP}
+           )`)
+            .get(this.#requireAgentId(agentName));
         return row.n;
     }
-    /** M8C-ABUSE-1: is a NEW inbound session from this counterparty within the acceptance bounds?
-     *  Known contacts are exempt entirely ("bounded only by disk" — DoD). Checked BEFORE accepting
-     *  a fresh inbound session (the counts reflect sessions already active, not yet counting this one). */
+    /** M8C-ABUSE-1 + DOD-TIER-2/3: is a NEW inbound session from this counterparty within the
+     *  acceptance bounds? The per-sender cap is now the sender's TIER cap (DEFAULT_TIER_BOUNDS), not a
+     *  flat "3 for strangers, unbounded for contacts". This is where DOD-TIER-3 falls out for free: a
+     *  BLOCKED sender's cap is 0, so `perSender (>= 0) >= 0` refuses it through the SAME reason and the
+     *  SAME path an over-cap UNKNOWN takes — no separate blocked branch, no distinguishing oracle. The
+     *  global anti-swarm cap then applies ONLY to UNKNOWN-tier senders (KNOWN+ are trusted, not part of
+     *  the stranger pool; BLOCKED never reaches it). Checked BEFORE accepting a fresh inbound session
+     *  (counts reflect sessions already active, not yet counting this one). */
     checkUnknownSenderAcceptanceBound(agentName, counterpartyPubkey) {
-        if (this.isContact(agentName, counterpartyPubkey))
-            return { ok: true };
+        const tier = this.getTier(agentName, counterpartyPubkey);
+        const perSenderCap = this.resolveTierBound(agentName, tier, "max_sessions");
         const perSender = this.countActiveSessionsForCounterparty(agentName, counterpartyPubkey);
-        if (perSender >= ABUSE_MAX_SESSIONS_PER_UNKNOWN_SENDER) {
+        if (perSender >= perSenderCap) {
             return { ok: false, reason: "abuse_bound_sessions_per_sender" };
         }
-        const globalUnknown = this.countActiveSessionsFromUnknownSenders(agentName);
-        if (globalUnknown >= ABUSE_MAX_UNKNOWN_SESSIONS_GLOBAL) {
-            return { ok: false, reason: "abuse_bound_unknown_sessions_global" };
+        // The global stranger cap is only for the UNKNOWN pool. A KNOWN+ sender is past it by trust;
+        // a BLOCKED sender was already refused above (cap 0).
+        if (tier === TIER.UNKNOWN) {
+            const globalUnknown = this.countActiveSessionsFromUnknownSenders(agentName);
+            if (globalUnknown >= ABUSE_MAX_UNKNOWN_SESSIONS_GLOBAL) {
+                return { ok: false, reason: "abuse_bound_unknown_sessions_global" };
+            }
         }
         return { ok: true };
     }
@@ -814,6 +1099,42 @@ export class SessionNodeManager {
          ON CONFLICT(id) DO UPDATE SET bot_token = excluded.bot_token, allowlisted_chat_id = excluded.allowlisted_chat_id, updated_at = excluded.updated_at`)
             .run(botToken, allowlistedChatId, Date.now());
     }
+    /** DOD-SETTINGS-1: read a per-agent setting, or null if unset. The get-with-default is the CALLER's
+     *  job (an unset key falls back to the hardcoded grid/system default — the daemon runs correctly on
+     *  defaults alone, AC3). Returns null on a missing DB (settings are always optional). */
+    getSetting(agentName, key) {
+        if (!this.#db)
+            return null;
+        const row = this.#db
+            .prepare("SELECT value FROM agent_settings WHERE agent_id = ? AND key = ?")
+            .get(this.#requireAgentId(agentName), key);
+        return row?.value ?? null;
+    }
+    /** DOD-SETTINGS-1: write a per-agent setting (upsert). Key VALIDATION is the handler's boundary
+     *  (isValidSettingKey); value validation for typed settings (finite bounds, etc.) belongs to the
+     *  specific consumer. Throws on a missing DB — a write that silently no-ops would be a lie. */
+    setSetting(agentName, key, value) {
+        if (!this.#db)
+            throw new Error(`setSetting('${agentName}'): database not initialized`);
+        // Store-level backstop (review F2): the handler validates the key, but the dual-layer convention
+        // (cf. MONIKER-1) means an unknown key can NEVER be stored — an internal caller that hand-typed a
+        // key instead of using the builders would otherwise persist a setting that never takes effect.
+        if (!isValidSettingKey(key))
+            throw new Error(`invalid_key: '${key}' is not a known setting`);
+        this.#db
+            .prepare(`INSERT INTO agent_settings (agent_id, key, value, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(agent_id, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`)
+            .run(this.#requireAgentId(agentName), key, value, Date.now());
+    }
+    /** DOD-SETTINGS-1: all explicitly-set settings for an agent (the ones that OVERRIDE a default),
+     *  key-sorted. Unset keys are absent — the operator sees only what they changed. */
+    getAllSettings(agentName) {
+        if (!this.#db)
+            return [];
+        return this.#db
+            .prepare("SELECT key, value FROM agent_settings WHERE agent_id = ? ORDER BY key ASC")
+            .all(this.#requireAgentId(agentName));
+    }
     /** DOD-LOOP-1: whether the given agent has a standing receiver ready (any agent if omitted). */
     getStandingReceiverReady(agentName) {
         if (agentName !== undefined)
@@ -906,6 +1227,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 +1533,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 +1976,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 +2005,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 +2021,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 +2043,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 +2062,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 +2077,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 +2092,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 +2145,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 +2230,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 +2246,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 +2258,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 +2278,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 +2293,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 +2317,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 +2368,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 +2378,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
@@ -2463,10 +2869,15 @@ export class SessionNodeManager {
         // seam below (cheap + synchronous — fail fast on volume before spending gateway compute on
         // content headed for rejection anyway); both gates are independent and either rejects on its
         // own criteria, so ordering between them does not change correctness.
-        if (!this.isContact(agentName, senderPubkey)) {
+        {
+            // DOD-TIER-2 AC2: the per-session byte cap is the sender's TIER cap (DEFAULT_TIER_BOUNDS),
+            // applied to EVERY sender — no tier is unbounded (INV-TIER-BOUND), so a contact is no longer
+            // "exempt entirely". A stranger (no row → UNKNOWN) keeps the 25 MB cap; KNOWN+ get more.
+            const senderTier = this.getTier(agentName, senderPubkey);
+            const cap = this.resolveTierBound(agentName, senderTier, "max_bytes");
             const priorTotal = this.#getReceivedBytesTotal(agentName, sessionId);
             const heldTotal = this.#getHeldBytesTotal(agentName, sessionId);
-            if (priorTotal + heldTotal + content.length > ABUSE_MAX_SESSION_RECEIVED_BYTES) {
+            if (priorTotal + heldTotal + content.length > cap) {
                 this.#logger.warn("session.content.abuse_bound.session_size_exceeded", {
                     sessionId,
                     agentName,
@@ -2474,7 +2885,8 @@ export class SessionNodeManager {
                     priorTotal,
                     heldTotal,
                     incoming: content.length,
-                    cap: ABUSE_MAX_SESSION_RECEIVED_BYTES,
+                    cap,
+                    tier: senderTier,
                     correlationId,
                 });
                 return { ok: false, reason: "session_size_limit_exceeded" };
@@ -2579,10 +2991,16 @@ export class SessionNodeManager {
         // the append/hold branch is synchronous, so whichever call resumes first appends/holds before
         // the second's re-check runs, and the second's freshly-recomputed totals correctly include the
         // first's contribution.
-        if (!this.isContact(agentName, senderPubkey)) {
+        {
+            // DOD-TIER-2 AC2 (re-check): the SAME tier cap as the primary gate above, recomputed in this
+            // synchronous window (the totals can go stale across the screenInbound await). Applied to EVERY
+            // sender — a contact is no longer exempt (INV-TIER-BOUND). Must mirror the primary gate exactly
+            // so a sender can never pass one and fail the other.
+            const senderTier = this.getTier(agentName, senderPubkey);
+            const cap = this.resolveTierBound(agentName, senderTier, "max_bytes");
             const priorTotal = this.#getReceivedBytesTotal(agentName, sessionId);
             const heldTotal = this.#getHeldBytesTotal(agentName, sessionId);
-            if (priorTotal + heldTotal + content.length > ABUSE_MAX_SESSION_RECEIVED_BYTES) {
+            if (priorTotal + heldTotal + content.length > cap) {
                 this.#logger.warn("session.content.abuse_bound.session_size_exceeded", {
                     sessionId,
                     agentName,
@@ -2590,7 +3008,8 @@ export class SessionNodeManager {
                     priorTotal,
                     heldTotal,
                     incoming: content.length,
-                    cap: ABUSE_MAX_SESSION_RECEIVED_BYTES,
+                    cap,
+                    tier: senderTier,
                     correlationId,
                     recheck: true,
                 });
@@ -2803,8 +3222,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 +3392,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 +3843,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 +3867,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 +3890,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) {