@unoverse-platform/studio 0.1.100 → 0.1.102

package/vendor/base/src/manifests/executor/toolBridge.ts

@@ -95,20 +95,6 @@ export async function toolBridgeFor(executionContext: any): Promise<ToolBridge |
    */
   const handoffTools = new Set<string>();
 
-  /**
-   * THE GUEST'S OWN WORDS, from the search that is about to unlock a page.
-   *
-   * A page's `query:` places ask half a sentence each (§9e rule 4) — the half true of every
-   * guest — and the platform joins the half that is different for each. This is where that
-   * half is picked up: the model wrote the guest's ask into its search args a moment ago, so
-   * nothing has to be re-derived or, worse, re-invented.
-   *
-   * Captured on the CALL and read on the ABSORB, because `absorb` receives only the result.
-   * Whoever knows the situation supplies it (§9d) — the shell-open passes it on rather than
-   * the server guessing what the conversation was about.
-   */
-  let lastAsk = "";
-
   const stringify = (r: unknown): string => (typeof r === "string" ? r : JSON.stringify(r));
 
   /**
@@ -198,11 +184,6 @@ export async function toolBridgeFor(executionContext: any): Promise<ToolBridge |
     async call(name, args) {
       const app = appInvokers.get(name);
       if (app) return stringify(await app(args));
-      if (harness.DISCOVERY_TOOL_NAMES.includes(name)) {
-        const a = (args ?? {}) as Record<string, unknown>;
-        const q = typeof a.query === "string" ? a.query : Array.isArray(a.queries) ? String(a.queries[0] ?? "") : "";
-        if (q.trim()) lastAsk = q.trim();
-      }
       // THE ARGUMENTS GO OUT AS THE MODEL WROTE THEM. A wire-level rewrite used to strip
       // queries the conversation had already searched; it was removed 2026-08-16 because it
       // silently competed with the tool descriptions for the same decision, and the
@@ -248,18 +229,11 @@ export async function toolBridgeFor(executionContext: any): Promise<ToolBridge |
            * 2026-09-06). This used to open the shell at MINT — every app a search unlocked
            * was rendered before the model had read the results (observed 2026-09-07: two
            * surfaces opened at once, neither asked for). Tasks are asked: the unlock mints the
-           * tool and nothing more. What the shell-open used to carry — the unlocking search's
-           * ranked rows for drafting, the guest's ask for the page's own searches, the run's
-           * ids for tracing — rides the model's CALL instead, beneath its own arguments.
+           * tool and nothing more. What the shell-open used to carry, the unlocking search's
+           * ranked rows for drafting, rides the model's CALL instead, beneath its own arguments.
            */
           const draftRefs = harness.rankedRowIds(resultContent);
-          const ride = {
-            __draftRefs: draftRefs,
-            ...(lastAsk ? { __ask: lastAsk } : {}),
-            ...(executionContext?.workflowId ? { __workflowId: executionContext.workflowId } : {}),
-            ...(executionContext?.executionId ? { __executionId: executionContext.executionId } : {}),
-            ...(executionContext?.nodeId ? { __nodeId: executionContext.nodeId } : {}),
-          };
+          const ride = { __draftRefs: draftRefs };
           appInvokers.set(def.name, (input: unknown) => invoke({ ...ride, ...((input ?? {}) as Record<string, unknown>) }));
           minted.push({ name: def.name, description: def.description, parameters: def.parameters, ...(def.outputSchema ? { outputSchema: def.outputSchema } : {}) });
         },

package/vendor/base/src/manifests/runtime/duplex/audioLane.ts

@@ -24,11 +24,33 @@
  * error: a voice node with nowhere to send audio still holds a valid conversation, and the
  * transcripts still reach the workflow.
  */
+/** What a session hands the lane when it claims a conversation. */
+export interface LaneSession {
+  /** A microphone frame for this conversation. */
+  audio(data: ArrayBuffer): void | Promise<void>;
+  /** A control message for this conversation (`stop` when the person hangs up). */
+  control(message: any): void | Promise<void>;
+  /** Another session has claimed this conversation: close. */
+  replaced(): void;
+}
+
 export interface AudioLane {
   sendAudio(conversationId: string, bytes: Buffer): void;
   sendControl(conversationId: string, message: unknown): void;
-  setAudioDataHandler?(fn: (sessionId: string, data: ArrayBuffer) => void | Promise<void>): void;
-  setControlMessageHandler?(fn: (sessionId: string, message: any) => void | Promise<void>): void;
+  /**
+   * ONE LIVE SESSION PER CONVERSATION (docs/VOICE_STREAMING_GUIDE.md, "One Live Session Per
+   * Conversation"). A session claims its conversation when its vendor socket opens, and from then
+   * on that conversation's microphone frames and control messages reach it and nothing else.
+   *
+   * A second claim on the same conversation REPLACES the first: the lane calls the old session's
+   * `replaced`, and it closes. Two sessions never hold one conversation, so a page swapping from
+   * one task's voice to another's never bills for both, and two visitors calling at once never
+   * take each other's microphone.
+   *
+   * Returns the release, called when the session ends. It lets go of this claim only, so a
+   * replaced session finishing late cannot remove the one that replaced it.
+   */
+  claim?(conversationId: string, session: LaneSession): () => void;
   startAudioSession?(sessionId: string, conversationId: string): void;
 
   /**
@@ -49,18 +71,19 @@ export interface AudioLane {
   /**
    * IS ANYONE THERE YET? Resolves true once the far end is listening, false if it never will be.
    *
-   * ABSENT MEANS ALREADY CONNECTED, which is the browser: the page dialled us, so its socket
-   * exists before the node runs and there is nothing to wait for. A lane that has to REACH
-   * someone is the other case, and the difference matters more than it sounds. A telephone rings
-   * for twenty or thirty seconds, and without this the vendor session opens immediately, the
-   * model speaks its opening line to a ringing tone, and by the time a person says hello the
-   * greeting has already happened and been thrown away (observed live 2026-09-20).
+   * Every lane has to reach someone. A telephone rings for twenty or thirty seconds; a page that
+   * only started a workflow is asked to join (`JOIN_CALL`) and its audio socket follows. Without
+   * this the vendor session opens immediately and the model speaks its opening line to nobody
+   * (observed live 2026-09-20 on the phone). A page that dialled us first is already there, and
+   * the browser lane answers true at once.
+   *
+   * `false` is a call nobody came to: busy, declined, rung out, or a page that never joined. The
+   * session closes for one of those, or a realtime model sits billing against an empty line.
    *
-   * `false` is a call that was never answered: busy, declined, or rung out. The session must not
-   * open at all for one of those, or a realtime model sits billing by the minute against a
-   * telephone nobody picked up.
+   * `call` names who the call is for, so a lane can ask them to join. A lane that places its own
+   * call ignores it.
    */
-  whenConnected?(conversationId: string): Promise<boolean>;
+  whenConnected?(conversationId: string, call?: { userId?: string; workflowId?: string }): Promise<boolean>;
 
   /**
    * END THE CALL AT THE FAR END. Not closing our socket to the vendor: that stops the MODEL,

package/vendor/base/src/manifests/runtime/duplex/session.ts

@@ -59,6 +59,13 @@ import { makeAudioBuffer, resamplePcm16, mulawToPcm16, CLIENT_RATE, type AudioLa
 const HANG_UP_DRAIN_MS = 1500;
 
 const IDLE_TIMEOUT_MS = 30_000;
+/**
+ * NOBODY HAS SPOKEN FOR A MINUTE: the call ends (docs/VOICE_STREAMING_GUIDE.md, "Every Call
+ * Ends"). The idle timer above cannot catch this: the page's microphone streams frames the whole
+ * time, spoken into or not, so a call left open on a quiet page was billed until MAX. Only
+ * speech holds this one (`control.speech`), and so does work in progress away from the call.
+ */
+const SILENCE_TIMEOUT_MS = 60_000;
 const MAX_SESSION_MS = 30 * 60_000;
 
 import { offerDiscovered, parseMaybeJson, recordToolTrace, type ToolBridge } from "../tools/toolloop.js";
@@ -73,7 +80,9 @@ async function message(spec: unknown, ctx: RunContext, extra: Record<string, unk
 
 export interface DuplexResult {
   /** Why the session ended, for the caller to record. */
-  reason: "closed" | "ended" | "error" | "idle" | "maxDuration" | "notConnected";
+  /** `replaced`: another session claimed this conversation (AudioLane.claim). `silence`: nobody
+   *  spoke for SILENCE_TIMEOUT_MS. `stopped`: the run was stopped (a page that left). */
+  reason: "closed" | "ended" | "error" | "idle" | "maxDuration" | "notConnected" | "replaced" | "silence" | "stopped";
   error?: string;
 }
 
@@ -156,13 +165,14 @@ export async function runDuplexSession(opts: {
    * generated early and flushes it the instant the call connects (twilioAudio.ts). So the only
    * thing that still waits for the answer is the sound itself.
    *
-   * The browser lane declares no `whenConnected` at all, because the page dialled US and its
-   * socket is already there. Nothing below changes for it.
+   * The browser lane is the same: a page that only started a workflow is asked to join, and the
+   * lane holds the greeting until its audio socket arrives. A page that dialled us is already
+   * there and answers at once.
    */
   let answered: Promise<boolean> | null = null;
   if (lane?.whenConnected) {
     lane.startAudioSession?.(conversationId, conversationId);
-    answered = lane.whenConnected(conversationId);
+    answered = lane.whenConnected(conversationId, { userId: ctx.scope?.userId, workflowId: ctx.scope?.workflowId });
   }
 
   const ws = new WebSocket(url, { headers });
@@ -231,6 +241,32 @@ export async function runDuplexSession(opts: {
   /** Set while the session is open and takes `CONTINUE` inputs; cleared when it ends. */
   let unregisterLive: (() => void) | undefined;
 
+  /**
+   * THE PERSON'S TURN AND THE BACKEND'S WORK, said to the client once per change. A vendor with
+   * no start or end event of its own marks them with an event that repeats (GPT-Live's
+   * transcript deltas, one per word), and forwarding every repeat sent the client the same
+   * state dozens of times a second. A state that names a tool always goes, because the name is
+   * new information.
+   */
+  const lastState: { user?: string; tool?: string } = {};
+  const sendState = (group: "user" | "tool", state: string, metadata?: Record<string, unknown>) => {
+    // Work starting or finishing away from the call is the call being alive.
+    if (group === "tool") heard();
+    if (lastState[group] === state && !metadata) return;
+    lastState[group] = state;
+    lane?.sendControl(conversationId, { type: "AUDIO_STATE", state, ...(metadata ? { metadata } : {}) });
+  };
+
+  /**
+   * SOMEONE SPOKE: the events that mean it, the node's own list or the person's speech and the
+   * assistant's audio. Restarts the silence timer; set once the session is open.
+   */
+  const speechEvents: string[] = audio.control?.speech ?? [audio.control?.userSpeaking, outSpec?.match].filter(Boolean);
+  let heard: () => void = () => {};
+
+  /** This session's claim on its conversation's audio lane; let go when it ends. */
+  let release: (() => void) | undefined;
+
   const send = (payload: unknown) => {
     if (ws.readyState !== WebSocket.OPEN) return;
     ws.send(JSON.stringify(payload));
@@ -263,6 +299,12 @@ export async function runDuplexSession(opts: {
       void shutdown("maxDuration").then(() => finish({ reason: "maxDuration" }));
     }, MAX_SESSION_MS);
 
+    // THE RUN WAS STOPPED (a page that left, a reaped run): the call ends with it, closed the
+    // way a hang-up closes it. Without this a stopped run left the vendor billing until silence.
+    const stop = () => void shutdown("stopped").then(() => finish({ reason: "stopped" }));
+    if (ctx.abort?.aborted) stop();
+    else ctx.abort?.addEventListener("abort", stop, { once: true });
+
     /**
      * Restarted by every inbound vendor frame AND by every outbound mic frame, so it only fires
      * when BOTH sides have gone quiet. The vendor is legitimately silent while the person speaks
@@ -278,6 +320,17 @@ export async function runDuplexSession(opts: {
       }, IDLE_TIMEOUT_MS);
     };
 
+    // SILENCE (SILENCE_TIMEOUT_MS). A tool or hand-off still running is not silence: the timer
+    // waits another round for it, so a slow answer is never cut off.
+    let silenceTimer: ReturnType<typeof setTimeout> | undefined;
+    heard = () => {
+      if (silenceTimer) clearTimeout(silenceTimer);
+      silenceTimer = setTimeout(() => {
+        if (lastState.tool === "TOOL_USE") return heard();
+        void shutdown("silence").then(() => finish({ reason: "silence" }));
+      }, SILENCE_TIMEOUT_MS);
+    };
+
     /**
      * THE ONE PLACE A SESSION ENDS, and now the one place a CALL ends with it.
      *
@@ -292,7 +345,18 @@ export async function runDuplexSession(opts: {
       if (settled) return;
       settled = true;
       unregisterLive?.();
+      release?.();
       if (idleTimer) clearTimeout(idleTimer);
+      if (silenceTimer) clearTimeout(silenceTimer);
+      // THE PAGE IS TOLD, so its microphone stops and its avatar goes idle. Not when replaced:
+      // the next session is already on the call, and the call goes on.
+      if (result.reason !== "replaced") {
+        try {
+          lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "SESSION_ENDED" });
+        } catch {
+          /* a lane already gone has nobody to tell */
+        }
+      }
       if (drainTimer) clearTimeout(drainTimer);
       clearTimeout(maxTimer);
       try {
@@ -342,6 +406,8 @@ export async function runDuplexSession(opts: {
 
     ws.on("open", async () => {
       touch();
+      // The silence clock starts with the call: a call nobody ever speaks on still ends.
+      heard();
       try {
         /**
          * THE TOOLS THE CALL OPENS WITH, discovered before the handshake goes out because the
@@ -400,6 +466,8 @@ export async function runDuplexSession(opts: {
           unregisterLive = registerLiveInput(key, async (handle, value) => {
             if (ws.readyState !== WebSocket.OPEN) return false;
             touch();
+            // The task moving on (a step handed back) is the call being worked.
+            heard();
             const scope = { input: { handle, value }, seen, said };
             let sent = 0;
             for (const rule of call.send ?? []) {
@@ -428,44 +496,54 @@ export async function runDuplexSession(opts: {
           // lane twice would place a second call.
           if (!lane.whenConnected) lane.startAudioSession?.(conversationId, conversationId);
 
-          lane.setAudioDataHandler?.(async (sessionId, data) => {
-            if (sessionId !== conversationId || ws.readyState !== WebSocket.OPEN) return;
-            touch();
-            const raw = Buffer.from(data);
-            const rate = inSpec.resampleTo ?? CLIENT_RATE;
-
-            // NOTHING TO DO: the vendor asked for this lane's own codec (see `passthrough`
-            // above), so these are the bytes to send. The rate travels as the LANE's, because
-            // that is what the samples actually are.
-            if (passthrough) {
+          // THE CONVERSATION IS THIS SESSION'S NOW (AudioLane.claim): its microphone and its
+          // control reach this session only, and a session that held it before is told to close.
+          release = lane.claim?.(conversationId, {
+            audio: async (data) => {
+              if (ws.readyState !== WebSocket.OPEN) return;
+              touch();
+              const raw = Buffer.from(data);
+              const rate = inSpec.resampleTo ?? CLIENT_RATE;
+
+              // NOTHING TO DO: the vendor asked for this lane's own codec (see `passthrough`
+              // above), so these are the bytes to send. The rate travels as the LANE's, because
+              // that is what the samples actually are.
+              if (passthrough) {
+                send(
+                  await message(inSpec.message, ctx, {
+                    audio: { base64: raw.toString("base64"), bytes: raw.length, rate: lane.rate ?? CLIENT_RATE },
+                  }),
+                );
+                return;
+              }
+              /**
+               * DECODE BEFORE RESAMPLING. A mu-law byte is one sample, not half of one, so
+               * interpolating the raw bytes would treat pairs of samples as single ones and
+               * produce half-speed noise. And mu-law is logarithmic, so even the arithmetic
+               * would be wrong: the midpoint of two bytes is not the midpoint of two sounds.
+               *
+               * The browser lane declares neither, so both lines are identity for it.
+               */
+              const decoded = lane.codec === "mulaw" ? mulawToPcm16(raw) : raw;
+              const pcm = resamplePcm16(decoded, lane.rate ?? CLIENT_RATE, rate);
               send(
                 await message(inSpec.message, ctx, {
-                  audio: { base64: raw.toString("base64"), bytes: raw.length, rate: lane.rate ?? CLIENT_RATE },
+                  audio: { base64: pcm.toString("base64"), bytes: pcm.length, rate },
                 }),
               );
-              return;
-            }
-            /**
-             * DECODE BEFORE RESAMPLING. A mu-law byte is one sample, not half of one, so
-             * interpolating the raw bytes would treat pairs of samples as single ones and
-             * produce half-speed noise. And mu-law is logarithmic, so even the arithmetic
-             * would be wrong: the midpoint of two bytes is not the midpoint of two sounds.
-             *
-             * The browser lane declares neither, so both lines are identity for it.
-             */
-            const decoded = lane.codec === "mulaw" ? mulawToPcm16(raw) : raw;
-            const pcm = resamplePcm16(decoded, lane.rate ?? CLIENT_RATE, rate);
-            send(
-              await message(inSpec.message, ctx, {
-                audio: { base64: pcm.toString("base64"), bytes: pcm.length, rate },
-              }),
-            );
-          });
-
-          lane.setControlMessageHandler?.(async (sessionId, msg) => {
-            if (sessionId !== conversationId) return;
-            const endOn: string[] = audio.control?.endOn ?? [];
-            if (endOn.includes(String(msg?.type))) finish({ reason: await shutdown("ended") ?? "ended" });
+            },
+            control: async (msg) => {
+              const endOn: string[] = audio.control?.endOn ?? [];
+              if (endOn.includes(String(msg?.type))) finish({ reason: await shutdown("ended") ?? "ended" });
+            },
+            // ANOTHER SESSION TOOK THIS CONVERSATION: the page moved to a task another voice works.
+            // Closed the way a hang-up closes it, through the `close` list. What it had not yet
+            // played is thrown away, not flushed: the person has moved on, and the next voice
+            // must not be talked over by the last one.
+            replaced: () => {
+              buffer?.discard();
+              void shutdown("replaced").then(() => finish({ reason: "replaced" }));
+            },
           });
         }
       } catch (err: any) {
@@ -484,6 +562,7 @@ export async function runDuplexSession(opts: {
         return; // a frame that is not JSON is not something a manifest can describe
       }
       const type = String(event?.type ?? "");
+      if (speechEvents.includes(type)) heard();
 
       // A REJECTED SESSION MUST SAY WHY. Every vendor this runtime speaks names its complaint in
       // an `error` event and then closes; without this line a refused handshake looks exactly like
@@ -592,17 +671,17 @@ export async function runDuplexSession(opts: {
         // Separate from `interruptOn` even when both name the same event: this tells the client the
         // person is talking, that one throws away the audio they talked over.
         if (audio.control?.userSpeaking && type === audio.control.userSpeaking) {
-          lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "USER_SPEECH_STARTED" });
+          sendState("user", "USER_SPEECH_STARTED");
         }
         if (audio.control?.userStopped && type === audio.control.userStopped) {
-          lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "USER_SPEECH_ENDED" });
+          sendState("user", "USER_SPEECH_ENDED");
         }
         // Work done off the call (a vendor's hand-off to a backend), for the call state's "thinking".
         if (audio.control?.toolUse && type === audio.control.toolUse) {
-          lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "TOOL_USE" });
+          sendState("tool", "TOOL_USE");
         }
         if (audio.control?.toolUseCompleted && type === audio.control.toolUseCompleted) {
-          lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "TOOL_USE_COMPLETED" });
+          sendState("tool", "TOOL_USE_COMPLETED");
         }
 
         /**
@@ -670,11 +749,7 @@ export async function runDuplexSession(opts: {
               let output: string;
               // A lookup takes 8-9s, and silence on a call reads as a dropped line. The client,
               // the lookup-indicator and the docs all had this wired already; nothing ever sent it.
-              lane?.sendControl(conversationId, {
-                type: "AUDIO_STATE",
-                state: "TOOL_USE",
-                metadata: { toolName: name },
-              });
+              sendState("tool", "TOOL_USE", { toolName: name });
               // Started BEFORE the call, so the timeline bar measures the wait the caller
               // actually sat through, not the bookkeeping after it.
               const toolStart = Date.now();
@@ -758,7 +833,7 @@ export async function runDuplexSession(opts: {
               recordToolTrace(node, ctx, name, parseMaybeJson(rawArgs), output, toolStart, toolOk, tools.kindOf?.(name) ?? "tool");
               // After the catch, so a tool that THREW still stops the dots. Spinning forever is
               // worse than no indicator: it promises something still coming.
-              lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "TOOL_USE_COMPLETED" });
+              sendState("tool", "TOOL_USE_COMPLETED");
               // PARSED for the connector lane only (readable mcpResult, same as the HTTP
               // loop); the model message two lines down keeps the raw `output` string —
               // the vendor wire requires text.

package/vendor/base/src/manifests/runtime/index.ts

@@ -52,7 +52,7 @@ export { performDoc, MUTATING_DOC_OPS, docKeyFor } from "./docstore/index.js";
 export { runDuplexSession } from "./duplex/session.js";
 // The audio lane is its own module: session.ts owns the VENDOR socket, audioLane.ts owns the bytes
 // and the browser. Two sockets, two files.
-export { resamplePcm16, mulawToPcm16, pcm16ToMulaw, makeAudioBuffer, CLIENT_RATE, type AudioLane } from "./duplex/audioLane.js";
+export { resamplePcm16, mulawToPcm16, pcm16ToMulaw, makeAudioBuffer, CLIENT_RATE, type AudioLane, type LaneSession } from "./duplex/audioLane.js";
 export { performApi, type RunResult } from "./channels/workflow.js";
 export { runFinal } from "./channels/final.js";
 export { performService } from "./channels/service.js";

package/vendor/base/src/platform/audioManager.ts

@@ -8,10 +8,14 @@
  */
 
 import { clientTransport } from "./clientTransport.js";
+import type { LaneSession } from "../manifests/runtime/duplex/audioLane.js";
+
+/** How long a call the workflow started waits for its page to join before nobody is there. */
+const JOIN_WAIT_MS = 15_000;
 
 export interface AudioWebSocketManager {
-  setAudioDataHandler(handler: (conversationId: string, audioData: ArrayBuffer, metadata?: any) => Promise<void>): void;
-  setControlMessageHandler(handler: (conversationId: string, message: any) => Promise<void>): void;
+  claim(conversationId: string, session: LaneSession): () => void;
+  whenConnected(conversationId: string, call?: { userId?: string; workflowId?: string }): Promise<boolean>;
   startAudioSession(conversationId: string, novaSessionId?: string): void;
   endAudioSession(conversationId: string): void;
   isConnected(conversationId: string): boolean;
@@ -23,26 +27,86 @@ class DistributedAudioManager implements AudioWebSocketManager {
   private audioSessions: Map<string, { novaSessionId?: string; active: boolean }> = new Map();
 
   /**
-   * Set audio data handler (called by WebSocketAudioSubscriber)
+   * THE LIVE SESSION OF EACH CONVERSATION, one each (docs/VOICE_STREAMING_GUIDE.md, "One Live
+   * Session Per Conversation"). The transport has ONE audio handler and ONE control handler for
+   * the whole process, so they are installed once, here, and hand each frame and each control
+   * message to the session that holds that conversation and to no other.
+   *
+   * Installing a session's own handler into the transport instead, as this did, meant the
+   * newest session anywhere on the server took every conversation's microphone: the one before
+   * went deaf, never heard `stop`, and idled out, and two visitors calling at once broke each
+   * other.
+   */
+  private live = new Map<string, LaneSession>();
+
+  /**
+   * CALLS WAITING FOR THEIR PAGE (docs/VOICE_STREAMING_GUIDE.md, "Call Initialization"). What the
+   * session sends meanwhile, its greeting first, is held in order and played once the page's
+   * audio socket arrives, so nothing it says is spoken to nobody.
    */
-  setAudioDataHandler(
-    handler: (conversationId: string, audioData: ArrayBuffer, metadata?: any) => Promise<void>
-  ): void {
+  private joining = new Map<string, { held: Array<() => void>; answer: (ok: boolean) => void }>();
+
+  /** Conversations whose microphone has been reported, so each is said once, not per frame. */
+  private heard = new Map<string, "session" | "nobody">();
+
+  private install(): void {
     clientTransport().setAudioDataHandler(async (conversationId, audioData) => {
-      const session = this.audioSessions.get(conversationId);
-      if (session?.active) {
-        await handler(conversationId, audioData, { novaSessionId: session.novaSessionId });
+      const session = this.live.get(conversationId);
+      // THE MICROPHONE, SAID ONCE: where a conversation's frames first go. A frame nobody holds
+      // is dropped silently otherwise, and heard only as an assistant who never listens.
+      const now = session ? "session" : "nobody";
+      if (this.heard.get(conversationId) !== now) {
+        this.heard.set(conversationId, now);
+        console.log(`[DistributedAudioManager] ${conversationId}: microphone frames reach ${now === "session" ? "the live voice session" : "NO session (dropped)"}`);
       }
+      await session?.audio(audioData);
+    });
+    clientTransport().setAudioControlHandler(async (conversationId, message) => {
+      await this.live.get(conversationId)?.control(message);
     });
-    // Wiring, not news.
+    clientTransport().setAudioSocketHandler((conversationId) => this.joining.get(conversationId)?.answer(true));
   }
 
   /**
-   * Set control message handler (called by WebSocketAudioSubscriber)
+   * IS THE PAGE THERE? A page that dialled us already has its audio socket. One that only started
+   * a workflow is asked to join on the stream it already holds, and has JOIN_WAIT_MS to do it.
    */
-  setControlMessageHandler(handler: (conversationId: string, message: any) => Promise<void>): void {
-    clientTransport().setAudioControlHandler(handler);
-    // Wiring, not news.
+  whenConnected(conversationId: string, call?: { userId?: string; workflowId?: string }): Promise<boolean> {
+    this.install();
+    if (clientTransport().hasAudioSocket(conversationId)) return Promise.resolve(true);
+    return new Promise<boolean>((resolve) => {
+      const answer = (ok: boolean) => {
+        clearTimeout(timer);
+        const waiting = this.joining.get(conversationId);
+        if (waiting?.answer !== answer) return;
+        this.joining.delete(conversationId);
+        console.log(`[DistributedAudioManager] ${conversationId}: ${ok ? "the page joined the call" : "the page never joined; the call ends"}`);
+        if (ok) for (const send of waiting.held) send();
+        resolve(ok);
+      };
+      const timer = setTimeout(() => answer(false), JOIN_WAIT_MS);
+      this.joining.set(conversationId, { held: [], answer });
+      const asked = !!call?.userId && clientTransport().pushToClient(call.userId, conversationId, { type: "JOIN_CALL", workflowId: call.workflowId });
+      console.log(`[DistributedAudioManager] ${conversationId}: ${asked ? "asked the page to join" : "no page stream to ask; waiting for its audio socket"}`);
+    });
+  }
+
+  claim(conversationId: string, session: LaneSession): () => void {
+    this.install();
+    const before = this.live.get(conversationId);
+    this.live.set(conversationId, session);
+    console.log(`[DistributedAudioManager] ${conversationId}: a voice session claimed the call`);
+    if (before && before !== session) {
+      console.log(`[DistributedAudioManager] ${conversationId}: a new voice session took the call; the one before it closes`);
+      try {
+        before.replaced();
+      } catch (err: any) {
+        console.error(`[DistributedAudioManager] ${conversationId}: the replaced session did not close: ${err?.message ?? err}`);
+      }
+    }
+    return () => {
+      if (this.live.get(conversationId) === session) this.live.delete(conversationId);
+    };
   }
 
   /**
@@ -75,6 +139,12 @@ class DistributedAudioManager implements AudioWebSocketManager {
    * Send audio to client via server
    */
   sendAudio(conversationId: string, audioData: Buffer | ArrayBuffer): boolean {
+    const waiting = this.joining.get(conversationId);
+    if (waiting) {
+      const bytes = Buffer.isBuffer(audioData) ? Buffer.from(audioData) : audioData.slice(0);
+      waiting.held.push(() => clientTransport().sendAudioToClient(conversationId, bytes));
+      return true;
+    }
     return clientTransport().sendAudioToClient(conversationId, audioData);
   }
 
@@ -83,6 +153,11 @@ class DistributedAudioManager implements AudioWebSocketManager {
    */
   sendControl(conversationId: string, message: Record<string, any>): boolean {
     if (message.type === "AUDIO_STATE" || message.state) {
+      const waiting = this.joining.get(conversationId);
+      if (waiting) {
+        waiting.held.push(() => clientTransport().sendAudioStateToClient(conversationId, message.state || message.type, message.metadata));
+        return true;
+      }
       return clientTransport().sendAudioStateToClient(conversationId, message.state || message.type, message.metadata);
     }
     return false;

package/vendor/base/src/platform/clientTransport.ts

@@ -38,6 +38,12 @@ export interface ClientTransport {
 
   /** Register the handler for audio control messages from a client. */
   setAudioControlHandler(handler: (conversationId: string, message: Record<string, unknown>) => Promise<void>): void;
+
+  /** Is a client's audio socket on this conversation, and not one a call has already ended on? */
+  hasAudioSocket(conversationId: string): boolean;
+
+  /** Register the handler told each time a client's audio socket arrives for a conversation. */
+  setAudioSocketHandler(handler: (conversationId: string) => void): void;
 }
 
 /**
@@ -50,6 +56,8 @@ const NONE: ClientTransport = {
   sendAudioStateToClient: () => false,
   setAudioDataHandler: () => {},
   setAudioControlHandler: () => {},
+  hasAudioSocket: () => false,
+  setAudioSocketHandler: () => {},
 };
 
 let transport: ClientTransport = NONE;

package/vendor/base/src/security/permissions.ts

@@ -13,7 +13,7 @@
  * had no role check at all, so "who is an administrator" had two answers and one of them was
  * "nobody". One map, imported twice.
  *
- * ROLES ARE THE TOKEN'S SHAPE; PERMISSIONS ARE THE CODE'S SHAPE. Auth0 issues this
+ * ROLES ARE THE TOKEN'S SHAPE; PERMISSIONS ARE THE CODE'S SHAPE. The IdP issues this
  * platform `roles: ["admin"]` / `["author"]`, and the tokens carry no permissions claim we
  * can rely on. So `ROLE_GRANTS` is the bridge, and it is deliberately the ONLY place the
  * two vocabularies meet: one map, read once, so switching to real permission claims later
@@ -59,7 +59,7 @@ export const PERMISSIONS = [
 export type Permission = (typeof PERMISSIONS)[number];
 
 /**
- * WHICH ROLE GRANTS WHAT. The one bridge between Auth0's vocabulary and this code's.
+ * WHICH ROLE GRANTS WHAT. The one bridge between the IdP's vocabulary and this code's.
  *
  * `admin` is `author` plus the secrets. That is the entire difference between them, stated
  * as data rather than described in a comment somewhere, so it cannot drift.