@monotykamary/pi-better-openai 0.1.24 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-better-openai",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Improve OpenAI in pi with fast mode, usage stats, realtime voice, image generation, and footer polish.",
   "keywords": [
     "fast",

package/src/live/controller.ts

@@ -25,7 +25,14 @@ Treat delegation context as your own internal progress and result. Never mention
 
 For greetings, clarification, or ordinary conversation that needs no tools, answer directly without delegating. Preserve one-assistant continuity: converse here, delegate execution, then communicate the returned result as your own.`;
 
-export type LivePhase = "connecting" | "listening" | "working" | "speaking" | "muted" | "error";
+export type LivePhase =
+  | "standby"
+  | "connecting"
+  | "listening"
+  | "working"
+  | "speaking"
+  | "muted"
+  | "error";
 
 export interface LiveTranscript {
   role: "user" | "assistant";

package/src/live/focus.ts

@@ -0,0 +1,92 @@
+// Terminal focus tracking via private mode 1004 (xterm focus-event reporting).
+// Enabling `CSI ? 1004 h` makes the terminal emit `CSI I` on focus-in and
+// `CSI O` on focus-out as input sequences; pi-tui's stdin buffer frames them
+// as generic CSI and forwards them to input listeners unmodified, so an
+// extension can observe them without any upstream keymap changes. Support is
+// detected with a DECRQM probe (`CSI ? 1004 $ p` -> `CSI ? 1004 ; 1 $ y` set /
+// `; 2 $ y` reset); terminals that ignore both sequences simply fall back to
+// the FIFO floor policy. Supported by iTerm2, kitty, WezTerm, Alacritty, foot,
+// Windows Terminal, xterm.js, and modern tmux.
+
+export const FOCUS_REPORTING_ENABLE = "\x1b[?1004h";
+export const FOCUS_REPORTING_DISABLE = "\x1b[?1004l";
+export const FOCUS_IN_SEQUENCE = "\x1b[I";
+export const FOCUS_OUT_SEQUENCE = "\x1b[O";
+export const DECRQM_FOCUS_QUERY = "\x1b[?1004$p";
+
+export type FocusInputListener = (data: string) => { consume?: boolean; data?: string } | undefined;
+
+export interface FocusTerminalHandle {
+  write(data: string): void;
+  addInputListener(listener: FocusInputListener): () => void;
+}
+
+export function parseFocusSequence(data: string): boolean | undefined {
+  if (data === FOCUS_IN_SEQUENCE) return true;
+  if (data === FOCUS_OUT_SEQUENCE) return false;
+  return undefined;
+}
+
+export function parseDecrqmFocusResponse(data: string): boolean | undefined {
+  if (data === "\x1b[?1004;1$y" || data === "\x1b[?1004;3$y") return true;
+  if (data === "\x1b[?1004;2$y" || data === "\x1b[?1004;4$y") return false;
+  return undefined;
+}
+
+export function probeFocusReporting(
+  handle: FocusTerminalHandle,
+  timeoutMs = 400,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let removeListener: (() => void) | undefined;
+    const done = (supported: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      removeListener?.();
+      resolve(supported);
+    };
+    const timer = setTimeout(() => done(false), timeoutMs);
+    timer.unref?.();
+    try {
+      removeListener = handle.addInputListener((data) => {
+        const state = parseDecrqmFocusResponse(data);
+        if (state === undefined) return undefined;
+        done(true);
+        return { consume: true };
+      });
+      handle.write(DECRQM_FOCUS_QUERY);
+    } catch {
+      done(false);
+    }
+  });
+}
+
+export function attachFocusReporting(
+  handle: FocusTerminalHandle,
+  onFocus: (focused: boolean) => void,
+): () => void {
+  const removeListener = handle.addInputListener((data) => {
+    const focused = parseFocusSequence(data);
+    if (focused === undefined) return undefined;
+    onFocus(focused);
+    return { consume: true };
+  });
+  try {
+    handle.write(FOCUS_REPORTING_ENABLE);
+  } catch {
+    // The terminal write path is best-effort; focus events simply never arrive.
+  }
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    removeListener();
+    try {
+      handle.write(FOCUS_REPORTING_DISABLE);
+    } catch {
+      // Nothing to undo on a torn-down tty.
+    }
+  };
+}

package/src/live/index.ts

@@ -8,10 +8,20 @@ import {
   type LiveSessionControllerOptions,
   type LiveTranscript,
 } from "./controller.ts";
+import { attachFocusReporting, probeFocusReporting, type FocusTerminalHandle } from "./focus.ts";
+import {
+  LIVE_QUEUE_TICK_MS,
+  LiveFloorArbiter,
+  type LiveActivationCause,
+  type LiveFloorArbiterCallbacks,
+  type LiveFloorArbiterLike,
+  type LiveFloorArbiterOptions,
+} from "./queue.ts";
 import { LiveVisualizer, LIVE_VISUALIZER_TOGGLE_KEY } from "./visualizer.ts";
 
 export const LIVE_COMMAND = "live";
 export const LIVE_DELEGATION_MESSAGE_TYPE = "better-openai-live-delegation";
+export const LIVE_FOCUS_SETTLE_MS = 400;
 
 interface LiveSessionRuntime {
   start(): Promise<void>;
@@ -21,17 +31,48 @@ interface LiveSessionRuntime {
   handleAgentSettled(): void;
 }
 
+// An enrollment outlives any single realtime session: `/live` opens the
+// visualizer and joins the cross-process queue, then the arbiter activates
+// (creates the actual mic + WebRTC session) and parks (stops it) as the floor
+// comes and goes. Only the floor holder runs a realtime session at all, so a
+// dozen enrolled windows cost zero open connections while standby.
 interface ActiveLiveRun {
-  session: LiveSessionRuntime;
+  getSession(): LiveSessionRuntime | undefined;
   finishUi(result: LiveUiResult): void;
+  dispose(): Promise<void>;
 }
 
 type LiveUiResult = { error?: Error };
 
 type LiveSessionFactory = (options: LiveSessionControllerOptions) => LiveSessionRuntime;
 
+type LiveArbiterFactory = (
+  options: LiveFloorArbiterOptions,
+  callbacks: LiveFloorArbiterCallbacks,
+) => LiveFloorArbiterLike;
+
 export interface LiveRegistrationDependencies {
   createSession?: LiveSessionFactory;
+  createArbiter?: LiveArbiterFactory;
+  probeFocusReporting?: typeof probeFocusReporting;
+  attachFocusReporting?: typeof attachFocusReporting;
+  notifyActivatedUnfocused?: (handle: FocusTerminalHandle, label: string) => void;
+  tickMs?: number;
+}
+
+// eslint-disable-next-line no-control-regex -- OSC payloads must not carry raw control characters; matching them is the point
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001F\u007F-\u009F]/g;
+
+export function notifyActivatedUnfocused(handle: FocusTerminalHandle, label: string): void {
+  // OSC 9 desktop toast. Reaching this branch means the mic went hot in a
+  // window the user is not typing into (FIFO promotion or a vacant-floor
+  // background claim), so the toast is the only signal that it happened.
+  const safeLabel = label.replace(CONTROL_CHARACTER_PATTERN, " ").trim();
+  try {
+    handle.write(`\x1b]9;Live voice is now active in ${safeLabel}\x07`);
+  } catch {
+    // Notification support is optional and terminal-dependent.
+  }
 }
 
 function messageText(content: unknown): string {
@@ -51,6 +92,10 @@ function messageText(content: unknown): string {
     .join("\n");
 }
 
+function errorFrom(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
 export function registerOpenAILive(
   pi: ExtensionAPI,
   getConfig: (ctx: ExtensionContext) => ResolvedConfig,
@@ -58,21 +103,24 @@ export function registerOpenAILive(
 ): { isActive(): boolean; stop(): Promise<void> } {
   const createSession =
     dependencies.createSession ?? ((options) => new LiveSessionController(options));
+  const createArbiter: LiveArbiterFactory =
+    dependencies.createArbiter ??
+    ((options, callbacks) => new LiveFloorArbiter(options, callbacks));
+  const probeFocus = dependencies.probeFocusReporting ?? probeFocusReporting;
+  const attachFocus = dependencies.attachFocusReporting ?? attachFocusReporting;
+  const notifyUnfocused = dependencies.notifyActivatedUnfocused ?? notifyActivatedUnfocused;
+  const tickMs = dependencies.tickMs ?? LIVE_QUEUE_TICK_MS;
   let activeRun: ActiveLiveRun | undefined;
   let settling: Promise<void> | undefined;
 
-  async function stopRun(run: ActiveLiveRun): Promise<void> {
-    run.finishUi({});
-    await run.session.stop();
-  }
-
   async function stopActive(): Promise<void> {
     const run = activeRun;
     if (!run) {
       if (settling) await settling;
       return;
     }
-    await stopRun(run);
+    run.finishUi({});
+    await run.dispose();
   }
 
   async function start(ctx: ExtensionContext): Promise<void> {
@@ -89,56 +137,160 @@ export function registerOpenAILive(
 
     const result = await ctx.ui.custom<LiveUiResult>((tui, theme, _keybindings, done) => {
       let completed = false;
-      let session: LiveSessionRuntime;
+      let disposed = false;
+      let session: LiveSessionRuntime | undefined;
+      let sessionParked = false;
+      let arbiter: LiveFloorArbiterLike | undefined;
+      let tickInterval: NodeJS.Timeout | undefined;
+      let focusDebounce: NodeJS.Timeout | undefined;
+      let disposeFocus: (() => void) | undefined;
+
       const finishUi = (value: LiveUiResult) => {
         if (completed) return;
         completed = true;
         done(value);
       };
+
       const visualizer = new LiveVisualizer({
         theme,
         requestRender: () => tui.requestRender(),
         onStop: () => finishUi({}),
-        onToggleMute: () => session.toggleMute(),
+        onToggleMute: () => session?.toggleMute(),
       });
-      const updateTranscript = (transcript: LiveTranscript | undefined) => {
-        visualizer.setTranscript(transcript);
+      visualizer.setPhase("standby");
+
+      const terminalHandle: FocusTerminalHandle = {
+        write: (data) => tui.terminal.write(data),
+        addInputListener: (listener) => tui.addInputListener(listener),
       };
-      session = createSession({
-        sessionId: ctx.sessionManager.getSessionId(),
-        voice: cfg.live.voice,
-        getCredentials: (signal) => getCodexCredentials(ctx, signal),
-        delegate: (request) => {
-          pi.sendMessage(
-            {
-              customType: LIVE_DELEGATION_MESSAGE_TYPE,
-              content: request,
-              display: true,
-              details: { source: "live" },
+
+      const parkSession = () => {
+        const current = session;
+        session = undefined;
+        sessionParked = true;
+        visualizer.setPhase("standby");
+        visualizer.setTranscript(undefined);
+        if (current) void current.stop().catch(() => undefined);
+      };
+
+      const activateSession = () => {
+        if (completed || session) return;
+        sessionParked = false;
+        const created = createSession({
+          sessionId: ctx.sessionManager.getSessionId(),
+          voice: cfg.live.voice,
+          getCredentials: (signal) => getCodexCredentials(ctx, signal),
+          delegate: (request) => {
+            pi.sendMessage(
+              {
+                customType: LIVE_DELEGATION_MESSAGE_TYPE,
+                content: request,
+                display: true,
+                details: { source: "live" },
+              },
+              { triggerTurn: true, deliverAs: "steer" },
+            );
+          },
+          callbacks: {
+            onPhase: (phase) => visualizer.setPhase(phase),
+            onLevels: (input) => visualizer.setInputLevel(input),
+            onTranscript: (transcript: LiveTranscript | undefined) =>
+              visualizer.setTranscript(transcript),
+            onTerminal: (error) => {
+              if (sessionParked) return;
+              finishUi(error ? { error } : {});
             },
-            { triggerTurn: true, deliverAs: "steer" },
-          );
-        },
-        callbacks: {
-          onPhase: (phase) => visualizer.setPhase(phase),
-          onLevels: (input) => visualizer.setInputLevel(input),
-          onTranscript: updateTranscript,
-          onTerminal: (error) => finishUi(error ? { error } : {}),
-        },
-      });
-      activeRun = { session, finishUi };
-      setImmediate(() => {
-        void session.start().catch((cause) => {
-          const error = cause instanceof Error ? cause : new Error(String(cause));
-          finishUi({ error });
+          },
+        });
+        session = created;
+        setImmediate(() => {
+          if (session !== created) return;
+          void created.start().catch((cause) => {
+            finishUi({ error: errorFrom(cause) });
+          });
         });
+      };
+
+      const dispose = async (): Promise<void> => {
+        if (disposed) return;
+        disposed = true;
+        if (focusDebounce) clearTimeout(focusDebounce);
+        if (tickInterval) clearInterval(tickInterval);
+        disposeFocus?.();
+        arbiter?.leave();
+        const current = session;
+        session = undefined;
+        if (current) await current.stop().catch(() => undefined);
+      };
+
+      const run: ActiveLiveRun = {
+        getSession: () => session,
+        finishUi,
+        dispose,
+      };
+      activeRun = run;
+
+      setImmediate(() => {
+        void (async () => {
+          try {
+            const focusSupported = await probeFocus(terminalHandle);
+            if (completed) return;
+            const enrolled = createArbiter(
+              {
+                pid: process.pid,
+                sessionId: ctx.sessionManager.getSessionId(),
+                cwd: ctx.cwd,
+                policy: focusSupported ? "focus" : "fifo",
+              },
+              {
+                onActivated: (cause: LiveActivationCause) => {
+                  if (cause !== "focus") notifyUnfocused(terminalHandle, enrolled.label);
+                  activateSession();
+                },
+                onDeactivated: parkSession,
+              },
+            );
+            arbiter = enrolled;
+            enrolled.join();
+            tickInterval = setInterval(() => {
+              try {
+                enrolled.tick();
+              } catch {
+                // A failing tick must not tear down the enrollment.
+              }
+            }, tickMs);
+            tickInterval.unref?.();
+            if (!focusSupported) return;
+            disposeFocus = attachFocus(terminalHandle, (focused) => {
+              if (focusDebounce) clearTimeout(focusDebounce);
+              if (!focused) {
+                enrolled.setFocused(false);
+                return;
+              }
+              // Debounce focus-in so window-manager focus flicker does not flap
+              // floor ownership between two live windows.
+              focusDebounce = setTimeout(() => {
+                focusDebounce = undefined;
+                try {
+                  enrolled.setFocused(true);
+                } catch {
+                  // Focus edges are advisory; a lost race settles next tick.
+                }
+              }, LIVE_FOCUS_SETTLE_MS);
+              focusDebounce.unref?.();
+            });
+          } catch (cause) {
+            finishUi({ error: errorFrom(cause) });
+          }
+        })();
       });
+
       return visualizer;
     });
 
     const run = activeRun;
     if (run) {
-      const cleanup = stopRun(run).catch(() => undefined);
+      const cleanup = run.dispose().catch(() => undefined);
       settling = cleanup;
       await cleanup;
       if (activeRun === run) activeRun = undefined;
@@ -178,11 +330,11 @@ export function registerOpenAILive(
   });
 
   pi.on("message_end", (event) => {
-    activeRun?.session.handleAgentMessage(event.message);
+    activeRun?.getSession()?.handleAgentMessage(event.message);
   });
 
   pi.on("agent_settled", () => {
-    activeRun?.session.handleAgentSettled();
+    activeRun?.getSession()?.handleAgentSettled();
   });
 
   pi.on("session_shutdown", async () => {

package/src/live/queue.ts

@@ -0,0 +1,388 @@
+import { randomBytes } from "node:crypto";
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { piAgentDir } from "../paths.ts";
+
+// Cross-process floor arbitration for /live. Every enrolled pi process drops a
+// heartbeat file into a shared per-user directory; exactly one process holds
+// the floor (owns the microphone, the WebRTC session, and delegation routing).
+// The floor holder is chosen explicitly (atomic create) or by preemption
+// (atomic replace), so concurrent starters converge within one tick instead of
+// racing into parallel realtime sessions. Stale entries from crashed processes
+// are reclaimed via pid liveness plus heartbeat age — `process.kill(pid, 0)`
+// throws ESRCH for dead pids and EPERM for alive-but-unowned ones.
+//
+// Focus handling is deliberately asymmetric: gaining focus grants claiming
+// rights (and preempts a holder whose terminal is not focused), while losing
+// focus never yields the floor — a conversation must survive alt-tabbing to a
+// browser. Claiming a *vacant* floor needs only "not known to be unfocused", so
+// terminals that report focus-support but skip the initial state event still
+// behave sensibly for a single enrolled session.
+
+export const LIVE_QUEUE_TICK_MS = 1_000;
+export const LIVE_QUEUE_STALE_MS = 8_000;
+
+export type LiveFloorPolicy = "focus" | "fifo";
+
+export type LiveActivationCause = "focus" | "background" | "fifo";
+
+export interface LiveQueueMember {
+  id: string;
+  pid: number;
+  sessionId: string;
+  label: string;
+  joinedAt: number;
+  heartbeatAt: number;
+}
+
+interface LiveFloorClaim {
+  holderId: string;
+  pid: number;
+  token: string;
+  claimedAt: number;
+}
+
+export interface LiveFloorArbiterCallbacks {
+  onActivated(cause: LiveActivationCause): void;
+  onDeactivated(): void;
+}
+
+export interface LiveFloorArbiterOptions {
+  pid: number;
+  sessionId: string;
+  cwd: string;
+  policy: LiveFloorPolicy;
+  directory?: string;
+  now?: () => number;
+  isProcessAlive?: (pid: number) => boolean;
+}
+
+// Structural subset of LiveFloorArbiter used by the registration wiring, so
+// tests can substitute an in-memory arbiter without touching the filesystem.
+export interface LiveFloorArbiterLike {
+  readonly id: string;
+  readonly label: string;
+  readonly policy: LiveFloorPolicy;
+  readonly hasFloor: boolean;
+  join(): void;
+  leave(): void;
+  tick(): void;
+  setFocused(focused: boolean): void;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function defaultIsProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (
+      typeof cause === "object" &&
+      cause !== null &&
+      (cause as NodeJS.ErrnoException).code === "EPERM"
+    );
+  }
+}
+
+export function liveQueueDirectory(agentDir = piAgentDir()): string {
+  return join(agentDir, "live-queue");
+}
+
+export function liveQueueLabel(cwd: string, sessionId: string): string {
+  const folder = basename(cwd) || cwd;
+  return `${folder} · ${sessionId.slice(0, 8)}`;
+}
+
+function sanitizeId(id: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+function parseMember(value: unknown): LiveQueueMember | undefined {
+  if (
+    isRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.pid === "number" &&
+    typeof value.sessionId === "string" &&
+    typeof value.joinedAt === "number" &&
+    typeof value.heartbeatAt === "number"
+  ) {
+    return {
+      id: value.id,
+      pid: value.pid,
+      sessionId: value.sessionId,
+      label: typeof value.label === "string" ? value.label : value.id,
+      joinedAt: value.joinedAt,
+      heartbeatAt: value.heartbeatAt,
+    };
+  }
+  return undefined;
+}
+
+function parseClaim(value: unknown): LiveFloorClaim | undefined {
+  if (
+    isRecord(value) &&
+    typeof value.holderId === "string" &&
+    typeof value.pid === "number" &&
+    typeof value.token === "string" &&
+    typeof value.claimedAt === "number"
+  ) {
+    return {
+      holderId: value.holderId,
+      pid: value.pid,
+      token: value.token,
+      claimedAt: value.claimedAt,
+    };
+  }
+  return undefined;
+}
+
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function writeJsonAtomic(file: string, value: unknown): void {
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value));
+  renameSync(tmp, file);
+}
+
+export class LiveFloorArbiter implements LiveFloorArbiterLike {
+  readonly #directory: string;
+  readonly #memberFile: string;
+  readonly #floorFile: string;
+  readonly #pid: number;
+  readonly #sessionId: string;
+  readonly #label: string;
+  readonly #policy: LiveFloorPolicy;
+  readonly #now: () => number;
+  readonly #isProcessAlive: (pid: number) => boolean;
+  readonly #callbacks: LiveFloorArbiterCallbacks;
+  readonly #id: string;
+  readonly #token: string;
+  #joined = false;
+  #joinedAt = 0;
+  #focused: boolean | undefined;
+  #hasFloor = false;
+
+  constructor(options: LiveFloorArbiterOptions, callbacks: LiveFloorArbiterCallbacks) {
+    this.#directory = options.directory ?? liveQueueDirectory();
+    this.#pid = options.pid;
+    this.#sessionId = options.sessionId;
+    this.#label = liveQueueLabel(options.cwd, options.sessionId);
+    this.#policy = options.policy;
+    this.#now = options.now ?? Date.now;
+    this.#isProcessAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+    this.#callbacks = callbacks;
+    this.#id = `${options.pid}-${options.sessionId}`;
+    this.#token = `${options.pid}-${randomBytes(6).toString("hex")}`;
+    this.#memberFile = join(this.#directory, "members", `${sanitizeId(this.#id)}.json`);
+    this.#floorFile = join(this.#directory, "floor.json");
+  }
+
+  get id(): string {
+    return this.#id;
+  }
+
+  get label(): string {
+    return this.#label;
+  }
+
+  get policy(): LiveFloorPolicy {
+    return this.#policy;
+  }
+
+  get joined(): boolean {
+    return this.#joined;
+  }
+
+  get hasFloor(): boolean {
+    return this.#hasFloor;
+  }
+
+  get focused(): boolean | undefined {
+    return this.#focused;
+  }
+
+  join(): void {
+    if (this.#joined) return;
+    mkdirSync(join(this.#directory, "members"), { recursive: true });
+    this.#joined = true;
+    this.#joinedAt = this.#now();
+    this.#writeMember();
+    this.tick();
+  }
+
+  leave(): void {
+    if (!this.#joined) return;
+    this.#joined = false;
+    this.#releaseFloor();
+    rmSync(this.#memberFile, { force: true });
+  }
+
+  // Focus edges arrive from the owning terminal via mode 1004 input events.
+  setFocused(focused: boolean): void {
+    this.#focused = focused;
+    this.#evaluate();
+  }
+
+  tick(): void {
+    if (!this.#joined) return;
+    this.#writeMember();
+    this.#sweep();
+    this.#evaluate();
+  }
+
+  #writeMember(): void {
+    const member: LiveQueueMember = {
+      id: this.#id,
+      pid: this.#pid,
+      sessionId: this.#sessionId,
+      label: this.#label,
+      joinedAt: this.#joinedAt,
+      heartbeatAt: this.#now(),
+    };
+    try {
+      writeJsonAtomic(this.#memberFile, member);
+    } catch {
+      // A wiped queue directory mid-run is recoverable on the next tick.
+    }
+  }
+
+  #readMembers(): LiveQueueMember[] {
+    let files: string[];
+    try {
+      files = readdirSync(join(this.#directory, "members"));
+    } catch {
+      return [];
+    }
+    const members: LiveQueueMember[] = [];
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const member = parseMember(readJson(join(this.#directory, "members", file)));
+      if (member) members.push(member);
+    }
+    members.sort((a, b) => a.joinedAt - b.joinedAt || a.id.localeCompare(b.id));
+    return members;
+  }
+
+  #readClaim(): LiveFloorClaim | undefined {
+    return parseClaim(readJson(this.#floorFile));
+  }
+
+  #isMemberAlive(member: LiveQueueMember): boolean {
+    if (member.pid === this.#pid) return true;
+    if (!this.#isProcessAlive(member.pid)) return false;
+    return this.#now() - member.heartbeatAt <= LIVE_QUEUE_STALE_MS;
+  }
+
+  #sweep(): void {
+    let files: string[];
+    try {
+      files = readdirSync(join(this.#directory, "members"));
+    } catch {
+      return;
+    }
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const path = join(this.#directory, "members", file);
+      const member = parseMember(readJson(path));
+      if (!member || (member.pid !== this.#pid && !this.#isMemberAlive(member))) {
+        rmSync(path, { force: true });
+      }
+    }
+  }
+
+  #evaluate(): void {
+    const now = this.#now();
+    const aliveMembers = this.#readMembers().filter((member) => this.#isMemberAlive(member));
+    const claim = this.#readClaim();
+    const holderAlive =
+      claim !== undefined &&
+      (claim.pid === this.#pid || this.#isProcessAlive(claim.pid)) &&
+      aliveMembers.some(
+        (member) => member.id === claim.holderId && now - member.heartbeatAt <= LIVE_QUEUE_STALE_MS,
+      );
+
+    if (this.#hasFloor) {
+      if (!this.#joined || claim?.token !== this.#token || claim.holderId !== this.#id) {
+        this.#hasFloor = false;
+        this.#callbacks.onDeactivated();
+      }
+      return;
+    }
+
+    if (claim && holderAlive) {
+      // Only a genuinely focused challenger preempts; the displaced holder
+      // steps down on its next tick when the token no longer matches its own.
+      if (this.#policy === "focus" && this.#focused === true && claim.holderId !== this.#id) {
+        this.#claim("focus", true);
+      }
+      return;
+    }
+
+    if (claim && !holderAlive) {
+      rmSync(this.#floorFile, { force: true });
+    }
+    if (this.#policy === "fifo") {
+      if (aliveMembers[0]?.id === this.#id) this.#claim("fifo", false);
+      return;
+    }
+    if (this.#focused !== false) {
+      this.#claim(this.#focused === true ? "focus" : "background", false);
+    }
+  }
+
+  #claim(cause: LiveActivationCause, preempt: boolean): void {
+    const claim: LiveFloorClaim = {
+      holderId: this.#id,
+      pid: this.#pid,
+      token: this.#token,
+      claimedAt: this.#now(),
+    };
+    try {
+      if (preempt) {
+        writeJsonAtomic(this.#floorFile, claim);
+      } else {
+        const fd = openSync(this.#floorFile, "wx");
+        try {
+          writeFileSync(fd, JSON.stringify(claim));
+        } finally {
+          closeSync(fd);
+        }
+      }
+    } catch {
+      return;
+    }
+    const confirmed = this.#readClaim();
+    if (confirmed?.token !== this.#token) return;
+    this.#hasFloor = true;
+    this.#callbacks.onActivated(cause);
+  }
+
+  #releaseFloor(): void {
+    const wasHolding = this.#hasFloor;
+    this.#hasFloor = false;
+    const claim = this.#readClaim();
+    if (claim?.token === this.#token) {
+      rmSync(this.#floorFile, { force: true });
+    }
+    if (wasHolding) this.#callbacks.onDeactivated();
+  }
+}

package/src/live/visualizer.ts

@@ -151,7 +151,12 @@ export class LiveVisualizer implements Component {
 
   #renderLines(width: number): string[] {
     if (width === 1) {
-      const color = this.#phase === "error" ? "error" : this.#phase === "muted" ? "dim" : "success";
+      const color =
+        this.#phase === "error"
+          ? "error"
+          : this.#phase === "muted" || this.#phase === "standby"
+            ? "dim"
+            : "success";
       return [
         this.#options.theme.fg("border", "┐"),
         this.#options.theme.fg(color, "▂"),
@@ -167,7 +172,7 @@ export class LiveVisualizer implements Component {
       theme.fg("border", "│") + content + theme.fg("border", "│");
     const top = theme.fg("border", `┌${"─".repeat(innerWidth)}┐`);
     const spectrumColor: ThemeColor =
-      this.#phase === "muted" || this.#phase === "connecting"
+      this.#phase === "muted" || this.#phase === "connecting" || this.#phase === "standby"
         ? "dim"
         : this.#phase === "error"
           ? "error"
@@ -207,6 +212,7 @@ export class LiveVisualizer implements Component {
     const theme = this.#options.theme;
     const spinners = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
     const staticIcons: Record<LivePhase, string> = {
+      standby: "◌",
       connecting: "○",
       listening: "●",
       working: "○",
@@ -219,6 +225,7 @@ export class LiveVisualizer implements Component {
         ? spinners[this.#frame % spinners.length]!
         : staticIcons[this.#phase];
     const phaseColors: Record<LivePhase, ThemeColor> = {
+      standby: "dim",
       connecting: "dim",
       listening: "success",
       working: "warning",
@@ -251,7 +258,10 @@ export class LiveVisualizer implements Component {
     const microphoneEnergy = Math.min(1, Math.sqrt(this.#displayLevel * 5));
     const connectingEnergy =
       this.#phase === "connecting" ? 0.06 + 0.03 * Math.sin(this.#frame * 0.35) : 0;
-    const energy = this.#phase === "muted" ? 0 : Math.max(microphoneEnergy, connectingEnergy);
+    const energy =
+      this.#phase === "muted" || this.#phase === "standby"
+        ? 0
+        : Math.max(microphoneEnergy, connectingEnergy);
     const maxHeight = rows * (blocks.length - 1);
     for (let column = 0; column < width; column += 1) {
       const carrier = 0.5 + 0.5 * Math.sin(this.#frame * 0.43 + column * 0.71);