clauderipple 0.10.0 → 0.11.0

package/dist/cli/src/awake-setup.js

@@ -0,0 +1,314 @@
+// `clauderipple awake setup [--ssid NAME] [--remove]` — the one privileged step behind lid-closed
+// awake and hotspot failover (router: awake.ts, tether.ts).
+//
+// It installs /etc/sudoers.d/clauderipple, which lets this user run exactly these as root, without a
+// password (the router only ever uses `sudo -n`, which fails rather than prompting):
+//   /usr/bin/pmset -a disablesleep 0 | 1     hold a closed MacBook awake, and release it
+//   /usr/bin/pmset sleepnow                  put a closed Mac to sleep when we release it
+//   /usr/sbin/networksetup -setairportnetwork <wifi device> <hotspot name>   (only with a hotspot name)
+// The grant is per user, not per app (Insomnia's README says the same of its own rule).
+//
+// The rule text is built here and written to a temp file by this (unprivileged) process; the one
+// privileged step is a single `osascript … do shell script … with administrator privileges`, so the
+// user types their password into macOS's own dialog. That script copies the file root-owned, checks
+// its SHA-256 against what was built (nothing can swap it in between), checks it with `visudo -cf`,
+// moves it into place, and checks the whole sudoers config again — removing ours if that fails, so a
+// broken rule can never lock the user out of sudo. Only then does it clear Insomnia's privileged
+// leftovers; the rest of Insomnia is removed unprivileged afterwards. Everything is built as data
+// and unit-tested as text: no SSID ever reaches a shell (it is validated, then only written to the
+// file), and every path in the script is single-quoted.
+//
+// Windows has no privileged step (docs/ARCHITECTURE.md §8, Windows): power plans carry one ACL that
+// gives Authenticated Users read/write, and joining a saved Wi-Fi profile is a user action. `awake
+// setup` there checks instead of installing: that this account may change the lid-close action (a
+// write of the values already there — a Group Policy override refuses it), and with `--ssid` that the
+// Wi-Fi adapter, the hotspot's saved profile and an automatic profile to come back to exist.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ssidProblem } from "../../router/src/config.js";
+import { PMSET, SUDO, SUDOERS_FILE, readJournal } from "../../router/src/awake.js";
+import { POWERSHELL, powershellEnv, psArgs, readLidAction, restoreLidFromJournal, writeLidAction } from "../../router/src/awake-win.js";
+import { NETWORKSETUP, parseWifiDevice } from "../../router/src/tether.js";
+import { FIND_WIFI_PS, WIN_HINTS, autoProfiles, hotspotProfile, listWifiProfiles, parseAdapterName } from "../../router/src/tether-win.js";
+export const OSASCRIPT = "/usr/bin/osascript";
+const STAGED = "/etc/sudoers.d/.clauderipple.new"; // sudo ignores names containing a dot
+const INSOMNIA_SUDOERS = "/etc/sudoers.d/insomnia";
+const INSOMNIA_LABEL = "com.insomnia.backstop";
+const INSOMNIA_KEYCHAIN_SERVICE = "insomnia-hotspot";
+/** POSIX single quotes: the only character that needs care inside them is the quote itself. */
+export function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** An AppleScript string literal. */
+export function asString(s) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+export function userProblem(user) {
+    return /^[A-Za-z_][A-Za-z0-9_.-]{0,31}$/.test(user) ? null : `unexpected user name "${user}"`;
+}
+/** The sudoers drop-in. Throws on anything that could not be written literally. */
+export function sudoersRule(o) {
+    const bad = userProblem(o.user);
+    if (bad)
+        throw new Error(bad);
+    const commands = [`${PMSET} -a disablesleep 0`, `${PMSET} -a disablesleep 1`, `${PMSET} sleepnow`];
+    if (o.ssid !== undefined) {
+        const problem = ssidProblem(o.ssid);
+        if (problem)
+            throw new Error(problem);
+        if (!o.wifiDevice || !/^en\d+$/.test(o.wifiDevice))
+            throw new Error(`unexpected Wi-Fi device "${o.wifiDevice ?? ""}"`);
+        commands.push(`${NETWORKSETUP} -setairportnetwork ${o.wifiDevice} ${o.ssid}`);
+    }
+    return [
+        "# ClaudeRipple: keep the Mac awake with the lid closed, and join the phone hotspot.",
+        "# Installed by `clauderipple awake setup`; removed by `clauderipple awake setup --remove`.",
+        `${o.user} ALL=(root) NOPASSWD: ${commands.join(", ")}`,
+        "",
+    ].join("\n");
+}
+function pathProblem(p) {
+    return /^\/[A-Za-z0-9/._-]+$/.test(p) ? null : `unexpected characters in path ${p}`;
+}
+/** The privileged shell script for install. One line, run by `do shell script` (/bin/sh). */
+export function installScript(o) {
+    const bad = pathProblem(o.tempFile);
+    if (bad)
+        throw new Error(bad);
+    if (!/^[0-9a-f]{64}$/.test(o.sha256))
+        throw new Error("bad sha256");
+    const undoStaged = `{ /bin/rm -f ${shQuote(STAGED)}; exit 3; }`;
+    const steps = [
+        "set -e",
+        `/usr/bin/install -m 0440 -o root -g wheel ${shQuote(o.tempFile)} ${shQuote(STAGED)}`,
+        `[ "$(/usr/bin/shasum -a 256 ${shQuote(STAGED)} | /usr/bin/cut -c1-64)" = ${shQuote(o.sha256)} ] || ${undoStaged}`,
+        `/usr/sbin/visudo -cf ${shQuote(STAGED)} || ${undoStaged}`,
+        `/bin/mv -f ${shQuote(STAGED)} ${shQuote(SUDOERS_FILE)}`,
+        `/usr/sbin/visudo -c || { /bin/rm -f ${shQuote(SUDOERS_FILE)}; exit 4; }`,
+    ];
+    // Insomnia's privileged leftovers, only after ours is safely in place: clear the sleep bit it may
+    // have left set (its backstop is about to go), then its rule.
+    if (o.removeInsomnia)
+        steps.push(`${PMSET} -a disablesleep 0`, `/bin/rm -f ${shQuote(INSOMNIA_SUDOERS)}`);
+    return steps.join("; ");
+}
+/** The privileged shell script for `--remove`. Clears the bit only if our journal says we set it. */
+export function removeScript(o) {
+    const steps = ["set -e"];
+    if (o.clearSleepBit)
+        steps.push(`${PMSET} -a disablesleep 0`);
+    steps.push(`/bin/rm -f ${shQuote(SUDOERS_FILE)} ${shQuote(STAGED)}`);
+    return steps.join("; ");
+}
+/** `osascript` arguments that run `script` as root after macOS's own password dialog. */
+export function adminOsascriptArgs(script, prompt) {
+    return ["-e", `do shell script ${asString(script)} with prompt ${asString(prompt)} with administrator privileges`];
+}
+export function insomniaPaths(home) {
+    return {
+        plist: path.join(home, "Library", "LaunchAgents", `${INSOMNIA_LABEL}.plist`),
+        app: path.join(home, "Applications", "Insomnia.app"),
+    };
+}
+/** Insomnia's unprivileged leftovers, in order. Failures are reported, not fatal. */
+export function insomniaCleanupSteps(o) {
+    const p = insomniaPaths(o.home);
+    const steps = [{ label: "stop Insomnia's backstop agent", kind: "run", file: "/bin/launchctl", args: ["bootout", `gui/${o.uid}/${INSOMNIA_LABEL}`] }];
+    if (o.exists(p.plist))
+        steps.push({ label: "move the backstop agent's plist to the Trash", kind: "trash", path: p.plist });
+    steps.push({ label: "quit Insomnia", kind: "run", file: "/usr/bin/killall", args: ["-TERM", "Insomnia"] });
+    if (o.exists(p.app))
+        steps.push({ label: "move Insomnia.app to the Trash", kind: "trash", path: p.app });
+    steps.push({ label: "delete Insomnia's hotspot password from the keychain", kind: "run", file: "/usr/bin/security", args: ["delete-generic-password", "-s", INSOMNIA_KEYCHAIN_SERVICE] });
+    return steps;
+}
+export function insomniaPresent(home, exists) {
+    const p = insomniaPaths(home);
+    return exists(INSOMNIA_SUDOERS) || exists(p.plist) || exists(p.app);
+}
+export function defaultSetupDeps(run, rippleHome) {
+    const info = os.userInfo();
+    return {
+        platform: process.platform,
+        run,
+        user: info.username,
+        uid: info.uid,
+        home: os.homedir(),
+        rippleHome,
+        exists: (p) => fs.existsSync(p),
+        writeTemp: (content) => {
+            const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clauderipple-sudoers-"));
+            const file = path.join(dir, "clauderipple");
+            fs.writeFileSync(file, content, { mode: 0o644 });
+            return file;
+        },
+        removeTemp: (file) => fs.rmSync(path.dirname(file), { recursive: true, force: true }),
+        trashFallback: (p) => {
+            const trash = path.join(os.homedir(), ".Trash");
+            let target = path.join(trash, path.basename(p));
+            if (fs.existsSync(target))
+                target = path.join(trash, `${path.basename(p, path.extname(p))} ${Date.now()}${path.extname(p)}`);
+            fs.renameSync(p, target);
+        },
+        print: (line) => console.log(line),
+    };
+}
+const LID_NAMES = ["Do nothing", "Sleep", "Hibernate", "Shut down"];
+/** Windows: nothing to install; check what the router will need, and say what is missing. */
+async function windowsSetup(o, d) {
+    if (o.ssid !== undefined) {
+        const problem = ssidProblem(o.ssid);
+        if (problem)
+            return { ok: false, detail: problem };
+    }
+    const { lid, error } = await readLidAction(d.run);
+    if (lid) {
+        // Writing back the values already there changes nothing and proves the write is allowed.
+        const err = await writeLidAction(d.run, lid.scheme, lid.ac, lid.dc);
+        if (err)
+            return { ok: false, detail: `Windows does not let this account change the power plan's lid-close action (a Group Policy setting?): ${err}` };
+        d.print(`✓ the lid-close action can be changed without administrator rights (now: plugged in ${LID_NAMES[lid.ac]}, on battery ${LID_NAMES[lid.dc]}); ClaudeRipple sets "Do nothing" only while it holds the PC awake, and puts these back`);
+    }
+    else
+        d.print(`· this PC has no lid-close setting${error ? ` (${error})` : ""}: only idle sleep is held off`);
+    let wifiDevice;
+    if (o.ssid !== undefined) {
+        const r = await d.run(POWERSHELL, psArgs(FIND_WIFI_PS), { env: powershellEnv(), timeoutMs: 20_000 });
+        wifiDevice = (r.code === 0 ? parseAdapterName(r.stdout) : null) ?? undefined;
+        if (!wifiDevice)
+            return { ok: false, detail: "no Wi-Fi adapter found (Get-NetAdapter)" };
+        const list = await listWifiProfiles(d.run);
+        if (list.location)
+            d.print(`· ${WIN_HINTS["needs-location"]}`);
+        else if (list.error)
+            d.print(`· could not list the saved Wi-Fi networks: ${list.error}`);
+        else {
+            const hotspot = hotspotProfile(list.profiles, o.ssid);
+            d.print(hotspot ? `✓ Windows has joined "${o.ssid}" before (saved profile "${hotspot.name}")` : `· ${WIN_HINTS["no-hotspot-profile"]}`);
+            const autos = autoProfiles(list.profiles, o.ssid);
+            d.print(autos.length
+                ? `✓ ${autos.length} other Wi-Fi network${autos.length === 1 ? "" : "s"} connect${autos.length === 1 ? "s" : ""} automatically, so ClaudeRipple can come back from the hotspot`
+                : "· no other Wi-Fi on this PC is set to connect automatically, so ClaudeRipple would stay on the hotspot");
+            if (hotspot?.auto)
+                d.print(`· the hotspot's profile connects automatically too, so Windows may pick it over your Wi-Fi when coming back; \`netsh wlan set profileparameter name="${hotspot.name}" connectionmode=manual\` stops that (ClaudeRipple joins it by name either way)`);
+        }
+    }
+    return { ok: true, detail: "setup complete (Windows needs no administrator step)", ...(wifiDevice ? { wifiDevice } : {}) };
+}
+export async function awakeSetup(o, d) {
+    if (d.platform === "win32")
+        return windowsSetup(o, d);
+    if (d.platform !== "darwin")
+        return { ok: false, detail: "lid-closed awake and hotspot failover are macOS and Windows only" };
+    let wifiDevice;
+    if (o.ssid !== undefined) {
+        const problem = ssidProblem(o.ssid);
+        if (problem)
+            return { ok: false, detail: problem };
+        const ports = await d.run(NETWORKSETUP, ["-listallhardwareports"]);
+        wifiDevice = (ports.code === 0 ? parseWifiDevice(ports.stdout) : null) ?? undefined;
+        if (!wifiDevice)
+            return { ok: false, detail: "no Wi-Fi interface found (networksetup -listallhardwareports)" };
+    }
+    const rule = sudoersRule({ user: d.user, ...(o.ssid !== undefined ? { ssid: o.ssid, wifiDevice: wifiDevice } : {}) });
+    const removeInsomnia = insomniaPresent(d.home, d.exists);
+    const temp = d.writeTemp(rule);
+    let r;
+    try {
+        const script = installScript({ tempFile: temp, sha256: crypto.createHash("sha256").update(rule).digest("hex"), removeInsomnia });
+        d.print("macOS will ask for your password once, in its own dialog (ClaudeRipple never sees it).");
+        r = await d.run(OSASCRIPT, adminOsascriptArgs(script, "ClaudeRipple wants to keep your Mac awake with the lid closed and join your phone hotspot when Wi-Fi fails."), { timeoutMs: 5 * 60_000 });
+    }
+    finally {
+        d.removeTemp(temp);
+    }
+    if (r.code !== 0) {
+        const text = (r.stderr || r.stdout).trim();
+        return { ok: false, detail: /-128|cancel/i.test(text) ? "cancelled; nothing was changed" : `the privileged step failed: ${text.slice(0, 300)}` };
+    }
+    const check = await d.run(SUDO, ["-n", "-l", PMSET, "-a", "disablesleep", "1"]);
+    if (check.code !== 0)
+        return { ok: false, detail: "the rule was installed but `sudo -n -l` does not allow pmset; check /etc/sudoers.d/clauderipple" };
+    d.print(`✓ installed ${SUDOERS_FILE}${o.ssid !== undefined ? ` (pmset, and joining "${o.ssid}" on ${wifiDevice})` : " (pmset)"}`);
+    if (removeInsomnia) {
+        d.print("✓ cleared Insomnia's sleep setting and its sudoers rule");
+        for (const step of insomniaCleanupSteps({ uid: d.uid, home: d.home, exists: d.exists }))
+            d.print(`${(await runCleanupStep(step, d)) ? "✓" : "·"} ${step.label}`);
+    }
+    return { ok: true, detail: "setup complete", ...(wifiDevice ? { wifiDevice } : {}) };
+}
+async function runCleanupStep(step, d) {
+    if (step.kind === "run")
+        return (await d.run(step.file, step.args)).code === 0;
+    const r = await d.run("/usr/bin/trash", [step.path]);
+    if (r.code === 0)
+        return true;
+    try {
+        d.trashFallback(step.path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function awakeRemove(d) {
+    if (d.platform === "win32") {
+        // Nothing was installed; put back a lid action a router left changed.
+        const r = await releaseAwake(d.run, d.rippleHome, "awake setup --remove", "win32");
+        if (r === "failed")
+            return { ok: false, detail: `could not restore the lid-close action: ${releaseFailedHint("win32")}` };
+        return { ok: true, detail: `nothing to remove on Windows${r === "released" ? "; the lid-close action is back to yours" : ""}` };
+    }
+    if (d.platform !== "darwin")
+        return { ok: false, detail: "lid-closed awake is macOS and Windows only" };
+    const journal = readJournal(path.join(d.rippleHome, "awake.json"));
+    const script = removeScript({ clearSleepBit: journal?.applied === true });
+    d.print("macOS will ask for your password once, in its own dialog.");
+    const r = await d.run(OSASCRIPT, adminOsascriptArgs(script, "ClaudeRipple wants to remove its lid-closed awake permission."), { timeoutMs: 5 * 60_000 });
+    if (r.code !== 0) {
+        const text = (r.stderr || r.stdout).trim();
+        return { ok: false, detail: /-128|cancel/i.test(text) ? "cancelled; nothing was changed" : `the privileged step failed: ${text.slice(0, 300)}` };
+    }
+    if (journal?.applied)
+        writeReleasedJournal(d.rippleHome, "awake setup --remove");
+    return { ok: true, detail: `removed ${SUDOERS_FILE}` };
+}
+function writeReleasedJournal(rippleHome, reason) {
+    const file = path.join(rippleHome, "awake.json");
+    const prev = readJournal(file);
+    fs.writeFileSync(file, JSON.stringify({ applied: false, since: new Date().toISOString(), reason, ...(prev?.lastActivityAt !== undefined ? { lastActivityAt: prev.lastActivityAt } : {}) }) + "\n", { mode: 0o600 });
+}
+/** What to tell a user whose machine could not be released. */
+export function releaseFailedHint(platform = process.platform) {
+    return platform === "win32"
+        ? "set it back in Control Panel → Power Options → Choose what closing the lid does"
+        : "run `sudo pmset -a disablesleep 0`";
+}
+/**
+ * If the router set the sleep bit (journal), clear it now with `sudo -n`; on Windows, put back the
+ * lid-close action it saved (the execution state died with the router's child). For `stop`,
+ * `uninstall` and `awake off` with no router answering: a router that is gone cannot reconcile it.
+ */
+export async function releaseAwake(run, rippleHome, reason, platform = process.platform) {
+    if (platform === "win32") {
+        const journal = readJournal(path.join(rippleHome, "awake.json"));
+        const r = await restoreLidFromJournal(run, journal);
+        if (r === "failed")
+            return r;
+        if (journal?.applied)
+            writeReleasedJournal(rippleHome, reason);
+        return r;
+    }
+    if (platform !== "darwin")
+        return "not-held";
+    const journal = readJournal(path.join(rippleHome, "awake.json"));
+    if (!journal?.applied)
+        return "not-held";
+    const r = await run(SUDO, ["-n", PMSET, "-a", "disablesleep", "0"]);
+    if (r.code !== 0)
+        return "failed";
+    writeReleasedJournal(rippleHome, reason);
+    return "released";
+}

package/dist/cli/src/bundle.js

@@ -12,6 +12,14 @@ export function bundlePath(home) {
 export function launcherPath(home) {
     return path.join(bundlePath(home), "Contents", "MacOS", "ClaudeRipple");
 }
+/** The launcher's text; `repair` compares an existing one against it. */
+export function launcherScript(opts) {
+    return `#!/bin/sh
+# ClaudeRipple router launcher (generated by \`clauderipple install\`).
+export CLAUDERIPPLE_HOME="${opts.home}"
+exec "${opts.node}" "${opts.script}"
+`;
+}
 export function writeBundle(opts) {
     const app = bundlePath(opts.home);
     const macos = path.join(app, "Contents", "MacOS");
@@ -33,11 +41,7 @@ export function writeBundle(opts) {
 </plist>
 `);
     const launcher = launcherPath(opts.home);
-    fs.writeFileSync(launcher, `#!/bin/sh
-# ClaudeRipple router launcher (generated by \`clauderipple install\`).
-export CLAUDERIPPLE_HOME="${opts.home}"
-exec "${opts.node}" "${opts.script}"
-`, { mode: 0o755 });
+    fs.writeFileSync(launcher, launcherScript(opts), { mode: 0o755 });
     try {
         execFileSync("codesign", ["--force", "--sign", "-", "--identifier", BUNDLE_ID, app], { stdio: "ignore" });
     }

package/dist/cli/src/direct.js

@@ -0,0 +1,159 @@
+// `clauderipple direct on|off` — "use Claude's default connection" and back.
+//
+// on:  takes Claude Code (settings.json env) and Claude Desktop (our Config Library entry) off the
+//      router, removing only values that are ours, and keeps what it removed in <home>/direct.json.
+//      The router, CA trust, agent files and the status mod are left alone, so `off` is instant.
+// off: puts back exactly what direct.json kept. A proxy someone set in the meantime is refused
+//      unless forced, and a router that is not answering is repaired first: pointing Claude at a
+//      dead router is the failure this command exists to get out of.
+//
+// Both need Claude restarted: Desktop reads its proxy at start, Claude Code sessions at start.
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigStore, adminPort } from "../../router/src/config.js";
+import { certPaths } from "./certs.js";
+import { classifyMode, cliProxyState, desktopProxyState, fetchRouterStatus, proxyUrlFor, repair } from "./doctor.js";
+import { applyAppProxy, currentAppProxy, removeAppProxy } from "./picker.js";
+import { MODEL_SLOT_ENV, editSettingsEnv, settingsEnv } from "./settings.js";
+export function directStatePath(home) {
+    return path.join(home, "direct.json");
+}
+function readState(home) {
+    try {
+        const s = JSON.parse(fs.readFileSync(directStatePath(home), "utf8"));
+        return s && typeof s.cli === "object" ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+function config(home) {
+    return new ConfigStore(path.join(home, "config.json")).get();
+}
+/** A model name Claude answers itself. Anything else in a slot only works through the router. */
+const CLAUDE_MODEL = /claude|opus|sonnet|haiku|fable|mythos|^default$/i;
+function currentMode(home) {
+    const cfg = config(home);
+    const proxyUrl = proxyUrlFor(cfg.listen.port);
+    const cli = cliProxyState(settingsEnv(), proxyUrl, certPaths(home).caPem);
+    const desktop = desktopProxyState(currentAppProxy(), proxyUrl);
+    return classifyMode(cli.proxy, desktop.proxy, cfg.picker?.enabled === true);
+}
+export function directOn(home) {
+    const cfg = config(home);
+    const proxyUrl = proxyUrlFor(cfg.listen.port);
+    const caPath = certPaths(home).caPem;
+    const removedCli = {};
+    const notes = [];
+    const edit = editSettingsEnv((env) => {
+        const proxy = cliProxyState(env, proxyUrl, caPath);
+        if (proxy.proxy === "ripple" || proxy.stale) {
+            removedCli.HTTPS_PROXY = env.HTTPS_PROXY;
+            delete env.HTTPS_PROXY;
+        }
+        else if (env.HTTPS_PROXY)
+            notes.push(`left HTTPS_PROXY=${env.HTTPS_PROXY} (not ClaudeRipple's)`);
+        if (env.NODE_EXTRA_CA_CERTS === caPath) {
+            removedCli.NODE_EXTRA_CA_CERTS = env.NODE_EXTRA_CA_CERTS;
+            delete env.NODE_EXTRA_CA_CERTS;
+        }
+        // A slot naming a routed model makes every request on it fail once the router is out of the
+        // path (Anthropic answers 404), so those go too — but only when Claude Code is now direct.
+        if (!env.HTTPS_PROXY) {
+            for (const [slot, name] of Object.entries(MODEL_SLOT_ENV)) {
+                const value = env[name];
+                if (value === undefined)
+                    continue;
+                const ours = value === cfg.cli.models?.[slot] || !CLAUDE_MODEL.test(value);
+                if (!ours)
+                    continue;
+                removedCli[name] = value;
+                delete env[name];
+            }
+        }
+        return Object.keys(removedCli).length > 0;
+    });
+    let desktop = null;
+    const ap = currentAppProxy();
+    if (ap.ours && ap.egressProxyUrl) {
+        removeAppProxy();
+        desktop = { egressProxyUrl: ap.egressProxyUrl, appliedAfter: currentAppProxy().appliedId };
+    }
+    else if (ap.egressProxyUrl === proxyUrl)
+        notes.push(`Claude Desktop's applied configuration ${ap.appliedId} points at ClaudeRipple but was not written by it; left as it is`);
+    const changed = edit.changed || desktop !== null;
+    if (changed) {
+        // Merged with an earlier direct.json: running `direct on` twice must not forget the first.
+        const previous = readState(home);
+        const state = { at: new Date().toISOString(), cli: { ...(previous?.cli ?? {}), ...removedCli }, desktop: desktop ?? previous?.desktop ?? null };
+        fs.mkdirSync(home, { recursive: true });
+        fs.writeFileSync(directStatePath(home), JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+    }
+    const removed = [
+        ...Object.keys(removedCli).map((k) => `settings.json env.${k}`),
+        ...(desktop ? ["Claude Desktop's proxy entry"] : []),
+    ];
+    const detail = changed
+        ? `Claude now connects directly. Removed: ${removed.join(", ")}. Saved in ${directStatePath(home)}.${edit.backup ? ` settings.json backup: ${edit.backup}.` : ""}`
+        : "Claude was already on its default connection; nothing of ClaudeRipple's was in its settings.";
+    return { ok: true, mode: currentMode(home), restartClaude: true, detail: [detail, ...notes].join(" ") };
+}
+export async function directOff(deps, opts = {}) {
+    const home = deps.home;
+    const cfg = config(home);
+    const proxyUrl = proxyUrlFor(cfg.listen.port);
+    const saved = readState(home);
+    // No direct.json (it was removed, or Claude was taken off by hand): what `install` and
+    // `picker on` would have written is the closest thing to "exactly as before".
+    const cli = saved?.cli ?? {
+        HTTPS_PROXY: proxyUrl,
+        NODE_EXTRA_CA_CERTS: certPaths(home).caPem,
+        ...Object.fromEntries(Object.entries(MODEL_SLOT_ENV).flatMap(([slot, name]) => {
+            const model = cfg.cli.models?.[slot];
+            return model ? [[name, model]] : [];
+        })),
+    };
+    const desktopUrl = saved ? saved.desktop?.egressProxyUrl ?? null : cfg.picker?.enabled ? proxyUrl : null;
+    const fail = (detail) => ({ ok: false, mode: currentMode(home), restartClaude: true, detail });
+    // Something set since `direct on` is someone else's choice, and replacing it needs saying so.
+    const env = settingsEnv();
+    if (!opts.force && cli.HTTPS_PROXY && env.HTTPS_PROXY && env.HTTPS_PROXY !== cli.HTTPS_PROXY) {
+        return fail(`settings.json now sets HTTPS_PROXY=${env.HTTPS_PROXY}, which is not ClaudeRipple's; left everything as it is. Run \`clauderipple direct off --force\` to replace it.`);
+    }
+    const ap = currentAppProxy();
+    const desktopChanged = ap.appliedId !== (saved?.desktop?.appliedAfter ?? ap.appliedId);
+    if (!opts.force && desktopUrl && ap.egressProxyUrl && ap.egressProxyUrl !== desktopUrl && (desktopChanged || !saved)) {
+        return fail(`Claude Desktop now uses another proxy (${ap.egressProxyUrl}); left everything as it is. Run \`clauderipple direct off --force\` to replace it.`);
+    }
+    const notes = [];
+    if ((await (deps.routerStatus ?? fetchRouterStatus)(`http://127.0.0.1:${adminPort(cfg)}`, 4_000)) === null) {
+        const fixed = await repair(deps);
+        if (!fixed.doctor.router.responding) {
+            const failed = fixed.steps.filter((s) => !s.ok).map((s) => `${s.name}: ${s.detail}`).join("; ");
+            return fail(`the router is not answering even after a repair (${failed || "no step failed, it just did not come up"}), so Claude stays on its default connection.`);
+        }
+        notes.push("The router was not answering; repaired it first.");
+    }
+    const restoredKeys = [];
+    const edit = editSettingsEnv((current) => {
+        for (const [k, v] of Object.entries(cli)) {
+            if (current[k] !== v) {
+                current[k] = v;
+                restoredKeys.push(k);
+            }
+        }
+        return restoredKeys.length > 0;
+    });
+    let desktopApplied = false;
+    if (desktopUrl) {
+        const now = currentAppProxy();
+        if (!(now.ours && now.egressProxyUrl === desktopUrl)) {
+            applyAppProxy(desktopUrl);
+            desktopApplied = true;
+        }
+    }
+    fs.rmSync(directStatePath(home), { force: true });
+    const restored = [...restoredKeys.map((k) => `settings.json env.${k}`), ...(desktopApplied ? ["Claude Desktop's proxy entry"] : [])];
+    const detail = restored.length > 0 ? `Claude goes through ClaudeRipple again. Restored: ${restored.join(", ")}.${edit.backup ? ` settings.json backup: ${edit.backup}.` : ""}` : "Claude already went through ClaudeRipple; nothing to restore.";
+    return { ok: true, mode: currentMode(home), restartClaude: true, detail: [...notes, detail].join(" ") };
+}