@khalido/home 0.1.0 → 0.1.2

package/dist/connectors/spotify/index.js

@@ -33,10 +33,12 @@ const COMMAND_TIMEOUT_MS = 3000;
 const QUERY_TIMEOUT_MS = 1000;
 /** A socket that has said nothing this long after opening is closed: Soloist sends `auth_state` at once on connect. */
 const HELLO_MS = 10_000;
-/** After an idle → playing change, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
+/** After a start signal, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
 const CAP_WINDOW_MS = 10_000;
 /** How long a write waits for Soloist to report the change it asked for. Loopback events arrive in milliseconds; a stated guess. */
 const CONFIRM_MS = 2000;
+/** Between the two halves of `setRepeat`: back to back left repeat on `track`, 600 ms apart worked (live, 2026-11-09). */
+const REPEAT_GAP_MS = 600;
 /** Between two commands. Soloist publishes no limit; it is on loopback; a stated guess. */
 const WRITE_GAP_MS = 100;
 /** While playing, a stall check this often: one `get_state`. Soloist issue #5 reports stalls 71–150 s into a track; a stated guess. */
@@ -45,6 +47,8 @@ const STALL_CHECK_MS = 20_000;
 const OVERRUN_MS = 15_000;
 /** After a repair's seek, how long before looking whether the position moves again. */
 const REPAIR_WAIT_MS = 5000;
+/** A reported volume is rounded (phone steps are sixteenths: 43.75 shows as 44), so "it took" allows this much. */
+const VOLUME_SLACK = 1;
 const MIN_BACKOFF_MS = 1000;
 const MAX_BACKOFF_MS = 60_000;
 /** Signed out is Soloist's normal state until someone picks the speaker (seen live 2026-11-08); a bad key looks the same (issue #18). */
@@ -78,15 +82,17 @@ export function spotify(config = {}) {
     const checkMs = config.stallCheckMs ?? STALL_CHECK_MS;
     let state = { asOf: asOf(clock) };
     let socket;
-    let open = false;
-    let heard = false; // an auth_state on this socket: until then the part stays connecting
-    let whole = false; // signed in, the first playback_state has come too (or HELLO_MS passed): a one-shot read sees the track
+    // This socket's progress. "heard": signed in, the first playback_state still to come. "whole": a one-shot read sees the track (or HELLO_MS passed).
+    let link = "down";
+    const isOpen = () => link !== "down";
     let down; // why the last socket ended, while there is none open
     let statusKnown = false; // Soloist has told this socket its status: only then is idle → playing an edge
     let queueAsked = false; // get_queue sent on this socket
     let signedIn = false; // signed out → in on this socket: the first status after it counts as a start if it is playing
     let capUntil = -Infinity;
-    let capped = false; // the cap has been sent in this window
+    let capped = false; // the cap took in this window
+    let capping = false; // a lowering is on its way
+    let startBuffering = false; // a start from idle is still buffering
     let capNote; // the last first-play lowering, in `anomaly` until the speaker goes idle
     let frameNote; // a frame the schema rejected, or an error nothing was waiting for
     let note; // a write the integration made itself that failed (the cap, interrupt's resume), in `detail`
@@ -98,10 +104,10 @@ export function spotify(config = {}) {
     const publish = () => {
         let status;
         let detail;
-        if (!open)
+        if (link === "down")
             ((status = reported || down ? "disconnected" : "connecting"),
                 (detail = down));
-        else if (!heard || (state.loggedIn === true && !whole))
+        else if (link !== "whole")
             status = "connecting";
         else
             ((status = "connected"),
@@ -127,7 +133,7 @@ export function spotify(config = {}) {
      */
     const command = (name, fields = {}, answers) => new Promise((resolve, reject) => {
         const s = socket;
-        if (!s || !open || s.readyState !== OPEN)
+        if (!s || !isOpen() || s.readyState !== OPEN)
             return reject(offline());
         if (state.loggedIn === false && !answers)
             return reject(new ConnectorError(WAITING, { code: "waiting" }));
@@ -156,11 +162,17 @@ export function spotify(config = {}) {
             p.finish(new ConnectorError(`Soloist did not answer ${name} in ${ms / 1000} s`, { code: "timeout" })));
     });
     const send = async (body) => {
+        if (body.activeFirst && inactive()) {
+            await command("activate").catch(() => { }); // best effort: the write itself says how it went
+            await waitFor(() => state.active === true || !isOpen(), CONFIRM_MS);
+        }
         const before = state;
         const at = clock.now();
         await command(body.command, body.fields, body.answers);
-        if (body.then)
+        if (body.then) {
+            await clock.sleep(REPEAT_GAP_MS);
             await command(body.then.command, body.then.fields); // repeat's second half, still this write's turn
+        }
         return { before, at };
     };
     let once = 0; // skips and queued tracks never merge: two nexts are two skips
@@ -173,7 +185,7 @@ export function spotify(config = {}) {
     const change = async (slot, body) => {
         const sent = await write(slot, body);
         const took = () => body.took?.(state, sent.before, sent.at) ?? true;
-        await waitFor(() => took() || !open, CONFIRM_MS);
+        await waitFor(() => took() || !isOpen(), CONFIRM_MS);
         return { state, confirmed: took() };
     };
     /** The track restarted: a new anchor near 0 when it had been 5 s or more in (a prev past the first seconds, a next on repeat-track). */
@@ -182,11 +194,14 @@ export function spotify(config = {}) {
         (positionMs(b, at) ?? 0) >= 5000;
     const newTrack = (s, b) => !!s.track && s.track.uri !== b.track?.uri;
     const invalid = (message) => new ConnectorError(message, { code: "invalid" });
+    const near = (volume, v) => volume !== undefined && Math.abs(volume - v) <= VOLUME_SLACK;
     const volumeTo = (v) => change("volume", {
         command: "set_volume",
         fields: { volume: v },
-        took: (s) => s.volume === v,
+        took: (s) => near(s.volume, v),
     });
+    /** Soloist accepts a `set_volume` while it isn't the active device and drops it (three times live, 2026-11-09). */
+    const inactive = () => isOpen() && state.loggedIn !== false && state.active === false;
     /** Ask Soloist for something, through the lane; the same query twice merges. A refusal is an anomaly, a drop is the status's to say. */
     const ANSWERS = {
         get_state: "playback_state",
@@ -206,22 +221,48 @@ export function spotify(config = {}) {
         frameNote = `${name} failed: ${errorText(error)}`;
         publish();
     });
-    /** Within the window after idle → playing, a volume above the cap is lowered to it, once (issue #23). */
+    /**
+     * Within the window after a start signal, a volume above the cap is lowered to it (issue #23). Only while active, since
+     * Soloist drops it otherwise, and retried until Soloist reports it. A volume raised after that is someone's choice;
+     * one raised before it is reported can't be told from the start's own jump, so it is lowered too.
+     */
     const applyCap = () => {
         if (cap === undefined ||
             capped ||
+            capping ||
             state.volume === undefined ||
-            clock.now() > capUntil ||
-            state.volume <= cap)
+            state.volume <= cap + VOLUME_SLACK ||
+            state.active === false ||
+            clock.now() > capUntil)
             return;
-        capped = true;
-        capNote = `started at volume ${state.volume}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
-        change("volume", {
-            command: "set_volume",
-            fields: { volume: cap },
-            took: (s) => s.volume === cap,
-        }).catch((error) => ((note = `lowering the volume to ${cap} failed: ${errorText(error)}`),
-            publish()));
+        capping = true;
+        const from = state.volume;
+        const window = capUntil;
+        volumeTo(cap).then(({ confirmed }) => {
+            capping = false;
+            if (capUntil !== window)
+                return applyCap(); // a new start while it went: this lowering doesn't speak for that one
+            if (confirmed) {
+                capped = true;
+                if (state.status === "idle")
+                    return;
+                capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
+                note = undefined;
+                return publish();
+            }
+            if (clock.now() > capUntil) {
+                note = `could not lower the volume to ${cap}: Soloist has not reported it`;
+                return publish();
+            }
+            applyCap();
+        }, (error) => {
+            capping = false;
+            if (error instanceof ConnectorError && error.code === "offline")
+                return; // the status says it
+            capped = true; // refused or unanswered: not again this window
+            note = `lowering the volume to ${cap} failed: ${errorText(error)}`;
+            publish();
+        });
     };
     const handle = (data) => {
         let raw;
@@ -253,12 +294,17 @@ export function spotify(config = {}) {
         }
         const before = state.status;
         const wasSignedIn = state.loggedIn;
+        const wasActive = link === "open" ? undefined : state.active; // the first frames on a socket are not a change
         state = fold(state, f, asOf(clock));
+        if (state.track?.uri !== repairedFor)
+            repairedFor = undefined; // one repair per play of a track
+        // Going active makes a new stream, at WirePlumber's saved level (live, 2026-11-09): the likeliest moment for a loud start.
+        if (wasActive === false && state.active === true)
+            ((capUntil = clock.now() + CAP_WINDOW_MS), (capped = false));
         if (f.type === "auth_state") {
             // Signed out there is no playback_state to wait for, and a later sign-in must not send the part back to connecting.
-            if (!heard && f.logged_in !== true)
-                whole = true;
-            heard = true;
+            if (link === "open" || (link === "heard" && f.logged_in === false))
+                link = f.logged_in === true ? "heard" : "whole";
             if (f.logged_in === false)
                 statusKnown = false;
             // A first sign-in (someone picked the speaker) sends only auth_state; the docs don't promise a playback_state after it.
@@ -268,16 +314,20 @@ export function spotify(config = {}) {
         if (f.type === "playback_state") {
             if (!queueAsked)
                 ((queueAsked = true), query("get_queue", { limit: 10 })); // queue_changed pushes changes only, so ask once per socket
-            whole = true;
+            link = "whole";
         }
         if (pending?.answers === f.type)
             pending.finish();
         if ((f.type === "playback_state" || f.type === "playback_changed") &&
             f.status !== undefined) {
-            // A start is idle → playing, or a sign-in whose first status is playing: a phone picked the speaker and played (issue #23).
-            const started = f.status === "playing" && (statusKnown ? before === "idle" : signedIn);
+            // A start is idle → playing or buffering, or a sign-in whose first status is either: a phone picked the speaker and played.
+            // The volume can land just after `playing` (issue #23), so a start through buffering opens the window again then.
+            const started = ((f.status === "playing" || f.status === "buffering") &&
+                (statusKnown ? before === "idle" : signedIn)) ||
+                (f.status === "playing" && startBuffering);
             if (started)
                 ((capUntil = clock.now() + CAP_WINDOW_MS), (capped = false));
+            startBuffering = f.status === "buffering" && (started || startBuffering);
             signedIn = false;
             if (f.status === "idle")
                 capNote = undefined;
@@ -314,13 +364,12 @@ export function spotify(config = {}) {
             signal.removeEventListener("abort", stop);
             if (socket === s)
                 socket = undefined;
-            const was = open;
-            open = false;
-            heard = false;
-            whole = false;
+            const was = isOpen();
+            link = "down";
             queueAsked = false;
             statusKnown = false;
             signedIn = false;
+            startBuffering = false;
             pending?.finish(offline());
             for (const w of [...waiters])
                 w(); // a write waiting to confirm stops waiting
@@ -329,21 +378,24 @@ export function spotify(config = {}) {
         };
         const stop = () => (end("stopped"), s.close());
         signal.addEventListener("abort", stop, { once: true });
+        // An ended socket's late events belong to no session: they must not touch the next socket's state.
         s.onopen = () => {
-            open = true;
+            if (ended)
+                return;
+            link = "open";
             down = undefined;
             note = undefined; // a new socket: what failed on the last one is history
             void clock.sleep(HELLO_MS, quiet.signal).then(() => {
                 if (quiet.signal.aborted)
                     return;
-                if (!heard)
+                if (link === "open")
                     return (end(`Soloist said nothing in ${HELLO_MS / 1000} s`),
                         s.close());
-                if (!whole)
-                    ((whole = true), publish()); // signed in, no playback_state: connected with what there is
+                if (link === "heard")
+                    ((link = "whole"), publish()); // signed in, no playback_state: connected with what there is
             });
         };
-        s.onmessage = (ev) => handle(ev.data);
+        s.onmessage = (ev) => void (ended || handle(ev.data));
         s.onerror = () => { }; // onclose follows and says it
         s.onclose = () => end("Soloist closed the socket");
     });
@@ -358,7 +410,7 @@ export function spotify(config = {}) {
         waiters.delete(check);
     };
     /** Not connected or not playing: the reason `duck` and `interrupt` just run `fn`. */
-    const notPlaying = () => !open
+    const notPlaying = () => !isOpen()
         ? "Soloist is not connected"
         : state.status === "playing" || state.status === "buffering"
             ? undefined
@@ -379,7 +431,7 @@ export function spotify(config = {}) {
      */
     const aside = (kind, fn, enter, leave) => {
         const run = async () => {
-            if (open)
+            if (isOpen())
                 marked(kind);
             try {
                 return await within();
@@ -414,10 +466,20 @@ export function spotify(config = {}) {
             why: failed(`sent the ${what}; Soloist has not reported it`),
         };
     const actions = {
+        async activate() {
+            if (isOpen() && state.loggedIn !== false && state.active === true)
+                return { state, confirmed: true }; // a second activate might make a new stream
+            return change("activate", {
+                command: "activate",
+                took: (s) => s.active === true,
+            });
+        },
+        // A `play` while inactive didn't take live; going active first is untested for this. `resume` worked inactive, so it doesn't.
         async play(linkOrUri) {
             if (linkOrUri === undefined)
                 return change("transport", {
                     command: "play",
+                    activeFirst: true,
                     took: (s) => s.status === "playing",
                 });
             const uri = toSpotifyUri(linkOrUri);
@@ -426,6 +488,7 @@ export function spotify(config = {}) {
             return change("transport", {
                 command: "play",
                 fields: { uri },
+                activeFirst: true,
                 took: (s) => s.status === "playing" &&
                     (s.track?.uri === uri || s.context?.uri === uri),
             });
@@ -462,6 +525,8 @@ export function spotify(config = {}) {
         async setVolume(volume) {
             if (!Number.isFinite(volume) || volume < 0 || volume > 100)
                 throw invalid(`volume is 0–100, not ${volume}`);
+            if (inactive())
+                throw new ConnectorError("the speaker is not the active Spotify device, so Soloist would drop this; activate it first (`home spotify activate`; its volume may jump to the level last saved)", { code: "inactive" });
             return volumeTo(Math.round(cap === undefined ? volume : Math.min(volume, cap)));
         },
         async queue(track) {
@@ -535,6 +600,8 @@ export function spotify(config = {}) {
                 const no = notPlaying();
                 if (no)
                     return no;
+                if (inactive())
+                    return "it is not the active device, so its volume can't be changed";
                 if (state.volume === undefined)
                     return "its volume is not known";
                 if (state.volume <= to)
@@ -547,7 +614,7 @@ export function spotify(config = {}) {
                     return failed(`lowering the volume for duck failed: ${errorText(error)}`);
                 }
             }, async () => {
-                if (state.volume !== Math.round(to))
+                if (!near(state.volume, Math.round(to)))
                     return {
                         music: "kept",
                         why: shown
@@ -584,7 +651,7 @@ export function spotify(config = {}) {
         state = rest;
     }
     let seen; // the last check's reported position
-    let repairedFor; // at most one repair per track
+    let repairedFor; // at most one repair per play of a track
     /** Ask Soloist where it is, waiting for the answer (or the query's timeout). */
     const fresh = () => write("query-get_state", {
         command: "get_state",
@@ -605,7 +672,7 @@ export function spotify(config = {}) {
         a.track === b.track &&
         b.atMs - a.atMs >= gap &&
         Math.abs(b.ms - a.ms) < 1000;
-    const playing = () => open && state.status === "playing" && !state.aside;
+    const playing = () => isOpen() && state.status === "playing" && !state.aside;
     /** One look while playing: a fresh position, then frozen, overrun, recovered or fine (Soloist issue #5). */
     const checkStall = async () => {
         if (!playing())
@@ -645,7 +712,7 @@ export function spotify(config = {}) {
         repairedFor = track;
         const tried = (what) => state.stalled && stallAs({ ...state.stalled, tried: what });
         // Still ours to fix: playing this track, stalled, and no duck, interrupt or person in between.
-        const ours = () => open &&
+        const ours = () => isOpen() &&
             state.status === "playing" &&
             state.track?.uri === track &&
             state.stalled?.track === track &&
@@ -689,8 +756,10 @@ export function spotify(config = {}) {
         /** Ask Soloist for its state again (`get_state`, or `get_auth_state` without a session); while it is unreachable, reconnect now. */
         refresh() {
             const s = socket;
-            if (s && open && s.readyState === OPEN)
-                return query(state.loggedIn === false || !heard ? "get_auth_state" : "get_state");
+            if (s && isOpen() && s.readyState === OPEN)
+                return query(state.loggedIn === false || link === "open"
+                    ? "get_auth_state"
+                    : "get_state");
             wake?.abort();
         },
         async run(signal, update) {

package/dist/connectors/up/index.d.ts

@@ -82,8 +82,10 @@ export declare function toSnapshot(txs: Transaction[], categories: Category[], a
     truncated: boolean;
     household?: Household;
 }): UpSnapshot;
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
-export declare function up(config: UpConfig): Integration<UpSnapshot, "up">;
+/** Up as a home integration: two months of transactions now, then every 15 minutes. The integration only reads; `client` is there for a consumer's writes. */
+export declare function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
+    client: UpClient;
+};
 /** "Oct so far $2,140 · Sep $1,980 · 3 to categorise": this month's spend against last month's. */
 export declare function upText(s: UpSnapshot): string;
 /** One line per parent category this month, largest five: "home $1,030: groceries $620, utilities $410". */

package/dist/connectors/up/index.js

@@ -97,13 +97,14 @@ export function toSnapshot(txs, categories, at) {
         truncated: at.truncated,
     };
 }
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
+/** Up as a home integration: two months of transactions now, then every 15 minutes. The integration only reads; `client` is there for a consumer's writes. */
 export function up(config) {
     const client = upClient(config);
     const clock = config.clock ?? realClock;
     const poll = poller(clock);
     return {
         name: "up",
+        client,
         refresh: poll.nudge,
         async run(signal, update) {
             let last;

package/dist/connectors/weather/index.js

@@ -151,17 +151,30 @@ export function weather(config) {
 }
 /** "20:20" in the home's time zone (the runtime's when unset), or "?". */
 const hhmmIn = (iso, timeZone) => iso ? localTime(Date.parse(iso), timeZone) : "?";
-const day = (d) => d
+const day = (d, rainLeft) => d
     ? [
         d.minC === undefined && d.maxC === undefined
             ? ""
             : `${d.minC ?? "?"}–${d.maxC ?? "?"} °C`,
         d.text?.replace(/\.$/, "").toLowerCase() ?? "",
-        d.rainChance === undefined ? "" : `${d.rainChance}% chance of rain`,
+        d.rainChance === undefined
+            ? ""
+            : rainLeft !== undefined && rainLeft < d.rainChance
+                ? `${rainLeft}% chance of rain the rest of the day`
+                : `${d.rainChance}% chance of rain`,
     ]
         .filter(Boolean)
         .join(" ")
     : "?";
+/** The highest hourly chance left today, all 24 hours of it, when the hourly forecast is the same source and day as the forecast: sources are never mixed. */
+const rainLeftToday = (w, at) => {
+    if (!w.hourly || w.hourly.source !== w.forecast?.source)
+        return undefined;
+    const rest = dayBlocks(w.hourly, at, w.timeZone, [
+        { name: "rest", from: 0, to: 24 },
+    ])?.today[0];
+    return rest?.date === w.forecast.today?.date ? rest?.rainChance : undefined;
+};
 /** "rain in 30 min, ends in 55 min, 70%, 0.8 mm, moderate (google)", "raining, ends in 25 min", or "no rain for 2 h"; nothing when the forecast covers none of the window. */
 export function rainText(rain, r) {
     if (!r || !rain)
@@ -206,7 +219,7 @@ export function weatherText(w, sun) {
         : "";
     const f = w.forecast;
     const forecast = f
-        ? `today ${day(f.today)}, tomorrow ${day(f.tomorrow)} (${f.source}${f.modelled ? " modelled" : ""})`
+        ? `today ${day(f.today, rainLeftToday(w, Date.parse(sun.at)))}, tomorrow ${day(f.tomorrow)} (${f.source}${f.modelled ? " modelled" : ""})`
         : "";
     const k = w.sky;
     const skyParts = k

package/dist/discover.d.ts

@@ -85,6 +85,7 @@ export type CachedAddress = {
     host: string;
     port?: number;
     name?: string;
+    model?: string;
     seenAt: string;
 };
 /**
@@ -111,6 +112,7 @@ export declare function addressBook(cache: AddressCache | undefined, options?: {
         host: string;
         port?: number;
         name?: string;
+        model?: string;
     }): void;
     entries: () => {
         [x: string]: CachedAddress;
@@ -119,7 +121,8 @@ export declare function addressBook(cache: AddressCache | undefined, options?: {
 /**
  * Run one discovery `passes` times, `gapMs` apart, and return the union (first answer wins). `onPass` sees each pass's
  * additions as they come; `done` ends it early once what was looked for has answered. A pass that throws adds nothing;
- * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found.
+ * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found. An error
+ * `stopOn` accepts is thrown at once: no later pass could do better.
  */
 export declare function discover<T = Found>(pass: () => Promise<T[]>, options: {
     clock: Clock;
@@ -127,6 +130,7 @@ export declare function discover<T = Found>(pass: () => Promise<T[]>, options: {
     gapMs?: number;
     key?: (t: T) => string;
     done?: (all: T[]) => boolean;
+    stopOn?: (error: unknown) => boolean;
     onPass?: (n: number, added: T[]) => void;
     signal?: AbortSignal;
 }): Promise<T[]>;

package/dist/discover.js

@@ -241,13 +241,16 @@ export function addressBook(cache, options = {}) {
                 c.host === address.host &&
                 c.port === address.port &&
                 isFresh(c) &&
-                (!address.name || address.name === c.name))
+                (!address.name || address.name === c.name) &&
+                (!address.model || address.model === c.model))
                 return;
             const name = address.name || c?.name;
+            const model = address.model || c?.model;
             entries[key] = {
                 host: address.host,
                 ...(address.port === undefined ? {} : { port: address.port }),
                 ...(name ? { name } : {}),
+                ...(model ? { model } : {}),
                 seenAt: new Date(now()).toISOString(),
             };
             cache.write({ ...entries });
@@ -258,7 +261,8 @@ export function addressBook(cache, options = {}) {
 /**
  * Run one discovery `passes` times, `gapMs` apart, and return the union (first answer wins). `onPass` sees each pass's
  * additions as they come; `done` ends it early once what was looked for has answered. A pass that throws adds nothing;
- * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found.
+ * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found. An error
+ * `stopOn` accepts is thrown at once: no later pass could do better.
  */
 export async function discover(pass, options) {
     const key = options.key ?? foundKey;
@@ -272,7 +276,12 @@ export async function discover(pass, options) {
         if (options.signal?.aborted)
             break;
         ran++;
-        const answers = await pass().catch((error) => (errors.push(error), []));
+        const answers = await pass().catch((error) => {
+            if (options.stopOn?.(error))
+                throw error;
+            errors.push(error);
+            return [];
+        });
         const added = answers.filter((t) => !all.has(key(t)) && all.set(key(t), t));
         options.onPass?.(n, added);
         if (options.done?.([...all.values()]))

package/dist/energy.js

@@ -1,3 +1,4 @@
+import { kw } from "./manifest.js";
 /**
  * Within this many watts either way the grid flow reads as "balanced": a display rule for the word and the animation,
  * so a meter wobbling around zero does not flip between importing and exporting. `gridW` and `surplusW` stay as read.
@@ -77,7 +78,6 @@ export function solarLevel(now, capacityW) {
  * "balanced (-10 W)", or "" with no grid reading. Rounded for reading only; the numbers above stay as read.
  */
 export function gridText(now) {
-    const kw = (w) => `${(w / 1000).toFixed(1)} kW`;
     const rate = (c, positive, negative) => c === undefined
         ? ""
         : `, ${c >= 0 ? positive : negative} ${Math.round(Math.abs(c))} c/h`;

package/dist/finders.d.ts

@@ -1,4 +1,7 @@
 import { type AddressCache, type Connector, type Finder, type Found } from "./discover.ts";
+/** The system's mDNS tool is not installed: discovery can't run until it is. */
+export declare class MissingTool extends Error {
+}
 /**
  * Run a long-lived `dns-sd` query (or `avahi-browse`, by `command`) and return what it printed. It never exits by itself, so it is stopped once `done`
  * says the answer is in, or `quietMs` after the last output, or at `maxMs`. The system's mDNS cache usually answers in

package/dist/finders.js

@@ -12,6 +12,9 @@ import { parseAvahi, parseAvahiBrowse, parseBrowse, parseResolve, } from "./disc
 // nothing here binds UDP 5353 beside it; a slow device (the Enphase gateway took 4 s to answer a fresh query; Bun 1.4.3, 2026-10-16)
 // does not slow a scan. Without the tool the mDNS finders throw, naming it, rather than "nothing answered".
 // `fileCache` keeps the addresses discovery found in a file between runs, so the next run connects straight away.
+/** The system's mDNS tool is not installed: discovery can't run until it is. */
+export class MissingTool extends Error {
+}
 /**
  * Run a long-lived `dns-sd` query (or `avahi-browse`, by `command`) and return what it printed. It never exits by itself, so it is stopped once `done`
  * says the answer is in, or `quietMs` after the last output, or at `maxMs`. The system's mDNS cache usually answers in
@@ -38,9 +41,9 @@ export function dnsSd(argv, options = {}) {
             resolve(out));
         proc.on("error", (error) => {
             (clearTimeout(timer), clearTimeout(quiet));
-            reject(new Error(error.code === "ENOENT"
-                ? `${command} not found; mDNS discovery needs it${install ? ` (${install})` : ""}`
-                : `${command}: ${error.message}`));
+            reject(error.code === "ENOENT"
+                ? new MissingTool(`${command} not found; mDNS discovery needs it${install ? ` (${install})` : ""}`)
+                : new Error(`${command}: ${error.message}`));
         });
         proc.on("close", finish);
     });

package/dist/lane.js

@@ -24,28 +24,32 @@ export function writeLane(options) {
     }
     async function run() {
         running = true;
-        while (queue.length) {
-            const now = clock.now();
-            const next = queue.find((p) => readyAt(p.slot) <= now);
-            if (!next) {
-                wake = new AbortController();
-                await clock.sleep(Math.min(...queue.map((p) => readyAt(p.slot))) - now, wake.signal);
-                continue;
-            }
-            queue.splice(queue.indexOf(next), 1);
-            lastAt = now;
-            sent.set(next.slot, [...recent(next.slot), now]);
-            try {
-                const result = await next.write(next.body);
-                for (const w of next.waiters)
-                    w.resolve(result);
-            }
-            catch (error) {
-                for (const w of next.waiters)
-                    w.reject(error);
+        try {
+            while (queue.length) {
+                const now = clock.now();
+                const next = queue.find((p) => readyAt(p.slot) <= now);
+                if (!next) {
+                    wake = new AbortController();
+                    await clock.sleep(Math.min(...queue.map((p) => readyAt(p.slot))) - now, wake.signal);
+                    continue;
+                }
+                queue.splice(queue.indexOf(next), 1);
+                lastAt = now;
+                sent.set(next.slot, [...recent(next.slot), now]);
+                try {
+                    const result = await next.write(next.body);
+                    for (const w of next.waiters)
+                        w.resolve(result);
+                }
+                catch (error) {
+                    for (const w of next.waiters)
+                        w.reject(error);
+                }
             }
         }
-        running = false;
+        finally {
+            running = false; // a throw here must not leave the lane stuck
+        }
     }
     return {
         send(slot, body, write, merge = (_, newer) => newer) {

package/docs/cast.md

@@ -109,7 +109,7 @@ No host: a group's host changes with its leader. All entries fold into one `cast
 - `announce(target, clip, { volume?, timeoutMs? })`, target a device or group, `clip` a URL or bytes with their type (KO's own dictation as recorded, or TTS output; the library never synthesises) served by `serveClip`. The result names each member it could not restore. Read status, set volume, launch Default Media Receiver (`CC1AD845`), `LOAD` the clip, wait for `IDLE`/`FINISHED` (with a timeout), then restore: a prior Default Media Receiver `contentId` is re-loaded at its `currentTime`, an idle device gets `STOP`, then the volume. Spotify, YouTube and other apps cannot be resumed generically (our launch ends their session); the result says so.
 - `castUrl(name, url)` launches DashCast (`84912283`, pychromecast's list) with the URL. HA casts its dashboard with its own registered receiver (`A078F6B0`), a hint at DashCast's limits. KO's own receiver costs a one-off Cast SDK fee and must be published (unpublished ones run only on serial-registered devices). Try DashCast first.
 
-**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3, AAC, WAV; not AIFF): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
+**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3 or AAC; not AIFF; a 24 kHz mono WAV failed on audio-only Nest speakers, live 2026-11-09): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
 
 **CLI.** `home status`: `cast  7 · Display A idle 47% · TV B standby · Whole house (3, led by Display A) idle`. `home probe`: this probe.