obsbot-mcp 0.3.0 → 0.4.0

package/dist/device/manager.js

@@ -1,45 +1,741 @@
 import { WindowsTransport } from "../transport/windows.js";
 import { LinuxTransport } from "../transport/linux.js";
 import { MacosTransport } from "../transport/macos.js";
+// USB vendor ID 0x3564 is registered to **Remo Inc.** — the manufacturer. OBSBOT
+// is a Remo product brand, and Remo ships non-OBSBOT (and non-camera) devices
+// under the same VID, so candidacy must gate on VID **and** a known model PID —
+// never VID alone. Add a PID here (and mirror it in native/macos/helper.m's
+// OBSBOT_MODEL_PIDS) when a new OBSBOT camera model is verified on hardware.
+const REMO_VID = 0x3564;
+const OBSBOT_MODEL_PIDS = new Map([
+    [REMO_VID, new Set([0xfef8 /* Tiny 2 */])],
+]);
+// Legacy name match — used ONLY as a fallback on platforms whose helper does not
+// yet report USB vid/pid (Linux today: its /dev/videoN paths carry no USB
+// identity). Windows and macOS helpers report vid/pid, so there the gate is
+// strict and branded software sources — e.g. the "OBSBOT Virtual Camera"
+// DirectShow filter, which matched this regex and poisoned multi-candidate
+// binding — are correctly excluded.
+const OBSBOT_NAME_RE = /obsbot/i;
+/** Message text from an unknown thrown value, for diagnostics. */
+const errText = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * Is this enumerated device a controllable OBSBOT camera worth binding? On
+ * Windows/macOS the helper reports USB vid/pid, so gate strictly on the Remo
+ * VID + known-model PID table (a software "OBSBOT Virtual Camera" has no vid/pid
+ * and is rejected). On Linux the helper does not report vid/pid yet, so fall
+ * back to the name match there until it does.
+ */
+function isObsbotCamera(d) {
+    if (process.platform === "linux")
+        return OBSBOT_NAME_RE.test(d.name);
+    if (d.vid === undefined || d.pid === undefined)
+        return false;
+    return OBSBOT_MODEL_PIDS.get(d.vid)?.has(d.pid) ?? false;
+}
+/** Thrown by get() with no selector when more than one camera is attached. */
+export class AmbiguousCameraError extends Error {
+    available;
+    constructor(available) {
+        super(`multiple cameras attached; specify one of: ${available.join(", ")}`);
+        this.name = "AmbiguousCameraError";
+        this.available = available;
+    }
+}
+/** Thrown by get(serial) when no attached, bindable camera has that serial. */
+export class UnknownCameraError extends Error {
+    available;
+    constructor(serial, available) {
+        super(`unknown camera "${serial}"; available: ${available.length ? available.join(", ") : "(none)"}`);
+        this.name = "UnknownCameraError";
+        this.available = available;
+    }
+}
+/**
+ * Serial-keyed multi-camera registry. Identity is the serial (read via
+ * ObsbotTransport.readSerial() on a freshly-opened device); locationId is
+ * only ever a display/correlation hint, never persisted as truth for
+ * binding.
+ *
+ * Steady state is one HelperProcess per bound camera (Map<serial, {helper,
+ * transport, locationId}>), spawned lazily — nothing is spawned until a
+ * camera is actually needed (get() or listCameras()). While scanning for a
+ * camera to bind, candidates are tried on a single scratch helper reused
+ * across attempts, mirroring the native helper's own behaviour: `doOpen`
+ * unconditionally releases whatever device it previously held before
+ * opening the next one, so re-opening a different candidate on the same
+ * helper is exactly what one physical device-swap looks like to it. A
+ * scratch helper that turns out to be the winning candidate is promoted
+ * directly into the registry (no extra spawn); one that never opens a
+ * usable camera is kept around for the next scan instead of being spawned
+ * again. Consequently DeviceManager never closes a helper it did not spawn
+ * itself for a *losing* attempt — ownership of a bound camera's helper
+ * transfers to the registry, and callers that hand in an already-started,
+ * externally-owned helper (see the .mjs scripts) keep owning its shutdown.
+ *
+ * USB open is exclusive: a camera another process holds fails `open` with
+ * an exclusive-access error. Per multi-camera spec §4.3, ANY open failure
+ * during a scan is treated as "not mine, skip" — not fatal — because the
+ * helper does not currently surface a clean, stable way to distinguish
+ * exclusive-access from other open failures at this layer.
+ *
+ * invalidate() is the escape hatch out of "once bound, stay bound": it
+ * drops a registry entry (best-effort closing its helper first) so the
+ * next get()/bind() re-scans through a fresh helper instead of handing back
+ * a transport that may be talking to a device that already re-enumerated.
+ */
 export class DeviceManager {
-    helper;
-    constructor(helper) {
-        this.helper = helper;
+    makeHelper;
+    registry = new Map();
+    /** Lazily spawned, reused across scans until promoted into the registry. */
+    scanHelper;
+    /**
+     * Long-lived listener. Holds no device and never scans for one — its only job
+     * is to still be alive, and still subscribed, when the cable moves.
+     */
+    watcher;
+    /**
+     * Reconnect tracking, folded in from the retired DeviceSession. `everBound`
+     * records every serial this manager has bound at least once — deliberately
+     * SEPARATE from the registry Map so it survives invalidate() dropping a
+     * registry entry (the registry says "bound right now", this says "bound at
+     * some point"). A promote() of a serial already in `everBound` is therefore a
+     * RE-bind — a self-heal after a mid-session disconnect — and lands the serial
+     * in `reconnectedSerials`, which the readiness gate drains via
+     * takeReconnected() to surface `reconnected: true` on the next command.
+     */
+    everBound = new Set();
+    reconnectedSerials = new Set();
+    /**
+     * @param makeHelper Factory for a HelperProcess, invoked whenever a fresh
+     *   scratch helper is needed (each scan, and each rebind after
+     *   invalidate()). CONTRACT: it MUST return a freshly-started,
+     *   exclusively-owned HelperProcess on every call — DeviceManager may call
+     *   it repeatedly across a session and always expects a clean handle, not
+     *   a shared one. A factory that instead returns the SAME already-started
+     *   helper on every call (as the single-camera `.mjs` scripts under
+     *   scripts/ do, to keep one native session alive for their whole run)
+     *   MUST NOT bind more than one serial through this manager: a second
+     *   scan would hand that same shared helper back and silently steal the
+     *   first bound camera's native session out from under it. No current
+     *   caller does this (all are single-camera); this is latent and not
+     *   guarded in code — the proper fix belongs to multi-camera .mjs/CLI
+     *   wiring, not to DeviceManager itself.
+     */
+    /** True while an arrival re-bind ladder is running (see handleCameraArrived). */
+    rebinding = false;
+    /**
+     * Delays before each arrival re-bind attempt, in order — so four attempts
+     * spanning ~4.5s, the first immediate.
+     *
+     * Sized from hardware, 2026-07-21: for many seconds after a USB
+     * re-enumeration the Tiny 2's vendor mailbox is intermittently not-ready
+     * (the reply slot reads back with its magic byte zeroed), and readSerial's
+     * own 8 x 30ms poll is too short to ride it out. Measured 22 failures in 80
+     * attempts across the first 14s after a replug, against 0 in 120 in steady
+     * state — so a single attempt on arrival is roughly a 1-in-4 coin flip, and
+     * losing it silently leaves the camera unbound until the user's next call.
+     * Four spread attempts make a lost re-bind unlikely without retrying forever
+     * at a camera that is simply not answering.
+     */
+    arrivalBackoffMs;
+    /**
+     * Where a failed or retried arrival re-bind is reported. STDERR by default —
+     * never stdout, which is the JSON-RPC channel.
+     *
+     * Exists because the ladder was silent: a ladder that fired and a clean first
+     * attempt looked identical from outside the process, so the retry could not
+     * be observed on hardware even once it existed. A self-heal that fails
+     * quietly is the failure mode that cost a day of debugging.
+     */
+    log;
+    constructor(makeHelper, opts = {}) {
+        this.makeHelper = makeHelper;
+        this.arrivalBackoffMs = opts.arrivalBackoffMs ?? [0, 400, 1200, 3000];
+        this.log = opts.log ?? ((m) => console.error(m));
     }
-    createTransport() {
+    createTransport(helper) {
         if (process.platform === "linux") {
-            return new LinuxTransport(this.helper);
+            return new LinuxTransport(helper);
         }
         if (process.platform === "darwin") {
-            return new MacosTransport(this.helper);
+            return new MacosTransport(helper);
+        }
+        return new WindowsTransport(helper);
+    }
+    /**
+     * Close and forget the scratch helper. Closing matters as much as forgetting:
+     * the process is alive and holding whatever it opened, so dropping only the
+     * reference leaks it and leaves the replacement unable to open the camera —
+     * the same mistake pruneDeadEntries() makes if it merely deletes an entry.
+     */
+    async discardScanHelper() {
+        const helper = this.scanHelper;
+        this.scanHelper = undefined;
+        if (!helper)
+            return;
+        try {
+            await helper.close();
+        }
+        catch {
+            // best-effort — a disconnected helper's close() may itself throw
         }
-        return new WindowsTransport(this.helper);
     }
+    /**
+     * Keep one helper alive purely to receive bus events.
+     *
+     * Bus events are delivered per PROCESS (helperFactory subscribes each one it
+     * spawns), and every process that could be listening gets closed: a departure
+     * closes the registry helper, and a failed bind closes the scratch scanner.
+     * Since promote() clears `scanHelper`, the bound steady state is exactly ONE
+     * live helper — the registry's — so handleCameraDeparted() alone drops the
+     * subscriber count to zero. The arrival that follows is then delivered to
+     * nobody and the camera stays unbound until a tool call fails against it.
+     *
+     * PRIMING IS NOT OPTIONAL. A helper that has never enumerated receives
+     * nothing. Measured on hardware (darwin-arm64, Tiny 2, 2026-07-21) across one
+     * same-port replug, three processes, none of which opened the device:
+     *
+     *   enumerated while camera present -> departure YES, arrival YES
+     *   never enumerated                -> departure NO,  arrival NO
+     *   enumerated while camera absent   -> arrival YES
+     *
+     * The silent one stayed alive the whole run and answered a later enumerate
+     * correctly, so that was genuine non-delivery. Its first enumerate took 71ms
+     * against ~1ms for the primed pair — AVFoundation's discovery subsystem
+     * starting up for the first time. Registering the observers
+     * (helper.m:registerCameraNotifications) is NOT what starts delivery;
+     * touching the device list is.
+     *
+     * Windows enforces the same rule for an unrelated reason: helper.cpp drops
+     * any event whose path is missing from `g_knownPaths`, which only enumerate
+     * fills, and that cache is per-process. There the path must have been seen
+     * WHILE THE CAMERA WAS PRESENT — an enumerate during an absence cannot cache
+     * it. macOS has no such constraint: an arm primed during an absence received
+     * the arrival in the same millisecond as one primed while present.
+     *
+     * Both halves are now MEASURED, one platform each, same three-arm experiment:
+     *
+     *            primed-present   never-primed   primed-during-absence
+     *   macOS         yes              NO                 yes
+     *   Windows       yes              NO                 NO
+     *
+     * The Windows run logged its own mechanism rather than inferring it — the
+     * absent-camera enumerate recorded "Tiny 2 in its list = false", so there was
+     * no path to cache and the arrival died at helper.cpp:1022.
+     *
+     * PRIMING REPEATS ON EVERY CALL, and that is Windows insurance specifically.
+     * macOS does NOT need it — measured across two full replug cycles, a watcher
+     * primed once at startup kept delivering (arrived=2, departed=2), identical
+     * to one that re-primed after every departure. The prime is a one-time
+     * activation there, not a lease. On Windows a watcher whose predecessor DIED
+     * during an absence gets replaced while the camera is gone, never caches the
+     * path, and never self-corrects, because the guard below would otherwise
+     * early-return on a watcher that is alive and useless. Hardware-confirmed on
+     * Windows: that scenario ends `available`, never `bound`, with no arrival ever
+     * seen — where the same code on macOS recovers.
+     *
+     * So the repeat only helps at a moment the camera is PRESENT. Re-priming
+     * during an absence is a no-op on Windows; only the next successful bind can
+     * cure a deaf watcher there.
+     *
+     * Costs one idle process once a camera has been bound. It opens nothing, so
+     * it holds no exclusive USB handle and the camera stays available to Zoom,
+     * OBS and OBSBOT Center — the constraint that shaped handleCameraArrived.
+     */
+    async ensureWatcher() {
+        if (this.everBound.size === 0)
+            return; // never ours — stay hands-off
+        try {
+            if (!this.watcher || this.watcher.isDead)
+                this.watcher = await this.makeHelper();
+            await this.watcher.enumerate(); // the touch that starts delivery — see above
+        }
+        catch (e) {
+            // NEVER fatal. This runs AFTER promote(), so throwing would escape bind()
+            // with the camera already in the registry: the caller sees an exception
+            // while listCameras() reports it bound. The watcher only buys a proactive
+            // re-bind — without it recovery falls back to the failure-driven path,
+            // which is one extra call, exactly where things stood before it existed.
+            //
+            // Self-healing by construction: a spawn failure leaves `watcher`
+            // undefined and a prime failure leaves it unprimed, and either way the
+            // next ensureWatcher() call retries. Logged because a self-heal that
+            // fails quietly is the failure mode that cost a day of debugging.
+            this.log(`obsbot-mcp: bus watcher unavailable (${errText(e)}); ` +
+                `replug recovery falls back to the next tool call`);
+        }
+    }
+    async getScanHelper() {
+        // A cached scan helper whose process has died must be discarded, not
+        // handed back. invalidate() only drops REGISTRY entries, so a helper that
+        // died mid-scan (before promote() moved it into the registry) would
+        // otherwise stay cached here and every later scan would talk to a corpse —
+        // the one path where failing fast on the transport isn't enough to recover.
+        if (this.scanHelper?.isDead)
+            this.scanHelper = undefined;
+        if (!this.scanHelper) {
+            this.scanHelper = await this.makeHelper();
+        }
+        return this.scanHelper;
+    }
+    /**
+     * Compat: raw enumerate() pass-through (unfiltered, no serials). Used by
+     * obsbot_capture_snapshot's virtual/ndi source lookup, not by obsbot_devices
+     * (which reports the identified fleet via listCameras() instead).
+     */
     async list() {
-        return this.helper.enumerate();
+        const helper = await this.getScanHelper();
+        return helper.enumerate();
+    }
+    /**
+     * Scan attached candidates on the scratch helper for a camera to bind.
+     *
+     * - `wantSerial` given: stop at the first candidate whose serial matches;
+     *   throws UnknownCameraError (listing every identifiable serial seen)
+     *   if the scan exhausts without a match.
+     * - `wantSerial` omitted: every candidate must be probed so the full
+     *   fleet is known — a partial scan could under-report ambiguity or
+     *   silently pick the wrong "only" camera. Binds if exactly one distinct
+     *   serial turns up; throws AmbiguousCameraError (all distinct serials)
+     *   if more than one does; throws if none do.
+     */
+    async bind(wantSerial) {
+        const helper = await this.getScanHelper();
+        const devices = await helper.enumerate();
+        const candidates = devices.filter(isObsbotCamera);
+        const found = new Map();
+        let matched;
+        // Why each candidate was passed over. Every `continue` below is a silent
+        // rejection, and when they ALL reject the caller used to get a bare "no
+        // OBSBOT camera found" — the same message it gets with nothing plugged in.
+        // Carrying the reasons into the error is the difference between "no camera"
+        // and "the camera is right there but wouldn't answer".
+        const rejected = [];
+        for (const d of candidates) {
+            let xuNode;
+            try {
+                xuNode = await helper.open(d.path);
+            }
+            catch (e) {
+                // ANY open failure (exclusive access or otherwise) — skip, not
+                // fatal. The next candidate's open() releases this attempt.
+                rejected.push(`${d.path}: open failed: ${errText(e)}`);
+                continue;
+            }
+            if (xuNode < 0) {
+                // Opened, but this node has no XU unit (e.g. the metadata/ISP node
+                // the Tiny 2 also exposes) — not a usable candidate.
+                rejected.push(`${d.path}: opened but has no XU unit`);
+                continue;
+            }
+            const transport = this.createTransport(helper);
+            let serial;
+            try {
+                serial = await transport.readSerial();
+            }
+            catch (e) {
+                rejected.push(`${d.path}: ${errText(e)}`);
+                continue;
+            }
+            if (!found.has(serial))
+                found.set(serial, { locationId: d.locationId, name: d.name });
+            matched = { transport, serial, locationId: d.locationId, path: d.path, name: d.name };
+            if (wantSerial && serial === wantSerial)
+                break;
+        }
+        if (wantSerial) {
+            if (matched && matched.serial === wantSerial) {
+                this.promote(matched);
+                await this.ensureWatcher();
+                return { transport: matched.transport, serial: matched.serial };
+            }
+            throw new UnknownCameraError(wantSerial, [...found.keys()]);
+        }
+        if (found.size === 0) {
+            // A helper that SAW a camera and still could not bind it is suspect —
+            // drop it rather than cache it for the next attempt.
+            //
+            // Hardware, 2026-07-21 replug: the macOS helper derives `path` from
+            // AVFoundation, whose device list lags the USB bus and, in a long-lived
+            // process, did not refresh at all. A helper spawned while the camera was
+            // unplugged therefore kept enumerating it with vid/pid but an EMPTY path
+            // — unopenable — for over two minutes, while a freshly spawned process
+            // saw the device immediately. Retrying on the cached helper could never
+            // converge; only a new process could.
+            //
+            // Deliberately UNCONDITIONAL, including when the bus looks empty.
+            //
+            // It is tempting to narrow this to "only when a candidate was rejected",
+            // since a helper reporting an empty bus looks healthy and the churn is
+            // real — the verified run forked 16 processes in 15s. That narrowing was
+            // written, unit-tested, and then REVERTED: in the hardware run that
+            // actually recovered, every retry during the recovery window reported an
+            // empty bus with NO rejected candidate, and it recovered precisely
+            // because each attempt forked a fresh process with a fresh IOKit/
+            // AVFoundation view. Keeping the helper in that case would restore the
+            // bug. A stale process can under-report the bus as empty, so "empty" is
+            // not evidence the helper is healthy.
+            //
+            // Cost is bounded: one spawn (~60ms) per FAILED bind, nothing on the
+            // happy path, and it stops as soon as a camera binds.
+            await this.discardScanHelper();
+            // That discard just closed what may have been the only process left. If
+            // the watcher had already died and nothing was bound, this failing call
+            // is the ONLY signal that the camera went away — the unplug itself was
+            // heard by nobody. Restore the listener (never the scanner, which stays
+            // unconditionally fresh) before throwing, or the replug that follows is
+            // silent too and costs a second failed call.
+            await this.ensureWatcher();
+            // With nothing attached there is nothing to explain, so that message
+            // stays exactly as it was.
+            throw new Error(rejected.length === 0
+                ? "no OBSBOT camera found"
+                : `no OBSBOT camera found — ${rejected.length} candidate(s) rejected: ${rejected.join("; ")}`);
+        }
+        if (found.size > 1) {
+            throw new AmbiguousCameraError([...found.keys()]);
+        }
+        // Exactly one distinct serial: `matched` is guaranteed bound to it
+        // (every successful candidate shared that one serial).
+        this.promote(matched);
+        await this.ensureWatcher();
+        return { transport: matched.transport, serial: matched.serial };
+    }
+    /** Move the current scratch helper into the registry under `m.serial`. */
+    promote(m) {
+        // Reconnect bookkeeping BEFORE recording the bind: if we've bound this
+        // serial before, this promote is a re-bind (self-heal after a disconnect),
+        // so flag it reconnected. The very first bind of a serial is never a
+        // reconnect. everBound must NOT be gated on the registry (invalidate drops
+        // registry entries) — that's the whole point of tracking it separately.
+        if (this.everBound.has(m.serial))
+            this.reconnectedSerials.add(m.serial);
+        this.everBound.add(m.serial);
+        this.registry.set(m.serial, {
+            helper: this.scanHelper,
+            transport: m.transport,
+            locationId: m.locationId,
+            path: m.path,
+            name: m.name,
+        });
+        // This helper now belongs to the registry entry; the next scan needs
+        // its own (lazily spawned on next use).
+        this.scanHelper = undefined;
+    }
+    /**
+     * Whether the camera identified by `serial` (or, with no arg, the single
+     * bound camera) was RE-bound after a prior bind — i.e. self-healed across a
+     * mid-session disconnect — clearing that flag on read. Single-camera
+     * semantics (no serial): return true if ANY serial is pending-reconnected,
+     * draining them all. Preserves the exact contract the retired
+     * DeviceSession.takeReconnected() had.
+     */
+    takeReconnected(serial) {
+        if (serial !== undefined) {
+            const r = this.reconnectedSerials.has(serial);
+            this.reconnectedSerials.delete(serial);
+            return r;
+        }
+        if (this.reconnectedSerials.size === 0)
+            return false;
+        this.reconnectedSerials.clear();
+        return true;
     }
+    /**
+     * Drop bound camera(s) from the registry so the next get()/bind() spawns a
+     * fresh scratch helper and re-scans from scratch — the correct move after
+     * a device has re-enumerated (e.g. unplug/replug), since a stale cached
+     * transport talks to a helper that may no longer own a live handle.
+     * Closing each dropped helper is best-effort: a helper whose native
+     * session already died (the common case right after a disconnect) can
+     * throw on close(), and that must not stop the entry from being dropped.
+     *
+     *   serial given -> drop just that camera (no-op if it isn't bound)
+     *   no serial    -> drop every bound camera
+     */
+    async invalidate(serial) {
+        const drop = async (s, entry) => {
+            try {
+                await entry.helper.close();
+            }
+            catch {
+                // best-effort — a dead/disconnected helper's close() may itself throw
+            }
+            this.registry.delete(s);
+        };
+        if (serial) {
+            const entry = this.registry.get(serial);
+            if (entry)
+                await drop(serial, entry);
+            return;
+        }
+        await Promise.all([...this.registry].map(([s, entry]) => drop(s, entry)));
+    }
+    /**
+     * Drop registry entries whose helper process has died, so the next resolve
+     * re-binds instead of handing back a transport that can only ever fail.
+     *
+     * "Once bound, stay bound" is the right default, but a bound entry whose
+     * helper is GONE isn't a binding — it's a corpse. Without this, only the
+     * tools that route through ensureReady() (which calls invalidate()) could
+     * recover; every other tool resolved straight through get() and returned the
+     * same dead transport forever. Recovery then required the caller to happen to
+     * invoke a different tool — and the caller here is an LLM, which will instead
+     * retry the failing tool or report broken hardware that is actually fine.
+     *
+     * Deliberately a `dead` check and not a liveness probe: it costs a boolean,
+     * adds no round trip to the hot path, and leaves a LIVE binding untouched (a
+     * guard that re-scanned every call would spawn a helper per tool call).
+     *
+     * A wedged-but-alive helper is intentionally NOT caught here — that is the
+     * per-request timeout's job, and condemning a session for one slow op would
+     * throw away a working binding.
+     */
+    async pruneDeadEntries() {
+        for (const [serial, entry] of this.registry) {
+            // `deviceLost` covers the unplug case, where the helper PROCESS is alive
+            // and healthy but the camera behind it is gone. Hardware-tested
+            // 2026-07-21: without this, a replug left every call failing forever —
+            // the handle was stranded and only killing the helper recovered it,
+            // because process death was the only condition anything watched for.
+            if (!entry.helper.isDead && !entry.helper.deviceLost)
+                continue;
+            // CLOSE, don't just forget. A device-lost helper is still RUNNING and
+            // still holding the USB device, so dropping the reference alone leaks the
+            // process and the replacement helper can never open the camera. The first
+            // cut of this fix did exactly that and turned one stranded handle into a
+            // helper leak — every retry spawned another one and recovery never
+            // happened. (A dead helper's close() is a harmless no-op, same as in
+            // invalidate(), which has always closed-then-deleted for this reason.)
+            try {
+                await entry.helper.close();
+            }
+            catch {
+                // best-effort — a disconnected helper's close() may itself throw
+            }
+            this.registry.delete(serial);
+        }
+    }
+    /**
+     * Resolve to a bound transport.
+     *   no serial + one camera attached  -> bind & return it
+     *   no serial + several attached     -> AmbiguousCameraError
+     *   serial given + match             -> bind (lazily) & return
+     *   serial given + no match          -> UnknownCameraError
+     * Already-bound cameras are returned directly from the registry without
+     * rescanning — "bind lazily" means once bound, stay bound.
+     */
+    async get(serial) {
+        await this.pruneDeadEntries();
+        if (serial) {
+            const existing = this.registry.get(serial);
+            if (existing)
+                return existing.transport;
+            const { transport } = await this.bind(serial);
+            return transport;
+        }
+        if (this.registry.size === 1) {
+            return [...this.registry.values()][0].transport;
+        }
+        if (this.registry.size > 1) {
+            throw new AmbiguousCameraError([...this.registry.keys()]);
+        }
+        const { transport } = await this.bind();
+        return transport;
+    }
+    /**
+     * The OS reported a camera detached. Drop any binding on that path now,
+     * instead of waiting for a tool call to fail against a dead handle.
+     *
+     * Without this the registry stays authoritative until something errors, so
+     * `obsbot_devices` reports a phantom `bound` entry — serial and all — for a
+     * camera physically sitting on the desk. The prune is otherwise reactive:
+     * `deviceLost` is only set when an op fails, and listCameras() deliberately
+     * does not re-open bound entries to check.
+     *
+     * Closes the helper rather than merely forgetting it, for the same reason
+     * pruneDeadEntries() does: a helper left running still holds the device, so
+     * the replacement could never open it.
+     */
+    async handleCameraDeparted(e) {
+        for (const [serial, entry] of this.registry) {
+            if (entry.path !== e.path)
+                continue;
+            try {
+                await entry.helper.close();
+            }
+            catch {
+                // best-effort — a disconnected helper's close() may itself throw
+            }
+            this.registry.delete(serial);
+        }
+        // The close above may have removed the last live subscriber, and the arrival
+        // this departure pairs with has not happened yet. Replacing the watcher here
+        // matters when it died unnoticed while the camera was bound: the registry
+        // helper was still alive to hear THIS event, but nothing would be alive to
+        // hear the next one.
+        //
+        // The replacement is necessarily spawned with the camera absent, which
+        // primes it on macOS but not on Windows — see ensureWatcher(). On Windows
+        // this degrades to the failure-driven path and the next successful bind
+        // re-primes it, so the call is worth making on both.
+        await this.ensureWatcher();
+    }
+    /**
+     * The OS reported a camera attached. Re-establish a binding this process
+     * ALREADY held — a genuine self-heal after a replug — and nothing more.
+     *
+     * Deliberately does not bind a camera we never had. The Tiny 2 is a device
+     * Zoom, OBS and OBSBOT Center also want, and a server that grabbed it the
+     * moment it appeared would make it busy for them even if nobody ever used
+     * this server. `everBound` is the record of what was ours; it survives
+     * invalidate() precisely so a re-bind can be recognised as a reconnect.
+     *
+     * Never throws: the caller is a stdout line handler, and an unhandled
+     * rejection there would take down the reader and wedge every in-flight
+     * request. A failed re-bind just leaves the next tool call to bind normally.
+     */
+    async handleCameraArrived(_e) {
+        if (this.everBound.size === 0)
+            return; // never ours — stay hands-off
+        // Something is already bound, so there is nothing to restore.
+        if (this.registry.size > 0)
+            return;
+        // One ladder at a time. Two would double the helper spawns and race two
+        // binds into promote(), which assumes the scratch helper is still there.
+        if (this.rebinding)
+            return;
+        this.rebinding = true;
+        const total = this.arrivalBackoffMs.length;
+        try {
+            for (let i = 0; i < total; i++) {
+                const delay = this.arrivalBackoffMs[i];
+                if (delay > 0)
+                    await new Promise((r) => setTimeout(r, delay));
+                // A tool call may have bound it while we waited — it got there first.
+                if (this.registry.size > 0)
+                    return;
+                try {
+                    await this.bind();
+                    // Silent on the happy path; every replug would otherwise print. A
+                    // retried success is worth a line precisely because it is the only
+                    // evidence the ladder ever does anything.
+                    if (i > 0)
+                        this.log(`obsbot-mcp: arrival re-bind succeeded on attempt ${i + 1}`);
+                    return;
+                }
+                catch (e) {
+                    // Keep trying: see the backoff's own comment for why one attempt is
+                    // a coin flip. Arrival is still only a hint — if the ladder runs out
+                    // the next tool call binds normally.
+                    this.log(`obsbot-mcp: arrival re-bind attempt ${i + 1}/${total} failed: ${errText(e)}`);
+                }
+            }
+            this.log(`obsbot-mcp: arrival re-bind gave up after ${total} attempts; ` +
+                `the next tool call will bind normally`);
+        }
+        finally {
+            this.rebinding = false;
+        }
+    }
+    /**
+     * Close everything this manager is holding: registry helpers, the scratch
+     * scanner, and the watcher.
+     *
+     * Helpers already self-terminate when the parent goes away — they exit on
+     * stdin EOF — so this is not what stops them leaking on a crash. It exists
+     * because the watcher is the first helper deliberately built to outlive every
+     * operation: nothing else bounds its lifetime, so an orderly stop needs
+     * something explicit to call. Best-effort throughout; a shutdown path that can
+     * itself throw is worse than one that leaves a process for the OS to reap.
+     */
+    async shutdown() {
+        const close = async (h) => {
+            if (!h)
+                return;
+            try {
+                await h.close();
+            }
+            catch {
+                // best-effort — a disconnected helper's close() may itself throw
+            }
+        };
+        const watcher = this.watcher;
+        this.watcher = undefined;
+        await Promise.all([
+            ...[...this.registry.values()].map((e) => close(e.helper)),
+            this.discardScanHelper(),
+            close(watcher),
+        ]);
+        this.registry.clear();
+    }
+    /** Compat shim for the single-camera API B1 retires. */
     async openFirstObsbot() {
-        const devices = await this.list();
-        const obsbotDevices = devices.filter((d) => /obsbot/i.test(d.name));
-        if (obsbotDevices.length === 0) {
-            throw new Error("no OBSBOT Tiny 2 found");
-        }
-        // The OBSBOT exposes two /dev/videoN nodes: one is the video capture
-        // interface (has the vendor XU extension unit), the other is metadata/ISP
-        // (no XU). Try each in turn until we find one with an XU unit.
-        const errors = [];
-        for (const device of obsbotDevices) {
+        return this.get();
+    }
+    /**
+     * Per attached camera: serial (where obtainable), locationId, name, and
+     * status. A camera this process cannot open is reported `busy` WITHOUT a
+     * serial rather than omitted — it is enumerable but not identifiable.
+     * Already-bound cameras are reported from the registry without
+     * re-opening (avoids a pointless self-conflict against our own handle).
+     */
+    async listCameras() {
+        // Registry entries are reported as `bound` without re-opening them, so a
+        // stale one is indistinguishable from a healthy camera. Observed on
+        // hardware 2026-07-21: obsbot_devices kept reporting status:"bound" with a
+        // serial for a camera that was physically UNPLUGGED — a caller reads that
+        // as "present and ready", which is exactly backwards.
+        await this.pruneDeadEntries();
+        const results = [];
+        const seenSerials = new Set();
+        const boundLocationIds = new Set();
+        const boundPaths = new Set();
+        for (const [serial, entry] of this.registry) {
+            results.push({ serial, locationId: entry.locationId, name: entry.name, status: "bound" });
+            seenSerials.add(serial);
+            if (entry.locationId !== undefined)
+                boundLocationIds.add(entry.locationId);
+            boundPaths.add(entry.path);
+        }
+        const helper = await this.getScanHelper();
+        const devices = await helper.enumerate();
+        const candidates = devices.filter(isObsbotCamera);
+        for (const d of candidates) {
+            // locationId is macOS-only (undefined on Linux/Windows); `path` is
+            // populated on every platform, so it's the dedup key that actually
+            // works cross-platform. Without it, a bound camera off-macOS gets
+            // re-opened here, collides with the registry helper's own held-open
+            // handle, and is double-reported a second time as a serial-less
+            // "busy" entry alongside its correct "bound" one.
+            if (boundPaths.has(d.path)) {
+                continue; // already reported as bound above
+            }
+            if (d.locationId !== undefined && boundLocationIds.has(d.locationId)) {
+                continue; // already reported as bound above
+            }
             try {
-                const xuNode = await this.helper.open(device.path);
-                if (xuNode >= 0)
-                    return this.createTransport();
-                errors.push(`${device.path}: no XU unit`);
+                const xuNode = await helper.open(d.path);
+                if (xuNode < 0)
+                    continue;
+                const transport = this.createTransport(helper);
+                const serial = await transport.readSerial();
+                if (seenSerials.has(serial))
+                    continue; // duplicate node of an already-listed camera
+                seenSerials.add(serial);
+                results.push({ serial, locationId: d.locationId, name: d.name, status: "available" });
             }
             catch (e) {
-                errors.push(`${device.path}: ${e.message}`);
+                results.push({
+                    locationId: d.locationId,
+                    name: d.name,
+                    status: "busy",
+                    reason: errText(e),
+                });
             }
         }
-        throw new Error(`could not open any OBSBOT device:\n  ${errors.join("\n  ")}`);
+        return results;
     }
 }
 //# sourceMappingURL=manager.js.map