@mulingai-npm/redis 3.40.51 → 3.40.55

package/dist/data/listener-presence.d.ts

@@ -0,0 +1,80 @@
+/**
+ * How long a listener counts as being in the room, and as being there RIGHT NOW.
+ *
+ * ─── WHY THIS LIVES IN THE REDIS PACKAGE ────────────────────────────────────
+ *
+ * Presence is decided from the listener hash in Redis and nowhere else, and
+ * every service that asks about it does so through MulingstreamListenerManager:
+ * the pipeline asking what to translate, the billing tick asking whether a pass
+ * is being spent, the listener service asking whether a language slot is free,
+ * the realtime service asking who has gone. Putting the thresholds beside the
+ * only code that reads them means there is exactly one definition. The obvious
+ * alternative, @mulingai-npm/shared, would have made this the first dependency
+ * between two private packages and changed the publish order for everyone, to
+ * hold two numbers that nothing outside this file interprets.
+ *
+ * ─── WHY THERE ARE TWO THRESHOLDS AND NOT ONE ───────────────────────────────
+ *
+ * There used to be one, at fifteen minutes, and it was answering five questions
+ * with completely different tolerances:
+ *
+ *   "translate and synthesise this language?"  wrong for seconds = money, per chunk
+ *   "does this listener hold a language slot?" wrong for seconds = somebody shut out
+ *   "is this pass being consumed?"             wrong for minutes = a pass spent on nobody
+ *   "how many listeners does the speaker see?" wants to be STEADY, not fast
+ *   "when did this session end?"               does not need answering in real time at all
+ *
+ * The last one is now answered from the last heartbeat at the moment the session
+ * is closed, so it needs no threshold at all. The rest split cleanly in two.
+ *
+ * **PRESENT** is the fast question. A phone that has been dark for two minutes is
+ * receiving nothing, so translating and synthesising for it costs real money for
+ * nobody, and holding its language slot denies that slot to a guest who is
+ * actually in the room. This has to lapse quickly.
+ *
+ * **IN THE ROOM** is the slow question. The speaker's listener count must not
+ * flicker every time a congregation locks its phones during a song, and one
+ * person's attendance must not be recorded as five short sessions, which is
+ * exactly what shortening the single threshold would have done to the analytics
+ * it was meant to fix.
+ *
+ * Separating them is what lets the second stay generous. Patience about departure
+ * now costs nothing, because nothing expensive waits on it any more.
+ */
+/**
+ * How long a heartbeat stays fresh: three missed beats at the client's 30 second
+ * interval, so one dropped beat on a bad connection never marks anybody away.
+ *
+ * A listener past this is AWAY. Still in the room, still shown to the speaker,
+ * still holding their session and their identity, but not translated for, not
+ * counted toward a pass, and not holding a language slot. They come back the
+ * instant a heartbeat arrives, having lost nothing.
+ */
+export declare const LISTENER_PRESENT_MS: number;
+/**
+ * How long a listener stays in the room with no heartbeat before being removed
+ * and their session closed.
+ *
+ * Fifteen minutes, unchanged, and now deliberately generous rather than generous
+ * by accident. A phone locked through announcements, a worship set or a long
+ * prayer must not cost somebody their place. That generosity used to be paid for
+ * in translation nobody heard and passes spent on people who had gone home; it is
+ * not any more. The only thing this number now controls is how long a returning
+ * listener keeps their identity.
+ */
+export declare const LISTENER_GONE_MS: number;
+/** What the client sends. Here so the thresholds above can be read against it. */
+export declare const LISTENER_HEARTBEAT_INTERVAL_MS: number;
+export type ListenerPresence = 'present' | 'away' | 'gone';
+/**
+ * Which of the three states a listener is in.
+ *
+ * `isAway` is the client having said so, and it is what makes a locked screen
+ * register at once instead of after three missed beats. It is a separate flag
+ * rather than a backdated heartbeat, because the heartbeat is now also the
+ * recorded end of the session and has to stay honest about when the listener was
+ * genuinely last there.
+ */
+export declare function listenerPresence(lastHeartbeatMs: number, isAway: boolean, now?: number): ListenerPresence;
+/** Shorthand for the common question: is this listener consuming anything right now. */
+export declare function isListenerPresent(lastHeartbeatMs: number, isAway: boolean, now?: number): boolean;

package/dist/data/listener-presence.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * How long a listener counts as being in the room, and as being there RIGHT NOW.
+ *
+ * ─── WHY THIS LIVES IN THE REDIS PACKAGE ────────────────────────────────────
+ *
+ * Presence is decided from the listener hash in Redis and nowhere else, and
+ * every service that asks about it does so through MulingstreamListenerManager:
+ * the pipeline asking what to translate, the billing tick asking whether a pass
+ * is being spent, the listener service asking whether a language slot is free,
+ * the realtime service asking who has gone. Putting the thresholds beside the
+ * only code that reads them means there is exactly one definition. The obvious
+ * alternative, @mulingai-npm/shared, would have made this the first dependency
+ * between two private packages and changed the publish order for everyone, to
+ * hold two numbers that nothing outside this file interprets.
+ *
+ * ─── WHY THERE ARE TWO THRESHOLDS AND NOT ONE ───────────────────────────────
+ *
+ * There used to be one, at fifteen minutes, and it was answering five questions
+ * with completely different tolerances:
+ *
+ *   "translate and synthesise this language?"  wrong for seconds = money, per chunk
+ *   "does this listener hold a language slot?" wrong for seconds = somebody shut out
+ *   "is this pass being consumed?"             wrong for minutes = a pass spent on nobody
+ *   "how many listeners does the speaker see?" wants to be STEADY, not fast
+ *   "when did this session end?"               does not need answering in real time at all
+ *
+ * The last one is now answered from the last heartbeat at the moment the session
+ * is closed, so it needs no threshold at all. The rest split cleanly in two.
+ *
+ * **PRESENT** is the fast question. A phone that has been dark for two minutes is
+ * receiving nothing, so translating and synthesising for it costs real money for
+ * nobody, and holding its language slot denies that slot to a guest who is
+ * actually in the room. This has to lapse quickly.
+ *
+ * **IN THE ROOM** is the slow question. The speaker's listener count must not
+ * flicker every time a congregation locks its phones during a song, and one
+ * person's attendance must not be recorded as five short sessions, which is
+ * exactly what shortening the single threshold would have done to the analytics
+ * it was meant to fix.
+ *
+ * Separating them is what lets the second stay generous. Patience about departure
+ * now costs nothing, because nothing expensive waits on it any more.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isListenerPresent = exports.listenerPresence = exports.LISTENER_HEARTBEAT_INTERVAL_MS = exports.LISTENER_GONE_MS = exports.LISTENER_PRESENT_MS = void 0;
+/**
+ * How long a heartbeat stays fresh: three missed beats at the client's 30 second
+ * interval, so one dropped beat on a bad connection never marks anybody away.
+ *
+ * A listener past this is AWAY. Still in the room, still shown to the speaker,
+ * still holding their session and their identity, but not translated for, not
+ * counted toward a pass, and not holding a language slot. They come back the
+ * instant a heartbeat arrives, having lost nothing.
+ */
+exports.LISTENER_PRESENT_MS = 90 * 1000;
+/**
+ * How long a listener stays in the room with no heartbeat before being removed
+ * and their session closed.
+ *
+ * Fifteen minutes, unchanged, and now deliberately generous rather than generous
+ * by accident. A phone locked through announcements, a worship set or a long
+ * prayer must not cost somebody their place. That generosity used to be paid for
+ * in translation nobody heard and passes spent on people who had gone home; it is
+ * not any more. The only thing this number now controls is how long a returning
+ * listener keeps their identity.
+ */
+exports.LISTENER_GONE_MS = 15 * 60 * 1000;
+/** What the client sends. Here so the thresholds above can be read against it. */
+exports.LISTENER_HEARTBEAT_INTERVAL_MS = 30 * 1000;
+/**
+ * Which of the three states a listener is in.
+ *
+ * `isAway` is the client having said so, and it is what makes a locked screen
+ * register at once instead of after three missed beats. It is a separate flag
+ * rather than a backdated heartbeat, because the heartbeat is now also the
+ * recorded end of the session and has to stay honest about when the listener was
+ * genuinely last there.
+ */
+function listenerPresence(lastHeartbeatMs, isAway, now = Date.now()) {
+    const age = now - lastHeartbeatMs;
+    if (age > exports.LISTENER_GONE_MS)
+        return 'gone';
+    if (isAway || age > exports.LISTENER_PRESENT_MS)
+        return 'away';
+    return 'present';
+}
+exports.listenerPresence = listenerPresence;
+/** Shorthand for the common question: is this listener consuming anything right now. */
+function isListenerPresent(lastHeartbeatMs, isAway, now = Date.now()) {
+    return listenerPresence(lastHeartbeatMs, isAway, now) === 'present';
+}
+exports.isListenerPresent = isListenerPresent;

package/dist/managers/mulingstream-listener-manager.d.ts

@@ -1,4 +1,7 @@
 import { RedisClient } from '../redis-client';
+import { ListenerPresence } from '../data/listener-presence';
+export { LISTENER_PRESENT_MS, LISTENER_GONE_MS, LISTENER_HEARTBEAT_INTERVAL_MS, listenerPresence } from '../data/listener-presence';
+export type { ListenerPresence } from '../data/listener-presence';
 export type ListenerBreakpoint = 'mobile' | 'desktop' | 'display';
 export type MulingstreamListenerData = {
     listenerId: string;
@@ -12,12 +15,54 @@ export type MulingstreamListenerData = {
     color?: string;
     isListening?: boolean;
     breakpoint?: ListenerBreakpoint;
+    /**
+     * The listener told us their page went into the background: screen locked,
+     * app switched, tab hidden.
+     *
+     * Set by the client rather than inferred, because the socket cannot tell the
+     * difference between a locked phone and a closed tab, and waiting for missed
+     * heartbeats to decide costs ninety seconds of translating for somebody who
+     * is demonstrably not looking. Cleared by the next heartbeat, which is what a
+     * returning page sends immediately.
+     *
+     * Being away is not being gone. See data/listener-presence.ts.
+     */
+    isAway?: boolean;
 };
 export declare class MulingstreamListenerManager {
     private redisClient;
     constructor(redisClient: RedisClient);
     private parseHashData;
     addListener(listenerData: MulingstreamListenerData): Promise<string>;
+    /**
+     * Every listener currently known, across every room.
+     *
+     * WHY THIS USES SCAN AND NOT KEYS
+     *
+     * It used to be `KEYS 'listener:*'`, with a TODO next to it saying it should
+     * not be. KEYS walks the entire keyspace in one go and Redis is single
+     * threaded, so for as long as it runs nothing else in the process is served:
+     * not a heartbeat, not a chunk being handed to the pipeline, not a listener
+     * joining. The cost is invisible on a development database with a few dozen
+     * keys and grows with the busiest moment we will ever have, which is precisely
+     * when it must not stall. This is called by the cleanup sweep every sixty
+     * seconds, for the entire life of the process, so it would have been the most
+     * frequently executed blocking command in the system.
+     *
+     * SCAN answers the same question in cursored batches, yielding between each,
+     * so a large keyspace costs more round trips rather than one long stall. The
+     * guarantees are weaker, deliberately: a key added or removed mid-scan may or
+     * may not appear. That is exactly right for the caller, which is looking for
+     * listeners who went silent minutes ago. One arriving during the scan is one
+     * for the next sweep, sixty seconds later, and there is nothing to do about a
+     * brand new listener anyway.
+     *
+     * The pattern also has to reject keys that merely start with `listener:`. The
+     * legacy `listener:panel-state:*` keys matched the old pattern and were parsed
+     * as listener records, producing entries with NaN timestamps. They never
+     * caused harm, since NaN fails every comparison, which is exactly how a
+     * defect like that survives.
+     */
     getAllListeners(): Promise<MulingstreamListenerData[]>;
     getListenersByRoom(roomId: string): Promise<MulingstreamListenerData[]>;
     getListener(listenerIdOrToken: string): Promise<MulingstreamListenerData | null>;
@@ -30,7 +75,54 @@ export declare class MulingstreamListenerManager {
      */
     updateBreakpoint(listenerIdOrToken: string, breakpoint: ListenerBreakpoint): Promise<MulingstreamListenerData | null>;
     getTargetSocketIdsByRoomLanguage(roomId: string, language: string): Promise<string[]>;
+    /**
+     * Which languages this room has someone PRESENT on.
+     *
+     * Feeds consumersFor, which decides what gets translated at all, so an
+     * over-generous answer here is money spent on every chunk for nobody. It
+     * therefore counts present listeners only: somebody whose phone has been dark
+     * for two minutes is receiving nothing, and translating for them is pure loss.
+     *
+     * It used to count every listener the room had ever registered, including ones
+     * whose heartbeat had been silent for fourteen minutes, because the only thing
+     * that removed a listener was the cleanup sweep. See data/listener-presence.ts
+     * for why that single threshold could not be lowered and had to be split.
+     */
     getUniqueLanguagesByRoom(roomId: string): Promise<string[]>;
+    /**
+     * How many PRESENT listeners in this room are on a language.
+     *
+     * Decides whether a guest-added language slot can be handed back, and counts
+     * the same population `consumersFor` reads, so the two cannot disagree about
+     * whether a language has an audience: a slot is released exactly when the
+     * translation for it stops, never one without the other.
+     *
+     * Present rather than merely registered, and that is the deliberate part. A
+     * listener whose phone has been dark for two minutes is not hearing the
+     * language, so holding the room's last slot for them denies it to a guest
+     * standing in the room who is. If they come back and the slot has gone to
+     * somebody else, they choose again from what the room now has; if it is still
+     * free they simply take it back.
+     */
+    countListenersOnLanguage(roomId: string, language: string): Promise<number>;
+    /**
+     * The client saying its page went into the background, or came back.
+     *
+     * This is the difference between reacting to a locked screen at once and
+     * reacting to it after three missed heartbeats. Both end in the same state;
+     * one of them costs ninety seconds of translation and synthesis for a phone
+     * nobody is looking at, on every language in the room.
+     *
+     * Does NOT touch lastHeartbeat. That field is now also the recorded end of the
+     * listener's session, so it has to keep meaning "when they were genuinely last
+     * there" and nothing else.
+     */
+    setAwayState(listenerIdOrToken: string, isAway: boolean): Promise<MulingstreamListenerData | null>;
+    /**
+     * Present, away or gone, for one listener. For anything that needs to SHOW the
+     * distinction rather than act on it.
+     */
+    getPresence(listenerIdOrToken: string): Promise<ListenerPresence | null>;
     updateHeartbeat(listenerIdOrToken: string): Promise<MulingstreamListenerData | null>;
     getListenerStats(roomId: string): Promise<{
         totalListeners: number;
@@ -41,14 +133,35 @@ export declare class MulingstreamListenerManager {
      *
      * Church passes turn on this number rather than on how many people joined. A
      * pass is spent only when translation reached a human being, so somebody
-     * sitting on the join screen, or with the tab open and audio stopped, must
-     * not burn a church's pass.
-     *
-     * `isListening` is already maintained by setListeningState, so this is the
-     * honest count rather than a proxy for it. Falls back to counting a listener
-     * whose flag has never been written, because the flag arrived after some
-     * clients shipped and an older client that is genuinely playing audio should
-     * still count.
+     * sitting on the join screen must not burn a church's pass.
+     *
+     * ─── RECEIVING MEANS AUDIO **OR** TEXT ──────────────────────────────────
+     *
+     * Corrected 2026-08-19. This used to require `isListening`, the audio
+     * playback flag, so a guest who joined, chose their language and sat reading
+     * the translated text counted for nothing: the pass clock stayed at zero
+     * until they pressed Listening. David found it on a phone, and the counting
+     * spec had said otherwise all along, in as many words: "the listener session
+     * is open AND we are delivering translated output to it, audio or text".
+     *
+     * The reading is the product. A deaf guest, a guest in a quiet room, a guest
+     * with no headphones and a guest who simply prefers to read are all being
+     * served, all costing us translation on every chunk, and none of them are
+     * pressing an audio button. Charging only for audio would have meant a
+     * church whose congregation reads never spends a pass, which sounds generous
+     * until you notice we are paying for every word of it.
+     *
+     * So the test is PRESENCE, and nothing else. Presence already means joined,
+     * in a language, and with a heartbeat inside the last ninety seconds, which
+     * is exactly the population `consumersFor` is translating for. Whether they
+     * also chose to hear it is not our business, and the spec is explicit that we
+     * do not police attention: a phone in a pocket with audio playing is
+     * listening, and a phone in a hand with text on it is reading.
+     *
+     * `isListening` keeps its real job, which is a different question: whether to
+     * SYNTHESISE SPEECH. See getLanguagesWithActiveListeners. Speech is the most
+     * expensive thing we produce and nobody should pay to generate audio no one
+     * is playing. Text is already produced for the room either way.
      */
     getReceivingCount(roomId: string): Promise<number>;
     private capKey;

package/dist/managers/mulingstream-listener-manager.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MulingstreamListenerManager = void 0;
+exports.MulingstreamListenerManager = exports.listenerPresence = exports.LISTENER_HEARTBEAT_INTERVAL_MS = exports.LISTENER_GONE_MS = exports.LISTENER_PRESENT_MS = void 0;
+const listener_presence_1 = require("../data/listener-presence");
+var listener_presence_2 = require("../data/listener-presence");
+Object.defineProperty(exports, "LISTENER_PRESENT_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_PRESENT_MS; } });
+Object.defineProperty(exports, "LISTENER_GONE_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_GONE_MS; } });
+Object.defineProperty(exports, "LISTENER_HEARTBEAT_INTERVAL_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_HEARTBEAT_INTERVAL_MS; } });
+Object.defineProperty(exports, "listenerPresence", { enumerable: true, get: function () { return listener_presence_2.listenerPresence; } });
 const EXPIRATION = 24 * 60 * 60; // 24 hours in seconds
 /**
  * Generates a bright RGB color suitable for dark backgrounds.
@@ -48,7 +54,8 @@ class MulingstreamListenerManager {
             language: data.language || '',
             color: data.color || '',
             isListening: data.isListening === 'true',
-            breakpoint: bp === 'mobile' || bp === 'desktop' || bp === 'display' ? bp : undefined
+            breakpoint: bp === 'mobile' || bp === 'desktop' || bp === 'display' ? bp : undefined,
+            isAway: data.isAway === 'true'
         };
     }
     // Creates a new listener.
@@ -74,25 +81,60 @@ class MulingstreamListenerManager {
             language: (_c = listenerData.language) !== null && _c !== void 0 ? _c : '',
             color,
             isListening: 'false',
-            breakpoint: (_d = listenerData.breakpoint) !== null && _d !== void 0 ? _d : ''
+            breakpoint: (_d = listenerData.breakpoint) !== null && _d !== void 0 ? _d : '',
+            // A listener who just joined is looking at the page by definition.
+            isAway: 'false'
         });
         // expire listener
         await this.redisClient.expire(`listener:${listenerId}`, EXPIRATION);
         return listenerId;
     }
+    /**
+     * Every listener currently known, across every room.
+     *
+     * WHY THIS USES SCAN AND NOT KEYS
+     *
+     * It used to be `KEYS 'listener:*'`, with a TODO next to it saying it should
+     * not be. KEYS walks the entire keyspace in one go and Redis is single
+     * threaded, so for as long as it runs nothing else in the process is served:
+     * not a heartbeat, not a chunk being handed to the pipeline, not a listener
+     * joining. The cost is invisible on a development database with a few dozen
+     * keys and grows with the busiest moment we will ever have, which is precisely
+     * when it must not stall. This is called by the cleanup sweep every sixty
+     * seconds, for the entire life of the process, so it would have been the most
+     * frequently executed blocking command in the system.
+     *
+     * SCAN answers the same question in cursored batches, yielding between each,
+     * so a large keyspace costs more round trips rather than one long stall. The
+     * guarantees are weaker, deliberately: a key added or removed mid-scan may or
+     * may not appear. That is exactly right for the caller, which is looking for
+     * listeners who went silent minutes ago. One arriving during the scan is one
+     * for the next sweep, sixty seconds later, and there is nothing to do about a
+     * brand new listener anyway.
+     *
+     * The pattern also has to reject keys that merely start with `listener:`. The
+     * legacy `listener:panel-state:*` keys matched the old pattern and were parsed
+     * as listener records, producing entries with NaN timestamps. They never
+     * caused harm, since NaN fails every comparison, which is exactly how a
+     * defect like that survives.
+     */
     async getAllListeners() {
-        // get all keys that match 'listener:*'
-        // TODO: if we have many keys, consider using SCAN instead of KEYS to avoid performance issues.
-        const keys = await this.redisClient.keys('listener:*');
-        if (!keys || keys.length === 0) {
-            return [];
-        }
-        // fetch each hash with HGETALL
         const listeners = [];
-        for (const key of keys) {
-            const data = await this.redisClient.hgetall(key);
-            listeners.push(this.parseHashData(data));
-        }
+        let cursor = 0;
+        do {
+            const [nextCursor, keys] = await this.redisClient.scan(cursor, 'listener:*', 500);
+            cursor = Number(nextCursor);
+            for (const key of keys || []) {
+                // `listener:{id}` only. Anything with a further colon belongs to
+                // some other feature that happens to share the prefix.
+                if (key.split(':').length !== 2)
+                    continue;
+                const data = await this.redisClient.hgetall(key);
+                if (!data || Object.keys(data).length === 0)
+                    continue;
+                listeners.push(this.parseHashData(data));
+            }
+        } while (cursor !== 0);
         return listeners;
     }
     async getListenersByRoom(roomId) {
@@ -189,13 +231,23 @@ class MulingstreamListenerManager {
         });
         return filteredListeners.map((listener) => listener.socketId);
     }
+    /**
+     * Which languages this room has someone PRESENT on.
+     *
+     * Feeds consumersFor, which decides what gets translated at all, so an
+     * over-generous answer here is money spent on every chunk for nobody. It
+     * therefore counts present listeners only: somebody whose phone has been dark
+     * for two minutes is receiving nothing, and translating for them is pure loss.
+     *
+     * It used to count every listener the room had ever registered, including ones
+     * whose heartbeat had been silent for fourteen minutes, because the only thing
+     * that removed a listener was the cleanup sweep. See data/listener-presence.ts
+     * for why that single threshold could not be lowered and had to be split.
+     */
     async getUniqueLanguagesByRoom(roomId) {
-        // 1) Fetch all listeners for the room.
-        //    (This includes inactive ones, but feel free to filter out isActive === false if you only want active ones.)
-        const listeners = await this.getListenersByRoom(roomId);
-        // if I wanted to get only active listeners
-        // const listeners = (await this.getListenersByRoom(roomId)).filter(l => l.isActive);
-        // 2) Count how many times each language appears.
+        const now = Date.now();
+        const listeners = (await this.getListenersByRoom(roomId)).filter((listener) => (0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now));
+        // Count how many times each language appears.
         const languageCountMap = {};
         for (const listener of listeners) {
             // skip blank/unset language
@@ -211,6 +263,57 @@ class MulingstreamListenerManager {
         // 4) Map back to just the language strings in order
         return sortedEntries.map(([language]) => language);
     }
+    /**
+     * How many PRESENT listeners in this room are on a language.
+     *
+     * Decides whether a guest-added language slot can be handed back, and counts
+     * the same population `consumersFor` reads, so the two cannot disagree about
+     * whether a language has an audience: a slot is released exactly when the
+     * translation for it stops, never one without the other.
+     *
+     * Present rather than merely registered, and that is the deliberate part. A
+     * listener whose phone has been dark for two minutes is not hearing the
+     * language, so holding the room's last slot for them denies it to a guest
+     * standing in the room who is. If they come back and the slot has gone to
+     * somebody else, they choose again from what the room now has; if it is still
+     * free they simply take it back.
+     */
+    async countListenersOnLanguage(roomId, language) {
+        if (!roomId || !language)
+            return 0;
+        const now = Date.now();
+        const listeners = await this.getListenersByRoom(roomId);
+        return listeners.filter((listener) => listener.language === language && (0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now)).length;
+    }
+    /**
+     * The client saying its page went into the background, or came back.
+     *
+     * This is the difference between reacting to a locked screen at once and
+     * reacting to it after three missed heartbeats. Both end in the same state;
+     * one of them costs ninety seconds of translation and synthesis for a phone
+     * nobody is looking at, on every language in the room.
+     *
+     * Does NOT touch lastHeartbeat. That field is now also the recorded end of the
+     * listener's session, so it has to keep meaning "when they were genuinely last
+     * there" and nothing else.
+     */
+    async setAwayState(listenerIdOrToken, isAway) {
+        const listener = await this.getListener(listenerIdOrToken);
+        if (!listener)
+            return null;
+        await this.redisClient.hset(`listener:${listener.listenerId}`, { isAway: isAway.toString() });
+        return { ...listener, isAway };
+    }
+    /**
+     * Present, away or gone, for one listener. For anything that needs to SHOW the
+     * distinction rather than act on it.
+     */
+    async getPresence(listenerIdOrToken) {
+        const listener = await this.getListener(listenerIdOrToken);
+        if (!listener)
+            return null;
+        return (0, listener_presence_1.listenerPresence)(listener.lastHeartbeat, listener.isAway === true);
+    }
     async updateHeartbeat(listenerIdOrToken) {
         const listener = await this.getListener(listenerIdOrToken);
         if (!listener) {
@@ -218,9 +321,16 @@ class MulingstreamListenerManager {
             return null;
         }
         const now = Date.now();
-        // Update the heartbeat timestamp
+        // Update the heartbeat timestamp, and clear away in the same write.
+        //
+        // A heartbeat only arrives from a page that is running, so receiving one is
+        // proof the listener is back: an explicit "I have returned" event would be
+        // a second way of saying the same thing, and a second way to get it wrong.
+        // A returning page sends a heartbeat immediately on visibility, so this is
+        // as fast as anything else could be.
         await this.redisClient.hset(`listener:${listener.listenerId}`, {
-            lastHeartbeat: now.toString()
+            lastHeartbeat: now.toString(),
+            isAway: 'false'
         });
         // Reset expiration on activity
         await this.redisClient.expire(`listener:${listener.listenerId}`, EXPIRATION);
@@ -244,18 +354,40 @@ class MulingstreamListenerManager {
      *
      * Church passes turn on this number rather than on how many people joined. A
      * pass is spent only when translation reached a human being, so somebody
-     * sitting on the join screen, or with the tab open and audio stopped, must
-     * not burn a church's pass.
+     * sitting on the join screen must not burn a church's pass.
+     *
+     * ─── RECEIVING MEANS AUDIO **OR** TEXT ──────────────────────────────────
+     *
+     * Corrected 2026-08-19. This used to require `isListening`, the audio
+     * playback flag, so a guest who joined, chose their language and sat reading
+     * the translated text counted for nothing: the pass clock stayed at zero
+     * until they pressed Listening. David found it on a phone, and the counting
+     * spec had said otherwise all along, in as many words: "the listener session
+     * is open AND we are delivering translated output to it, audio or text".
      *
-     * `isListening` is already maintained by setListeningState, so this is the
-     * honest count rather than a proxy for it. Falls back to counting a listener
-     * whose flag has never been written, because the flag arrived after some
-     * clients shipped and an older client that is genuinely playing audio should
-     * still count.
+     * The reading is the product. A deaf guest, a guest in a quiet room, a guest
+     * with no headphones and a guest who simply prefers to read are all being
+     * served, all costing us translation on every chunk, and none of them are
+     * pressing an audio button. Charging only for audio would have meant a
+     * church whose congregation reads never spends a pass, which sounds generous
+     * until you notice we are paying for every word of it.
+     *
+     * So the test is PRESENCE, and nothing else. Presence already means joined,
+     * in a language, and with a heartbeat inside the last ninety seconds, which
+     * is exactly the population `consumersFor` is translating for. Whether they
+     * also chose to hear it is not our business, and the spec is explicit that we
+     * do not police attention: a phone in a pocket with audio playing is
+     * listening, and a phone in a hand with text on it is reading.
+     *
+     * `isListening` keeps its real job, which is a different question: whether to
+     * SYNTHESISE SPEECH. See getLanguagesWithActiveListeners. Speech is the most
+     * expensive thing we produce and nobody should pay to generate audio no one
+     * is playing. Text is already produced for the room either way.
      */
     async getReceivingCount(roomId) {
+        const now = Date.now();
         const listeners = await this.getListenersByRoom(roomId);
-        return listeners.filter((l) => l.isListening !== false).length;
+        return listeners.filter((l) => (0, listener_presence_1.isListenerPresent)(l.lastHeartbeat, l.isAway === true, now)).length;
     }
     // ─── Per-room listener capacity (design B, 2026-07-09) ────────────────────
     // The cap value is the room owner's plan `max_audience`, resolved ONCE by the
@@ -424,6 +556,7 @@ class MulingstreamListenerManager {
      * Used by pipeline to determine which languages need TTS generation.
      */
     async getLanguagesWithActiveListeners(roomId) {
+        const now = Date.now();
         const listeners = await this.getListenersByRoom(roomId);
         const languageCountMap = {};
         for (const listener of listeners) {
@@ -431,6 +564,10 @@ class MulingstreamListenerManager {
                 continue;
             if (!listener.isListening)
                 continue;
+            // Speech synthesis is the most expensive thing we do. A language whose
+            // only listener has a dark phone must not be synthesised.
+            if (!(0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now))
+                continue;
             const lang = listener.language;
             languageCountMap[lang] = (languageCountMap[lang] || 0) + 1;
         }

package/package.json

@@ -1,34 +1,34 @@
-{
-    "name": "@mulingai-npm/redis",
-    "version": "3.40.51",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/mulingai/mulingai-backend.git"
-    },
-    "publishConfig": {
-        "registry": "https://registry.npmjs.org/"
-    },
-    "private": false,
-    "scripts": {
-        "dev": "rm -f tsconfig.tsbuildinfo && tsc --watch",
-        "build": "rm -f tsconfig.tsbuildinfo && tsc",
-        "prepublishOnly": "npm run build"
-    },
-    "dependencies": {
-        "ioredis": "^5.6.0",
-        "uuid": "^11.1.0"
-    },
-    "devDependencies": {
-        "concurrently": "^9.1.2",
-        "copyfiles": "^2.4.1",
-        "nodemon": "^3.1.9",
-        "typescript": "^4.9.5"
-    },
-    "files": [
-        "dist",
-        "package.json",
-        "README.md"
-    ]
-}
+{
+    "name": "@mulingai-npm/redis",
+    "version": "3.40.55",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mulingai/mulingai-backend.git"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/"
+    },
+    "private": false,
+    "scripts": {
+        "dev": "rm -f tsconfig.tsbuildinfo && tsc --watch",
+        "build": "rm -f tsconfig.tsbuildinfo && tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "dependencies": {
+        "ioredis": "^5.6.0",
+        "uuid": "^11.1.0"
+    },
+    "devDependencies": {
+        "concurrently": "^9.1.2",
+        "copyfiles": "^2.4.1",
+        "nodemon": "^3.1.9",
+        "typescript": "^4.9.5"
+    },
+    "files": [
+        "dist",
+        "package.json",
+        "README.md"
+    ]
+}