clauderipple 0.10.0 → 0.11.0

package/dist/cli/src/doctor.js

@@ -0,0 +1,205 @@
+// `clauderipple doctor` and `clauderipple repair`: what is wrong with the chain Claude depends on,
+// and the idempotent fix. Both serve the menu-bar app, which has to work when the router — and
+// with it the dashboard — is down: Claude Desktop and Claude Code send everything to 127.0.0.1
+// and fail with ECONNREFUSED, and nothing the router serves can explain why (2026-10-20).
+//
+// Everything that reaches the machine is a dependency (`RecoveryDeps`), so tests run with a fake
+// supervisor and temp files and never touch launchd, the user's settings or the live router.
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigStore, adminPort } from "../../router/src/config.js";
+import { certPaths } from "./certs.js";
+import { applyAppProxy, currentAppProxy } from "./picker.js";
+import { applyProxyEnv, settingsEnv } from "./settings.js";
+export async function fetchRouterStatus(adminUrl, timeoutMs) {
+    try {
+        const res = await fetch(`${adminUrl}/api/status`, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return { version: typeof body.version === "string" ? body.version : null };
+    }
+    catch {
+        return null;
+    }
+}
+const sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
+const LOOPBACK_PROXY = /^http:\/\/(127\.0\.0\.1|localhost|\[::1\]):\d+\/?$/;
+export function proxyUrlFor(port) {
+    return `http://127.0.0.1:${port}`;
+}
+/**
+ * Claude Code's proxy, from settings.json env. `stale` is a proxy that is ours — our CA beside a
+ * loopback URL — on a port the config no longer listens on: the one case repair may rewrite.
+ */
+export function cliProxyState(env, proxyUrl, caPath) {
+    const url = env.HTTPS_PROXY || null;
+    if (!url)
+        return { proxy: "none", url: null, stale: false };
+    if (url === proxyUrl)
+        return { proxy: "ripple", url, stale: false };
+    return { proxy: "other", url, stale: env.NODE_EXTRA_CA_CERTS === caPath && LOOPBACK_PROXY.test(url) };
+}
+/** Claude Desktop's proxy, from the applied Config Library entry. An entry with no proxy is "none". */
+export function desktopProxyState(ap, proxyUrl) {
+    const url = ap.egressProxyUrl;
+    if (!url)
+        return { proxy: "none", url: null, stale: false };
+    if (url === proxyUrl)
+        return { proxy: "ripple", url, stale: false };
+    return { proxy: "other", url, stale: ap.ours };
+}
+/**
+ * Claude Code always goes through the router in Ripple mode; Claude Desktop itself only when picker
+ * mode is on (the Code tab's sessions read settings.json either way). Nothing through us is
+ * "direct"; anything in between is "mixed".
+ */
+export function classifyMode(cli, desktop, pickerEnabled) {
+    const cliRipple = cli === "ripple";
+    const desktopRipple = desktop === "ripple";
+    if (cliRipple && (desktopRipple || !pickerEnabled))
+        return "ripple";
+    if (!cliRipple && !desktopRipple)
+        return "direct";
+    return "mixed";
+}
+function configFile(home) {
+    return path.join(home, "config.json");
+}
+async function snapshot(deps) {
+    const installed = fs.existsSync(configFile(deps.home));
+    const cfg = new ConfigStore(configFile(deps.home)).get();
+    const proxyUrl = proxyUrlFor(cfg.listen.port);
+    const adminUrl = `http://127.0.0.1:${adminPort(cfg)}`;
+    const caPath = certPaths(deps.home).caPem;
+    const status = await (deps.routerStatus ?? fetchRouterStatus)(adminUrl, 4_000);
+    const view = deps.supervisor.inspect();
+    const cli = cliProxyState(settingsEnv(), proxyUrl, caPath);
+    const desktop = desktopProxyState(currentAppProxy(), proxyUrl);
+    const pickerEnabled = cfg.picker?.enabled === true;
+    const mode = classifyMode(cli.proxy, desktop.proxy, pickerEnabled);
+    const problems = [];
+    const add = (code, message) => void problems.push({ code, message });
+    if (!installed)
+        add("not-installed", `ClaudeRipple is not installed here (no ${configFile(deps.home)}). Run: clauderipple install`);
+    if (!view.registered)
+        add("supervisor-missing", "The router is not registered to start at login, so nothing starts it. Repair registers it again.");
+    else if (!view.programExists)
+        add("supervisor-program-missing", `The router's startup entry points at a program that no longer exists (${view.program ?? "none"}). Repair points it at this installation.`);
+    else if (!view.current)
+        add("supervisor-other-install", `The router's startup entry belongs to another ClaudeRipple installation (${view.program}).`);
+    if (!status) {
+        add("router-down", `The router is not answering on ${adminUrl}. ${mode === "direct" ? "Claude is on its default connection, so it is not affected." : "Claude Desktop and Claude Code cannot connect while it is down."}`);
+        if (view.registered && view.state !== "running")
+            add("supervisor-not-running", "The router's background service is not running.");
+    }
+    else if (status.version && status.version !== deps.version) {
+        add("router-version-mismatch", `The running router is ${status.version}; this ClaudeRipple is ${deps.version}.`);
+    }
+    if (cli.stale)
+        add("cli-port-mismatch", `Claude Code is set to a ClaudeRipple port that is no longer used (${cli.url}; the router listens on ${proxyUrl}).`);
+    else if (cli.proxy === "other")
+        add("cli-foreign-proxy", `Claude Code goes through another proxy (${cli.url}), not ClaudeRipple.`);
+    if (desktop.stale)
+        add("desktop-port-mismatch", `Claude Desktop is set to a ClaudeRipple port that is no longer used (${desktop.url}; the router listens on ${proxyUrl}).`);
+    else if (desktop.proxy === "other")
+        add("desktop-foreign-proxy", `Claude Desktop goes through another proxy (${desktop.url}), not ClaudeRipple.`);
+    if (mode === "mixed")
+        add("mixed-mode", `Claude Code ${cli.proxy === "ripple" ? "goes" : "does not go"} through ClaudeRipple, Claude Desktop ${desktop.proxy === "ripple" ? "does" : "does not"}.`);
+    return {
+        report: {
+            mode,
+            router: { responding: status !== null, version: status?.version ?? null, pid: view.pid, url: proxyUrl, adminUrl },
+            supervisor: { registered: view.registered, program: view.program, programExists: view.programExists, state: view.state },
+            desktop: { proxy: desktop.proxy, url: desktop.url },
+            cli: { proxy: cli.proxy, url: cli.url },
+            problems,
+        },
+        installed,
+        cfg,
+        view,
+        caPath,
+        cliStale: cli.stale,
+        desktopStale: desktop.stale,
+    };
+}
+export async function doctor(deps) {
+    return (await snapshot(deps)).report;
+}
+/**
+ * Fixes what doctor finds, in order, and is safe to run again: re-register the supervisor for this
+ * installation, start it, wait for it to answer, and correct a Claude proxy setting that is ours but
+ * names an old port. It never switches between Ripple and direct mode (that is `direct on|off`) and
+ * never touches a proxy setting that is not ours.
+ */
+export async function repair(deps) {
+    const sleep = deps.sleep ?? sleepDefault;
+    const status = deps.routerStatus ?? fetchRouterStatus;
+    const steps = [];
+    const before = await snapshot(deps);
+    if (!before.installed) {
+        steps.push({ name: "config", ok: false, detail: `no ${configFile(deps.home)}; run \`clauderipple install\` first` });
+        return { ok: false, steps, doctor: before.report };
+    }
+    const responding = before.report.router.responding;
+    const view = before.view;
+    // A working router is never cut off for a definition that merely differs: re-registering unloads
+    // the running job, which drains it and drops every Claude connection (ARCHITECTURE §5).
+    const mustRegister = !view.registered || !view.programExists || (!view.current && !responding);
+    if (mustRegister) {
+        try {
+            const where = deps.supervisor.register();
+            steps.push({ name: "supervisor", ok: true, detail: `registered for this installation: ${where}` });
+        }
+        catch (e) {
+            steps.push({ name: "supervisor", ok: false, detail: e.message });
+        }
+    }
+    else {
+        steps.push({
+            name: "supervisor",
+            ok: true,
+            detail: view.current ? "already registered for this installation" : `left as it is: the router answers, and its entry names another installation (${view.program}); run \`clauderipple install\` to move it`,
+        });
+    }
+    if (responding) {
+        steps.push({ name: "start", ok: true, detail: "the router is already answering" });
+    }
+    else {
+        const started = deps.supervisor.start();
+        steps.push({ name: "start", ok: started !== "failed", detail: started === "failed" ? "the supervisor could not start the router" : started === "already-running" ? "the supervisor reports it running" : "started" });
+        const adminUrl = before.report.router.adminUrl;
+        const budget = deps.healthBudgetMs ?? 20_000;
+        const t0 = Date.now();
+        let up = false;
+        while (!up) {
+            up = (await status(adminUrl, 3_000)) !== null;
+            if (up || Date.now() - t0 >= budget)
+                break;
+            await sleep(1_000);
+        }
+        steps.push({ name: "health", ok: up, detail: up ? `answering on ${adminUrl} after ${Math.round((Date.now() - t0) / 100) / 10}s` : `still not answering on ${adminUrl} after ${Math.round(budget / 1000)}s; see ${path.join(deps.home, "logs", "router.log")}` });
+    }
+    const proxyUrl = proxyUrlFor(before.cfg.listen.port);
+    if (before.cliStale) {
+        try {
+            // Ours by our CA beside a loopback URL (cliProxyState), so replacing it is not overriding anyone.
+            const edit = applyProxyEnv({ proxyUrl, caPath: before.caPath, force: true });
+            steps.push({ name: "cli-proxy", ok: true, detail: `Claude Code now points at ${proxyUrl}${edit.backup ? ` (backup: ${edit.backup})` : ""}` });
+        }
+        catch (e) {
+            steps.push({ name: "cli-proxy", ok: false, detail: e.message });
+        }
+    }
+    if (before.desktopStale) {
+        try {
+            applyAppProxy(proxyUrl);
+            steps.push({ name: "desktop-proxy", ok: true, detail: `Claude Desktop now points at ${proxyUrl} (quit and reopen it to apply)` });
+        }
+        catch (e) {
+            steps.push({ name: "desktop-proxy", ok: false, detail: e.message });
+        }
+    }
+    const after = await doctor(deps);
+    return { ok: steps.every((s) => s.ok) && after.router.responding, steps, doctor: after };
+}

package/dist/cli/src/index.js

@@ -15,7 +15,9 @@ import { adminPort } from "../../router/src/admin.js";
 import { certsExist, certPaths, generateCerts } from "./certs.js";
 import { applyProxyEnv, checkProxyEnv, currentProxyEnv, removeProxyEnv, settingsPath } from "./settings.js";
 import { agentDefinitionPath, agentState, installAgent, isLinux, isSupported, isWindows, removeAgent, restartAgent, startAgent, stopAgent, supervisorName } from "./supervisor.js";
-import { BUNDLE_ID, removeBundle, writeBundle } from "./bundle.js";
+import { removeBundle, writeBundle } from "./bundle.js";
+import { nativeSupervisor, registration, writePaths } from "./registration.js";
+import { installLauncher, uninstallLauncher } from "./launcher.js";
 import { applyAppProxy, caTrusted, currentAppProxy, nssDb, removeAppProxy, trustCa, untrustCa } from "./picker.js";
 import { runtime } from "./runtime.js";
 import { codexOff, codexOn } from "./codex.js";
@@ -201,37 +203,17 @@ async function install() {
     checkProxyEnv({ proxyUrl, force: flag("force") });
     // Persist the single execution contract so the GUI, admin API, hooks, and supervisor all use
     // this installation's runtime rather than any Node installation on the user's PATH.
-    fs.writeFileSync(path.join(home, "paths.json"), JSON.stringify({
-        node: installedRuntime.node,
-        env: installedRuntime.env,
-        cli: installedRuntime.cli,
-        router: installedRuntime.router,
-        hookScript: installedRuntime.hookScript,
-        repo: installedRuntime.repo,
-    }, null, 2) + "\n");
+    writePaths(installedRuntime, home);
     // Windows and Linux register node + the router script directly (schtasks.ts writes its own .cmd
     // launcher); a macOS source checkout gets a small .app so the agent shows a real name in Login Items.
-    if (installedRuntime.packaged || isWindows || isLinux) {
-        const plist = installAgent({
-            program: installedRuntime.node,
-            args: [installedRuntime.router],
-            bundleId: "com.clauderipple.app",
-            home,
-            env: { ...installedRuntime.env, ...(process.env.CLAUDE_SETTINGS_PATH ? { CLAUDE_SETTINGS_PATH: process.env.CLAUDE_SETTINGS_PATH } : {}) },
-        });
-        console.log(`✓ ${supervisorName()} registered: ${plist}${isLinux ? "" : ' (shows as "ClaudeRipple" in Login Items)'}`);
-    }
-    else {
-        const launcher = writeBundle({ home, node: installedRuntime.node, script: installedRuntime.router, version: VERSION });
+    // registration.ts holds the mapping, so `repair` registers exactly the same thing.
+    const reg = registration(installedRuntime, home, VERSION);
+    if (reg.bundle) {
+        const launcher = writeBundle({ home, node: reg.bundle.node, script: reg.bundle.script, version: reg.bundle.version });
         console.log(`✓ background item bundle written: ${path.dirname(path.dirname(path.dirname(launcher)))} (shows as "ClaudeRipple" in Login Items)`);
-        const plist = installAgent({
-            program: launcher,
-            bundleId: BUNDLE_ID,
-            home,
-            ...(process.env.CLAUDE_SETTINGS_PATH ? { env: { CLAUDE_SETTINGS_PATH: process.env.CLAUDE_SETTINGS_PATH } } : {}),
-        });
-        console.log(`✓ ${supervisorName()} registered: ${plist}`);
     }
+    const plist = installAgent({ program: reg.program, args: reg.args, bundleId: reg.bundleId, home, env: reg.env });
+    console.log(`✓ ${supervisorName()} registered: ${plist}${isLinux || reg.bundle ? "" : ' (shows as "ClaudeRipple" in Login Items)'}`);
     // launchd starts the agent the moment it is bootstrapped (RunAtLoad); a scheduled task waits for
     // its logon trigger, so the router would only appear after the next sign-in. Start it either way.
     const started = startAgent();
@@ -257,9 +239,21 @@ async function install() {
     console.log(edit.changed ? `✓ ${settingsPath()} updated (backup: ${edit.backup ?? "none"})` : `✓ ${settingsPath()} already correct`);
     for (const n of edit.notes)
         console.log(`  note: ${n}`);
+    // Something to double-click for the menu-bar app, which is what offers repair when the router is
+    // down. Never fatal: the router and Claude's settings are already in place.
+    try {
+        const app = installLauncher({ rt: installedRuntime, home, version: VERSION });
+        if (app.paths.length)
+            console.log(`✓ menu-bar app launcher: ${app.paths.join(", ")}`);
+        else if (!app.ok)
+            console.log(`  menu-bar app launcher not written: ${app.detail}`);
+    }
+    catch (e) {
+        console.log(`  menu-bar app launcher not written: ${e.message}`);
+    }
     console.log("\nDone. New Claude Desktop Code sessions go through ClaudeRipple. Existing sessions pick up settings.json env changes on their next request.");
 }
-function uninstall() {
+async function uninstall() {
     const home = homeDir();
     const cfg = new ConfigStore(configPath()).get();
     // Stop the router before unregistering it. On macOS unloading the agent takes the process with
@@ -268,9 +262,19 @@ function uninstall() {
     // Windows 11 arm64 VM).
     if (stopAgent())
         console.log("✓ router stopped");
+    // Before --purge can take the journal that says whether the router left sleep disabled.
+    await releaseHeldSleep("uninstalled");
     const removed = removeAgent();
     console.log(removed ? `✓ ${supervisorName()} removed (${agentDefinitionPath()})` : `✓ no ${supervisorName()} registered`);
     removeBundle(home);
+    try {
+        const app = uninstallLauncher({ rt: installedRuntime, home, version: VERSION });
+        if (app.paths.length)
+            console.log(`✓ menu-bar app launcher removed (${app.paths.join(", ")})`);
+    }
+    catch (e) {
+        console.log(`  could not remove the menu-bar app launcher: ${e.message}`);
+    }
     const edit = removeProxyEnv({ proxyUrl: proxyUrlFor(cfg.listen.port), caPath: certPaths(home).caPem });
     console.log(edit.changed ? `✓ ${settingsPath()} restored (backup: ${edit.backup ?? "none"})` : `✓ ${settingsPath()} had no ClaudeRipple keys`);
     for (const n of edit.notes)
@@ -443,12 +447,126 @@ async function update() {
     if (!result.ok)
         process.exitCode = 1;
 }
+// ---- Recovery: doctor, repair, direct, app ------------------------------------------------
+//
+// The menu-bar app calls these when the router is down and the dashboard with it. With --json each
+// prints one JSON object on stdout and exits 0 whatever the diagnosis; a non-zero exit means the
+// command itself could not run.
+/** This machine's supervisor, registering this installation's runtime and files. */
+function recoveryDeps() {
+    const home = homeDir();
+    const ops = nativeSupervisor(registration(installedRuntime, home, VERSION), home);
+    return {
+        home,
+        version: VERSION,
+        supervisor: {
+            inspect: () => ops.inspect(),
+            // paths.json is part of what install registers: the GUI and hooks run what it names.
+            register: () => {
+                writePaths(installedRuntime, home);
+                return ops.register();
+            },
+            start: () => ops.start(),
+        },
+    };
+}
+function printDoctor(d) {
+    const sup = d.supervisor;
+    const rows = [
+        ["mode", d.mode === "ripple" ? "ClaudeRipple" : d.mode === "direct" ? "Claude's default connection (direct)" : "mixed"],
+        ["router", d.router.responding ? `answering${d.router.version ? ` (${d.router.version}${d.router.pid ? `, pid ${d.router.pid}` : ""})` : ""} on ${d.router.url}` : `NOT answering (${d.router.adminUrl})`],
+        [supervisorName(), sup.registered ? `registered · ${sup.state} · ${sup.programExists ? "program ok" : "PROGRAM MISSING"} (${sup.program ?? "-"})` : "NOT registered"],
+        ["claude code", `${d.cli.proxy}${d.cli.url ? ` (${d.cli.url})` : ""}`],
+        ["claude desktop", `${d.desktop.proxy}${d.desktop.url ? ` (${d.desktop.url})` : ""}`],
+    ];
+    const w = Math.max(...rows.map((r) => r[0].length));
+    for (const [k, v] of rows)
+        console.log(`${k.padEnd(w)}  ${v}`);
+    if (d.problems.length === 0)
+        console.log("\n✓ no problems found");
+    else {
+        console.log("\nproblems:");
+        for (const p of d.problems)
+            console.log(`  ✗ ${p.message} [${p.code}]`);
+        console.log("\nFix what can be fixed with: clauderipple repair");
+    }
+}
+async function recovery() {
+    const json = flag("json");
+    const out = (value, text) => {
+        if (json)
+            console.log(JSON.stringify(value));
+        else {
+            text();
+            if ("ok" in value && value.ok === false)
+                process.exitCode = 1;
+        }
+    };
+    if (cmd === "doctor") {
+        const { doctor } = await import("./doctor.js");
+        const d = await doctor(recoveryDeps());
+        out(d, () => printDoctor(d));
+        return;
+    }
+    if (cmd === "repair") {
+        const { repair } = await import("./doctor.js");
+        const r = await repair(recoveryDeps());
+        out(r, () => {
+            for (const s of r.steps)
+                console.log(`${s.ok ? "✓" : "✗"} ${s.name}: ${s.detail}`);
+            console.log("");
+            printDoctor(r.doctor);
+        });
+        return;
+    }
+    if (cmd === "direct") {
+        const sub = args[1];
+        if (sub !== "on" && sub !== "off")
+            throw new Error("usage: clauderipple direct on|off [--force] [--json]");
+        const { directOn, directOff } = await import("./direct.js");
+        const r = sub === "on" ? directOn(homeDir()) : await directOff(recoveryDeps(), { force: flag("force") });
+        out(r, () => {
+            console.log(`${r.ok ? "✓" : "✗"} ${r.detail}`);
+            if (r.ok)
+                console.log("Quit and reopen Claude Desktop, and start new Claude Code sessions: both read this at start.");
+        });
+        return;
+    }
+    if (cmd === "app") {
+        const install = flag("install");
+        if (install === flag("uninstall"))
+            throw new Error("usage: clauderipple app --install|--uninstall [--json]");
+        const o = { rt: installedRuntime, home: homeDir(), version: VERSION };
+        const r = install ? installLauncher(o) : uninstallLauncher(o);
+        out(r, () => console.log(`${r.ok ? "✓" : "✗"} ${r.detail}${r.paths.length ? `\n  ${r.paths.join("\n  ")}` : ""}`));
+    }
+}
+/**
+ * A router that exits leaves the lid-closed sleep bit as it was, for its successor to reconcile
+ * (router awake.ts). When it is stopped for good there is no successor, so clear it here.
+ */
+async function releaseHeldSleep(reason) {
+    const { releaseAwake, releaseFailedHint } = await import("./awake-setup.js");
+    const { execRunner } = await import("../../router/src/awake.js");
+    const r = await releaseAwake(execRunner(), homeDir(), reason);
+    if (r === "released")
+        console.log(process.platform === "win32" ? "✓ the lid-close action is back to yours (lid-closed awake had set it to Do nothing)" : "✓ sleep re-enabled (lid-closed awake was holding the Mac awake)");
+    if (r === "failed")
+        console.log(`✗ could not re-enable sleep: ${releaseFailedHint()}`);
+}
 function help() {
     console.log(`clauderipple <command>
 
   install [--port N] [--force] [--max-context-tokens N]
   uninstall [--purge]
   status
+  doctor [--json]   what is wrong with the router, its background service and Claude's connection settings
+  repair [--json]   fix what doctor finds: re-register and start the router, wait for it to answer
+  direct on|off [--force] [--json]
+                    on: use Claude's default connection (Claude Desktop and Claude Code skip ClaudeRipple;
+                    the router stays installed); off: go through ClaudeRipple again. Restart Claude after either.
+  app --install|--uninstall [--json]
+                    a double-clickable launcher for the menu-bar app (~/Applications, Start Menu, app menu)
   start | stop | restart
   logs [-n N] [-f]
   remote [install|uninstall|status|pair]  run or manage the phone host (macOS, Windows, Linux systemd)
@@ -474,6 +592,14 @@ function help() {
   agent-title on|off|status
                     prefix subagent titles with the real model and thinking depth ("Terra·high · …") via a Claude Code hook
   mod on|off|status show where each request went above the Claude Code prompt, and the request log in a pane (/ripple-log), via a Claude Code mod
+  awake setup [--ssid <hotspot name>] [--remove]
+                    allow ClaudeRipple to keep the laptop awake with the lid closed (and join that phone hotspot).
+                    macOS: asks for your password once in macOS's own dialog, and removes Insomnia if it is installed;
+                    Windows: no administrator step, only checks (power plan, Wi-Fi adapter, saved hotspot profile)
+  awake on|off|working [--until HH:MM]
+                    working: awake while Claude works and 10 min after; on: always (until HH:MM); off: never
+  tether on|off     join the phone hotspot when Wi-Fi has no internet, and go back to Wi-Fi when a known one works
+  power [--json]    lid-closed awake and hotspot state
 
 Home directory: ${homeDir()}  (override with CLAUDERIPPLE_HOME)`);
 }
@@ -520,11 +646,17 @@ try {
             await install();
             break;
         case "uninstall":
-            uninstall();
+            await uninstall();
             break;
         case "status":
             await status();
             break;
+        case "doctor":
+        case "repair":
+        case "direct":
+        case "app":
+            await recovery();
+            break;
         case "start": {
             const r = startAgent();
             console.log(r === "already-running" ? "already running" : r === "started" ? "started" : "start failed (is it installed?)");
@@ -535,6 +667,7 @@ try {
             break;
         case "stop":
             console.log(stopAgent() ? "stopped (run `clauderipple start` or `install` to bring it back)" : "stop failed (not loaded?)");
+            await releaseHeldSleep("router stopped");
             break;
         case "logs":
             logs();
@@ -684,6 +817,24 @@ try {
         case "image":
             await image();
             break;
+        case "power":
+        case "awake":
+        case "tether": {
+            const { powerCli, adminPowerCall } = await import("./power.js");
+            const { defaultSetupDeps } = await import("./awake-setup.js");
+            const { execRunner } = await import("../../router/src/awake.js");
+            const run = execRunner();
+            process.exitCode = await powerCli(args, {
+                call: adminPowerCall(adminPort(new ConfigStore(configPath()).get())),
+                configFile: configPath(),
+                rippleHome: homeDir(),
+                run,
+                setupDeps: () => defaultSetupDeps(run, homeDir()),
+                print: (line) => console.log(line),
+                now: () => new Date(),
+            });
+            break;
+        }
         case "ui":
             ui();
             break;
@@ -691,7 +842,9 @@ try {
             await update();
             break;
         case "tray": {
-            const result = args.includes("--install") ? installTrayRuntime() : await startTray();
+            // --ensure is what the app launcher runs: fetch Electron once if it is missing, then start.
+            const ensured = args.includes("--ensure") && !installedRuntime.packaged ? installTrayRuntime() : null;
+            const result = args.includes("--install") ? installTrayRuntime() : ensured && !ensured.ok ? ensured : await startTray();
             console.log(result.message);
             if (!result.ok)
                 process.exit(1);

package/dist/cli/src/launchd.js

@@ -10,8 +10,10 @@ export const LABEL = "com.clauderipple.router";
 export function launchdLabel() {
     return process.env.CLAUDERIPPLE_LAUNCHD_LABEL ?? LABEL;
 }
+/** Test-only override (CLAUDERIPPLE_LAUNCH_AGENTS_DIR); production always uses ~/Library/LaunchAgents. */
 export function plistPath() {
-    return path.join(os.homedir(), "Library", "LaunchAgents", `${launchdLabel()}.plist`);
+    const dir = process.env.CLAUDERIPPLE_LAUNCH_AGENTS_DIR ?? path.join(os.homedir(), "Library", "LaunchAgents");
+    return path.join(dir, `${launchdLabel()}.plist`);
 }
 function esc(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -60,49 +62,56 @@ ${environment}
 </plist>
 `;
 }
-function launchctl(args) {
+/**
+ * The real launchctl, with a timeout: the menu-bar app runs doctor/repair and must get an answer.
+ * CLAUDERIPPLE_LAUNCHCTL is a test-only override naming a fake binary for end-to-end CLI tests.
+ */
+export const launchctl = (args) => {
     try {
-        const out = execFileSync("launchctl", args, { stdio: ["ignore", "pipe", "pipe"] }).toString();
+        // bootout waits for the router to exit, and a router drains for up to 90s (ExitTimeOut 120):
+        // that one call keeps a budget the drain fits in, so `stop` never reports a drain as a failure.
+        const timeout = args[0] === "bootout" ? 150_000 : 20_000;
+        const out = execFileSync(process.env.CLAUDERIPPLE_LAUNCHCTL ?? "launchctl", args, { stdio: ["ignore", "pipe", "pipe"], timeout }).toString();
         return { ok: true, out };
     }
     catch (e) {
         const err = e;
-        return { ok: false, out: `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}`.trim() };
+        return { ok: false, out: `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}`.trim() || (err.message ?? "launchctl failed") };
     }
-}
+};
 function domain() {
     return `gui/${process.getuid?.() ?? 501}`;
 }
-export function installAgent(opts) {
+export function installAgent(opts, run = launchctl) {
     const file = plistPath();
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const stdoutLog = path.join(opts.home, "logs", "launchd.log");
     fs.mkdirSync(path.dirname(stdoutLog), { recursive: true });
     fs.writeFileSync(file, renderPlist({ ...opts, stdoutLog }));
-    launchctl(["bootout", domain(), file]); // ignore result: may not be loaded
-    const r = launchctl(["bootstrap", domain(), file]);
+    run(["bootout", domain(), file]); // ignore result: may not be loaded
+    const r = run(["bootstrap", domain(), file]);
     if (!r.ok)
         throw new Error(`launchctl bootstrap failed: ${r.out}`);
     return file;
 }
-export function removeAgent() {
+export function removeAgent(run = launchctl) {
     const file = plistPath();
     if (!fs.existsSync(file))
         return false;
-    launchctl(["bootout", domain(), file]);
+    run(["bootout", domain(), file]);
     fs.unlinkSync(file);
     return true;
 }
-export function agentState() {
-    const r = launchctl(["print", `${domain()}/${launchdLabel()}`]);
+export function agentState(run = launchctl) {
+    const r = run(["print", `${domain()}/${launchdLabel()}`]);
     if (!r.ok)
         return "not-loaded";
     return /state = running/.test(r.out) ? "running" : "loaded";
 }
 /** `force` adds -k, which SIGKILLs a running instance ~5s after SIGTERM. Only restart wants that. */
-export function kickstart(opts = {}) {
+export function kickstart(opts = {}, run = launchctl) {
     const args = ["kickstart", ...(opts.force ? ["-k"] : []), `${domain()}/${launchdLabel()}`];
-    return launchctl(args).ok;
+    return run(args).ok;
 }
 /**
  * Idempotent start. A router that is already up (or still coming up) is left alone: `kickstart -k`
@@ -110,18 +119,18 @@ export function kickstart(opts = {}) {
  * up killed it and started the wait over (observed 2026-09-14: three runs in the four minutes
  * after login). Re-bootstraps the plist when the agent was unloaded by `clauderipple stop`.
  */
-export function startAgent() {
-    if (agentState() === "running")
+export function startAgent(run = launchctl) {
+    if (agentState(run) === "running")
         return "already-running";
-    if (kickstart())
+    if (kickstart({}, run))
         return "started";
     const file = plistPath();
-    if (fs.existsSync(file) && launchctl(["bootstrap", domain(), file]).ok)
+    if (fs.existsSync(file) && run(["bootstrap", domain(), file]).ok)
         return "started";
     return "failed";
 }
-export function agentPid() {
-    const r = launchctl(["print", `${domain()}/${launchdLabel()}`]);
+export function agentPid(run = launchctl) {
+    const r = run(["print", `${domain()}/${launchdLabel()}`]);
     if (!r.ok)
         return null;
     const m = /^\s*pid = (\d+)/m.exec(r.out);