clauderipple 0.9.4 → 0.10.0

package/dist/remote/src/local-control.js

@@ -0,0 +1,138 @@
+// Host-local HTTP boundary. Relay peers enter HostServer.connected(), never this handler.
+import fs from "node:fs";
+import path from "node:path";
+import qrcode from "qrcode-generator";
+import { DEFAULT_RELAY, loadConfig, newToken, normalizeRelay, pairingUrl, relayPairingUrl, resolveBind, saveConfig, tokenMatches } from "./config.js";
+export function isLoopback(address) {
+    return address === "::1" || /^127(?:\.\d{1,3}){3}$/.test(address ?? "") || /^::ffff:127(?:\.\d{1,3}){3}$/i.test(address ?? "");
+}
+/** Exclusive creation makes concurrent starts agree on one secret; never generated by the router. */
+export function localSecret(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, "local.secret");
+    try {
+        fs.writeFileSync(file, newToken() + "\n", { flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    fs.chmodSync(file, 0o600);
+    const secret = fs.readFileSync(file, "utf8").trim();
+    if (secret.length < 32)
+        throw new Error("invalid local control secret");
+    return secret;
+}
+function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+    res.end(JSON.stringify(body));
+}
+async function settingsBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += Buffer.byteLength(chunk);
+        if (size > 4096)
+            throw new Error("settings body exceeds 4096 bytes");
+        chunks.push(Buffer.from(chunk));
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+export class LocalControl {
+    secret;
+    running;
+    where;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+        this.secret = localSecret(opts.dir);
+        this.running = { ...opts.config };
+        this.where = resolveBind(this.running.bind);
+    }
+    /** No caller-supplied error text is logged or reflected: pairing credentials stay out of logs. */
+    async handle(req, res) {
+        if (!isLoopback(req.socket.remoteAddress) || !tokenMatches(this.secret, req.headers["x-ripple-local"])) {
+            json(res, 403, { error: "local control authentication required" });
+            return;
+        }
+        const route = new URL(req.url ?? "/", "http://local").pathname;
+        try {
+            if (route === "/local/status" && req.method === "GET") {
+                const cfg = this.running;
+                const saved = loadConfig(this.opts.dir, false);
+                json(res, 200, {
+                    version: this.opts.version, mode: cfg.relay ? "relay" : this.where.reachableFromPhone ? "direct" : "local-only",
+                    ...(cfg.relay ? { relay: cfg.relay } : {}), bind: cfg.bind, port: cfg.port,
+                    reachableFromPhone: !!cfg.relay || this.where.reachableFromPhone, pushReady: !!cfg.relay,
+                    phones: this.opts.phones(), settings: { bind: saved.bind, ...(saved.relay ? { relay: saved.relay } : {}) }, defaultRelay: DEFAULT_RELAY,
+                    restartRequired: saved.bind !== cfg.bind || saved.relay !== cfg.relay,
+                });
+                return;
+            }
+            if (route === "/local/shutdown" && req.method === "POST" && this.opts.shutdown) {
+                res.once("finish", () => this.opts.shutdown?.());
+                json(res, 200, { ok: true });
+                return;
+            }
+            if (route === "/local/pairing" && req.method === "GET") {
+                const cfg = this.running;
+                const url = cfg.relay ? relayPairingUrl(cfg.relay, cfg.serverId, this.opts.hostPublicKey, this.opts.config.token)
+                    : pairingUrl(this.where.advertise, cfg.port, this.opts.config.token);
+                const qr = qrcode(0, "M");
+                qr.addData(url);
+                qr.make();
+                json(res, 200, { url, svg: qr.createSvgTag({ cellSize: 4, margin: 2, scalable: true }) });
+                return;
+            }
+            if (route === "/local/settings" && req.method === "POST") {
+                let next;
+                try {
+                    next = this.settings(await settingsBody(req));
+                }
+                catch {
+                    json(res, 400, { error: "invalid settings: use an HTTPS Relay URL (or off) and bind local, lan or tailscale; the selected network must be available" });
+                    return;
+                }
+                saveConfig(next, this.opts.dir);
+                json(res, 200, { restartRequired: next.bind !== this.running.bind || next.relay !== this.running.relay });
+                return;
+            }
+            if (route === "/local/rotate" && req.method === "POST") {
+                const next = loadConfig(this.opts.dir, false);
+                next.token = newToken();
+                saveConfig(next, this.opts.dir);
+                this.opts.config.token = next.token;
+                this.opts.rotate(next.token);
+                json(res, 200, { ok: true });
+                return;
+            }
+            json(res, 404, { error: "unknown local control endpoint or method" });
+        }
+        catch {
+            json(res, 500, { error: "host local control failed" });
+        }
+    }
+    settings(raw) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw new Error("expected object");
+        const body = raw;
+        if (Object.keys(body).some(key => key !== "relay" && key !== "bind"))
+            throw new Error("unknown setting");
+        const cfg = loadConfig(this.opts.dir, false);
+        if (body.relay !== undefined) {
+            if (typeof body.relay !== "string")
+                throw new Error("invalid relay");
+            if (body.relay === "off")
+                delete cfg.relay;
+            else
+                cfg.relay = normalizeRelay(body.relay);
+        }
+        if (body.bind !== undefined) {
+            if (body.bind !== "local" && body.bind !== "lan" && body.bind !== "tailscale")
+                throw new Error("invalid bind");
+            cfg.bind = body.bind === "local" ? "127.0.0.1" : body.bind;
+            resolveBind(cfg.bind);
+        }
+        return cfg;
+    }
+}

package/dist/remote/src/main.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// ripple-host: runs Claude Code sessions on this machine for the phone.
+//   ripple-host [--bind 127.0.0.1|tailscale|lan|0.0.0.0|<ip>] [--port 8797] [--relay <https url>|off] [--new-token]
+//   ripple-host install [same options] [--print]   launchd agent com.clauderipple.host (--print: only show the plist)
+//   ripple-host uninstall                           stop and remove the agent
+//   ripple-host status                              agent state and health (prints no secret)
+//   ripple-host pair                                print the pairing QR and link (they carry the pairing key)
+// Options are remembered in host.json. The host never stops on its own; day to day it runs as the
+// launchd agent (KeepAlive), which restarts it after a crash; on start it recovers persisted
+// sessions and permission requests (Sessions.recover). With a relay it also keeps one outbound
+// socket to it, so the phone reaches the Mac from anywhere over an https origin (relay.ts).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { listSessions } from "@anthropic-ai/claude-agent-sdk";
+import { sdkQuery as query } from "./sdk-launcher.js";
+import qrcode from "qrcode-generator";
+import nacl from "tweetnacl";
+import { WebSocket } from "ws";
+import { loadConfig, newToken, normalizeRelay, pairingUrl, relayPairingUrl, remoteHome, resolveBind, saveConfig } from "./config.js";
+import { MacAway } from "./away.js";
+import { toB64u } from "./e2ee.js";
+import { PermissionQueue } from "./permissions.js";
+import { PowerHold } from "./power.js";
+import { Notifier, loadVapid, webPushSender } from "./push.js";
+import { ExpoNotifier, expoSender } from "./expo-push.js";
+import { RelayHost, loadHostKey } from "./relay.js";
+import { RouterClient } from "./router.js";
+import { HostServer } from "./server.js";
+import { LocalControl } from "./local-control.js";
+import { findClaude, specFor } from "./service.js";
+import { installService, uninstallService, serviceStatus, servicePaths, renderService, supervisorName, controlShutdown } from "./host-service.js";
+import { Sessions } from "./sessions.js";
+import { desktopHandoff } from "./handoff.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8")).version;
+const out = (s) => { process.stdout.write(s); };
+function arg(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > 0 ? process.argv[i + 1] : undefined;
+}
+function qr(text) {
+    const q = qrcode(0, "M");
+    q.addData(text);
+    q.make();
+    const n = q.getModuleCount();
+    const dark = (r, c) => r >= 0 && c >= 0 && r < n && c < n && q.isDark(r, c);
+    const lines = [];
+    // Two rows per character with half blocks and a quiet zone of 2. Black on an explicit white
+    // background, so it scans the same on a light or a dark terminal.
+    for (let r = -2; r < n + 2; r += 2) {
+        let line = "\x1b[30;47m";
+        for (let c = -2; c < n + 2; c++) {
+            const top = dark(r, c), bottom = dark(r + 1, c);
+            line += top && bottom ? "█" : top ? "▀" : bottom ? "▄" : " ";
+        }
+        lines.push(line + "\x1b[0m");
+    }
+    return lines.join("\n");
+}
+/** --bind / --port / --relay / --new-token given on the command line are remembered. */
+function configFromArgs(dir) {
+    const cfg = loadConfig(dir);
+    const bind = arg("bind");
+    const port = arg("port");
+    const relay = arg("relay");
+    if (bind)
+        cfg.bind = bind;
+    if (port)
+        cfg.port = Number(port);
+    if (relay === "off")
+        delete cfg.relay;
+    else if (relay)
+        cfg.relay = normalizeRelay(relay);
+    if (process.argv.includes("--new-token"))
+        cfg.token = newToken();
+    if (bind || port || relay || process.argv.includes("--new-token"))
+        saveConfig(cfg, dir);
+    return cfg;
+}
+function printPairing(cfg, dir) {
+    const where = resolveBind(cfg.bind);
+    let url;
+    if (cfg.relay) {
+        // The fragment (token, server id, host key) never leaves the phone; the relay only sees the page request.
+        url = relayPairingUrl(cfg.relay, cfg.serverId, toB64u(loadHostKey(dir, nacl).publicKey), cfg.token);
+        out(`\nThrough the relay ${cfg.relay} (works from anywhere; notifications need this https address).\n`);
+    }
+    else {
+        url = pairingUrl(where.advertise, cfg.port, cfg.token);
+        out(where.reachableFromPhone
+            ? "\nDirect http: works on this network only, and without notifications (they need https: use --relay).\n"
+            : "\nOnly this computer can reach it. For the phone, use --relay <url> (anywhere) or --bind lan / tailscale (same network).\n");
+    }
+    out(`\nScan with the phone's camera (the link carries the pairing key — do not share it):\n\n${qr(url)}\n\n${url}\n\n`);
+}
+/**
+ * Under launchd both streams are the log file: start every line with an ISO time, so a run of
+ * reconnects or errors can be placed next to sleep, network and relay events afterwards. Wraps the
+ * stream itself, so lines written by libraries and child processes' relayed output get one too.
+ */
+function stampLines(stream) {
+    const write = stream.write.bind(stream);
+    let lineStart = true;
+    stream.write = ((chunk, ...rest) => {
+        const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+        if (!text)
+            return write(chunk, ...rest);
+        let stamped = "";
+        for (const piece of text.split(/(?<=\n)/)) {
+            stamped += (lineStart && piece !== "\n" ? `${new Date().toISOString()} ` : "") + piece;
+            lineStart = piece.endsWith("\n");
+        }
+        return write(stamped, ...rest);
+    });
+}
+async function runHost() {
+    if (!process.stdout.isTTY)
+        stampLines(process.stdout);
+    if (!process.stderr.isTTY)
+        stampLines(process.stderr);
+    const dir = remoteHome();
+    const cfg = configFromArgs(dir);
+    const where = resolveBind(cfg.bind);
+    const router = new RouterClient(cfg.adminUrl);
+    const permissions = PermissionQueue.open(path.join(dir, "permissions.json"));
+    let server = null;
+    const claudePath = findClaude(cfg.claudePath);
+    const power = new PowerHold();
+    const log = (line) => { process.stderr.write(`${line}\n`); };
+    // A VAPID subject must be an https: or mailto: URL; the relay is this host's one real https origin.
+    const vapid = loadVapid(dir, cfg.relay?.startsWith("https:") ? cfg.relay : "mailto:ripple-host@clauderipple.invalid");
+    let sessions = null;
+    const notifier = new Notifier({
+        dir, send: webPushSender(vapid), log,
+        seenRecently: (id) => server?.sessionSeenRecently(id) ?? false,
+        summary: (id) => sessions?.summaryOf(id),
+    });
+    const expoNotifier = new ExpoNotifier({ dir, send: expoSender(), log,
+        seenRecently: (id) => server?.sessionSeenRecently(id) ?? false,
+        context: (id, event) => sessions?.pushContext(id, event) ?? {},
+    });
+    // Mac sessions the host is not tailing push only while the Mac is away (screen locked or idle).
+    const away = new MacAway({ log });
+    sessions = new Sessions({
+        dir, router, permissions,
+        desktopProjects: path.join(os.homedir(), ".claude", "projects"),
+        ...(process.platform === "darwin" ? { desktopSidebar: {} } : {}),
+        queryFn: query,
+        ...(claudePath ? { claudePath, ...(process.platform === "darwin" ? { handoff: desktopHandoff(claudePath) } : {}) } : {}),
+        log,
+        onEvent: (id, event) => { server?.onEvent(id); void notifier.onEvent(id, event); void expoNotifier.onEvent(id, event); },
+        away: () => away.away(),
+        onAlert: (id, body) => { void notifier.onEvent(id, body); void expoNotifier.onEvent(id, body); },
+        onSessions: () => { server?.onSessions(); if (sessions)
+            power.update(sessions.busy()); },
+        onDesktopProblem: (problem) => server?.setDesktopProblem(problem),
+    });
+    sessions.recover();
+    const live = sessions;
+    const host = new HostServer({
+        listen: where.listen, port: cfg.port, token: cfg.token, webDir: path.resolve(here, "..", "web"), sessions: live, router,
+        hostName: os.hostname().replace(/\.local$/, ""), version: VERSION,
+        recentCli: async () => (await listSessions({ limit: 300, includeProgrammatic: false })).flatMap((s) => (s.cwd ? [{ path: s.cwd, lastUsed: s.lastModified }] : [])),
+        log,
+        push: { publicKey: vapid.publicKey, subscribe: (id, sub, lang) => notifier.subscribe(id, sub, lang), unsubscribe: (id) => notifier.unsubscribe(id) },
+        expoPush: expoNotifier,
+        pushDevices: () => [...new Set([...notifier.devices(), ...expoNotifier.devices()])],
+        clearPush: () => {
+            for (const id of notifier.devices())
+                notifier.unsubscribe(id);
+            for (const id of expoNotifier.devices())
+                expoNotifier.unsubscribe(id);
+        },
+        local: new LocalControl({
+            dir, config: cfg, version: VERSION, hostPublicKey: toB64u(loadHostKey(dir, nacl).publicKey),
+            phones: () => server?.phones() ?? [],
+            rotate: token => { server?.rotateToken(token); },
+            shutdown: () => stop(),
+        }),
+    });
+    server = host;
+    await host.listen();
+    power.update(live.busy());
+    const relay = cfg.relay
+        ? new RelayHost({
+            relay: cfg.relay, serverId: cfg.serverId, secret: cfg.relaySecret, hostKey: loadHostKey(dir, nacl), nacl, log,
+            makeSocket: (url, headers) => new WebSocket(url, { headers, maxPayload: 2 * 1024 * 1024 }),
+            onPeer: (peer) => host.connected(peer),
+        })
+        : null;
+    relay?.start();
+    out(`\nRipple Remote ${VERSION} — listening on ${where.listen}:${cfg.port}${cfg.relay ? `, relay ${cfg.relay}` : ""}\n`);
+    if (claudePath)
+        out(`Claude Code: ${claudePath}\n`);
+    // Under launchd stdout is a log file; the pairing link carries the token and must not land there.
+    if (process.stdout.isTTY)
+        printPairing(cfg, dir);
+    else
+        out("Pairing QR: run `ripple-host pair` (npm run remote -- pair) in a terminal.\n");
+    const stop = () => {
+        power.release();
+        relay?.stop();
+        live.shutdown();
+        void host.close().then(() => process.exit(0));
+        setTimeout(() => process.exit(0), 3000).unref();
+    };
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+}
+async function status() {
+    const cfg = loadConfig(remoteHome());
+    const st = serviceStatus();
+    const p = servicePaths();
+    out(`${supervisorName()}: ${st.installed ? p.definition : "not installed"}${st.loaded ? `, loaded (state ${st.state ?? "?"}${st.pid ? `, pid ${st.pid}` : ""}${st.lastExit ? `, last exit ${st.lastExit}` : ""})` : ", not loaded"}\n`);
+    const listen = resolveBind(cfg.bind).listen;
+    const probe = listen === "0.0.0.0" || listen === "::" ? "127.0.0.1" : listen;
+    let health = "no answer";
+    try {
+        const r = await fetch(`http://${probe.includes(":") ? `[${probe}]` : probe}:${cfg.port}/healthz`, { signal: AbortSignal.timeout(2000) });
+        health = r.ok ? "ok" : `HTTP ${r.status}`;
+    }
+    catch { /* no answer */ }
+    out(`host: ${probe}:${cfg.port} — ${health} (bind ${cfg.bind})\n`);
+    out(`relay: ${cfg.relay ?? "off"}\nlogs: ${p.log}\n`);
+}
+async function installCmd() {
+    const dir = remoteHome();
+    // Read the running host's old port before command-line options persist a replacement.
+    if (process.platform === "win32" && !process.argv.includes("--print"))
+        await controlShutdown(dir);
+    const cfg = process.argv.includes("--print") ? loadConfig(dir, false) : configFromArgs(dir);
+    const spec = specFor({ script: fileURLToPath(import.meta.url), claudePath: findClaude(cfg.claudePath), ...(process.env.RIPPLE_REMOTE_HOME ? { remoteHome: process.env.RIPPLE_REMOTE_HOME } : {}) });
+    if (process.argv.includes("--print")) {
+        out(renderService(spec));
+        return;
+    }
+    for (const line of await installService(spec))
+        out(`${line}\n`);
+    out(`Pair the phone: clauderipple remote pair\n`);
+}
+async function main() {
+    const sub = process.argv[2] && !process.argv[2].startsWith("--") ? process.argv[2] : null;
+    switch (sub) {
+        case null: return runHost();
+        case "install": return installCmd();
+        case "uninstall":
+            for (const line of await uninstallService())
+                out(`${line}\n`);
+            return;
+        case "status": return status();
+        case "pair": {
+            const dir = remoteHome();
+            printPairing(configFromArgs(dir), dir);
+            return;
+        }
+        default: throw new Error(`unknown command "${sub}" (install, uninstall, status, pair)`);
+    }
+}
+main().catch((e) => {
+    process.stderr.write(`ripple-host: ${e.message}\n`);
+    process.exit(1);
+});

package/dist/remote/src/permissions.js

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import { readJson, writeFileAtomic } from "./fsutil.js";
+const WEEK = 7 * 24 * 60 * 60 * 1000;
+export class PermissionQueue {
+    expiredOnOpen;
+    file;
+    now;
+    records = new Map();
+    waiters = new Map();
+    constructor(file, now, expired) {
+        this.file = file;
+        this.now = now;
+        this.expiredOnOpen = structuredClone(expired);
+    }
+    static open(file, now = Date.now) {
+        // A JSON array is the complete snapshot; malformed state is never an empty queue.
+        const saved = readJson(file) ?? [];
+        if (!Array.isArray(saved))
+            throw new Error("Invalid permission queue");
+        const at = now();
+        const expired = [];
+        const records = new Map();
+        for (const record of saved) {
+            if (!validRecord(record) || records.has(record.id))
+                throw new Error("Invalid permission record");
+            if (record.state === "pending") {
+                record.state = "expired";
+                record.reason = "host_restarted";
+                record.decidedAt = at;
+                expired.push(record);
+            }
+            records.set(record.id, record);
+        }
+        const queue = new PermissionQueue(file, now, expired);
+        queue.persist(records, at);
+        return queue;
+    }
+    persist(records, at) {
+        const kept = new Map([...records].filter(([, record]) => record.state === "pending" || record.decidedAt >= at - WEEK));
+        writeFileAtomic(this.file, JSON.stringify([...kept.values()]));
+        // Memory and promises must not get ahead of durable state when a write fails.
+        this.records = kept;
+    }
+    request(r, signal) {
+        const at = this.now();
+        const record = { ...structuredClone(r), id: randomUUID(), createdAt: at, state: "pending" };
+        const records = new Map(this.records);
+        records.set(record.id, record);
+        this.persist(records, at);
+        const decision = new Promise(resolve => {
+            const abort = () => { this.expire(record.id, "aborted"); };
+            this.waiters.set(record.id, { resolve, cleanup: () => signal?.removeEventListener("abort", abort) });
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted)
+                abort();
+        });
+        return { record: structuredClone(this.records.get(record.id)), decision };
+    }
+    finish(ids, decision, reason, answers) {
+        const at = this.now();
+        const records = new Map(this.records);
+        const changed = [];
+        for (const id of ids) {
+            const record = records.get(id);
+            if (record?.state !== "pending")
+                continue;
+            const next = { ...record, state: decision, decidedAt: at };
+            if (reason !== undefined)
+                next.reason = reason;
+            records.set(id, next);
+            changed.push(next);
+        }
+        if (!changed.length)
+            return [];
+        this.persist(records, at);
+        for (const record of changed) {
+            const waiter = this.waiters.get(record.id);
+            if (!waiter)
+                continue;
+            this.waiters.delete(record.id);
+            waiter.cleanup();
+            const answer = { decision };
+            if (reason !== undefined)
+                answer.reason = reason;
+            if (answers !== undefined)
+                answer.answers = answers;
+            waiter.resolve(answer);
+        }
+        return structuredClone(changed);
+    }
+    decide(id, decision, reason, answers) {
+        // The type says the union, but a phone frame is runtime data: anything else would corrupt the
+        // record (a forged "expired" would close a card without answering it).
+        if (decision !== "allow" && decision !== "allow_always" && decision !== "deny")
+            throw new Error("invalid decision");
+        return this.finish([id], decision, reason, answers)[0] ?? null;
+    }
+    denySession(session, reason) {
+        return this.finish(this.pending(session).map(record => record.id), "deny", reason);
+    }
+    expire(id, reason) {
+        return this.finish([id], "expired", reason)[0] ?? null;
+    }
+    expireSession(session, reason) {
+        return this.finish(this.pending(session).map(record => record.id), "expired", reason);
+    }
+    pending(session) {
+        return structuredClone([...this.records.values()]
+            .filter(record => record.state === "pending" && (session === undefined || record.session === session))
+            .sort((a, b) => a.createdAt - b.createdAt));
+    }
+    get(id) {
+        const record = this.records.get(id);
+        return record === undefined ? undefined : structuredClone(record);
+    }
+}
+function validRecord(record) {
+    return record !== null && typeof record === "object"
+        && [record.id, record.session, record.tool, record.title, record.summary].every(value => typeof value === "string")
+        && Number.isFinite(record.createdAt)
+        && ["pending", "allow", "allow_always", "deny", "expired"].includes(record.state)
+        && (record.state === "pending" || Number.isFinite(record.decidedAt))
+        && (record.reason === undefined || typeof record.reason === "string");
+}

package/dist/remote/src/power.js

@@ -0,0 +1,76 @@
+// Keeps the Mac awake while a turn runs, and only then (spec: "a power assertion only while a
+// turn runs"). One `caffeinate -i -w <host pid>` child is held while any session is starting,
+// running or waiting on a permission — a turn that waits for the phone must not let the Mac
+// sleep under it, or the answer has nowhere to go. `-i` blocks idle sleep only (lid close and
+// the user's own sleep stay theirs); `-w` ends the assertion by itself if the host dies.
+import { spawn } from "node:child_process";
+export const nodeSpawner = (cmd, args) => {
+    const child = spawn(cmd, args, { stdio: "ignore", windowsHide: true });
+    // A missing binary must not crash the host; the hold just does not happen.
+    child.on("error", () => undefined);
+    return {
+        kill: () => { if (child.exitCode === null && child.signalCode === null)
+            child.kill("SIGTERM"); },
+        onExit: (fn) => { child.once("exit", fn); child.once("error", fn); },
+    };
+};
+export function keepAwakeCommand(platform, pid) {
+    if (platform === "darwin")
+        return { cmd: "/usr/bin/caffeinate", args: ["-i", "-w", String(pid)] };
+    if (platform === "win32")
+        return { cmd: "powershell.exe", args: ["-NoProfile", "-NonInteractive", "-Command",
+                `Add-Type -Namespace Ripple -Name Power -MemberDefinition '[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint flags);'; $hostProcess = Get-Process -Id ${pid} -ErrorAction Stop; try { [Ripple.Power]::SetThreadExecutionState([uint32]2147483649) | Out-Null; while (-not $hostProcess.HasExited) { Start-Sleep -Seconds 2 } } finally { [Ripple.Power]::SetThreadExecutionState([uint32]2147483648) | Out-Null }`] };
+    return { cmd: "systemd-inhibit", args: ["--what=idle", "--mode=block", "--who=Ripple Remote", "--why=Remote session active", process.execPath, "-e", `const t=setInterval(()=>{try{process.kill(${pid},0)}catch{clearInterval(t)}},2000)`] };
+}
+export class PowerHold {
+    spawner;
+    pid;
+    child = null;
+    wanted = false;
+    respawn = null;
+    retryMs;
+    platform;
+    constructor(opts = {}) {
+        this.platform = opts.platform ?? process.platform;
+        this.spawner = opts.spawner ?? nodeSpawner;
+        this.pid = opts.pid ?? process.pid;
+        this.retryMs = opts.retryMs ?? 5_000;
+    }
+    get holding() { return this.child !== null; }
+    /** Call whenever session states change; spawns once on the first busy session, kills when none is. */
+    update(busy) {
+        this.wanted = busy;
+        if (busy && !this.child)
+            this.hold();
+        if (!busy)
+            this.release();
+    }
+    release() {
+        this.wanted = false;
+        if (this.respawn) {
+            clearTimeout(this.respawn);
+            this.respawn = null;
+        }
+        const c = this.child;
+        this.child = null;
+        c?.kill();
+    }
+    hold() {
+        if (this.respawn) {
+            clearTimeout(this.respawn);
+            this.respawn = null;
+        }
+        const command = keepAwakeCommand(this.platform, this.pid);
+        const c = this.spawner(command.cmd, command.args);
+        this.child = c;
+        c.onExit(() => {
+            if (this.child !== c)
+                return;
+            // Killed by someone else while a turn still runs: take it again, but not in a tight loop.
+            this.child = null;
+            if (this.wanted && !this.respawn)
+                this.respawn = setTimeout(() => { this.respawn = null; if (this.wanted && !this.child)
+                    this.hold(); }, this.retryMs);
+        });
+    }
+}

package/dist/remote/src/processes.js

@@ -0,0 +1,24 @@
+// One OS process snapshot for transcript liveness. Desktop registry identity remains macOS-only.
+import { execFileSync } from "node:child_process";
+import { windowsPowerShellEnv } from "../../cli/src/windows-powershell.js";
+export function listProcesses(platform = process.platform, exec = (file, args) => execFileSync(file, args, {
+    encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 5000, windowsHide: true, env: windowsPowerShellEnv(), stdio: ["ignore", "pipe", "pipe"],
+})) {
+    if (platform === "win32") {
+        const raw = JSON.parse(exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "$ErrorActionPreference = 'Stop'; [Console]::OutputEncoding = [Text.UTF8Encoding]::new(); ConvertTo-Json -Compress -InputObject @(Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine,@{Name='CreationDate';Expression={if ($_.CreationDate) {$_.CreationDate.ToUniversalTime().ToString('o')}}})"]));
+        if (!Array.isArray(raw))
+            throw new Error("invalid Windows process snapshot");
+        return raw.flatMap((value) => {
+            if (!value || typeof value !== "object")
+                return [];
+            const p = value;
+            return typeof p.ProcessId === "number" && typeof p.CommandLine === "string"
+                ? [{ pid: p.ProcessId, command: p.CommandLine, ...(typeof p.CreationDate === "string" ? { started: p.CreationDate } : {}) }] : [];
+        });
+    }
+    return exec("ps", ["-axo", "pid,command"]).split(/\r?\n/).flatMap(line => {
+        const m = /^\s*(\d+)\s+(.+)$/.exec(line);
+        return m ? [{ pid: Number(m[1]), command: m[2] }] : [];
+    });
+}
+export function processCommands() { return listProcesses().map(p => `${p.pid} ${p.command}`).join("\n"); }

package/dist/remote/src/protocol.js

@@ -0,0 +1,32 @@
+// Wire protocol between ripple-host and the phone client. Types and constants only, no
+// imports: the host also serves this file to the browser (as /src/protocol.ts), so both ends
+// read the same numbers.
+//
+// Every session has an append-only event log. An event's `seq` counts from 1 inside one
+// `epoch`; a new epoch means the log was replaced (never happens in normal operation) and a
+// client must drop what it holds for that session. A client that reconnects asks for
+// everything after the last `seq` it has, so a re-attach is cheap and idempotent.
+/** Largest WebSocket frame either side sends, in bytes of UTF-8 JSON (Paseo #2610: 8 MB killed the socket). */
+export const FRAME_CAP = 256 * 1024;
+/** A string field longer than this is moved out of the event into a blob fetched on demand. */
+export const INLINE_CAP = 32 * 1024;
+/** Client pings this often; either side calls the link stale after STALE_MS of silence. */
+export const PING_MS = 10_000;
+export const STALE_MS = 30_000;
+/** Reconnect backoff is min(BACKOFF_CAP_MS, attempt × 1 s) and never stops. */
+export const BACKOFF_CAP_MS = 30_000;
+/** A socket that opens but is not ready (relay hello, host ready) within this is abandoned. */
+export const READY_MS = 8_000;
+/** Largest frame the relay forwards: an encrypted FRAME_CAP frame (16-byte tag) with room to spare. */
+export const RELAY_FRAME_CAP = FRAME_CAP + 1024;
+/** Close codes the relay uses. `stale`: the host's control socket sent no ping for HOST_SILENT_MS. */
+export const RELAY_CLOSE = { badRequest: 4400, badSecret: 4401, hostOffline: 4404, stale: 4408, replaced: 4409, peerGone: 4410, tooBig: 1009 };
+/**
+ * The relay routes phones only to the host's newest control socket, and only while that socket
+ * pinged within this long (PING_MS cadence; a missed ping or two is not a verdict).
+ */
+export const HOST_SILENT_MS = STALE_MS + PING_MS;
+export const PERMISSION_MODES = ["plan", "default", "acceptEdits", "auto", "bypassPermissions"];
+export const ATTACHMENT_CAP = 8 * 1024 * 1024;
+export const ATTACHMENT_COUNT = 8;
+export function defaultEffort(efforts) { return efforts.includes("high") ? "high" : efforts[0] ?? null; }