@cello-protocol/daemon 0.0.45 → 0.0.47

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";
@@ -784,6 +786,24 @@ export async function startDaemon(config) {
             cursor += 1;
         advanceConnectionCursor(connectionId, sessionId, cursor);
     }
+    /**
+     * DOD-CURSOR-DURABLE-1: the same hole-safe walk, applied to the PERSISTED per-(agent, session)
+     * read watermark. Used by cello_get_transcript, whose delivery covers BOTH directions.
+     *
+     * Walks a CONTIGUOUS run from the agent's current watermark, stopping at the first gap — for the
+     * identical reason safeCursorAdvance does: leaf indices are contiguous across both directions, so
+     * a gap can hide an unread RECEIVED message (e.g. a row that failed to decrypt is absent from
+     * `messages`). Advancing past it would mark unseen counterparty content as read and unblock a
+     * send that never saw it — defeating the very guarantee this gate exists to enforce. Monotonic:
+     * advanceLastDeliveredSeq takes MAX, so this can never lower a watermark.
+     */
+    function safeWatermarkAdvance(agentName, sessionId, deliveredSeqs) {
+        let frontier = sessionNodeManager.getLastDeliveredSeq(agentName, sessionId);
+        while (deliveredSeqs.has(frontier + 1))
+            frontier += 1;
+        if (frontier >= 0)
+            sessionNodeManager.advanceLastDeliveredSeq(agentName, sessionId, frontier);
+    }
     // M8C-AWAY-1: away response — an unattended Primary auto-answers session requests + messages
     // with the default transparent away text and queues them (the DoD's own mandated default).
     // CORE ships now; the operator-configurable custom-text / opaque-privacy-mode SWITCH is PARKED
@@ -827,10 +847,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) {
@@ -3005,8 +3047,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 };
@@ -3429,7 +3473,16 @@ export async function startDaemon(config) {
         // reviewer HIGH finding (aa5928e2/a9099571): recordTranscriptMessage swallows a DB write
         // failure without rolling back the tree's leaf count, so a hole in `messages` is possible in
         // principle; the contiguous-run walk refuses to vault the cursor past such a hole even here.
-        safeCursorAdvance(connectionId, sessionId, new Set(messages.map((m) => m.sequence)));
+        const deliveredSeqs = new Set(messages.map((m) => m.sequence));
+        safeCursorAdvance(connectionId, sessionId, deliveredSeqs);
+        // DOD-CURSOR-DURABLE-1 (AC3): reading the full history IS reading — so this must advance the
+        // PERSISTED watermark too, not just this connection's in-memory cursor. Previously it advanced
+        // only the cursor, which made the gate's own guidance ("call cello_get_transcript, then retry")
+        // a dead end for any stateless client: a fresh process reads the transcript, exits, and the next
+        // process still presents an unread count. Same contiguous-run safety as the cursor — never vault
+        // past a gap (an undecryptable row is absent from `messages`, so the walk stops there and those
+        // messages correctly stay unread).
+        safeWatermarkAdvance(agentName, sessionId, deliveredSeqs);
         return { ok: true, session_id: sessionId, messages, undecryptable };
     });
     // cello_list_sessions: the discovery surface — every persisted session for the
@@ -4175,10 +4228,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
@@ -4194,6 +4248,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
@@ -4274,6 +4337,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,
@@ -4290,8 +4355,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).
@@ -4981,18 +5046,52 @@ export async function startDaemon(config) {
         // rather than let it send blind — the WhatsApp-group-chat model. Runs BEFORE M9's
         // governance-decisions parsing below — an access-control gate should short-circuit before any
         // unrelated prep work for a send that may not even be allowed to proceed.
+        // DOD-CURSOR-DURABLE-1: the gate now consults TWO authorities and passes if EITHER says the
+        // caller is caught up.
+        //
+        //   1. the connection cursor (in-memory, per-connection) — today's rule, UNCHANGED. A
+        //      long-lived client (the MCP shim, one socket for the whole session) satisfies this
+        //      exactly as before, so the shipped single-connection path is byte-for-byte identical.
+        //
+        //   2. the persisted per-(agent, session) read watermark — NEW. A STATELESS client (the `cello`
+        //      CLI runs a fresh process, and therefore a fresh connection, per command) always presents
+        //      cursor -1, so authority 1 can never be satisfied by it: after the counterparty spoke
+        //      once, every CLI send was refused forever, even though the agent had demonstrably read
+        //      the message. That made a two-way conversation impossible from bash — and it silently hit
+        //      any RECONNECTING MCP client too, whose fresh connectionId also resets the cursor to -1.
+        //
+        // What the gate protects, precisely: an agent must never reply to COUNTERPARTY content nobody
+        // on its side has seen. That guarantee is preserved and is now durable — it survives the socket.
+        //
+        // What it deliberately no longer protects (the approved trade — see
+        // 2026-07-11_cursor-durable-read-before-write-design.md §6, Andre's go): a message this agent
+        // SENT from a DIFFERENT local connection no longer blocks. Two attended windows on one agent
+        // used to gate each other; now they do not, because a locally-authored message is not "unread
+        // counterparty content" — the AGENT wrote it. The principal here is the agent, not the socket,
+        // and the daemon cannot referee which of an operator's own windows a human is looking at.
         const currentSeq = record.message_count - 1;
-        const lastReadSeq = getConnectionCursor(connectionId, sessionId);
-        if (lastReadSeq < currentSeq) {
+        const connectionCursor = getConnectionCursor(connectionId, sessionId);
+        const unreadReceived = sessionNodeManager.getUnreadReceivedCount(agentName, sessionId);
+        const caughtUp = connectionCursor >= currentSeq || unreadReceived === 0;
+        if (!caughtUp) {
             // M8C-CURSOR-1 (reviewer MEDIUM fix): every sibling rejection in this handler logs; this
             // gate must too — a security-relevant control-flow path with no observability is a gap.
-            logger.warn("session.send.blocked", { sessionId, currentSeq, lastReadSeq, connectionId });
+            // Both authorities are logged, so the next reader can tell WHICH one refused.
+            logger.warn("session.send.blocked", {
+                sessionId,
+                currentSeq,
+                lastReadSeq: connectionCursor,
+                unreadReceived,
+                connectionId,
+                agentName,
+            });
             return {
                 ok: false,
                 reason: "session_not_current",
                 current_seq: currentSeq,
-                last_read_seq: lastReadSeq,
-                guidance: `This connection hasn't caught up on session ${sessionId} — ${currentSeq - lastReadSeq} message(s) unread (this may include messages authored by another connection on this same agent). Call cello_get_transcript to read the full history (covers both sent and received), then retry the send.`,
+                last_read_seq: connectionCursor,
+                unread_received: unreadReceived,
+                guidance: `This agent hasn't read ${unreadReceived} received message(s) on session ${sessionId}. Call cello_receive (or cello_get_transcript for the full history) to read them, then retry the send.`,
             };
         }
         // M9-FEED-001 §6: the agent's governance re-send decisions, keyed by the flagId a prior `warn`
@@ -5139,8 +5238,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 });
         }
@@ -5365,7 +5467,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);
@@ -5413,7 +5529,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 });
@@ -5449,6 +5568,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) {
@@ -5473,6 +5643,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