@cello-protocol/daemon 0.0.45 → 0.0.47

package/dist/session-node-manager.js

@@ -70,6 +70,8 @@ import { openEncryptedDatabase, resolveDbKey, dbKeyPathFor, } from "./sqlcipher-
 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";
@@ -84,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 {
@@ -475,6 +480,11 @@ export class SessionNodeManager {
         // 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
@@ -487,6 +497,35 @@ 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
@@ -658,6 +697,16 @@ export class SessionNodeManager {
             .run(this.#requireAgentId(agentName), sessionId, seq);
         this.#logger.info("message.watermark.advanced", { agentName, sessionId, sequence: seq });
     }
+    /**
+     * The ONE definition of "unread" in this daemon: a RECEIVED transcript row whose sequence is
+     * beyond the agent's persisted read watermark. A constant, not a copy-pasted string, so the
+     * INBOX unread count and the DOD-CURSOR-DURABLE-1 read-before-write gate can never drift into
+     * disagreeing about what "unread" means — the gate deciding one thing while the inbox shows
+     * another is precisely the bug this shape prevents. Interpolated SQL only (no user input).
+     */
+    static #UNREAD_RECEIVED_WHERE = `
+           t.direction = 'received'
+           AND t.sequence > COALESCE(w.last_delivered_seq, -1)`;
     /** INBOX-1 (N2): per-session unread summary for an agent — sessions that have RECEIVED transcript
      *  messages beyond the read watermark. Content-free (counts + ids + last seq, never message text);
      *  a COUNT/MAX query, no decrypt. Only sessions with unread_count > 0 are returned. */
@@ -672,14 +721,39 @@ export class SessionNodeManager {
          LEFT JOIN message_watermarks w
            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)
+           AND ${SessionNodeManager.#UNREAD_RECEIVED_WHERE}
          GROUP BY t.session_id
          HAVING unread_count > 0
          ORDER BY t.session_id ASC`)
             .all(this.#requireAgentId(agentName));
         return rows;
     }
+    /**
+     * DOD-CURSOR-DURABLE-1: how many RECEIVED messages in THIS session the agent has not read —
+     * the durable half of the read-before-write gate. Same predicate as getUnreadSummary (shared
+     * constant above), scoped to one session.
+     *
+     * This is DURABLE and PER-AGENT, where the send gate's other authority (the connection cursor) is
+     * in-memory and per-connection. It is what lets a stateless client — the `cello` CLI, one process
+     * per command — prove it has read the counterparty, which a dead socket's cursor never can.
+     *
+     * FAILS CLOSED: an uninitialized DB returns a positive count (treated as "unread"), never 0. A 0
+     * here unblocks a send; guessing 0 from a broken DB would silently defeat the gate.
+     */
+    getUnreadReceivedCount(agentName, sessionId) {
+        if (!this.#db)
+            return 1; // fail closed — never unblock a send because the DB is unavailable
+        const row = this.#db
+            .prepare(`SELECT COUNT(*) AS unread_count
+         FROM transcript t
+         LEFT JOIN message_watermarks w
+           ON w.agent_id = t.agent_id AND w.session_id = t.session_id
+         WHERE t.agent_id = ?
+           AND t.session_id = ?
+           AND ${SessionNodeManager.#UNREAD_RECEIVED_WHERE}`)
+            .get(this.#requireAgentId(agentName), sessionId);
+        return row ? row.unread_count : 0;
+    }
     /** M8C-CONTACT-1: is this pubkey a known contact of this agent? */
     isContact(agentName, pubkey) {
         if (!this.#db)
@@ -687,12 +761,81 @@ export class SessionNodeManager {
         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
@@ -702,10 +845,17 @@ 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_id, pubkey, added_at) VALUES (?, ?, ?)")
-            .run(agentId, 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_id = ? AND pubkey = ?")
@@ -726,13 +876,128 @@ export class SessionNodeManager {
         const res = this.#db
             .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_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
@@ -749,13 +1014,23 @@ export class SessionNodeManager {
             .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_id = ? ORDER BY added_at ASC")
+            .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). */
@@ -795,8 +1070,12 @@ export class SessionNodeManager {
             .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)
@@ -804,23 +1083,36 @@ export class SessionNodeManager {
         const row = this.#db
             .prepare(`SELECT COUNT(*) AS n FROM sessions s
          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 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 };
     }
@@ -842,6 +1134,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)
@@ -2576,10 +2904,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,
@@ -2587,7 +2920,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" };
@@ -2692,10 +3026,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,
@@ -2703,7 +3043,8 @@ export class SessionNodeManager {
                     priorTotal,
                     heldTotal,
                     incoming: content.length,
-                    cap: ABUSE_MAX_SESSION_RECEIVED_BYTES,
+                    cap,
+                    tier: senderTier,
                     correlationId,
                     recheck: true,
                 });