clauderipple 0.10.0 → 0.11.0

package/dist/cli/src/launcher.js

@@ -0,0 +1,215 @@
+// `clauderipple app --install|--uninstall`: something to double-click that opens the menu-bar app.
+//
+// Installed from npm there is no application to open, and the menu-bar app is exactly what a
+// person needs when the router is down (it offers repair and Claude's default connection). So a
+// launcher runs `clauderipple tray --ensure`: fetch Electron once if it is missing, then start the
+// tray the way `clauderipple tray` does.
+//
+//   macOS   ~/Applications/ClaudeRipple.app — Info.plist + a shell script, bundle id
+//           com.clauderipple.launcher (the router's own background bundle in ~/.clauderipple is
+//           com.clauderipple.router, the packaged app com.clauderipple.app; none collide)
+//   Windows Start Menu and Desktop shortcuts (.lnk, WScript.Shell) to a hidden PowerShell launcher
+//   Linux   ~/.local/share/applications/clauderipple.desktop
+//
+// CLAUDERIPPLE_LAUNCHER_DIR replaces every target directory (tests, or a custom location).
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { windowsPowerShellEnv } from "./windows-powershell.js";
+export const LAUNCHER_BUNDLE_ID = "com.clauderipple.launcher";
+const APP_NAME = "ClaudeRipple";
+const DESKTOP_MARK = "X-ClaudeRipple-Launcher=1";
+function overrideDir() {
+    return process.env.CLAUDERIPPLE_LAUNCHER_DIR ?? null;
+}
+export function macAppPath() {
+    return path.join(overrideDir() ?? path.join(os.homedir(), "Applications"), `${APP_NAME}.app`);
+}
+export function desktopEntryPath() {
+    const data = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+    return path.join(overrideDir() ?? path.join(data, "applications"), "clauderipple.desktop");
+}
+export function windowsTrayLauncherPath(home) {
+    return path.join(home, "clauderipple-tray.ps1");
+}
+/** POSIX single-quoted literal. */
+function sh(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** PowerShell single-quoted literal; the only escape inside one is a doubled quote. */
+function ps(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** A desktop-entry Exec argument (freedesktop Desktop Entry spec, "The Exec key"). */
+function execArg(value) {
+    return `"${value.replace(/([\\"`$])/g, "\\$1").replace(/%/g, "%%")}"`;
+}
+function launchEnv(rt, home) {
+    return { CLAUDERIPPLE_HOME: home, ...rt.env };
+}
+/** The app icon (icon.icns / icon.png / icon.ico), committed in the app's assets and shipped in the npm package beside the tray. */
+function findIcon(rt, file) {
+    for (const dir of [path.join(rt.repo, "packages", "app", "assets"), path.join(rt.repo, "dist", "app", "assets")]) {
+        const p = path.join(dir, file);
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function macInfoPlist(version, icon) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key><string>${APP_NAME}</string>
+  <key>CFBundleDisplayName</key><string>${APP_NAME}</string>
+  <key>CFBundleIdentifier</key><string>${LAUNCHER_BUNDLE_ID}</string>
+  <key>CFBundleVersion</key><string>${version}</string>
+  <key>CFBundleShortVersionString</key><string>${version}</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleExecutable</key><string>${APP_NAME}</string>
+${icon ? "  <key>CFBundleIconFile</key><string>icon</string>\n" : ""}  <key>LSUIElement</key><true/>
+</dict>
+</plist>
+`;
+}
+export function macLauncherScript(rt, home) {
+    const log = path.join(home, "logs", "launcher.log");
+    return [
+        "#!/bin/sh",
+        "# Opens the ClaudeRipple menu-bar app (generated by `clauderipple app --install`).",
+        ...Object.entries(launchEnv(rt, home)).map(([k, v]) => `export ${k}=${sh(v)}`),
+        `mkdir -p ${sh(path.dirname(log))}`,
+        `exec ${sh(rt.node)} ${sh(rt.cli)} tray --ensure >> ${sh(log)} 2>&1`,
+        "",
+    ].join("\n");
+}
+export function desktopEntry(rt, home) {
+    const env = Object.entries(launchEnv(rt, home)).map(([k, v]) => execArg(`${k}=${v}`));
+    const icon = findIcon(rt, "icon.png");
+    return [
+        "[Desktop Entry]",
+        "Type=Application",
+        `Name=${APP_NAME}`,
+        "Comment=ClaudeRipple menu-bar app: router status, repair, and Claude's default connection",
+        `Exec=env ${env.join(" ")} ${execArg(rt.node)} ${execArg(rt.cli)} tray --ensure`,
+        ...(icon ? [`Icon=${icon}`] : []),
+        "Terminal=false",
+        "Categories=Utility;Development;",
+        DESKTOP_MARK,
+        "",
+    ].join("\n");
+}
+export function windowsTrayLauncher(rt, home) {
+    const log = path.join(home, "logs", "launcher.log");
+    return [
+        ...Object.entries(launchEnv(rt, home)).map(([k, v]) => `$env:${k} = ${ps(v)}`),
+        `New-Item -ItemType Directory -Force -Path ${ps(path.dirname(log))} | Out-Null`,
+        `& ${ps(rt.node)} ${ps(rt.cli)} tray --ensure *>> ${ps(log)}`,
+    ].join("\r\n") + "\r\n";
+}
+/**
+ * Creates (or, with `remove`, deletes) the shortcuts and prints each path. Without an override the
+ * folders are the user's own Start Menu programs and Desktop, as Windows names them.
+ */
+export function windowsShortcutScript(launcher, iconSource, dir, remove = false) {
+    const targets = dir
+        ? `@(${ps(path.join(dir, "Start Menu", `${APP_NAME}.lnk`))}, ${ps(path.join(dir, "Desktop", `${APP_NAME}.lnk`))})`
+        : `@((Join-Path ([Environment]::GetFolderPath('Programs')) '${APP_NAME}.lnk'), (Join-Path ([Environment]::GetFolderPath('Desktop')) '${APP_NAME}.lnk'))`;
+    if (remove) {
+        return [`$ErrorActionPreference = 'Stop'`, `foreach ($p in ${targets}) { if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p -Force; $p } }`].join("; ");
+    }
+    // conhost --headless: started directly, PowerShell gets a console from the default terminal and
+    // a window stays on screen (#49, the same reason the router's scheduled task uses it).
+    const args = `--headless powershell.exe -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${launcher}"`;
+    return [
+        `$ErrorActionPreference = 'Stop'`,
+        `$ws = New-Object -ComObject WScript.Shell`,
+        `foreach ($p in ${targets}) { New-Item -ItemType Directory -Force -Path (Split-Path -Parent $p) | Out-Null; $s = $ws.CreateShortcut($p); $s.TargetPath = (Join-Path $env:SystemRoot 'System32\\conhost.exe'); $s.Arguments = ${ps(args)}; $s.IconLocation = ${ps(`${iconSource},0`)}; $s.Description = 'ClaudeRipple menu-bar app'; $s.Save(); $p }`,
+    ].join("; ");
+}
+function runPowerShell(script) {
+    return execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+        env: windowsPowerShellEnv(),
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        timeout: 30_000,
+    }).toString();
+}
+/** Bundle id of an existing .app, or null when it has none we can read. */
+function bundleIdOf(app) {
+    try {
+        const plist = fs.readFileSync(path.join(app, "Contents", "Info.plist"), "utf8");
+        return /<key>CFBundleIdentifier<\/key>\s*<string>([^<]*)<\/string>/.exec(plist)?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function installLauncher(opts) {
+    const platform = opts.platform ?? process.platform;
+    if (opts.rt.packaged)
+        return { ok: true, paths: [], detail: "This is the standalone ClaudeRipple app, which opens the menu-bar app itself; no launcher needed." };
+    if (platform === "darwin") {
+        const app = macAppPath();
+        // The packaged app may sit there under the same name: never write into someone else's bundle.
+        if (fs.existsSync(app) && bundleIdOf(app) !== LAUNCHER_BUNDLE_ID) {
+            return { ok: false, paths: [], detail: `${app} already exists and is not ClaudeRipple's launcher; left it alone.` };
+        }
+        const contents = path.join(app, "Contents");
+        fs.mkdirSync(path.join(contents, "MacOS"), { recursive: true });
+        const icns = findIcon(opts.rt, "icon.icns");
+        if (icns) {
+            fs.mkdirSync(path.join(contents, "Resources"), { recursive: true });
+            fs.copyFileSync(icns, path.join(contents, "Resources", "icon.icns"));
+        }
+        fs.writeFileSync(path.join(contents, "Info.plist"), macInfoPlist(opts.version, icns !== null));
+        fs.writeFileSync(path.join(contents, "MacOS", APP_NAME), macLauncherScript(opts.rt, opts.home), { mode: 0o755 });
+        fs.chmodSync(path.join(contents, "MacOS", APP_NAME), 0o755);
+        return { ok: true, paths: [app], detail: `Open ${APP_NAME} from ${path.dirname(app)} (or Spotlight) to start the menu-bar app.` };
+    }
+    if (platform === "linux") {
+        const file = desktopEntryPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, desktopEntry(opts.rt, opts.home), { mode: 0o755 });
+        return { ok: true, paths: [file], detail: `${APP_NAME} is in your applications menu.` };
+    }
+    if (platform === "win32") {
+        const launcher = windowsTrayLauncherPath(opts.home);
+        fs.mkdirSync(opts.home, { recursive: true });
+        fs.writeFileSync(launcher, windowsTrayLauncher(opts.rt, opts.home));
+        const out = (opts.powershell ?? runPowerShell)(windowsShortcutScript(launcher, findIcon(opts.rt, "icon.ico") ?? opts.rt.node, overrideDir()));
+        const paths = out.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+        return { ok: true, paths, detail: `${APP_NAME} is in the Start Menu and on the Desktop.` };
+    }
+    return { ok: false, paths: [], detail: `no launcher for ${platform}; start the menu-bar app with: clauderipple tray` };
+}
+export function uninstallLauncher(opts) {
+    const platform = opts.platform ?? process.platform;
+    const removed = [];
+    if (platform === "darwin") {
+        const app = macAppPath();
+        if (fs.existsSync(app)) {
+            if (bundleIdOf(app) !== LAUNCHER_BUNDLE_ID)
+                return { ok: false, paths: [], detail: `${app} is not ClaudeRipple's launcher; left it alone.` };
+            fs.rmSync(app, { recursive: true, force: true });
+            removed.push(app);
+        }
+    }
+    else if (platform === "linux") {
+        const file = desktopEntryPath();
+        if (fs.existsSync(file)) {
+            if (!fs.readFileSync(file, "utf8").includes(DESKTOP_MARK))
+                return { ok: false, paths: [], detail: `${file} is not ClaudeRipple's launcher; left it alone.` };
+            fs.rmSync(file);
+            removed.push(file);
+        }
+    }
+    else if (platform === "win32") {
+        const out = (opts.powershell ?? runPowerShell)(windowsShortcutScript(windowsTrayLauncherPath(opts.home), opts.rt.node, overrideDir(), true));
+        removed.push(...out.split(/\r?\n/).map((l) => l.trim()).filter(Boolean));
+        fs.rmSync(windowsTrayLauncherPath(opts.home), { force: true });
+    }
+    return { ok: true, paths: removed, detail: removed.length ? "launcher removed" : "no launcher was installed" };
+}

package/dist/cli/src/power.js

@@ -0,0 +1,182 @@
+// `clauderipple power | awake … | tether …` — lid-closed awake and hotspot failover from the
+// terminal. Changes go through the running router's admin API (`PUT /api/power`), which saves them
+// and applies them at once; with no router answering they are saved to config.json and apply when it
+// starts (and `awake off` also clears a sleep bit the router left set).
+import { persistPowerChange } from "../../router/src/power.js";
+import { awakeRemove, awakeSetup, releaseAwake, releaseFailedHint } from "./awake-setup.js";
+/** `HH:MM` → the next time the clock shows it (today, else tomorrow), as ISO. A full ISO time is accepted too. */
+export function parseUntil(text, now) {
+    const m = /^(\d{1,2}):(\d{2})$/.exec(text);
+    if (!m) {
+        const t = Date.parse(text);
+        if (/^\d{4}-\d{2}-\d{2}T/.test(text) && !Number.isNaN(t))
+            return new Date(t).toISOString();
+        throw new Error(`--until takes HH:MM (24-hour), got "${text}"`);
+    }
+    const h = Number(m[1]);
+    const min = Number(m[2]);
+    if (h > 23 || min > 59)
+        throw new Error(`--until takes HH:MM (24-hour), got "${text}"`);
+    const at = new Date(now);
+    at.setHours(h, min, 0, 0);
+    if (at.getTime() <= now.getTime())
+        at.setDate(at.getDate() + 1);
+    return at.toISOString();
+}
+const clock = (iso) => new Date(iso).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+export function formatPower(s) {
+    const a = s.awake;
+    const t = s.tether;
+    const lines = [];
+    const setup = a.setup === "ok" ? "" : a.setup === "needs-setup" ? " · needs setup: clauderipple awake setup" : " · not supported here";
+    const machine = s.platform === "win32" ? "PC" : "Mac";
+    lines.push(`awake   ${a.mode}${a.until ? ` until ${clock(a.until)}` : ""} · ${a.applied ? `holding the ${machine} awake` : "sleep allowed"} (${a.reason})${setup}`);
+    const facts = [];
+    if (a.battery)
+        facts.push(a.battery.percent === null ? "no battery" : `battery ${a.battery.percent}% ${a.battery.onBattery ? "(on battery)" : "(on power)"}`);
+    if (a.thermal)
+        facts.push(`thermal ${a.thermal}`);
+    if (a.lidClosed !== null)
+        facts.push(`lid ${a.lidClosed ? "closed" : "open"}`);
+    if (facts.length)
+        lines.push(`        ${facts.join(" · ")}`);
+    if (!t.enabled)
+        lines.push(`tether  off${t.state === "unsupported" ? " (not supported here)" : ""}`);
+    else {
+        lines.push(`tether  on · ${t.network} · ${t.state}${t.pinned ? " (pinned)" : ""}${t.hotspotSsid ? ` · hotspot "${t.hotspotSsid}"` : ""}`);
+        if (t.lastProbe)
+            lines.push(`        last probe ${t.lastProbe.ok ? "ok" : "FAILED"} at ${clock(t.lastProbe.at)}`);
+        if (t.lastSwitch)
+            lines.push(`        last switch to ${t.lastSwitch.to} at ${clock(t.lastSwitch.at)}: ${t.lastSwitch.ok ? "ok" : "failed"} (${t.lastSwitch.reason})`);
+    }
+    if (t.hint && t.enabled)
+        lines.push(`        → ${t.hint}`);
+    return lines;
+}
+export function adminPowerCall(port) {
+    return async (method, body) => {
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/api/power`, {
+                method,
+                signal: AbortSignal.timeout(15_000),
+                ...(body ? { headers: { "content-type": "application/json" }, body: JSON.stringify(body) } : {}),
+            });
+            return { status: res.status, json: await res.json().catch(() => ({})) };
+        }
+        catch {
+            return null;
+        }
+    };
+}
+export const POWER_USAGE = `usage:
+  clauderipple power [--json]
+  clauderipple awake setup [--ssid <hotspot name>] [--remove]
+  clauderipple awake on|off|working [--until HH:MM]
+  clauderipple tether on|off`;
+/** Runs `power`, `awake …` or `tether …`; returns the exit code. */
+export async function powerCli(args, d) {
+    const [cmd, sub] = args;
+    const opt = (name) => {
+        const i = args.indexOf(`--${name}`);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const flag = (name) => args.includes(`--${name}`);
+    const platform = d.platform ?? process.platform;
+    const machine = platform === "win32" ? "PC" : "Mac";
+    const show = async () => {
+        const r = await d.call("GET");
+        if (!r) {
+            d.print("the router is not answering; start it with: clauderipple start");
+            return 1;
+        }
+        if (r.status !== 200) {
+            d.print(`error: ${r.json.error ?? `HTTP ${r.status}`}`);
+            return 1;
+        }
+        if (flag("json"))
+            d.print(JSON.stringify(r.json));
+        else
+            for (const line of formatPower(r.json))
+                d.print(line);
+        return 0;
+    };
+    /** Through the router when it answers; saved to the file otherwise. */
+    const change = async (c) => {
+        const r = await d.call("PUT", c);
+        if (r && r.status === 200) {
+            for (const line of formatPower(r.json))
+                d.print(line);
+            return 0;
+        }
+        if (r) {
+            d.print(`error: ${r.json.error ?? `HTTP ${r.status}`}`);
+            return 1;
+        }
+        persistPowerChange(d.configFile, c);
+        d.print("✓ saved to config.json; the router is not running, so it applies when it starts (clauderipple start)");
+        if (c.awake?.mode === "off") {
+            const released = await releaseAwake(d.run, d.rippleHome, "awake off (router not running)", platform);
+            if (released === "released")
+                d.print(platform === "win32" ? "✓ the lid-close action is back to yours (the router had left it on Do nothing)" : "✓ sleep re-enabled (the router had left it disabled)");
+            if (released === "failed")
+                d.print(`✗ could not re-enable sleep: ${releaseFailedHint(platform)}`);
+        }
+        return 0;
+    };
+    if (cmd === "power")
+        return show();
+    if (cmd === "awake") {
+        if (sub === undefined || sub === "status")
+            return show();
+        if (sub === "setup") {
+            if (flag("remove")) {
+                // Off first, so a running router stops re-applying while the rule goes away.
+                await change({ awake: { mode: "off" }, tether: { enabled: false } });
+                const r = await awakeRemove(d.setupDeps());
+                d.print(`${r.ok ? "✓" : "✗"} ${r.detail}`);
+                return r.ok ? 0 : 1;
+            }
+            const ssid = opt("ssid");
+            if (args.includes("--ssid") && (ssid === undefined || ssid.startsWith("--"))) {
+                d.print("usage: clauderipple awake setup --ssid <hotspot name>");
+                return 1;
+            }
+            const r = await awakeSetup(ssid !== undefined ? { ssid } : {}, d.setupDeps());
+            d.print(`${r.ok ? "✓" : "✗"} ${r.detail}`);
+            if (!r.ok)
+                return 1;
+            if (ssid !== undefined)
+                persistPowerChange(d.configFile, { tether: { hotspotSsid: ssid } });
+            d.print("");
+            d.print("Next:");
+            d.print(`  clauderipple awake working   keep the ${machine} awake (lid closed too) while Claude works, and 10 min after`);
+            d.print("  clauderipple awake on [--until HH:MM]   keep it awake regardless");
+            if (ssid !== undefined)
+                d.print("  clauderipple tether on       join the phone hotspot when Wi-Fi has no internet, and come back later");
+            d.print(`Keep a closed ${machine === "PC" ? "laptop" : "Mac"} on a hard, ventilated surface — never in a bag while it is held awake.`);
+            return 0;
+        }
+        if (sub === "on" || sub === "off" || sub === "working") {
+            const raw = opt("until");
+            let until = null;
+            if (raw !== undefined) {
+                if (sub === "off") {
+                    d.print("--until applies to on and working");
+                    return 1;
+                }
+                try {
+                    until = parseUntil(raw, d.now());
+                }
+                catch (e) {
+                    d.print(e.message);
+                    return 1;
+                }
+            }
+            return change({ awake: { mode: sub, until } });
+        }
+    }
+    if (cmd === "tether" && (sub === "on" || sub === "off"))
+        return change({ tether: { enabled: sub === "on" } });
+    d.print(POWER_USAGE);
+    return 1;
+}

package/dist/cli/src/registration.js

@@ -0,0 +1,157 @@
+// What `install` registers with the supervisor, as data — so `repair` can register exactly the
+// same thing and `doctor` can tell whether what is registered is still this installation's.
+//
+// The failure this exists for (2026-10-20): the launchd plist named a program that no longer
+// existed, so launchd could not start the router, Claude Desktop and Claude Code got
+// ECONNREFUSED on everything, and the dashboard — served by the router — was gone with it.
+import fs from "node:fs";
+import path from "node:path";
+import { BUNDLE_ID, launcherPath, launcherScript, writeBundle } from "./bundle.js";
+import * as launchd from "./launchd.js";
+import * as schtasks from "./schtasks.js";
+import * as systemd from "./systemd.js";
+/**
+ * Windows and Linux register the runtime + router script directly; so does a packaged app. A macOS
+ * source checkout or npm install runs a generated bundle instead (bundle.ts). `platform` is a
+ * parameter only so this pure mapping can be tested for every platform; nothing here runs anything.
+ */
+export function registration(rt, home, version, platform = process.platform, settingsPathEnv = process.env.CLAUDE_SETTINGS_PATH ?? null) {
+    const settingsEnv = settingsPathEnv ? { CLAUDE_SETTINGS_PATH: settingsPathEnv } : {};
+    if (rt.packaged || platform === "win32" || platform === "linux") {
+        return { program: rt.node, args: [rt.router], bundleId: "com.clauderipple.app", env: { ...rt.env, ...settingsEnv }, bundle: null };
+    }
+    return { program: launcherPath(home), args: [], bundleId: BUNDLE_ID, env: settingsEnv, bundle: { node: rt.node, script: rt.router, version } };
+}
+/** The single execution contract the GUI, admin API, hooks and supervisor read (`paths.json`). */
+export function writePaths(rt, home) {
+    const file = path.join(home, "paths.json");
+    fs.mkdirSync(home, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ node: rt.node, env: rt.env, cli: rt.cli, router: rt.router, hookScript: rt.hookScript, repo: rt.repo }, null, 2) + "\n");
+    return file;
+}
+/** Reads only the head of `file`: the program is often a 100MB binary, and only a script matters. */
+function head(file) {
+    let fd = null;
+    try {
+        fd = fs.openSync(file, "r");
+        const buf = Buffer.alloc(4096);
+        const n = fs.readSync(fd, buf, 0, buf.length, 0);
+        return buf.subarray(0, n).toString("utf8");
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== null)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * Whether everything the definition starts exists. A launcher script (the macOS bundle) is followed
+ * one step: its `exec "node" "router"` targets are what actually went missing when node moved.
+ */
+export function targetsExist(program, args) {
+    if (!program || !fs.existsSync(program))
+        return false;
+    const paths = args.filter((a) => path.isAbsolute(a));
+    const text = head(program);
+    if (text.startsWith("#!")) {
+        const exec = /^exec\s+(.+)$/m.exec(text)?.[1] ?? "";
+        for (const m of exec.matchAll(/"([^"]+)"|'([^']+)'/g)) {
+            const p = m[1] ?? m[2];
+            if (path.isAbsolute(p))
+                paths.push(p);
+        }
+    }
+    return paths.every((p) => fs.existsSync(p));
+}
+function unescapeXml(s) {
+    return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+/** ProgramArguments from a launchd plist, or [] when there are none. */
+export function plistProgramArguments(xml) {
+    const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml)?.[1];
+    if (!array)
+        return [];
+    return [...array.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unescapeXml(m[1]));
+}
+/** ExecStart's words from a systemd unit, undoing the quoting renderUnit applies. */
+export function unitExecStart(unit) {
+    const line = /^ExecStart=(.*)$/m.exec(unit)?.[1];
+    if (!line)
+        return [];
+    return [...line.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)].map((m) => m[1] !== undefined ? m[1].replace(/\$\$/g, "$").replace(/%%/g, "%").replace(/\\(.)/g, "$1") : m[2]);
+}
+/** Program and arguments from the Windows launcher script renderLauncher writes. */
+export function launcherProgram(ps1) {
+    const program = /-FilePath '((?:[^']|'')*)'/.exec(ps1)?.[1]?.replace(/''/g, "'");
+    if (!program)
+        return [];
+    const list = /^\$routerArgs = @\((.*)\)$/m.exec(ps1)?.[1] ?? "";
+    const args = [...list.matchAll(/'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'").replace(/^"(.*)"$/, "$1"));
+    return [program, ...args];
+}
+function readText(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function view(definition, registered, current, state, pid) {
+    const [program = null, ...args] = definition;
+    return { registered, program, args, programExists: targetsExist(program, args), state, pid, current };
+}
+/** launchd, with an injectable launchctl so tests never reach the real one. */
+export function launchdSupervisor(reg, home, run = launchd.launchctl) {
+    const stdoutLog = path.join(home, "logs", "launchd.log");
+    const opts = { program: reg.program, args: reg.args, bundleId: reg.bundleId, home, env: reg.env };
+    return {
+        inspect() {
+            const text = readText(launchd.plistPath());
+            const bundleCurrent = !reg.bundle || readText(launcherPath(home)) === launcherScript({ home, node: reg.bundle.node, script: reg.bundle.script });
+            const current = text !== null && text === launchd.renderPlist({ ...opts, stdoutLog }) && bundleCurrent;
+            return view(text ? plistProgramArguments(text) : [], text !== null, current, launchd.agentState(run), launchd.agentPid(run));
+        },
+        register() {
+            if (reg.bundle)
+                writeBundle({ home, node: reg.bundle.node, script: reg.bundle.script, version: reg.bundle.version });
+            return launchd.installAgent(opts, run);
+        },
+        start: () => launchd.startAgent(run),
+    };
+}
+export function systemdSupervisor(reg, home) {
+    const opts = { program: reg.program, args: reg.args, home, env: reg.env };
+    return {
+        inspect() {
+            const text = readText(systemd.unitPath());
+            return view(text ? unitExecStart(text) : [], text !== null, text === systemd.renderUnit(opts), systemd.agentState(), systemd.agentPid());
+        },
+        register: () => systemd.installAgent(opts),
+        start: () => systemd.startAgent(),
+    };
+}
+export function schtasksSupervisor(reg, home) {
+    const opts = { program: reg.program, args: reg.args, home, env: reg.env };
+    const launcher = path.join(home, "clauderipple-router.ps1");
+    return {
+        inspect() {
+            const text = readText(launcher);
+            const registered = schtasks.existingTaskDefinition() !== null;
+            return view(text ? launcherProgram(text) : [], registered, registered && text === schtasks.renderLauncher(opts), schtasks.agentState(), schtasks.agentPid());
+        },
+        // installAgent keeps an existing task whose whole definition already matches (issue #9).
+        register: () => schtasks.installAgent(opts),
+        start: () => schtasks.startAgent(),
+    };
+}
+/** This machine's supervisor. Chosen by the real platform, never a spoofed one. */
+export function nativeSupervisor(reg, home) {
+    if (process.platform === "win32")
+        return schtasksSupervisor(reg, home);
+    if (process.platform === "linux")
+        return systemdSupervisor(reg, home);
+    return launchdSupervisor(reg, home);
+}

package/dist/cli/src/schtasks.js

@@ -31,6 +31,8 @@ function run(script) {
             env: windowsPowerShellEnv(),
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
+            // A hung PowerShell must not hang doctor/repair, which the menu-bar app waits on.
+            timeout: 60_000,
         }).toString();
         return { ok: true, out: out.trim() };
     }

package/dist/cli/src/settings.js

@@ -157,6 +157,30 @@ export function removeProxyEnv(opts) {
     write(file, next);
     return { changed: true, backup: b, notes, wroteSlots: [] };
 }
+/**
+ * Applies `mutate` to a copy of settings.json's env block and writes it back (with a backup) only
+ * when it reports a change. Every other key in the file is kept as it was; an emptied env block is
+ * dropped. For callers that own a precise set of keys, such as `direct on|off`.
+ */
+export function editSettingsEnv(mutate) {
+    const file = settingsPath();
+    const s = readSettings(file);
+    const env = { ...(s.env ?? {}) };
+    if (!mutate(env))
+        return { changed: false, backup: null, notes: [], wroteSlots: [] };
+    const b = backup(file);
+    const next = { ...s };
+    if (Object.keys(env).length === 0)
+        delete next.env;
+    else
+        next.env = env;
+    write(file, next);
+    return { changed: true, backup: b, notes: [], wroteSlots: [] };
+}
+/** settings.json's whole env block (empty when the file or the block is missing). */
+export function settingsEnv() {
+    return { ...(readSettings(settingsPath()).env ?? {}) };
+}
 export function currentProxyEnv() {
     const env = readSettings(settingsPath()).env ?? {};
     const out = {};

package/dist/cli/src/tray.js

@@ -58,10 +58,13 @@ export function trayEnv(env = process.env) {
  */
 export async function startTray(options = {}) {
     const current = runtime();
+    // Started by hand (the app icon, `clauderipple tray`), the window opens; started by the logon
+    // supervisor in the foreground, it stays in the tray. The login item launches Electron directly.
+    const env = { ...trayEnv(), ...((options.detached ?? true) ? { CLAUDERIPPLE_APP_SHOW: "1" } : {}) };
     if (current.packaged) {
         // The packaged app IS the tray: relaunching its own binary with no script is what opens it.
         // Our own CLI runs under ELECTRON_RUN_AS_NODE here, and inheriting it would relaunch Node.
-        const child = spawn(current.node, [], { detached: true, stdio: "ignore", env: trayEnv() });
+        const child = spawn(current.node, [], { detached: true, stdio: "ignore", env });
         child.unref();
         return { ok: true, message: "✓ tray started" };
     }
@@ -85,7 +88,7 @@ export async function startTray(options = {}) {
         detached: options.detached ?? true,
         stdio: ["ignore", out, out],
         // Electron would otherwise re-enter as a plain Node process, since that is how the CLI runs.
-        env: trayEnv(),
+        env,
     });
     fs.closeSync(out);
     if (options.detached ?? true)