@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/agent-loader.js

@@ -0,0 +1,37 @@
+/**
+ * Agent identity loader for the CELLO daemon.
+ *
+ * Agents are enumerated from the encrypted `agents` table — ONE loading path. There is no flat-file
+ * fallback: on-disk key files are imported into the `agents` table by the one-time migration
+ * (identity-migration.ts) before this loader runs.
+ *
+ * Each agent's K_local Ed25519 seed is stored as a BLOB column; the loader builds a sign-only
+ * InMemoryKeyProvider from it (the private scalar never leaves the provider — only signatures and
+ * content-seal opens are emitted).
+ */
+import { InMemoryKeyProvider } from "@cello-protocol/crypto";
+import { DbIdentityStore } from "./db-identity-store.js";
+import { extractErrorMessage } from "./error-message.js";
+/**
+ * Load every agent from the encrypted `agents` table. A row whose seed is unusable (corrupt/wrong
+ * length) is reported as a failed agent and skipped — never silently dropped.
+ */
+export async function loadAgents(db, logger) {
+    const store = new DbIdentityStore(db, logger);
+    const loaded = [];
+    const failed = [];
+    for (const row of store.listAgents()) {
+        try {
+            const keyProvider = new InMemoryKeyProvider(row.kLocalSeed);
+            const pubkey = Buffer.from(await keyProvider.getPublicKey()).toString("hex");
+            loaded.push({ name: row.agentName, pubkey, keyProvider });
+        }
+        catch (err) {
+            const error = extractErrorMessage(err);
+            logger.error("agent.load.failed", { agentName: row.agentName, error });
+            failed.push({ name: row.agentName, error });
+        }
+    }
+    return { loaded, failed };
+}
+//# sourceMappingURL=agent-loader.js.map

package/dist/agent-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loader.js","sourceRoot":"","sources":["../src/agent-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAsBzD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAAkB,EAAE,MAAc;IACjE,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,IAAI,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC7E,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;YACvC,MAAM,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}

package/dist/agent-selection-root.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Which agent a call is FOR, and how a caller learns it fell back.
+ *
+ * One rule, in one place, because the alternative has already happened: several handlers each
+ * deciding what "the current agent" means is how a call lands on an agent the operator did not
+ * choose. The fallback notice rides an AsyncLocalStorage so an answer can carry WHY it fell back
+ * without every caller having to thread it through.
+ *
+ * The registration guidance stayed in the root: it is written between this block and the agent
+ * lifecycle handlers, and moving it would have meant moving the handler registration with it.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Logger } from "./types.js";
+export interface AgentSelectionDeps {
+    logger: Logger;
+    /** The live set — a copy would freeze at boot and the single-online-agent fallback would never fire. */
+    onlineAgents: ReadonlySet<string>;
+}
+export declare function createAgentSelection(deps: AgentSelectionDeps): {
+    fallbackNoticeStore: AsyncLocalStorage<{
+        notice?: Record<string, unknown>;
+    }>;
+    resolveCurrentAgent: (connState: {
+        currentAgent: string | null;
+        clearedAgent?: string;
+        clientType?: string;
+    } | undefined, explicitAgent?: string) => string | null;
+};
+//# sourceMappingURL=agent-selection-root.d.ts.map

package/dist/agent-selection-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-selection-root.d.ts","sourceRoot":"","sources":["../src/agent-selection-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,wGAAwG;IACxG,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB;;iBAwDE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;qCAGvE;QAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,kBAClF,MAAM,KACrB,MAAM,GAAG,IAAI;EA0DjB"}

package/dist/agent-selection-root.js

@@ -0,0 +1,126 @@
+/**
+ * Which agent a call is FOR, and how a caller learns it fell back.
+ *
+ * One rule, in one place, because the alternative has already happened: several handlers each
+ * deciding what "the current agent" means is how a call lands on an agent the operator did not
+ * choose. The fallback notice rides an AsyncLocalStorage so an answer can carry WHY it fell back
+ * without every caller having to thread it through.
+ *
+ * The registration guidance stayed in the root: it is written between this block and the agent
+ * lifecycle handlers, and moving it would have meant moving the handler registration with it.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { resolveCurrentAgentFor } from "./agent-selection.js";
+export function createAgentSelection(deps) {
+    const { logger, onlineAgents } = deps;
+    // M8C-AUTOSTART-1 (F18): resolve which agent an agent-defaulting tool should act on for this
+    // connection: an explicit { agent } wins; else the connection's current agent; else — when EXACTLY one
+    // agent is online daemon-wide — that sole agent (removes the "why did it forget my agent" moment
+    // after a /mcp reconnect). Two-or-more online with none selected stays ambiguous → null (the
+    // caller returns no_current_agent), because guessing between peers would misroute.
+    /**
+     * Which agent does this call act as?
+     *
+     * An explicit { agent } wins, then this connection's selection. Only with NEITHER does the daemon fall back
+     * to the sole online agent — a convenience for a caller that never chose, where "the online one"
+     * cannot mean anyone else.
+     *
+     * The fallback is REFUSED for a connection whose selection was taken away (`clearedAgent`): it
+     * chose an agent, that agent was stopped or retired, and the choice is gone. Falling back there
+     * silently re-targets the next call at whoever else happens to be online — the caller asked for
+     * alice, alice was stopped, and the work lands on bob reporting success. A lost intent is not the
+     * same as no intent, and it must fail loud (no_current_agent) rather than be guessed at.
+     */
+    /**
+     * Which agent this call acts as — `DOD-M15-SELECTION-1`, logic in `agent-selection.ts`.
+     *
+     * It used to end with `if (onlineAgents.size === 1) return [...onlineAgents][0]`, so a connection
+     * that had selected nothing acted as whichever agent happened to be the only one online. On a
+     * shared daemon that can be a DIFFERENT operator's agent, and a live MCP session was being bound
+     * to an identity it never asked for.
+     *
+     * The resolution is now attributable: every path reports how it was reached, and `fallback` — the
+     * one that was invisible — is logged at INFO. `DOD-M15-IPCVISIBLE-1`.
+     */
+    /**
+     * The fallback notice owed to THIS REQUEST's response — `DOD-M15-SELECTION-1` clause 2.
+     *
+     * ─── Why an AsyncLocalStorage and not a per-connection map ─────────────────────────────────────
+     *
+     * The first cut keyed a `WeakMap` on the per-connection state object, so the notice belonged to
+     * the CONNECTION and was read back at the response boundary. Review found that hands the notice to
+     * whichever response finishes first, and Claude Code issues tool calls in parallel:
+     *
+     *   1. the agent calls `cello_receive` — nothing selected, so the fallback resolves and records
+     *      the notice, then the handler BLOCKS for up to 30 s waiting for content;
+     *   2. in the same turn it calls `cello_sessions {agent: "bob"}`, which names an agent explicitly
+     *      and never falls back;
+     *   3. `cello_sessions` returns first and takes the notice on its way out.
+     *
+     * Bob's response now says *"no agent was selected, so 'solo' was used"* — false, on the one call
+     * that did name an agent — and `cello_receive`, the call that actually fell back, says nothing.
+     * Exactly inverted.
+     *
+     * A notice is a fact about ONE CALL, so it is stored in that call's async context. The store is
+     * created per request in `renderedHandlers` and dies with it, which also means a handler that
+     * THROWS cannot leave a notice behind to attach itself to some later, unrelated response — the
+     * other half of the same review finding.
+     */
+    const fallbackNoticeStore = new AsyncLocalStorage();
+    function resolveCurrentAgent(connState, explicitAgent) {
+        return resolveCurrentAgentFor({
+            connState,
+            onlineAgents,
+            ...(explicitAgent !== undefined ? { explicitAgent } : {}),
+            onResolved: (agent, trigger) => {
+                // Only the FALLBACK is announced. `explicit` and `selected` are the ordinary cases and
+                // logging them would bury the one that matters — a signal that fires on the normal case is
+                // not a signal.
+                if (trigger !== "fallback")
+                    return;
+                /**
+                 * RECORDED FOR THE RESPONSE, not just the log — `DOD-M15-SELECTION-1` clause 2.
+                 *
+                 * The log tells whoever reads the daemon log. The RESPONSE tells the agent that just acted
+                 * as an identity it never selected, which is the one that stops the half-attended state
+                 * being read as the protocol dropping messages.
+                 */
+                /**
+                 * No `connState` guard. The first cut wrote the notice only `if (agent && connState)`, and
+                 * `perConnectionState` is populated at `ipc.connect` — which `withIpc` in the CLI
+                 * (`core/cli/src/commands.ts`) does not send. So every plain `cello` invocation fell back
+                 * and got a response that said nothing, while the log line below fired regardless: the
+                 * clause asks for explicit IN THE RESPONSE, and those callers had it explicit in the log
+                 * only. The store is per-REQUEST, so it exists whether or not the connection ever
+                 * handshook.
+                 */
+                const store = fallbackNoticeStore.getStore();
+                if (agent && store) {
+                    store.notice = {
+                        acting_as: agent,
+                        agent_selection: "fallback",
+                        agent_selection_guidance: `No agent was selected on this connection, so '${agent}' was used because it is the ` +
+                            `only one online. This is a per-call subject, NOT an attendance: doorbells route by ` +
+                            `the connection's registered agent and this does not set it. Two things follow — ` +
+                            `this session will not WAKE on an incoming message even though sending and reading ` +
+                            `work, and anyone who opens a session with you is sent an AWAY auto-reply while you ` +
+                            `sit here able to answer. Run cello_use_agent to fix both. Naming the agent on each ` +
+                            `call is NOT a remedy for either: it settles which agent a call is about and leaves ` +
+                            `the connection just as unattended.`,
+                    };
+                }
+                logger.info("agent.current.fallback", {
+                    agentName: agent,
+                    clientType: connState?.clientType ?? "cli",
+                    impact: "this call had no selected agent and exactly one was online, so that one was used. It " +
+                        "is a per-call subject, NOT an attendance: doorbells route by the connection's " +
+                        "registered agent, which this does not set.",
+                    guidance: "If this was not the intended agent, name it explicitly, or run cello_use_agent to " +
+                        "select one for the connection.",
+                });
+            },
+        });
+    }
+    return { fallbackNoticeStore, resolveCurrentAgent };
+}
+//# sourceMappingURL=agent-selection-root.js.map

package/dist/agent-selection-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-selection-root.js","sourceRoot":"","sources":["../src/agent-selection-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAS9D,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAEtC,6FAA6F;IAC7F,uGAAuG;IACvG,iGAAiG;IACjG,6FAA6F;IAC7F,mFAAmF;IACnF;;;;;;;;;;;;OAYG;IACH;;;;;;;;;;OAUG;IACH;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,mBAAmB,GAAG,IAAI,iBAAiB,EAAwC,CAAC;IAE1F,SAAS,mBAAmB,CAC1B,SAAkG,EAClG,aAAsB;QAEtB,OAAO,sBAAsB,CAAC;YAC5B,SAAS;YACT,YAAY;YACZ,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;gBAC7B,uFAAuF;gBACvF,2FAA2F;gBAC3F,gBAAgB;gBAChB,IAAI,OAAO,KAAK,UAAU;oBAAE,OAAO;gBACnC;;;;;;mBAMG;gBACH;;;;;;;;mBAQG;gBACH,MAAM,KAAK,GAAG,mBAAmB,CAAC,QAAQ,EAAE,CAAC;gBAC7C,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;oBACnB,KAAK,CAAC,MAAM,GAAG;wBACb,SAAS,EAAE,KAAK;wBAChB,eAAe,EAAE,UAAU;wBAC3B,wBAAwB,EACtB,iDAAiD,KAAK,+BAA+B;4BACrF,qFAAqF;4BACrF,kFAAkF;4BAClF,oFAAoF;4BACpF,qFAAqF;4BACrF,qFAAqF;4BACrF,qFAAqF;4BACrF,oCAAoC;qBACvC,CAAC;gBACJ,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,wBAAwB,EAAE;oBACpC,SAAS,EAAE,KAAK;oBAChB,UAAU,EAAE,SAAS,EAAE,UAAU,IAAI,KAAK;oBAC1C,MAAM,EACJ,uFAAuF;wBACvF,gFAAgF;wBAChF,4CAA4C;oBAC9C,QAAQ,EACN,oFAAoF;wBACpF,gCAAgC;iBACnC,CAAC,CAAC;YACL,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,CAAC;AACtD,CAAC"}

package/dist/agent-selection.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Which agent a call acts as, and HOW that was decided — `DOD-M15-SELECTION-1`,
+ * `DOD-M15-IPCVISIBLE-1`.
+ *
+ * ─── The defect this is extracted from ─────────────────────────────────────────────────────────
+ *
+ * This logic was four lines inside `daemon.ts`, ending in:
+ *
+ *     if (onlineAgents.size === 1) return [...onlineAgents][0];
+ *
+ * A connection that had selected nothing therefore acted as whichever agent happened to be the only
+ * one online. On a shared daemon that can be a DIFFERENT operator's agent, which is how it was
+ * found: after a restart a released agent was silently reinstated under someone else's name.
+ *
+ * ─── Why the fallback is worse than it looks even when it picks the "right" agent ──────────────
+ *
+ * It produces a HALF-ATTENDED state. Tools resolve a subject and work; the notification dispatcher
+ * routes doorbells by the connection's REGISTERED current agent, which this never sets. So the
+ * session sends and receives on request but never wakes — and an operator reads that as the
+ * protocol dropping messages, not as a selection that was never made.
+ *
+ * ─── AND WHY IT IS STILL HERE ──────────────────────────────────────────────────────────────────
+ *
+ * My first version switched the fallback OFF for MCP on that reasoning, and four tests said no. CC-3
+ * added it deliberately, to fix "the post-/mcp-reconnect papercut": a reconnected session with
+ * exactly one agent online used to hard-fail `no_current_agent`.
+ *
+ * `DOD-M15-SELECTION-1`'s answer is narrower than removal — *"if a fallback is wanted it is EXPLICIT
+ * in the response, not announced as an accomplished fact"* — and it sequences the work: *"diagnosis
+ * first… with the trigger field from DOD-M15-IPCVISIBLE-1 distinguishing replay from fallback in one
+ * run."* So this module makes the decision ATTRIBUTABLE, which is the precondition, and changing
+ * what the fallback DOES waits for the diagnosis that attribution makes possible.
+ *
+ * ─── Every path reports how it got there ───────────────────────────────────────────────────────
+ *
+ * Two agent switches fired one second after a reconnect on 2026-08-09 and neither could be
+ * attributed, because an operator's explicit selection and the shim's reconnect replay arrive
+ * identically. `fallback` is the third value `DOD-M15-IPCVISIBLE-1` asks for, and the one that was
+ * invisible.
+ */
+/** How a call's acting agent was arrived at. Every branch reports one. */
+export type SelectionTrigger = 
+/** The caller named an agent on this call. */
+"explicit"
+/** The connection had selected one earlier with `cello_use_agent`. */
+ | "selected"
+/** Nothing was selected and one agent was online — a CLI convenience, never for a live session. */
+ | "fallback"
+/**
+ * The connection's choice was TAKEN AWAY — the agent was shut down or removed underneath it.
+ *
+ * NOT a voluntary release. `cello_stop_using_agent` deliberately does not set this: the operator
+ * choosing to hold nothing stays eligible for the sole-online fallback, whereas a connection whose
+ * agent vanished must not have a replacement guessed for it.
+ */
+ | "cleared"
+/** No agent could be determined. */
+ | "none";
+export interface SelectionConnState {
+    currentAgent: string | null;
+    /** Set by `cello_stop_using_agent`: this connection HAD an intent and gave it up. */
+    clearedAgent?: string;
+    /** `"mcp"` is a live session; anything else is treated as an ephemeral CLI invocation. */
+    clientType?: string;
+}
+export declare function resolveCurrentAgentFor(opts: {
+    connState: SelectionConnState | undefined;
+    onlineAgents: ReadonlySet<string>;
+    explicitAgent?: string;
+    /** Called exactly once with the outcome, so the decision is attributable in the log. */
+    onResolved?: (agent: string | null, trigger: SelectionTrigger) => void;
+}): string | null;
+//# sourceMappingURL=agent-selection.d.ts.map

package/dist/agent-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-selection.d.ts","sourceRoot":"","sources":["../src/agent-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB;AAC1B,8CAA8C;AAC5C,UAAU;AACZ,sEAAsE;GACpE,UAAU;AACZ,mGAAmG;GACjG,UAAU;AACZ;;;;;;GAMG;GACD,SAAS;AACX,oCAAoC;GAClC,MAAM,CAAC;AAEX,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,SAAS,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC1C,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACxE,GAAG,MAAM,GAAG,IAAI,CAsChB"}

package/dist/agent-selection.js

@@ -0,0 +1,80 @@
+/**
+ * Which agent a call acts as, and HOW that was decided — `DOD-M15-SELECTION-1`,
+ * `DOD-M15-IPCVISIBLE-1`.
+ *
+ * ─── The defect this is extracted from ─────────────────────────────────────────────────────────
+ *
+ * This logic was four lines inside `daemon.ts`, ending in:
+ *
+ *     if (onlineAgents.size === 1) return [...onlineAgents][0];
+ *
+ * A connection that had selected nothing therefore acted as whichever agent happened to be the only
+ * one online. On a shared daemon that can be a DIFFERENT operator's agent, which is how it was
+ * found: after a restart a released agent was silently reinstated under someone else's name.
+ *
+ * ─── Why the fallback is worse than it looks even when it picks the "right" agent ──────────────
+ *
+ * It produces a HALF-ATTENDED state. Tools resolve a subject and work; the notification dispatcher
+ * routes doorbells by the connection's REGISTERED current agent, which this never sets. So the
+ * session sends and receives on request but never wakes — and an operator reads that as the
+ * protocol dropping messages, not as a selection that was never made.
+ *
+ * ─── AND WHY IT IS STILL HERE ──────────────────────────────────────────────────────────────────
+ *
+ * My first version switched the fallback OFF for MCP on that reasoning, and four tests said no. CC-3
+ * added it deliberately, to fix "the post-/mcp-reconnect papercut": a reconnected session with
+ * exactly one agent online used to hard-fail `no_current_agent`.
+ *
+ * `DOD-M15-SELECTION-1`'s answer is narrower than removal — *"if a fallback is wanted it is EXPLICIT
+ * in the response, not announced as an accomplished fact"* — and it sequences the work: *"diagnosis
+ * first… with the trigger field from DOD-M15-IPCVISIBLE-1 distinguishing replay from fallback in one
+ * run."* So this module makes the decision ATTRIBUTABLE, which is the precondition, and changing
+ * what the fallback DOES waits for the diagnosis that attribution makes possible.
+ *
+ * ─── Every path reports how it got there ───────────────────────────────────────────────────────
+ *
+ * Two agent switches fired one second after a reconnect on 2026-08-09 and neither could be
+ * attributed, because an operator's explicit selection and the shim's reconnect replay arrive
+ * identically. `fallback` is the third value `DOD-M15-IPCVISIBLE-1` asks for, and the one that was
+ * invisible.
+ */
+export function resolveCurrentAgentFor(opts) {
+    const report = (agent, trigger) => {
+        opts.onResolved?.(agent, trigger);
+        return agent;
+    };
+    if (opts.explicitAgent)
+        return report(opts.explicitAgent, "explicit");
+    if (opts.connState?.currentAgent)
+        return report(opts.connState.currentAgent, "selected");
+    /**
+     * AN INVOLUNTARY CLEAR BLOCKS THE FALLBACK. Pre-existing behaviour, preserved.
+     *
+     * `clearedAgent` means the connection's agent was shut down or removed underneath it — do not
+     * guess a replacement. A VOLUNTARY release (`cello_stop_using_agent`) deliberately does not set
+     * it, because the operator choosing to hold nothing is not the same as having the choice taken,
+     * and they stay eligible for the fallback.
+     */
+    if (opts.connState?.clearedAgent)
+        return report(null, "cleared");
+    /**
+     * THE SOLE-ONLINE FALLBACK — behaviour UNCHANGED, visibility added.
+     *
+     * `DOD-M15-SELECTION-1` names this as the place a live MCP session gets bound to an identity it
+     * never asked for, and the instinct is to switch it off for MCP. That is wrong, and the tests say
+     * why: CC-3 introduced it deliberately to fix "the post-/mcp-reconnect papercut", where a
+     * reconnected session hard-failed `no_current_agent` with exactly one agent online.
+     *
+     * The line's own answer is narrower than removal: *"if a fallback is wanted it is EXPLICIT in the
+     * response, not announced as an accomplished fact."* And it sequences the work — *"diagnosis
+     * first… with the trigger field from DOD-M15-IPCVISIBLE-1 distinguishing replay from fallback in
+     * one run."* So this reports itself, and changing what it DOES waits for that diagnosis.
+     *
+     * Exactly one, never a guess between two: choosing between identities is a coin flip with the
+     * operator's name on it, not a convenience.
+     */
+    if (opts.onlineAgents.size === 1)
+        return report([...opts.onlineAgents][0], "fallback");
+    return report(null, "none");
+}
+//# sourceMappingURL=agent-selection.js.map

package/dist/agent-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-selection.js","sourceRoot":"","sources":["../src/agent-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AA6BH,MAAM,UAAU,sBAAsB,CAAC,IAMtC;IACC,MAAM,MAAM,GAAG,CAAC,KAAoB,EAAE,OAAyB,EAAiB,EAAE;QAChF,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,IAAI,IAAI,CAAC,aAAa;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,SAAS,EAAE,YAAY;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAEzF;;;;;;;OAOG;IACH,IAAI,IAAI,CAAC,SAAS,EAAE,YAAY;QAAE,OAAO,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAEjE;;;;;;;;;;;;;;;OAeG;IACH,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAE,EAAE,UAAU,CAAC,CAAC;IAExF,OAAO,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC9B,CAAC"}

package/dist/agent-settings-keys.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CELLO Daemon — the agent_settings key namespace (DOD-SETTINGS-1).
+ *
+ * A single source for every valid per-agent reachability-policy setting key, so the handler (which
+ * REFUSES an unknown key) and the consumers (TIER-BOUNDS-SETTINGS reads the bound overrides,
+ * AWAY-TIER-1 reads the away texts) can never drift. Keys are lower-snake, dotted namespaces:
+ *
+ *   bounds.<tier>.max_sessions   bounds.<tier>.max_bytes    — per-tier bound overrides
+ *   away.default                                            — the agent's default away text
+ *   away.tier.<tier>                                        — a per-tier away text
+ *
+ * `<tier>` is a tier NAME (not the integer), for legibility in the store. BLOCKED is deliberately NOT
+ * settable — 0/0 is fixed (you cannot "raise" a block), and it has no away text (a blocked sender is
+ * refused before any reply). So the settable tiers are unknown / known / whitelisted / vip.
+ */
+/** The tiers whose bounds and away texts are settable (BLOCKED is fixed, never overridable). */
+export declare const SETTABLE_TIER_NAMES: readonly ["unknown", "known", "whitelisted", "vip"];
+export type SettableTierName = (typeof SETTABLE_TIER_NAMES)[number];
+/** The tier NAME for a tier integer, or null for an unknown/unsettable value (e.g. BLOCKED=0).
+ *  Keyed off the TIER constants (review F3) so a renumbering in contacts-tier-migration can never
+ *  silently desync the settings namespace from the grid. */
+export declare function settableTierName(tier: number): SettableTierName | null;
+export type BoundField = "max_sessions" | "max_bytes";
+/** The setting key for a per-tier bound override. */
+export declare function boundSettingKey(tier: SettableTierName, field: BoundField): string;
+/** The setting key for a per-tier away text. */
+export declare function awayTierSettingKey(tier: SettableTierName): string;
+/** The setting key for the agent's default away text (the fallback below any per-tier text). */
+export declare const AWAY_DEFAULT_KEY = "away.default";
+/** True iff `key` is a known, settable reachability-policy key. An unknown key is REFUSED by the
+ *  handler (never silently stored — a typo'd key that persisted would be a setting that never takes
+ *  effect, invisible to the operator). */
+export declare function isValidSettingKey(key: string): boolean;
+/** The full list of valid keys (for surfacing in a settings-list / help). */
+export declare function allSettingKeys(): string[];
+/** True iff the key is a per-tier BOUND override (its value must be a positive integer). */
+export declare function isBoundKey(key: string): boolean;
+/**
+ * Validate a setting's VALUE for its key (DOD-TIER-BOUNDS-SETTINGS AC2). A bound override may only be
+ * a FINITE POSITIVE INTEGER — INV-TIER-BOUND: a setting can RAISE or lower a bound within finite
+ * limits, never REMOVE one. So `Infinity`, negatives, zero, non-integers, and non-numeric strings are
+ * refused (an unbounded tier is exactly what the grid forbids). Away-text values are free-form strings.
+ */
+export declare function validateSettingValue(key: string, value: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Max length of an away message (per-contact or per-tier/agent-default) — an answering-machine line. */
+export declare const AWAY_MESSAGE_MAX_LEN = 2048;
+//# sourceMappingURL=agent-settings-keys.d.ts.map

package/dist/agent-settings-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-settings-keys.d.ts","sourceRoot":"","sources":["../src/agent-settings-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,gGAAgG;AAChG,eAAO,MAAM,mBAAmB,qDAAqE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;4DAE4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAQtE;AAED,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,WAAW,CAAC;AAEtD,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAEjF;AAED,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAEjE;AAED,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAgB/C;;0CAE0C;AAC1C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAqC7G;AAED,yGAAyG;AACzG,eAAO,MAAM,oBAAoB,OAAO,CAAC"}

package/dist/agent-settings-keys.js

@@ -0,0 +1,114 @@
+/**
+ * CELLO Daemon — the agent_settings key namespace (DOD-SETTINGS-1).
+ *
+ * A single source for every valid per-agent reachability-policy setting key, so the handler (which
+ * REFUSES an unknown key) and the consumers (TIER-BOUNDS-SETTINGS reads the bound overrides,
+ * AWAY-TIER-1 reads the away texts) can never drift. Keys are lower-snake, dotted namespaces:
+ *
+ *   bounds.<tier>.max_sessions   bounds.<tier>.max_bytes    — per-tier bound overrides
+ *   away.default                                            — the agent's default away text
+ *   away.tier.<tier>                                        — a per-tier away text
+ *
+ * `<tier>` is a tier NAME (not the integer), for legibility in the store. BLOCKED is deliberately NOT
+ * settable — 0/0 is fixed (you cannot "raise" a block), and it has no away text (a blocked sender is
+ * refused before any reply). So the settable tiers are unknown / known / whitelisted / vip.
+ */
+import { TIER } from "./contacts-tier-migration.js";
+import { RELAY_ONLY_KEY } from "./relay-only.js";
+/** The tiers whose bounds and away texts are settable (BLOCKED is fixed, never overridable). */
+export const SETTABLE_TIER_NAMES = Object.freeze(["unknown", "known", "whitelisted", "vip"]);
+/** The tier NAME for a tier integer, or null for an unknown/unsettable value (e.g. BLOCKED=0).
+ *  Keyed off the TIER constants (review F3) so a renumbering in contacts-tier-migration can never
+ *  silently desync the settings namespace from the grid. */
+export function settableTierName(tier) {
+    switch (tier) {
+        case TIER.UNKNOWN: return "unknown";
+        case TIER.KNOWN: return "known";
+        case TIER.WHITELISTED: return "whitelisted";
+        case TIER.VIP: return "vip";
+        default: return null; // BLOCKED or out-of-range — not settable
+    }
+}
+/** The setting key for a per-tier bound override. */
+export function boundSettingKey(tier, field) {
+    return `bounds.${tier}.${field}`;
+}
+/** The setting key for a per-tier away text. */
+export function awayTierSettingKey(tier) {
+    return `away.tier.${tier}`;
+}
+/** The setting key for the agent's default away text (the fallback below any per-tier text). */
+export const AWAY_DEFAULT_KEY = "away.default";
+const BOUND_FIELDS = Object.freeze(["max_sessions", "max_bytes"]);
+/** Every valid setting key, precomputed. The handler validates a `set` against this exact set. */
+const VALID_KEYS = new Set([
+    AWAY_DEFAULT_KEY,
+    // DOD-M15-RELAYONLY-1: relay-only routing. A BOOLEAN key, and the first one here — see
+    // `validateSettingValue`, where it needs its own branch or the away-text fallback swallows it.
+    RELAY_ONLY_KEY,
+    ...SETTABLE_TIER_NAMES.flatMap((t) => [
+        ...BOUND_FIELDS.map((f) => boundSettingKey(t, f)),
+        awayTierSettingKey(t),
+    ]),
+]);
+/** True iff `key` is a known, settable reachability-policy key. An unknown key is REFUSED by the
+ *  handler (never silently stored — a typo'd key that persisted would be a setting that never takes
+ *  effect, invisible to the operator). */
+export function isValidSettingKey(key) {
+    return VALID_KEYS.has(key);
+}
+/** The full list of valid keys (for surfacing in a settings-list / help). */
+export function allSettingKeys() {
+    return [...VALID_KEYS];
+}
+/** True iff the key is a per-tier BOUND override (its value must be a positive integer). */
+export function isBoundKey(key) {
+    return key.startsWith("bounds.");
+}
+/**
+ * Validate a setting's VALUE for its key (DOD-TIER-BOUNDS-SETTINGS AC2). A bound override may only be
+ * a FINITE POSITIVE INTEGER — INV-TIER-BOUND: a setting can RAISE or lower a bound within finite
+ * limits, never REMOVE one. So `Infinity`, negatives, zero, non-integers, and non-numeric strings are
+ * refused (an unbounded tier is exactly what the grid forbids). Away-text values are free-form strings.
+ */
+export function validateSettingValue(key, value) {
+    if (isBoundKey(key)) {
+        // `^[1-9][0-9]*$` — a positive integer with no sign, decimal, or `Infinity`/`NaN` spelling.
+        if (!/^[1-9][0-9]*$/.test(value)) {
+            return { ok: false, reason: "a bound must be a finite positive integer (no 0, negative, decimal, or Infinity)" };
+        }
+        // Number.MAX_SAFE_INTEGER guard — a value past it loses precision and is meaningless as a cap.
+        if (Number(value) > Number.MAX_SAFE_INTEGER) {
+            return { ok: false, reason: "a bound must be <= Number.MAX_SAFE_INTEGER" };
+        }
+        return { ok: true };
+    }
+    // DOD-M15-RELAYONLY-1: a BOOLEAN key, and it must be caught BEFORE the away-text fallback below.
+    //
+    // ⚠️ THE FALLBACK IS THE HAZARD, not an edge case. Everything that is not a bound key falls
+    // through to away-text validation, which accepts any non-empty string under 2048 characters. So
+    // without this branch `transport.relay_only = "yes"` — or `"flase"` — would STORE successfully and
+    // then read as not-"true" forever: the operator sets the privacy control, is told it was saved,
+    // and has no protection. `isRelayOnly` deliberately treats anything but "true" as OFF, which is
+    // only safe because a bad value cannot get past here to be misread later.
+    if (key === RELAY_ONLY_KEY) {
+        if (value !== "true" && value !== "false") {
+            return { ok: false, reason: `${RELAY_ONLY_KEY} must be exactly "true" or "false"` };
+        }
+        return { ok: true };
+    }
+    // Away-text (review F2/F3): an EMPTY / whitespace-only away text is refused — to CLEAR, use null
+    // (cello_contact_set_away) or omit the key; storing "" would silently blank every away reply,
+    // including the minimal stranger disclosure. Bounded to a sane length (an answering-machine line,
+    // not a document).
+    if (value.trim().length === 0) {
+        return { ok: false, reason: "an away message cannot be empty or whitespace-only (omit the key or pass null to clear)" };
+    }
+    if (value.length > AWAY_MESSAGE_MAX_LEN) {
+        return { ok: false, reason: `an away message must be <= ${AWAY_MESSAGE_MAX_LEN} characters` };
+    }
+    return { ok: true };
+}
+/** Max length of an away message (per-contact or per-tier/agent-default) — an answering-machine line. */
+export const AWAY_MESSAGE_MAX_LEN = 2048;
+//# sourceMappingURL=agent-settings-keys.js.map

package/dist/agent-settings-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-settings-keys.js","sourceRoot":"","sources":["../src/agent-settings-keys.ts"],"names":[],"mappings":"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"}

package/dist/agent-state.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The one place an agent's state is decided.
+ *
+ * There are two status surfaces — the daemon-wide `getStatus()` the CLI prints, and the
+ * per-connection `cello_status` the MCP tools call — and they had two separate copies of this
+ * calculation. They already drifted once this week on a different field: the directory-health block
+ * existed on one surface and not the other, which is why an operator whose sessions were all failing
+ * could run `cello status` and be told nothing. Two copies of a truth claim is how that happens, so
+ * this exists as a single function both surfaces call.
+ *
+ * The ladder is documented on `AgentState` in types.ts. Order here IS the semantics: the first
+ * matching rung wins, worst fact first. An attended agent whose signaling is down reads
+ * `connecting`, not `online` — the severe fact is the one stopping it doing its job, and it is the
+ * one the operator needs. Reversing that would let attendance mask a dead connection, which is the
+ * exact class of lie this enum replaces.
+ */
+import type { AgentState } from "./types.js";
+/**
+ * Is this agent RUNNING — started, and not switched off?
+ *
+ * Use this wherever the old code asked `state === "online"` and MEANT "started". Narrowing `online`
+ * to also require an attendee changed the meaning of every such check silently: the string stayed
+ * valid, so the compiler caught none of them, and the symptom was `cello settings set` refusing a
+ * perfectly healthy agent with `selected_agent_offline`.
+ *
+ * The callers' actual question is the kill switch one — "may I claim this agent, or did the operator
+ * deliberately stop it?" So the excluded states are the ones where claiming it would be wrong:
+ * `stopped` and `paused` (resurrecting either would silently undo an operator's decision),
+ * `unregistered` (nobody can reach it), and `load_failed`.
+ *
+ * `unattended` counts: nobody is at the desk, so a caller gets the away message rather than a live
+ * reply, but the agent is up, reachable, and will record the session.
+ *
+ * `connecting` counts too, and that is deliberate. It is started; its directory stream is merely
+ * still coming up, which is NORMAL for a minute after registering. Excluding it made local commands
+ * — settings, moniker — refuse for want of a directory they never needed, which is the same
+ * over-reach in the opposite direction.
+ */
+export declare function isAgentRunning(state: AgentState | string | undefined): boolean;
+/** Everything the decision needs. Each field is a fact the daemon already tracks. */
+export interface AgentStateInputs {
+    /** The identity failed to load — a bad key file or database. Terminal. */
+    loadFailed: boolean;
+    /**
+     * Registration left a FROST share for this agent.
+     *
+     * Deliberately NOT a stored "registered" flag. Registration IS the distributed key ceremony, and
+     * the share is its durable product — so asking whether the share exists asks whether the thing
+     * actually happened, rather than whether someone remembered to record that it had. Before this,
+     * every agent on disk was labelled "registered" at load whether or not it ever was, so an agent
+     * created and not yet registered was indistinguishable from a working one.
+     */
+    hasFrostShare: boolean;
+    /** The operator deliberately took this agent offline — the kill switch. */
+    deliberatelyOffline: boolean;
+    /** The agent has been started in this daemon (it is in `onlineAgents`). */
+    started: boolean;
+    /** This agent's own directory signaling stream is connected. */
+    signalingConnected: boolean;
+    /** How many live connections are attending this agent right now. */
+    attendance: number;
+}
+/**
+ * Decide an agent's state. Pure — no clock, no I/O — so every rung is directly testable.
+ */
+export declare function resolveAgentState(i: AgentStateInputs): AgentState;
+//# sourceMappingURL=agent-state.d.ts.map

package/dist/agent-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state.d.ts","sourceRoot":"","sources":["../src/agent-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,2EAA2E;IAC3E,mBAAmB,EAAE,OAAO,CAAC;IAC7B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAqBjE"}