@cello-protocol/daemon 0.0.44 → 0.0.46

package/dist/daemon.js

@@ -32,6 +32,8 @@ import { loadAgents } from "./agent-loader.js";
 import { acquireLock, removeLock } from "./lock-file.js";
 import { createIpcServer } from "./ipc-server.js";
 import { SessionNodeManager } from "./session-node-manager.js";
+import { TIER, isKnownTierValue } from "./contacts-tier-migration.js";
+import { isValidSettingKey, allSettingKeys, validateSettingValue, AWAY_MESSAGE_MAX_LEN } from "./agent-settings-keys.js";
 import { classifySession } from "./session-category.js";
 import { PassthroughGatewayClient, GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT } from "@cello-protocol/gateway";
 import { RetryQueue } from "./retry-queue.js";
@@ -827,10 +829,32 @@ export async function startDaemon(config) {
         // every inbound interaction (promotion now requires operator engagement — an outbound initiate,
         // a cello_send reply, or an explicit contact add). No subsequent add is coupled to this line's
         // ordering anymore; it is a plain read of current contact state.
-        const isKnown = sessionNodeManager.isContact(agentName, record.counterparty_pubkey);
+        const isKnown = sessionNodeManager.isKnown(agentName, record.counterparty_pubkey);
         awayAckSent.add(dedupKey); // guard BEFORE the async send — concurrent arrivals must not double-ack
         try {
-            const contentBytes = new TextEncoder().encode(isKnown ? AWAY_TEXT[kind] : STRANGER_TEXT);
+            // DOD-AWAY-TIER-1: resolve most-specific-first — per-contact away_message → per-tier away
+            // (settings) → agent default (settings) → the system default (code, per kind). Total.
+            const awayText = sessionNodeManager.resolveAwayMessage(agentName, record.counterparty_pubkey)
+                ?? (isKnown ? AWAY_TEXT[kind] : STRANGER_TEXT);
+            const draftBytes = new TextEncoder().encode(awayText);
+            // SI (AWAY-TIER-1): an away message is now operator-configurable, i.e. an outbound DISCLOSURE.
+            // Screen it on the outbound path like any content — it does NOT bypass the gateway. A block/warn
+            // verdict means it is not sent (the dedup guard stays set — one screen per away period, no spam);
+            // a redact verdict sends the ALTERED bytes.
+            const awayVerdict = await securityGateway.screenOutbound(draftBytes, {
+                direction: "outbound", agentName, sessionId, correlationId: randomUUID(),
+            });
+            if (awayVerdict.disposition === "block" || awayVerdict.disposition === "warn") {
+                logger.info("session.away.response.screened_out", { agentName, sessionId, kind, disposition: awayVerdict.disposition });
+                return;
+            }
+            if (awayVerdict.disposition === "redact" && awayVerdict.content === undefined) {
+                logger.error("session.away.response.redact_without_content", { agentName, sessionId, kind });
+                return;
+            }
+            const contentBytes = awayVerdict.disposition === "redact" && awayVerdict.content !== undefined
+                ? new Uint8Array(awayVerdict.content)
+                : draftBytes;
             const contentHash = createHash("sha256").update(new Uint8Array([0x00])).update(contentBytes).digest();
             const sendResult = await sessionNodeManager.sendContent(agentName, sessionId, contentBytes, new Uint8Array(contentHash), randomUUID());
             if (!sendResult.ok) {
@@ -1450,12 +1474,14 @@ export async function startDaemon(config) {
     // entry; a TTF expiry records the un-acked content for the crash backstop (the relay
     // park deposit itself is added in 3b). Both side effects are best-effort and never
     // throw into the content stream handler.
+    // DOD-AGENT-ID-JOINKEY-1: RetryQueue owns an agent-scoped table, so it is handed the STABLE
+    // agent_id. The daemon resolves the operator-facing name ONCE, here at its own boundary.
     sessionNodeManager.setAwaitingAckHooks({
         onPersisted: (agentName, sessionId, contentHashHex) => {
-            retryQueue.markContentAcked(agentName, sessionId, Buffer.from(contentHashHex, "hex"));
+            retryQueue.markContentAcked(sessionNodeManager.resolveAgentId(agentName), sessionId, Buffer.from(contentHashHex, "hex"));
         },
         onTtf: (agentName, sessionId, contentHashHex, content) => {
-            retryQueue.enqueueAwaitingContent(agentName, sessionId, Buffer.from(contentHashHex, "hex"), content);
+            retryQueue.enqueueAwaitingContent(sessionNodeManager.resolveAgentId(agentName), sessionId, Buffer.from(contentHashHex, "hex"), content);
         },
     });
     // MSG-001-3b (2b): the LIVE content-park deposit. On a not-confirmed send (direct delivery
@@ -1508,8 +1534,14 @@ export async function startDaemon(config) {
     // PERSISTED session state (the in-memory entry is gone after a restart). Same seal + deposit
     // as the live hook above; the endpoint + recipient come from the sessions row.
     const startupParkFn = async (entry) => {
-        const ep = sessionNodeManager.getPersistedRelayEndpoint(entry.agentName, entry.sessionId);
-        const record = sessionNodeManager.getSessionRecord(entry.agentName, entry.sessionId);
+        // The durable row carries the OWNING agent's stable id. Resolve it back to a name for the
+        // name-addressed session/standing-receiver lookups. A retired owner resolves fine and then has no
+        // standing receiver, so the park fails loudly below rather than silently re-parking as someone else.
+        const ownerName = sessionNodeManager.agentNameForId(entry.agentId);
+        if (ownerName === null)
+            return { parked: false, error: "owning_agent_not_found" };
+        const ep = sessionNodeManager.getPersistedRelayEndpoint(ownerName, entry.sessionId);
+        const record = sessionNodeManager.getSessionRecord(ownerName, entry.sessionId);
         if (!ep)
             return { parked: false, error: "no_persisted_relay_endpoint" };
         if (!record?.counterparty_pubkey)
@@ -1543,18 +1575,23 @@ export async function startDaemon(config) {
     // Re-park un-acked awaiting content to the relay store-and-forward queue. Runs once pre-IPC
     // (the crash backstop) and again per-agent when an agent comes online — because post-DOD-LOOP-1
     // the native `startupParkFn` needs the OWNING agent's standing receiver, which exists only once
-    // that agent is online. `filterAgent` scopes the drain to one agent's sessions on the agent-
+    // that agent is online. `filterAgentName` scopes the drain to one agent's sessions on the agent-
     // online re-run; with no filter it attempts all (the pre-IPC pass / injected-target test path).
-    async function flushAwaitingContent(filterAgent) {
+    async function flushAwaitingContent(filterAgentName) {
+        // DOD-AGENT-ID-JOINKEY-1: the queue is keyed by the STABLE agent_id, but the caller (and the
+        // human-readable log) speak the NAME. Resolve once here; log the name, filter by the id.
+        const filterAgentId = filterAgentName !== undefined
+            ? sessionNodeManager.resolveAgentId(filterAgentName)
+            : undefined;
         const all = retryQueue.getAwaitingSessions();
-        const sessions = filterAgent === undefined
+        const sessions = filterAgentId === undefined
             ? all
-            : all.filter((s) => s.agentName === filterAgent);
+            : all.filter((s) => s.agentId === filterAgentId);
         if (sessions.length === 0)
             return;
         const parkFn = config.contentParkFn ?? startupParkFn;
         if (!parkFn) {
-            const pendingCount = sessions.reduce((n, s) => n + retryQueue.getAwaitingDepth(s.agentName, s.sessionId), 0);
+            const pendingCount = sessions.reduce((n, s) => n + retryQueue.getAwaitingDepth(s.agentId, s.sessionId), 0);
             logger.warn("content.park.flush.deferred", {
                 sessionCount: sessions.length,
                 pendingCount,
@@ -1565,7 +1602,7 @@ export async function startDaemon(config) {
         let parkedTotal = 0;
         for (const s of sessions) {
             try {
-                parkedTotal += await retryQueue.drainAwaitingToPark(s.agentName, s.sessionId, parkFn);
+                parkedTotal += await retryQueue.drainAwaitingToPark(s.agentId, s.sessionId, parkFn);
             }
             catch (err) {
                 logger.error("content.park.flush.failed", {
@@ -1577,7 +1614,7 @@ export async function startDaemon(config) {
         logger.info("content.park.flush.completed", {
             sessionCount: sessions.length,
             parkedCount: parkedTotal,
-            ...(filterAgent !== undefined ? { agentName: filterAgent } : {}),
+            ...(filterAgentName !== undefined ? { agentName: filterAgentName } : {}),
         });
     }
     await flushAwaitingContent();
@@ -2992,8 +3029,10 @@ export async function startDaemon(config) {
             }
         }
         // M8C-CONTACT-1 (D6): "initiating a session to X adds X" — pin at the pubkey the negotiator
-        // actually used (not re-resolved later).
-        sessionNodeManager.addContact(agentName, counterpartyPubkey);
+        // actually used (not re-resolved later). DOD-TIER-4 AC3: a deliberate outbound initiate makes the
+        // counterparty KNOWN, provenance 'initiated'. (Not WHITELISTED — auto-accept stays an explicit
+        // cello_contact_set_tier act, design §1.)
+        sessionNodeManager.addContact(agentName, counterpartyPubkey, undefined, "initiated", TIER.KNOWN);
         // AC-007: the session is usable immediately upon (relay) connection — the dcutr
         // upgrade runs in the background and is intentionally NOT awaited here.
         return { ok: true, sessionId, transportMode: result.mode, correlationId };
@@ -3507,10 +3546,16 @@ export async function startDaemon(config) {
         }
         // DOD-LOOP-1: awaiting content is keyed by the OWNING agent. Prefer an explicit agentName param;
         // fall back to the connection's current agent.
+        // DOD-AGENT-ID-JOINKEY-1: the old `?? ""` fell back to an EMPTY-STRING agent, silently merging
+        // every unaddressed caller's awaiting content into one nameless queue. There is no such agent.
         const agentName = params?.agentName
-            ?? perConnectionState.get(connectionId)?.currentAgent ?? "";
-        retryQueue.enqueueAwaitingContent(agentName, sessionId, Buffer.from(contentHashHex, "hex"), Buffer.from(contentHex, "hex"));
-        return { queued: true, awaitingDepth: retryQueue.getAwaitingDepth(agentName, sessionId) };
+            ?? perConnectionState.get(connectionId)?.currentAgent;
+        if (!agentName) {
+            return { error: "no_current_agent", guidance: "Select an agent with cello_use_agent, or pass agentName." };
+        }
+        const agentId = sessionNodeManager.resolveAgentId(agentName);
+        retryQueue.enqueueAwaitingContent(agentId, sessionId, Buffer.from(contentHashHex, "hex"), Buffer.from(contentHex, "hex"));
+        return { queued: true, awaitingDepth: retryQueue.getAwaitingDepth(agentId, sessionId) };
     });
     // CELLO-M7-MSG-001: a `persisted` delivery ACK (or a confirmed park) clears the durable
     // awaiting-ACK entry so the startup flush does not re-park already-delivered content.
@@ -3521,9 +3566,13 @@ export async function startDaemon(config) {
             return { error: "missing_params", guidance: "Provide sessionId and contentHash (hex)." };
         }
         const agentName = params?.agentName
-            ?? perConnectionState.get(connectionId)?.currentAgent ?? "";
-        retryQueue.markContentAcked(agentName, sessionId, Buffer.from(contentHashHex, "hex"));
-        return { acked: true, awaitingDepth: retryQueue.getAwaitingDepth(agentName, sessionId) };
+            ?? perConnectionState.get(connectionId)?.currentAgent;
+        if (!agentName) {
+            return { error: "no_current_agent", guidance: "Select an agent with cello_use_agent, or pass agentName." };
+        }
+        const agentId = sessionNodeManager.resolveAgentId(agentName);
+        retryQueue.markContentAcked(agentId, sessionId, Buffer.from(contentHashHex, "hex"));
+        return { acked: true, awaitingDepth: retryQueue.getAwaitingDepth(agentId, sessionId) };
     });
     handlers.set("check_nonce", async (params, _connectionId) => {
         const sessionId = params?.sessionId;
@@ -4152,10 +4201,11 @@ export async function startDaemon(config) {
     }
     async function acceptInboundAssignment(parsed, agentName, correlationId) {
         try {
-            // M8C-ABUSE-1 (anti-drip-feed / anti-swarm): bound acceptance from unknown (non-contact)
-            // senders — a per-sender cap (many sessions from ONE stranger) and a global cap (many
-            // sessions across ALL strangers combined). Known contacts are exempt ("bounded only by
-            // disk" — DoD). Checked FIRST, before any standing-receiver work, so a refusal is cheap.
+            // M8C-ABUSE-1 + DOD-TIER-2/3: bound acceptance by the sender's TIER — a per-sender cap that is
+            // the sender's tier cap (BLOCKED 0 → refused here, indistinguishably from an over-cap stranger),
+            // plus a global anti-swarm cap that applies only to the UNKNOWN-tier stranger pool. No tier is
+            // unbounded (INV-TIER-BOUND); KNOWN+ are exempt from the GLOBAL pool only, not from their own
+            // cap. Checked FIRST, before any standing-receiver work, so a refusal is cheap.
             // CC-10: reap provably-dead ghosts for THIS agent before counting — otherwise invisible
             // interrupted 0-received sessions (post-restart shape) consume the sender's budget forever
             // and lock the stranger out with no list read ever clearing them. Safe here: abandonSession
@@ -4171,6 +4221,15 @@ export async function startDaemon(config) {
                 });
                 return;
             }
+            // DOD-RENAME-1 AC1 (review F1 / DEC-AB-4): record the offered name as the rename baseline the
+            // moment the offer passes the acceptance gate — an ALLOWED peer (the bound check let them
+            // through) is tracked even if session formation transiently fails below. Deliberately AFTER the
+            // bound check, not at the raw parse point: a BLOCKED or over-cap peer must NOT be able to drive
+            // the operator's rename baseline or push notices into their inbox. Guarded by offeredMoniker !==
+            // null so a silent offer never clears the baseline (AC5).
+            if (parsed.offeredMoniker !== null) {
+                sessionNodeManager.recordOfferedMoniker(agentName, parsed.participantAPubkeyHex, parsed.offeredMoniker);
+            }
             // M8B F14 (fix 2): KICK creation before polling — an inbound offer arriving while no
             // receiver exists and none is being created must trigger the ensure itself (the doc
             // comment's "retries on demand" made true), instead of polling a creation nobody
@@ -4251,6 +4310,8 @@ export async function startDaemon(config) {
             // DOD-MONIKER-6: scoped to `agentName` — the agent this offer was received FOR.
             if (parsed.offeredMoniker !== null) {
                 offeredMonikers.set(offerKey(agentName, parsed.sessionIdHex), parsed.offeredMoniker);
+                // (DOD-RENAME-1's rename-baseline update runs earlier, right after the acceptance bound — see
+                // the recordOfferedMoniker call there. This map is only the session-scoped display material.)
             }
             enqueueInboundSession(agentName, {
                 sessionIdHex: parsed.sessionIdHex,
@@ -4267,8 +4328,8 @@ export async function startDaemon(config) {
             // CC-1 (2026-07-07): do NOT auto-add the requester here. Accepting the *connection* must not
             // grant *trust*. The old auto-add promoted any stranger who knocked once to "known" (Level-4
             // fast-track), which defeated BOTH the screening layer AND the ABUSE-1 acceptance caps
-            // (checkUnknownSenderAcceptanceBound exempts contacts, so sessions 2+ bypassed the per-sender
-            // cap — confirmed live 2026-07-07). Promotion to "known" now requires operator engagement only:
+            // (a higher tier raises the per-sender cap, so auto-promoting a stranger would have let their
+            // sessions 2+ ride a larger bound — DOD-TIER-2). Promotion to "known" now requires operator engagement only:
             // an outbound cello_initiate_session (below, ~3137), the operator replying INTO the session via
             // cello_send, or an explicit cello_contact_add. An unattended stranger is never auto-whitelisted.
             // See docs/planning/.../2026-07-07_1700_four-level-screening-policy.md (D21).
@@ -5116,8 +5177,11 @@ export async function startDaemon(config) {
         // auto-adds (that defeated screening + anti-spam). For an OUTBOUND session the counterparty is
         // already a contact (cello_initiate_session added it), so this is an idempotent no-op there; it
         // matters for inbound-originated sessions, where the reply is the trust signal. addContact is
-        // INSERT OR IGNORE — it never refreshes added_at.
-        sessionNodeManager.addContact(record.agent_name, recipientPubkey);
+        // INSERT OR IGNORE — it never refreshes added_at. DOD-TIER-4 AC3: engaging (a committed reply into
+        // an inbound session I accepted) makes the counterparty KNOWN, provenance 'accepted'. For an
+        // OUTBOUND session the row already exists ('initiated', KNOWN) and INSERT OR IGNORE leaves it
+        // untouched — 'initiated' correctly wins there.
+        sessionNodeManager.addContact(record.agent_name, recipientPubkey, undefined, "accepted", TIER.KNOWN);
         if (modified) {
             logger.info("security.verdict.returned", { disposition: "redact", sessionId, sequenceNumber: leafIndex, correlationId });
         }
@@ -5342,7 +5406,21 @@ export async function startDaemon(config) {
             }));
             const unread = sessionNodeManager.getUnreadSummary(agent);
             const total_unread = unread.reduce((sum, u) => sum + u.unread_count, 0);
-            return { agent, pending_session_requests: pending, expired_session_requests: expired, unread, total_unread };
+            // DOD-RENAME-1 AC3: pending rename notices surface HERE (the INBOX pull), never as a real-time
+            // push. The offered name is rendered as an untrusted CLAIM (quoted, with the pubkey) plus the
+            // command to adopt it — the daemon never auto-applies a self-declared name.
+            const rename_notices = sessionNodeManager.getRenameNotices(agent).map((n) => ({
+                pubkey: n.pubkey,
+                your_name_for_them: n.moniker,
+                claimed_name: n.offered_name,
+                noticed_at: n.noticed_at,
+                // Names the contact by the operator's OWN pet name (AC3); the self-declared name is a quoted,
+                // untrusted claim; the adopt command carries its arguments so it is copy-pasteable.
+                notice: `Your contact ${n.moniker !== null ? `"${n.moniker}" ` : ""}(${n.pubkey.slice(0, 16)}…) now calls themselves ` +
+                    `"${n.offered_name}" (self-declared — unverified). Adopt it: cello_contact_set_moniker ` +
+                    `{ pubkey: "${n.pubkey}", moniker: "${n.offered_name}" }, or ignore.`,
+            }));
+            return { agent, pending_session_requests: pending, expired_session_requests: expired, unread, total_unread, rename_notices };
         });
         const totalUnread = agents.reduce((sum, a) => sum + a.total_unread, 0);
         const totalPending = agents.reduce((sum, a) => sum + a.pending_session_requests.length, 0);
@@ -5390,7 +5468,10 @@ export async function startDaemon(config) {
                 };
             }
         }
-        sessionNodeManager.addContact(resolved.agent, pubkey, moniker);
+        // DOD-TIER-4 / DEC-AB-1: an explicit cello_contact_add is a deliberate operator vouch → KNOWN
+        // (still not auto-accept; that is a separate cello_contact_set_tier to whitelisted). provenance
+        // stays null — this relationship formed by neither initiating nor accepting a session (AC5).
+        sessionNodeManager.addContact(resolved.agent, pubkey, moniker, null, TIER.KNOWN);
         logger.info("contact.added", { agent: resolved.agent, pubkey });
         if (moniker !== undefined) {
             logger.info("contact.moniker.set", { agentName: resolved.agent, pubkey });
@@ -5426,6 +5507,57 @@ export async function startDaemon(config) {
         logger.info("contact.moniker.set", { agentName: resolved.agent, pubkey, cleared: moniker === null });
         return { ok: true, agent: resolved.agent, pubkey, moniker };
     });
+    // DOD-CONTACT-VIEW-1 AC1: set a contact's reachability tier. Validates the tier is a known constant
+    // (0..4) — an unknown value is REFUSED, never coerced. Emits contact.tier.changed (old→new).
+    handlers.set("cello_contact_set_tier", async (params, connectionId) => {
+        const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
+        const tier = typeof params?.tier === "number" ? params.tier : undefined;
+        if (!pubkey || tier === undefined) {
+            return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) and 'tier' (0=blocked, 1=unknown, 2=known, 3=whitelisted, 4=vip)." };
+        }
+        if (!isKnownTierValue(tier)) {
+            return { ok: false, reason: "invalid_tier", guidance: "tier must be one of 0 (blocked), 1 (unknown), 2 (known), 3 (whitelisted), 4 (vip)." };
+        }
+        const resolved = resolveContactAgent(perConnectionState.get(connectionId), params);
+        if (!resolved.ok)
+            return resolved;
+        const oldTier = sessionNodeManager.getTier(resolved.agent, pubkey);
+        if (!sessionNodeManager.setContactTier(resolved.agent, pubkey, tier)) {
+            return { ok: false, reason: "contact_not_found", guidance: `No contact ${pubkey.slice(0, 16)}… for agent '${resolved.agent}'. Add it first with cello_contact_add.` };
+        }
+        // Only an actual change is an audit event — a no-op re-set must not pollute the trail (review F4).
+        if (oldTier !== tier) {
+            logger.info("contact.tier.changed", { agentName: resolved.agent, pubkey, oldTier, newTier: tier });
+        }
+        return { ok: true, agent: resolved.agent, pubkey, tier };
+    });
+    // DOD-AWAY-TIER-1 AC2: set (or clear, with null) a contact's per-contact away message — the most
+    // specific level of the away-text resolution. Validated as a string-or-null; the text is screened
+    // on the outbound path at send time (SI), never here.
+    handlers.set("cello_contact_set_away", async (params, connectionId) => {
+        const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
+        if (!pubkey || !params || !("message" in params)) {
+            return { ok: false, reason: "missing_params", guidance: "Provide 'pubkey' (hex) and 'message' — a string away text, or null to clear it." };
+        }
+        const rawMessage = params.message === null ? null : typeof params.message === "string" ? params.message : undefined;
+        if (rawMessage === undefined) {
+            return { ok: false, reason: "invalid_message", guidance: "'message' must be a string (the away text) or null (to clear)." };
+        }
+        // Review F2/F3: an empty / whitespace-only message CLEARS (consistent with the CLI + null), never
+        // stores a blank away reply; a valid message is length-bounded.
+        const message = rawMessage !== null && rawMessage.trim().length === 0 ? null : rawMessage;
+        if (message !== null && message.length > AWAY_MESSAGE_MAX_LEN) {
+            return { ok: false, reason: "invalid_message", guidance: `The away message must be <= ${AWAY_MESSAGE_MAX_LEN} characters.` };
+        }
+        const resolved = resolveContactAgent(perConnectionState.get(connectionId), params);
+        if (!resolved.ok)
+            return resolved;
+        if (!sessionNodeManager.setContactAwayMessage(resolved.agent, pubkey, message)) {
+            return { ok: false, reason: "contact_not_found", guidance: `No contact ${pubkey.slice(0, 16)}… for agent '${resolved.agent}'. Add it first with cello_contact_add.` };
+        }
+        logger.info("contact.away.set", { agentName: resolved.agent, pubkey, cleared: message === null });
+        return { ok: true, agent: resolved.agent, pubkey };
+    });
     handlers.set("cello_contact_remove", async (params, connectionId) => {
         const pubkey = typeof params?.pubkey === "string" ? params.pubkey : undefined;
         if (!pubkey) {
@@ -5450,6 +5582,52 @@ export async function startDaemon(config) {
         }));
         return { ok: true, agent: resolved.agent, contacts };
     });
+    // DOD-SETTINGS-1 AC2: read a per-agent reachability-policy setting (or all set ones). An unset key
+    // returns value:null — the CONSUMER applies the hardcoded default (the daemon runs on defaults alone).
+    handlers.set("cello_settings_get", async (params, connectionId) => {
+        const resolved = resolveContactAgent(perConnectionState.get(connectionId), params);
+        if (!resolved.ok)
+            return resolved;
+        // A key was PROVIDED (present and non-null) → it must be a valid string key. Distinguish "key
+        // absent" (list all) from "key present but malformed/unknown" (review F1/F3) — a typo'd read must
+        // NOT masquerade as "unset", the exact invisibility this store exists to prevent.
+        if (params && "key" in params && params.key !== undefined && params.key !== null) {
+            if (typeof params.key !== "string") {
+                return { ok: false, reason: "missing_params", guidance: "'key' must be a string setting key, or omit it to list every set value." };
+            }
+            if (!isValidSettingKey(params.key)) {
+                return { ok: false, reason: "invalid_key", guidance: `Unknown setting key '${params.key}'. Valid keys: ${allSettingKeys().join(", ")}` };
+            }
+            return { ok: true, agent: resolved.agent, key: params.key, value: sessionNodeManager.getSetting(resolved.agent, params.key) };
+        }
+        return { ok: true, agent: resolved.agent, settings: sessionNodeManager.getAllSettings(resolved.agent) };
+    });
+    // DOD-SETTINGS-1 AC2: write a per-agent setting. The KEY is validated against the known namespace —
+    // an unknown key is REFUSED (a typo'd key that persisted would be a setting that never takes effect,
+    // invisible to the operator). Per-key VALUE validation (finite bounds, etc.) lives with the consumer.
+    handlers.set("cello_settings_set", async (params, connectionId) => {
+        const key = typeof params?.key === "string" ? params.key : undefined;
+        const rawValue = params?.value;
+        const value = typeof rawValue === "string" ? rawValue : typeof rawValue === "number" ? String(rawValue) : undefined;
+        if (!key || value === undefined) {
+            return { ok: false, reason: "missing_params", guidance: `Provide 'key' and 'value' (string or number). Valid keys: ${allSettingKeys().join(", ")}` };
+        }
+        if (!isValidSettingKey(key)) {
+            return { ok: false, reason: "invalid_key", guidance: `Unknown setting key '${key}'. Valid keys: ${allSettingKeys().join(", ")}` };
+        }
+        // DOD-TIER-BOUNDS-SETTINGS AC2: a bound value must be a finite positive integer (INV-TIER-BOUND —
+        // a setting cannot REMOVE a bound). Away-text values are free-form.
+        const valueCheck = validateSettingValue(key, value);
+        if (!valueCheck.ok) {
+            return { ok: false, reason: "invalid_value", guidance: valueCheck.reason };
+        }
+        const resolved = resolveContactAgent(perConnectionState.get(connectionId), params);
+        if (!resolved.ok)
+            return resolved;
+        sessionNodeManager.setSetting(resolved.agent, key, value);
+        logger.info("setting.changed", { agentName: resolved.agent, key });
+        return { ok: true, agent: resolved.agent, key, value };
+    });
     // MONIKER-1 AC2/AC3: cello_set_moniker — set (or clear, via explicit null) an agent's outbound-name
     // override on the agents table. Validated at set-time with the shared MONIKER-0 rule; an invalid
     // value is rejected here AND at the store (backstop) — it can never be stored. Local-only: the