@cello-protocol/daemon 0.0.230 → 0.0.232

package/dist/channel-admin-lookup.d.ts

@@ -0,0 +1,54 @@
+/**
+ * M16 020-CHANADMIN — asking a directory who administers a channel.
+ *
+ * A subscriber that has been handed a group key must check the agent that handed it over against
+ * what the directory says about the channel. The session proves who the counterparty IS; it says
+ * nothing about whether they have any authority over this channel. Without the check, any agent that
+ * can open a session with you becomes your channel.
+ *
+ * 019 built the check and it could not run: the answer lives in the directory's profile and no
+ * client-facing frame carried it. `channel_admin_query` (020, directory side) does, on the
+ * authenticated signaling stream. This is the client half.
+ *
+ * ⚠️ **"NOT A CHANNEL" AND "I COULD NOT FIND OUT" ARE DIFFERENT ANSWERS, and the whole value of this
+ * module is keeping them apart.** A negative is authoritative — the subscriber acts on it. A
+ * timeout, a down stream, a malformed reply or a directory-side `lookup_failed` are all the absence
+ * of an answer, and they leave the join refused. Collapsed into the negative, a directory outage
+ * would read as a verdict about the channel, and the step after that is accepting a key from
+ * whoever happened to answer.
+ */
+import type { Logger } from "./types.js";
+/**
+ * The part of a `SignalingManager` this needs. Structural rather than the class, so the lookup can
+ * be exercised without standing up a directory connection.
+ */
+export interface SignalingLike {
+    registerInboundHandler(handler: (frame: Record<string, unknown>) => void): () => void;
+    sendRaw(frame: unknown): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+export type ChannelAdminOutcome = 
+/** A registered channel, and the agent the directory says administers it. */
+{
+    kind: "admin";
+    adminPubkeyHex: string;
+}
+/** The directory answered, and this pubkey is not a channel — unregistered, or an ordinary agent. */
+ | {
+    kind: "not_a_channel";
+}
+/** No answer. NOT a verdict about the channel. */
+ | {
+    kind: "unavailable";
+    reason: string;
+};
+export interface ChannelAdminLookupDeps {
+    /** The asking agent's directory connection, or null when it has none. */
+    signalingFor: (agentId: string) => SignalingLike | null;
+    logger: Logger;
+    timeoutMs?: number;
+}
+export declare function createChannelAdminLookup(deps: ChannelAdminLookupDeps): (agentId: string, channelHex: string) => Promise<ChannelAdminOutcome>;
+//# sourceMappingURL=channel-admin-lookup.d.ts.map

package/dist/channel-admin-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-admin-lookup.d.ts","sourceRoot":"","sources":["../src/channel-admin-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACtF,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpE;AAED,MAAM,MAAM,mBAAmB;AAC7B,6EAA6E;AAC3E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE;AAC3C,qGAAqG;GACnG;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE;AAC3B,kDAAkD;GAChD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,aAAa,GAAG,IAAI,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmBD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,sBAAsB,GAC3B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CA0GvE"}

package/dist/channel-admin-lookup.js

@@ -0,0 +1,122 @@
+import { extractErrorMessage } from "./error-message.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** 64 lowercase hex characters, or nothing. A partial admin key must not reach a comparison. */
+function adminPubkeyOf(frame) {
+    const raw = frame["admin_pubkey"];
+    if (typeof raw !== "string" || !/^[0-9a-fA-F]{64}$/.test(raw))
+        return null;
+    return raw.toLowerCase();
+}
+function echoedChannelHex(frame) {
+    const raw = frame["channel_pubkey"];
+    if (raw instanceof Uint8Array)
+        return Buffer.from(raw).toString("hex");
+    if (Buffer.isBuffer(raw))
+        return raw.toString("hex");
+    if (typeof raw === "string" && /^[0-9a-fA-F]{64}$/.test(raw))
+        return raw.toLowerCase();
+    return null;
+}
+export function createChannelAdminLookup(deps) {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return async function lookup(agentId, channelHexRaw) {
+        const channelHex = channelHexRaw.toLowerCase();
+        const signaling = deps.signalingFor(agentId);
+        if (!signaling) {
+            // Answer now rather than waiting out the timeout for a reply that was never coming — this runs
+            // on the inbound join path, once per frame.
+            return { kind: "unavailable", reason: "signaling_unavailable" };
+        }
+        let resolveFrame;
+        const pending = new Promise((r) => { resolveFrame = r; });
+        /**
+         * ⚠️ **MATCHED ON THE ECHOED PUBKEY, not on the frame type alone.** The signaling stream is one
+         * multiplexed stream shared by every lookup this agent has in flight. Taking the first
+         * `channel_admin_result` that arrives would let two concurrent joins each accept the other's
+         * answer — and then the admin check runs against a different channel's administrator, where a
+         * match proves nothing.
+         */
+        const unregister = signaling.registerInboundHandler((frame) => {
+            const t = frame["type"];
+            if (t !== "channel_admin_result" && t !== "channel_admin_error")
+                return;
+            /**
+             * ⚠️ **THE ERROR IS MATCHED THE SAME WAY, and it was not at first.** An unmatched error
+             * resolved whichever lookup happened to be waiting: two joins in flight, a database fault on
+             * the first channel, and the second was refused although the directory had answered it
+             * perfectly. It fails closed, so nothing unsafe — it just turns one channel's outage into
+             * every concurrent join's refusal, which is a bad trade for a field.
+             */
+            if (echoedChannelHex(frame) !== channelHex)
+                return;
+            resolveFrame(frame);
+        });
+        let timer;
+        try {
+            const sent = await signaling.sendRaw({
+                type: "channel_admin_query",
+                channel_pubkey: new Uint8Array(Buffer.from(channelHex, "hex")),
+            });
+            if (!sent.ok) {
+                // The transport's own reason, never a guess about the directory or the channel.
+                return { kind: "unavailable", reason: sent.reason ?? "signaling_unavailable" };
+            }
+            const timeoutP = new Promise((r) => {
+                timer = setTimeout(() => r({ type: "__timeout__" }), timeoutMs);
+            });
+            const frame = await Promise.race([pending, timeoutP]);
+            if (frame["type"] === "__timeout__") {
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason: "timeout" });
+                return { kind: "unavailable", reason: "timeout" };
+            }
+            if (frame["type"] === "channel_admin_error") {
+                const reason = typeof frame["reason"] === "string" ? frame["reason"] : "lookup_failed";
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason });
+                return { kind: "unavailable", reason };
+            }
+            /**
+             * ⚠️ **SHAPE FIRST, AND THIS WAS A DEFECT THE TEST CAUGHT.** `registered !== true` is true for
+             * a field that is ABSENT as well as one that is `false` — so a reply missing the field
+             * entirely read as an authoritative "not a channel", which is precisely the collapse this
+             * module exists to prevent. A frame that does not carry both booleans is a directory that
+             * replied with something we cannot read, and that is not knowing.
+             */
+            if (typeof frame["registered"] !== "boolean" || typeof frame["channel"] !== "boolean") {
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason: "malformed_reply" });
+                return { kind: "unavailable", reason: "malformed_reply" };
+            }
+            if (frame["registered"] !== true || frame["channel"] !== true) {
+                // An answer, and a settled one: the subscriber is looking at something that is not a channel.
+                deps.logger.info("directory.channel.admin.lookup", { channel: channelHex.slice(0, 16), answered: "not_a_channel" });
+                return { kind: "not_a_channel" };
+            }
+            const adminPubkeyHex = adminPubkeyOf(frame);
+            if (adminPubkeyHex === null) {
+                /**
+                 * A registered channel whose answer carries no usable admin key. Reading a missing or
+                 * malformed field as `""` would put an empty key into the comparison against whoever
+                 * answered — which either matches nothing for ever or, worse, matches an empty counterparty.
+                 * So it is `unavailable`: there is no admin to check against, and that is not knowing.
+                 *
+                 * ⚠️ **NAMED FOR THE REGISTRATION, NOT THE WIRE.** Calling this `malformed_reply` sent the
+                 * operator to debug the protocol, when the directory answered exactly as designed about a
+                 * channel that was registered without an administrator. The reason has to point at the
+                 * thing that is actually wrong.
+                 */
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason: "channel_without_admin" });
+                return { kind: "unavailable", reason: "channel_without_admin" };
+            }
+            deps.logger.info("directory.channel.admin.lookup", { channel: channelHex.slice(0, 16), answered: "admin" });
+            return { kind: "admin", adminPubkeyHex };
+        }
+        catch (err) {
+            return { kind: "unavailable", reason: extractErrorMessage(err) };
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            unregister();
+        }
+    };
+}
+//# sourceMappingURL=channel-admin-lookup.js.map

package/dist/channel-admin-lookup.js.map

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

package/dist/channel-collect-tick.d.ts

@@ -1,12 +1,48 @@
 import type { Logger } from "./types.js";
 import type { ChannelCollector } from "./channel-collector.js";
 import type { ChannelSubscriptionStore } from "./channel-subscription-store.js";
-/** See the header: bounded by the shortest retention any channel may configure. */
+/**
+ * ⚠️ **THIS IS A BACKSTOP, NOT THE DELIVERY MECHANISM — 021-WAKE changed what it is FOR.**
+ *
+ * At five minutes this timer WAS how a post reached anyone, and the feature was email with a
+ * five-minute inbox check. Delivery is now the wake (021): the publisher asks a directory to poke
+ * the members and they fetch at once.
+ *
+ * The timer keeps a job because push is best-effort, and it is the only thing that covers a post
+ * sitting on a relay with nobody told: the publisher's daemon never sent the wake, the frame was
+ * lost while the signaling stream rotated, or the peer forward never reached this subscriber's
+ * node. It does not go to zero, because the case it cannot otherwise repair is a channel that goes
+ * QUIET right after the message you missed — which is exactly the "relays going down now" post.
+ */
 export declare const COLLECT_TICK_INTERVAL_MS: number;
-/** The widest the pubkey-derived offset can push a channel's tick. */
-export declare const COLLECT_JITTER_MS = 60000;
-/** A failing channel is backed off to at most this, then stays there until it succeeds. */
+/**
+ * The widest the pubkey-derived offset can push a channel's tick — **a proportion of the interval,
+ * which is why it is written as one.** A fixed 60 seconds was right for a 5-minute tick and is a
+ * narrow band inside an hour: the fleet would clump into the same minute every hour, which is the
+ * thundering herd this exists to prevent, arriving less often and so harder to notice.
+ */
+export declare const COLLECT_JITTER_MS: number;
+/**
+ * A failing channel is backed off to at most this, then stays there until it succeeds.
+ *
+ * ⚠️ **IT HAS TO EXCEED THE INTERVAL OR IT IS NOT A BACKOFF.** At 30 minutes against an hourly
+ * poll, a FAILING channel became due sooner than a healthy one — the first failure computed
+ * `min(30min, 60min×2)` = 30 minutes, and every subsequent one stayed there. This number was sized
+ * for a five-minute interval and not re-derived when the interval moved, which is the whole
+ * mistake: a constant that only makes sense relative to another constant should be written
+ * relative to it.
+ */
 export declare const COLLECT_MAX_BACKOFF_MS: number;
+/**
+ * Randomness added to a RETRY, on top of the stable per-channel jitter.
+ *
+ * ⚠️ **THE STEADY-STATE TIMER IS NOT THE STAMPEDE RISK — RECOVERY IS.** When a relay returns after
+ * an outage, every daemon that has been failing is on the retry path, not the timer, and
+ * `jitterForChannel` is stable per (agent, channel) so it does not stagger the returning WAVE: all
+ * of them back off to the same ceiling and come due on the same pass. This is the one place a
+ * re-rolled random belongs, because the thing being spread is a moment rather than a schedule.
+ */
+export declare const COLLECT_RETRY_SPREAD_MS: number;
 export interface ChannelCollectTickDeps {
     logger: Logger;
     collector: ChannelCollector;
@@ -19,12 +55,22 @@ export interface ChannelCollectTickDeps {
     intervalMs?: number;
     jitterMs?: number;
     maxBackoffMs?: number;
+    /** M16 021-WAKE: random spread on the RETRY path only. Set to 0 in a test that needs determinism. */
+    retrySpreadMs?: number;
 }
 export interface ChannelCollectTicker {
     /** Begin collecting. Idempotent: a second call does not stack a second timer. */
     start: () => void;
     /** One pass over every active subscription. Exposed so a test drives it without a clock. */
     collectAllDue: (now: number) => Promise<void>;
+    /**
+     * M16 021-WAKE: the doorbell rang — collect this agent's channels NOW.
+     *
+     * ⚠️ **EVERY channel this agent follows, because the wake names none.** The frame is deliberately
+     * empty so that channel→member never travels a second wire; the daemon already knows what it
+     * subscribes to, and fetching all of them is what makes the empty frame sufficient.
+     */
+    collectNow: (agentId: string) => Promise<void>;
     stop: () => void;
 }
 /**

package/dist/channel-collect-tick.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-collect-tick.d.ts","sourceRoot":"","sources":["../src/channel-collect-tick.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAGhF,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AACnD,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAc,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;IAC5B,aAAa,EAAE,wBAAwB,CAAC;IACxC;;;OAGG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,4FAA4F;IAC5F,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI9F;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,oBAAoB,CAgF7F"}
+{"version":3,"file":"channel-collect-tick.d.ts","sourceRoot":"","sources":["../src/channel-collect-tick.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAGhF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,QAAc,CAAC;AACpD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAA+B,CAAC;AAC9D;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,QAAc,CAAC;AAEnD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;IAC5B,aAAa,EAAE,wBAAwB,CAAC;IACxC;;;OAGG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,4FAA4F;IAC5F,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;;;;;OAMG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI9F;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,oBAAoB,CAyI7F"}

package/dist/channel-collect-tick.js

@@ -32,12 +32,48 @@
  */
 import { createHash } from "node:crypto";
 import { extractErrorMessage } from "./error-message.js";
-/** See the header: bounded by the shortest retention any channel may configure. */
-export const COLLECT_TICK_INTERVAL_MS = 5 * 60_000;
-/** The widest the pubkey-derived offset can push a channel's tick. */
-export const COLLECT_JITTER_MS = 60_000;
-/** A failing channel is backed off to at most this, then stays there until it succeeds. */
-export const COLLECT_MAX_BACKOFF_MS = 30 * 60_000;
+/**
+ * ⚠️ **THIS IS A BACKSTOP, NOT THE DELIVERY MECHANISM — 021-WAKE changed what it is FOR.**
+ *
+ * At five minutes this timer WAS how a post reached anyone, and the feature was email with a
+ * five-minute inbox check. Delivery is now the wake (021): the publisher asks a directory to poke
+ * the members and they fetch at once.
+ *
+ * The timer keeps a job because push is best-effort, and it is the only thing that covers a post
+ * sitting on a relay with nobody told: the publisher's daemon never sent the wake, the frame was
+ * lost while the signaling stream rotated, or the peer forward never reached this subscriber's
+ * node. It does not go to zero, because the case it cannot otherwise repair is a channel that goes
+ * QUIET right after the message you missed — which is exactly the "relays going down now" post.
+ */
+export const COLLECT_TICK_INTERVAL_MS = 60 * 60_000;
+/**
+ * The widest the pubkey-derived offset can push a channel's tick — **a proportion of the interval,
+ * which is why it is written as one.** A fixed 60 seconds was right for a 5-minute tick and is a
+ * narrow band inside an hour: the fleet would clump into the same minute every hour, which is the
+ * thundering herd this exists to prevent, arriving less often and so harder to notice.
+ */
+export const COLLECT_JITTER_MS = COLLECT_TICK_INTERVAL_MS / 2;
+/**
+ * A failing channel is backed off to at most this, then stays there until it succeeds.
+ *
+ * ⚠️ **IT HAS TO EXCEED THE INTERVAL OR IT IS NOT A BACKOFF.** At 30 minutes against an hourly
+ * poll, a FAILING channel became due sooner than a healthy one — the first failure computed
+ * `min(30min, 60min×2)` = 30 minutes, and every subsequent one stayed there. This number was sized
+ * for a five-minute interval and not re-derived when the interval moved, which is the whole
+ * mistake: a constant that only makes sense relative to another constant should be written
+ * relative to it.
+ */
+export const COLLECT_MAX_BACKOFF_MS = 4 * COLLECT_TICK_INTERVAL_MS;
+/**
+ * Randomness added to a RETRY, on top of the stable per-channel jitter.
+ *
+ * ⚠️ **THE STEADY-STATE TIMER IS NOT THE STAMPEDE RISK — RECOVERY IS.** When a relay returns after
+ * an outage, every daemon that has been failing is on the retry path, not the timer, and
+ * `jitterForChannel` is stable per (agent, channel) so it does not stagger the returning WAVE: all
+ * of them back off to the same ceiling and come due on the same pass. This is the one place a
+ * re-rolled random belongs, because the thing being spread is a moment rather than a schedule.
+ */
+export const COLLECT_RETRY_SPREAD_MS = 10 * 60_000;
 /**
  * A stable offset in [0, jitterMs) for a channel, from its public key. Same channel, same
  * subscriber, same offset every time — see the header for why that beats a fresh random each tick.
@@ -53,6 +89,7 @@ export function createChannelCollectTicker(deps) {
     const intervalMs = deps.intervalMs ?? COLLECT_TICK_INTERVAL_MS;
     const jitterMs = deps.jitterMs ?? COLLECT_JITTER_MS;
     const maxBackoffMs = deps.maxBackoffMs ?? COLLECT_MAX_BACKOFF_MS;
+    const retrySpreadMs = deps.retrySpreadMs ?? COLLECT_RETRY_SPREAD_MS;
     /** When each subscription is next due, and how far it has been backed off. */
     const nextDue = new Map();
     const backoff = new Map();
@@ -95,7 +132,12 @@ export function createChannelCollectTicker(deps) {
                 // and one channel's bad relay must not stop every other channel on this daemon.
                 const next = Math.min(maxBackoffMs, (backoff.get(key) ?? intervalMs) * 2);
                 backoff.set(key, next);
-                nextDue.set(key, now + next + jitterForChannel(sub.channel_pubkey, sub.agent_id, jitterMs));
+                // Stable jitter spreads channels across subscribers; the RANDOM part spreads the moment a
+                // whole fleet returns after an outage, which stable jitter cannot do because every failing
+                // channel lands on the same ceiling.
+                nextDue.set(key, now + next
+                    + jitterForChannel(sub.channel_pubkey, sub.agent_id, jitterMs)
+                    + Math.floor(Math.random() * retrySpreadMs));
                 logger.warn("channel.collect.tick_failed", {
                     channel_pubkey: sub.channel_pubkey,
                     reason: extractErrorMessage(err),
@@ -107,10 +149,64 @@ export function createChannelCollectTicker(deps) {
             }
         }
     }
+    /**
+     * M16 021-WAKE — a doorbell arrived for this agent. Fetch its channels at once.
+     *
+     * ⚠️ **IT DOES NOT TOUCH `nextDue`, and that is deliberate.** A wake that reset the schedule would
+     * let a chatty channel keep pushing the backstop out for every OTHER channel on this agent — and
+     * the backstop is the only thing that repairs a wake that never arrived.
+     *
+     * ⚠️ The online check is repeated here. The kill switch has to hold on this path too: collecting
+     * for an agent the operator switched off is the switch failing to switch something off, and a
+     * doorbell must not become the way around it.
+     */
+    async function collectNow(agentId) {
+        if (!isAgentOnline(agentId)) {
+            logger.debug("channel.collect.wake_ignored", { reason: "agent_offline" });
+            return;
+        }
+        for (const sub of subscriptions.active()) {
+            if (sub.agent_id !== agentId)
+                continue;
+            const key = keyOf(sub.agent_id, sub.channel_pubkey);
+            if (inFlight.has(key))
+                continue;
+            inFlight.add(key);
+            try {
+                await collector.collectOnce(sub.agent_id, sub.channel_pubkey);
+                await collector.repairGaps(sub.agent_id, sub.channel_pubkey);
+                backoff.delete(key);
+            }
+            catch (err) {
+                // One channel's bad relay must not stop the rest of this agent's channels collecting. The
+                // timer's own backoff is untouched: this pass is extra, not a replacement for it.
+                logger.warn("channel.collect.wake_failed", {
+                    channel_pubkey: sub.channel_pubkey, reason: extractErrorMessage(err),
+                });
+            }
+            finally {
+                inFlight.delete(key);
+            }
+        }
+    }
     return {
+        collectNow,
         start() {
             if (timer !== null)
                 return;
+            /**
+             * ⚠️ **ONE PASS NOW, BEFORE THE TIMER — and leaving this out made the order's own worst case
+             * twelve times worse.** At a five-minute interval a daemon that had just started waited five
+             * minutes for its first collection; at sixty it waits an hour. Your laptop was shut
+             * overnight, you open it, the daemon reconnects — and nothing is fetched until the next hour.
+             * The offline subscriber is exactly the case the backstop exists for.
+             *
+             * It is also what makes a NEW subscription arrive promptly: `collectAllDue` treats first
+             * sight as due immediately, but only a pass can notice it.
+             */
+            void collectAllDue(Date.now()).catch((err) => {
+                logger.warn("channel.collect.pass_failed", { reason: extractErrorMessage(err) });
+            });
             // The pass runs every interval and decides per subscription what is due; the jitter lives in
             // the due times rather than in the timer, so one slow channel cannot drag the others.
             timer = setInterval(() => {

package/dist/channel-collect-tick.js.map

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

package/dist/channel-config-store.d.ts

@@ -23,6 +23,9 @@ export interface ChannelConfig {
     relays: string[];
     guidance: string;
     retention_seconds: number;
+    members_visible?: boolean;
+    /** The agent that answers join requests. NOT the channel key — see the column comment. */
+    admin_pubkey?: string;
 }
 export declare class ChannelConfigStore {
     #private;

package/dist/channel-config-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-config-store.d.ts","sourceRoot":"","sources":["../src/channel-config-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEpE,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAE1D,eAAO,MAAM,yBAAyB,QAWrC,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,kBAAkB;;gBAIjB,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM;IAM9C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IA0B7C,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAiBlE"}
+{"version":3,"file":"channel-config-store.d.ts","sourceRoot":"","sources":["../src/channel-config-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEpE,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAE1D,eAAO,MAAM,yBAAyB,QA0BrC,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,kBAAkB;;gBAIjB,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM;IAM9C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAkC7C,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAsBlE"}

package/dist/channel-config-store.js

@@ -9,6 +9,21 @@ export const CHANNEL_CONFIG_CREATE_SQL = `
     relays             TEXT    NOT NULL,
     guidance           TEXT    NOT NULL DEFAULT '',
     retention_seconds  INTEGER NOT NULL DEFAULT ${String(DEFAULT_RETENTION_SECONDS)},
+    -- ─── M16 019-MEMBERSHIP: one table, not two ───────────────────────────────────────────────
+    -- 019 first added a channel_settings table duplicating four of these columns, and wired NO
+    -- writer to it — so every membership read came back empty and every join was refused on a
+    -- channel the daemon genuinely administered. Two tables for one fact, with the live path
+    -- reading the empty one. Collapsed here while the database is still empty, which makes it a
+    -- schema edit rather than a migration.
+    --
+    -- Whether members can see each other. A publisher's decision about its own channel.
+    members_visible    INTEGER NOT NULL DEFAULT 0,
+    -- 0 means NO KEY HAS EVER BEEN ISSUED. The first join mints generation 1; each ejection
+    -- advances it, and that number is what every body and every fetch key is bound to.
+    key_generation     INTEGER NOT NULL DEFAULT 0,
+    -- The AGENT that admits members and answers join requests. Distinct from the channel key: the
+    -- channel signs posts and never converses, the admin holds the sessions. Empty until set.
+    admin_pubkey       TEXT    NOT NULL DEFAULT '',
     updated_at         INTEGER NOT NULL
   );
 `;
@@ -22,7 +37,8 @@ export class ChannelConfigStore {
     }
     get(channelHex) {
         const row = this.#db
-            .prepare(`SELECT access, relays, guidance, retention_seconds FROM channel_config WHERE channel_pubkey = ?`)
+            .prepare(`SELECT access, relays, guidance, retention_seconds, members_visible, admin_pubkey
+           FROM channel_config WHERE channel_pubkey = ?`)
             .get(channelHex.toLowerCase());
         if (!row)
             return null;
@@ -43,16 +59,23 @@ export class ChannelConfigStore {
             relays,
             guidance: row.guidance,
             retention_seconds: Number(row.retention_seconds),
+            members_visible: Number(row.members_visible) === 1,
+            admin_pubkey: row.admin_pubkey,
         };
     }
     set(channelHex, config, now) {
         this.#db
-            .prepare(`INSERT INTO channel_config (channel_pubkey, access, relays, guidance, retention_seconds, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)
+            .prepare(
+        // ⚠️ `key_generation` is NOT in the update list, and must never be: it is advanced only by an
+        // ejection, and letting a settings edit touch it would silently re-key or un-re-key a channel.
+        `INSERT INTO channel_config
+           (channel_pubkey, access, relays, guidance, retention_seconds, members_visible, admin_pubkey, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT (channel_pubkey) DO UPDATE SET
            access = excluded.access, relays = excluded.relays, guidance = excluded.guidance,
-           retention_seconds = excluded.retention_seconds, updated_at = excluded.updated_at`)
-            .run(channelHex.toLowerCase(), config.access, JSON.stringify(config.relays), config.guidance, config.retention_seconds, now);
+           retention_seconds = excluded.retention_seconds, members_visible = excluded.members_visible,
+           admin_pubkey = excluded.admin_pubkey, updated_at = excluded.updated_at`)
+            .run(channelHex.toLowerCase(), config.access, JSON.stringify(config.relays), config.guidance, config.retention_seconds, config.members_visible === true ? 1 : 0, config.admin_pubkey ?? "", now);
         this.#logger.info("channel.config.set", {
             channel_pubkey: channelHex, access: config.access, relays: config.relays.length,
         });

package/dist/channel-config-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"channel-config-store.js","sourceRoot":"","sources":["../src/channel-config-store.ts"],"names":[],"mappings":"AAkBA,8DAA8D;AAC9D,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAE1D,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;kDAQS,MAAM,CAAC,yBAAyB,CAAC;;;CAGlF,CAAC;AASF,MAAM,OAAO,kBAAkB;IACpB,GAAG,CAAiB;IACpB,OAAO,CAAS;IAEzB,YAAY,EAAkB,EAAE,MAAc;QAC5C,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,UAAkB;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;aACjB,OAAO,CAAC,iGAAiG,CAAC;aAC1G,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAElB,CAAC;QACd,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QAEtB,IAAI,MAAM,GAAa,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAY,CAAC;YACjD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACP,8FAA8F;YAC9F,sCAAsC;YACtC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC,CAAC;YACpF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,MAAM,EAAE,GAAG,CAAC,MAAuB;YACnC,MAAM;YACN,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,iBAAiB,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC;SACjD,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,UAAkB,EAAE,MAAqB,EAAE,GAAW;QACxD,IAAI,CAAC,GAAG;aACL,OAAO,CACN;;;;4FAIoF,CACrF;aACA,GAAG,CACF,UAAU,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EACtE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,iBAAiB,EAAE,GAAG,CAC/C,CAAC;QACJ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE;YACtC,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;SAChF,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"channel-config-store.js","sourceRoot":"","sources":["../src/channel-config-store.ts"],"names":[],"mappings":"AAkBA,8DAA8D;AAC9D,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAE1D,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;kDAQS,MAAM,CAAC,yBAAyB,CAAC;;;;;;;;;;;;;;;;;;CAkBlF,CAAC;AAYF,MAAM,OAAO,kBAAkB;IACpB,GAAG,CAAiB;IACpB,OAAO,CAAS;IAEzB,YAAY,EAAkB,EAAE,MAAc;QAC5C,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,UAAkB;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;aACjB,OAAO,CACN;wDACgD,CACjD;aACA,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAKlB,CAAC;QACd,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QAEtB,IAAI,MAAM,GAAa,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAY,CAAC;YACjD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACP,8FAA8F;YAC9F,sCAAsC;YACtC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC,CAAC;YACpF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,MAAM,EAAE,GAAG,CAAC,MAAuB;YACnC,MAAM;YACN,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,iBAAiB,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC;YAChD,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,CAAC;YAClD,YAAY,EAAE,GAAG,CAAC,YAAY;SAC/B,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,UAAkB,EAAE,MAAqB,EAAE,GAAW;QACxD,IAAI,CAAC,GAAG;aACL,OAAO;QACN,8FAA8F;QAC9F,+FAA+F;QAC/F;;;;;;kFAM0E,CAC3E;aACA,GAAG,CACF,UAAU,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EACtE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,iBAAiB,EACzC,MAAM,CAAC,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,YAAY,IAAI,EAAE,EAAE,GAAG,CACxE,CAAC;QACJ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE;YACtC,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;SAChF,CAAC,CAAC;IACL,CAAC;CACF"}