@cello-protocol/daemon 0.0.198 → 0.0.200

package/dist/onboarding-guidance.js

@@ -0,0 +1,95 @@
+/**
+ * What a machine with NO agents is told, and why it is one string in one place.
+ *
+ * ─── The failure this exists to prevent ──────────────────────────────────────────────────────
+ * A new operator installs the plugin, runs `cello login`, and gets `No registered agents to
+ * start.` — nine words that name no next command, no token, and no bot. Measured 2026-09-07: the
+ * words "waitlist", "cohort" and "wave" appeared NOWHERE in the CLI, the daemon, or any of the
+ * five plugin skills, and the bot was referred to only as "the CELLO Operations Agent on
+ * Telegram" — a description, never a handle you could search for.
+ *
+ * ─── THERE ARE TWO TOKENS, AND CONFLATING THEM IS THE DEFECT ─────────────────────────────────
+ * The first draft of this text treated them as one thing and got the shape wrong.
+ *
+ *   **Waitlist token** — minted by a wave when you are admitted from the waitlist. The gate
+ *   handler calls it a grant of NETWORK ACCESS. You present it to the bot ONCE and it is
+ *   BURNED; the burn links your Telegram account. It is not per-agent and you never see it again.
+ *
+ *   **Agent token** — the `CELLO-` pre-authorization capability the bot issues so a specific
+ *   agent may register. One per agent, single-use, 24-hour expiry.
+ *
+ * The system's own name for the first is `waitlist_tokens`, and that is what it is called here.
+ * It is deliberately NOT "telegram token": `cello-ops-agent-telegram-bot-token` already exists in
+ * the infrastructure as the bot's API credential, and giving two unrelated secrets one name is a
+ * support conversation nobody can untangle.
+ *
+ * ─── WHY THE GATE IS AT THE BOTTOM, NOT THE TOP ──────────────────────────────────────────────
+ * An earlier version led with the cohort gate on the theory that it prevents a wasted trip to
+ * Telegram. Andre's correction, and the gate handler agrees with him: the gate's first step is
+ * "is this Telegram ID already linked? → proceed". Once the waitlist token is burned, the
+ * condition is permanently satisfied. Leading with it means everyone past that point reads a
+ * standing warning about a door they already walked through, every time they have no agent on a
+ * machine — which is also true on a second laptop, after a reset, and after an ecosystem wipe.
+ *
+ * So the happy path leads and the gate is a CONDITION underneath it, phrased as a question so a
+ * reader who is past it skips it instead of re-reading it.
+ *
+ * ─── Why the gate is bullets and not a paragraph ─────────────────────────────────────────────
+ * It was a prose block, and it dropped out of scanning mode exactly where the reader is still
+ * scanning. Both halves are now lists — numbered steps, then bulleted steps — so the whole
+ * message reads as one shape rather than switching from instructions to explanation halfway
+ * down. The bullets are ACTIONS for the same reason: at that point the reader's question is
+ * "what do I do", not "what is this thing".
+ *
+ * ─── Why the handle is DERIVED and not a constant ────────────────────────────────────────────
+ * There are two bots — production and staging — and a hardcoded handle sends a staging operator
+ * to the production bot, which will refuse their staging waitlist token with a message about a
+ * grant they do hold, on a bot they should not be talking to. `CELLO_ENV` already exists in this
+ * daemon and already carries `staging`, so the handle derives from it.
+ *
+ * **The mapping is a whitelist of ONE, deliberately.** `resolveCelloEnv` defaults an unset
+ * `CELLO_ENV` to `"local"`, and the overwhelmingly common case — an operator who installed from
+ * npm and set nothing — must never be pointed at staging. So only a literal `staging` gets the
+ * staging bot and everything else gets production: a misconfiguration sends someone to the real
+ * bot, which is the recoverable direction of that error.
+ *
+ * ─── Why it lives in the daemon ──────────────────────────────────────────────────────────────
+ * Two surfaces show it: the CLI (`cello login`) and the MCP shim, for the operator who never
+ * opens a terminal. The CLI imports this because `cli` depends on `daemon`. **`connect` depends
+ * on NO @cello-protocol package** — it is a 233 KB socket shim by design, and making it depend on
+ * the 7.8 MB daemon would put a native SQLCipher build on every session start. So the shim cannot
+ * import this, and the text reaches it over the wire: `cello_list_agents` returns it as
+ * `onboarding` when the roster is empty. One definition, two renderers, no drift.
+ */
+/** Where someone who has not signed up starts. Live as of 2026-09-07. */
+export const WAITLIST_URL = "https://cello.mygentic.ai/waitlist";
+/** The operations agent on Telegram, by environment. */
+export const BOT_HANDLE_PRODUCTION = "@CelloConnectBot";
+export const BOT_HANDLE_STAGING = "@CelloConnectStagingBot";
+/**
+ * Which bot to send this operator to. Only an explicit `staging` diverges — see the whitelist
+ * note above for why an unrecognised or unset value must resolve to production.
+ */
+export function botHandle(celloEnv = process.env["CELLO_ENV"]) {
+    return celloEnv === "staging" ? BOT_HANDLE_STAGING : BOT_HANDLE_PRODUCTION;
+}
+/**
+ * Shown when a machine has zero agents. Plain text, terminal-width, no ANSI — it is rendered
+ * verbatim by the CLI and passed through to an agent by the shim, and neither can assume a TTY.
+ */
+export function noAgentsGuidance(celloEnv) {
+    return ("No agents on this machine yet. To make one:\n" +
+        "\n" +
+        `  1. Get an agent token from ${botHandle(celloEnv)} on Telegram\n` +
+        "  2. cello create-agent <name>\n" +
+        "  3. cello register-agent <name> <token>\n" +
+        "\n" +
+        "That's it — your agent is live and reachable.\n" +
+        "\n" +
+        "First time with the bot? It asks for a waitlist token first. To get one:\n" +
+        "\n" +
+        `  - Join the waitlist: ${WAITLIST_URL}\n` +
+        "  - Wait to be admitted to a launch cohort — you'll be notified\n" +
+        "  - Give the bot that token once. It is burned on use and never asked for again");
+}
+//# sourceMappingURL=onboarding-guidance.js.map

package/dist/onboarding-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-guidance.js","sourceRoot":"","sources":["../src/onboarding-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,YAAY,GAAG,oCAAoC,CAAC;AAEjE,wDAAwD;AACxD,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAE5D;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,WAA+B,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC/E,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,qBAAqB,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAiB;IAChD,OAAO,CACL,+CAA+C;QAC/C,IAAI;QACJ,gCAAgC,SAAS,CAAC,QAAQ,CAAC,gBAAgB;QACnE,kCAAkC;QAClC,4CAA4C;QAC5C,IAAI;QACJ,iDAAiD;QACjD,IAAI;QACJ,4EAA4E;QAC5E,IAAI;QACJ,0BAA0B,YAAY,IAAI;QAC1C,mEAAmE;QACnE,iFAAiF,CAClF,CAAC;AACJ,CAAC"}

package/dist/session-relay-client.d.ts

@@ -5,6 +5,16 @@ import { type RelayReceiptStore } from "./relay-receipt-store.js";
 import type { SessionSealLeafStore } from "./session-seal-leaf-store.js";
 import type { SessionOwnChainStore } from "./session-own-chain-store.js";
 export declare const RELAY_PROTOCOL_ID = "/cello/relay/1.0.0";
+/**
+ * How long to wait before re-proving after a transport-class failure.
+ *
+ * Sized against the measured event, not guessed: libp2p logged
+ * `connection-manager closing 1 connections / stopped / started` inside 3ms, and the redial that
+ * followed completed ~1s later. A second is comfortably past the restart while still being
+ * invisible next to the ~5 minutes the previous behaviour cost (quarantine the relay, wait for the
+ * next reachability sweep).
+ */
+export declare const PROOF_RETRY_DELAY_MS = 1000;
 export declare const RELAY_AUTH_DOMAIN = "CELLO-RELAY-AUTH-v1";
 /** Structure 1 leaf kind: 0x00 = message, 0x02 = control (matches the relay). */
 /**
@@ -344,6 +354,33 @@ export declare class AgentRelayClient {
      * `purpose: "reservation"` so the relay proves possession WITHOUT rebinding the agent's delivery
      * stream (which would steal the live session's inbound leaves — see the relay-side dispatch).
      */
+    /**
+     * ⚠️ **THE FIRST ATTEMPT AFTER A COLD START IS EXPECTED TO FAIL, AND THAT IS NOT A FAULT ON
+     * EITHER SIDE.** Root-caused 2026-09-07 from libp2p's own debug log:
+     *
+     * ```
+     * circuit-relay listener: making reservation on relay
+     * reservation failed with status PERMISSION_DENIED     <- the relay's gate, working as designed
+     * could not add discovered relay
+     * connection-manager closing 1 connections / stopped / started
+     * ```
+     *
+     * libp2p's circuit-relay listener asks the relay for a reservation ON ITS OWN, before any CELLO
+     * code has proven anything. The relay's gate refuses an unproven peer — deliberately; its flow is
+     * *"asks, is refused, proves itself, and asks again"*. libp2p reacts to that refusal by discarding
+     * the relay and RESTARTING ITS CONNECTION MANAGER, which closes every connection — including the
+     * healthy one this proof is being opened on. Whichever lands first decides the outcome, so the
+     * failure is intermittent (measured 5/5, 2/4, 0/4, 1/6 across cold logins).
+     *
+     * **Both components are behaving as specified, so the refusal cannot be designed away from here** —
+     * removing it means either weakening the gate or reaching into libp2p's internal
+     * `transportManager.listen` to defer the circuit listener until after the proof. What the client
+     * CAN do is survive it: a transport-class failure is retried on a fresh connection, once.
+     *
+     * A REFUSAL IS NOT RETRIED. If the relay reached a verdict — no token, slot cap, misconfigured —
+     * the answer will be identical a second later, and retrying would spend the operator's reachability
+     * on a question already answered. Only a failure that never reached a verdict is retried.
+     */
     proveReservation(node: CelloNode): Promise<boolean>;
     /**
      * Submit a session's CONTENT-leaf hash to the relay. Connects/re-connects from `node` if needed.

package/dist/session-relay-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-relay-client.d.ts","sourceRoot":"","sources":["../src/session-relay-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-relay-client.d.ts","sourceRoot":"","sources":["../src/session-relay-client.ts"],"names":[],"mappings":"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"}

package/dist/session-relay-client.js

@@ -36,6 +36,16 @@ import { verify } from "@cello-protocol/crypto";
 import { extractErrorMessage } from "./error-message.js";
 import { evaluateRelayAck } from "./relay-receipt-store.js";
 export const RELAY_PROTOCOL_ID = "/cello/relay/1.0.0";
+/**
+ * How long to wait before re-proving after a transport-class failure.
+ *
+ * Sized against the measured event, not guessed: libp2p logged
+ * `connection-manager closing 1 connections / stopped / started` inside 3ms, and the redial that
+ * followed completed ~1s later. A second is comfortably past the restart while still being
+ * invisible next to the ~5 minutes the previous behaviour cost (quarantine the relay, wait for the
+ * next reachability sweep).
+ */
+export const PROOF_RETRY_DELAY_MS = 1_000;
 export const RELAY_AUTH_DOMAIN = "CELLO-RELAY-AUTH-v1";
 /** Structure 1 leaf kind: 0x00 = message, 0x02 = control (matches the relay). */
 /**
@@ -307,6 +317,17 @@ export class AgentRelayClient {
     getLastAuthRefusal() {
         return this.#lastAuthRefusal;
     }
+    /**
+     * Drop any verdict from an earlier attempt — review HIGH-2.
+     *
+     * A METHOD rather than an inline `= null`, deliberately: assigning the field directly narrows its
+     * type to `null` for the rest of the enclosing method, and the later
+     * `#lastAuthRefusal?.reason` read then fails to compile against `never`. Clearing through a call
+     * keeps the declared type and says what the reset is for.
+     */
+    #clearAuthRefusal() {
+        this.#lastAuthRefusal = null;
+    }
     #stream = null;
     #connecting = null;
     #closed = false;
@@ -1163,25 +1184,168 @@ export class AgentRelayClient {
      * `purpose: "reservation"` so the relay proves possession WITHOUT rebinding the agent's delivery
      * stream (which would steal the live session's inbound leaves — see the relay-side dispatch).
      */
+    /**
+     * ⚠️ **THE FIRST ATTEMPT AFTER A COLD START IS EXPECTED TO FAIL, AND THAT IS NOT A FAULT ON
+     * EITHER SIDE.** Root-caused 2026-09-07 from libp2p's own debug log:
+     *
+     * ```
+     * circuit-relay listener: making reservation on relay
+     * reservation failed with status PERMISSION_DENIED     <- the relay's gate, working as designed
+     * could not add discovered relay
+     * connection-manager closing 1 connections / stopped / started
+     * ```
+     *
+     * libp2p's circuit-relay listener asks the relay for a reservation ON ITS OWN, before any CELLO
+     * code has proven anything. The relay's gate refuses an unproven peer — deliberately; its flow is
+     * *"asks, is refused, proves itself, and asks again"*. libp2p reacts to that refusal by discarding
+     * the relay and RESTARTING ITS CONNECTION MANAGER, which closes every connection — including the
+     * healthy one this proof is being opened on. Whichever lands first decides the outcome, so the
+     * failure is intermittent (measured 5/5, 2/4, 0/4, 1/6 across cold logins).
+     *
+     * **Both components are behaving as specified, so the refusal cannot be designed away from here** —
+     * removing it means either weakening the gate or reaching into libp2p's internal
+     * `transportManager.listen` to defer the circuit listener until after the proof. What the client
+     * CAN do is survive it: a transport-class failure is retried on a fresh connection, once.
+     *
+     * A REFUSAL IS NOT RETRIED. If the relay reached a verdict — no token, slot cap, misconfigured —
+     * the answer will be identical a second later, and retrying would spend the operator's reachability
+     * on a question already answered. Only a failure that never reached a verdict is retried.
+     */
     async proveReservation(node) {
         if (this.#closed)
             return false;
+        const first = await this.#proveReservationOnce(node);
+        if (first !== "transport_failed")
+            return first;
+        /**
+         * The connection manager has just restarted, so the previous connection is gone and a fresh
+         * dial is required — which `#proveReservationOnce` does at its head. The brief wait is for
+         * libp2p to finish restarting; without it the redial races the restart it is recovering from.
+         */
+        await new Promise((r) => setTimeout(r, PROOF_RETRY_DELAY_MS));
+        if (this.#closed)
+            return false;
+        this.#logger.info("session.relay.reservation_proof.retry", {
+            relayPeerId: this.#relayPeerId,
+            afterMs: PROOF_RETRY_DELAY_MS,
+            impact: "the first proof never reached a verdict — the connection was destroyed under it, which is " +
+                "what libp2p does to a relay that just refused its automatic reservation. Retrying once on " +
+                "a fresh connection. If this succeeds the agent is reachable and nothing was wrong.",
+        });
+        const second = await this.#proveReservationOnce(node);
+        return second === true;
+    }
+    /**
+     * One attempt. `true`/`false` are VERDICTS (the relay answered); `"transport_failed"` means no
+     * verdict was reached and the question is still open — the distinction the retry above turns on.
+     */
+    async #proveReservationOnce(node) {
+        if (this.#closed)
+            return false;
+        /**
+         * ⚠️ **CLEAR THE REFUSAL FIRST — review HIGH-2.** `#lastAuthRefusal` is set when a relay REFUSES
+         * a proof on the merits, and cleared only on auth SUCCESS. Both early returns below are
+         * transport failures that never reach a verdict, so without this a stale refusal from an
+         * earlier attempt survives them — and `session-relay.ts` reads `getLastAuthRefusal()` off a
+         * CACHED client, writes it into `srRelayRefusal`, and quarantines the relay and rebuilds the
+         * receiver when it says `tryAnotherRelay`. One real refusal followed by a later transport blip
+         * would therefore explain the agent's unreachability with a cause that is no longer true, while
+         * churning receivers over it. A transport failure must leave no verdict behind.
+         */
+        this.#clearAuthRefusal();
+        /**
+         * A FAILED DIAL MUST NOT BE REPORTED AS A FAILED STREAM. This loop used to swallow every dial
+         * error and fall through to `newStream` regardless. `#connect()` below has always tracked this
+         * and logs `session.relay.dial.failed`; the two were written from one shape and this one lost
+         * the check.
+         *
+         * ⚠️ **This branch did NOT cause the cold-login failure** (measured 2026-09-07: the dial
+         * succeeds, because libp2p's `findExistingConnection` returns an already-open connection rather
+         * than dialling). It is a real gap on the malformed-address and limited-connection paths, and
+         * nothing more. Do not read its presence as the reachability fix.
+         */
+        let dialed = false;
+        let lastDialError = "";
         for (const addr of this.#relayAddrs) {
             try {
                 await node.dial(addr);
+                dialed = true;
                 break;
             }
-            catch { /* try the next address */ }
+            catch (err) {
+                lastDialError = extractErrorMessage(err);
+            }
+        }
+        if (!dialed && this.#relayAddrs.length > 0) {
+            this.#logger.warn("session.relay.reservation_proof.failed", {
+                relayPeerId: this.#relayPeerId,
+                relayAddrs: this.#relayAddrs,
+                reason: "dial",
+                error: lastDialError,
+                impact: "could not open a connection to this relay, so no proof was sent and the relay saw " +
+                    "nothing. The agent holds no reservation on it and is unreachable through it until a " +
+                    "later attempt succeeds. This is a REACHABILITY fault, not a rejection — the relay did " +
+                    "not refuse anything.",
+            });
+            return "transport_failed";
         }
+        // TEMPORARY INSTRUMENT (2026-09-07): snapshot immediately BEFORE newStream. Paired with the
+        // snapshot in the catch, this localises the destruction to the newStream call itself rather
+        // than "sometime around the failure".
+        const snap = () => node.getConnections().map((c) => ({
+            toThisRelay: c.peerId === this.#relayPeerId,
+            peer: c.peerId.slice(0, 16),
+            status: c.status,
+            muxer: c.muxerStatus,
+            streams: c.streamCount,
+            protocols: c.streamProtocols,
+        }));
+        const before = snap();
         let stream;
         try {
             stream = await node.newStream(this.#relayPeerId, RELAY_PROTOCOL_ID);
         }
         catch (err) {
+            /**
+             * ⚠️ **DO NOT COLLAPSE THIS TO `reason: "stream"`.** `CelloNode.newStream` throws STRUCTURED
+             * errors — plain objects, not `Error`s — whose `reason` is the only field that says what
+             * happened. This site used to overwrite it with the literal `"stream"`, so every distinct
+             * cause reached the operator as one line. Measured 2026-09-07: a whole clean-room
+             * investigation went to the relay servers because the cause was discarded at capture.
+             *
+             * The set is whatever `mapStreamError` returns — deliberately NOT enumerated here, because
+             * the first version of this comment listed four of the six and the two it missed
+             * (`protocol_not_supported`, `limited_connection_refused`) are exactly the ones a redial
+             * cannot fix.
+             *
+             * ⚠️ **`connection_lost` IS THE CATCH-ALL, NOT A DIAGNOSIS** (`node.ts` says so). It covers a
+             * dead muxer on a live socket, a per-protocol stream cap, and a remote reset during
+             * multistream negotiation alike. **`muxerStatus` is what separates them**, which is why the
+             * connections are dumped below: the transport exposes that field for this exact question and
+             * without it the next cold-login failure is guessed at again.
+             *
+             * And note what this does NOT establish: the relay's handler only runs AFTER negotiation
+             * succeeds, so a relay that reset the stream mid-negotiation would log nothing either. Relay
+             * silence is not relay innocence.
+             */
+            const raw = (err ?? {});
+            const reason = typeof raw.reason === "string" ? raw.reason : "stream";
             this.#logger.warn("session.relay.reservation_proof.failed", {
-                relayPeerId: this.#relayPeerId, reason: "stream", error: extractErrorMessage(err),
+                relayPeerId: this.#relayPeerId,
+                relayAddrs: this.#relayAddrs,
+                nodePeerId: node.getPeerId(),
+                reason,
+                error: extractErrorMessage(err),
+                // The discriminator. `status` is the SOCKET; `muxerStatus` is the layer that carries data
+                // and the one `newStream` checks first — a connection reading open/closed is the P5 shape.
+                connsBeforeNewStream: before,
+                connsAtFailure: snap(),
+                nodeStatusAtFailure: node.lifecycleStatus?.() ?? "(unavailable)",
+                impact: "no proof was sent, so this relay granted no reservation and the agent is unreachable " +
+                    "through it until a later attempt succeeds. The relay did not refuse anything — it may " +
+                    "never have seen the stream.",
             });
-            return false;
+            return "transport_failed";
         }
         try {
             const iter = lp.decode(stream)[Symbol.asyncIterator]();
@@ -1239,7 +1403,22 @@ export class AgentRelayClient {
             stream = await node.newStream(this.#relayPeerId, RELAY_PROTOCOL_ID);
         }
         catch (err) {
-            this.#logger.warn("session.relay.stream.failed", { relayPeerId: this.#relayPeerId, error: extractErrorMessage(err) });
+            /**
+             * Same error substitution as `proveReservation`'s stream branch, and on the MORE important
+             * path — this is the stream that carries `leaf_deliver` into a live session. `newStream`'s
+             * structured `reason` was being dropped here too, leaving `connection_lost`, a stream cap and
+             * a refused protocol indistinguishable while a conversation is running.
+             */
+            const raw = (err ?? {});
+            this.#logger.warn("session.relay.stream.failed", {
+                relayPeerId: this.#relayPeerId,
+                reason: typeof raw.reason === "string" ? raw.reason : "stream",
+                error: extractErrorMessage(err),
+                relayConnections: node
+                    .getConnections()
+                    .filter((c) => c.peerId === this.#relayPeerId)
+                    .map((c) => ({ status: c.status, muxerStatus: c.muxerStatus, streams: c.streamCount })),
+            });
             return false;
         }
         // ONE shared lp.decode iterator for the whole stream lifetime — splitting it signals