clauderipple 0.2.0

package/dist/cli/src/picker.js

@@ -0,0 +1,166 @@
+// `clauderipple picker on|off` — put real model names into Claude Desktop's model picker.
+//
+// on:  1. trust our CA in the login keychain (macOS asks the user for their password; we never see it)
+//      2. point the app itself at the router: Config Library entry {egressProxyUrl} + _meta.json appliedId
+//         (~/Library/Application Support/Claude-3p/configLibrary/ — the app keeps its managed-config
+//         library under the "-3p" userData dir in BOTH deployment modes; read once at start, no MDM needed)
+//      3. set picker.enabled in config.json
+//      → the user restarts Claude Desktop.
+// off: reverse all three.
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const CA_NAME = "ClaudeRipple local CA";
+function appSupport() {
+    // Verified in index.pre.js (AW()): userData + "-3p" regardless of 1P/3P mode. Not the plain "Claude" dir.
+    // Windows keeps userData under LOCALAPPDATA, not APPDATA — confirmed on Windows 11 (2026-09-14),
+    // where the app had already created %LOCALAPPDATA%\Claude-3p and read a configLibrary we put there.
+    if (process.env.CLAUDE_APP_SUPPORT)
+        return process.env.CLAUDE_APP_SUPPORT;
+    if (process.platform === "win32") {
+        return path.join(process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"), "Claude-3p");
+    }
+    return path.join(os.homedir(), "Library", "Application Support", "Claude-3p");
+}
+export function configLibraryDir() {
+    return path.join(appSupport(), "configLibrary");
+}
+function loginKeychain() {
+    return path.join(os.homedir(), "Library", "Keychains", "login.keychain-db");
+}
+const isWindows = process.platform === "win32";
+/** Single-quoted PowerShell literal; the only escape inside one is a doubled quote. */
+function ps(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * `interactive` drops -NonInteractive and lets a window show. Trusting (and untrusting) a root
+ * certificate is a UI operation: Windows puts up its own confirmation dialog with the fingerprint,
+ * and under -NonInteractive the call fails outright with "this operation cannot use the UI"
+ * (observed 2026-09-14 — the dialog never appeared and picker mode stopped there).
+ */
+function powershell(script, opts = {}) {
+    const stdio = opts.stdio ?? "pipe";
+    const args = ["-NoProfile", ...(opts.interactive ? [] : ["-NonInteractive"]), "-Command", script];
+    return execFileSync("powershell.exe", args, {
+        stdio: stdio === "pipe" ? ["ignore", "pipe", "pipe"] : stdio,
+        windowsHide: !opts.interactive,
+    })?.toString() ?? "";
+}
+/**
+ * Both platforms trust the CA for the current user only — never machine-wide, which would need
+ * administrator rights and would affect everyone on the box.
+ *   macOS   : login keychain, and the OS asks for the account password.
+ *   Windows : Cert:\CurrentUser\Root, and the OS shows a confirmation dialog with the fingerprint.
+ * Measured on Windows 11 (2026-09-14) as a standard user: the import succeeded with no UAC prompt,
+ * only that dialog. Removal shows a second confirmation, so `picker off` prompts the user too.
+ */
+export function caTrusted() {
+    try {
+        if (isWindows) {
+            const out = powershell(`@(Get-ChildItem Cert:\\CurrentUser\\Root | Where-Object { $_.Subject -eq 'CN=${CA_NAME}' }).Count`);
+            return Number(out.trim()) > 0;
+        }
+        execFileSync("security", ["find-certificate", "-c", CA_NAME, loginKeychain()], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Adds the CA as a trusted root for the current user. The OS shows its own prompt; we never see a password. */
+export function trustCa(caPem) {
+    if (caTrusted())
+        return;
+    if (isWindows) {
+        // stdio inherit: the confirmation dialog is the OS's, but errors should reach the user's terminal.
+        powershell(`Import-Certificate -FilePath ${ps(caPem)} -CertStoreLocation Cert:\\CurrentUser\\Root -ErrorAction Stop | Out-Null`, { stdio: "inherit", interactive: true });
+        return;
+    }
+    execFileSync("security", ["add-trusted-cert", "-r", "trustRoot", "-k", loginKeychain(), caPem], { stdio: "inherit" });
+}
+export function untrustCa(caPem) {
+    if (!caTrusted())
+        return false;
+    if (isWindows) {
+        try {
+            powershell(`Get-ChildItem Cert:\\CurrentUser\\Root | Where-Object { $_.Subject -eq 'CN=${CA_NAME}' } | ForEach-Object { Remove-Item -Path $_.PSPath -Force }`, { stdio: "inherit", interactive: true });
+        }
+        catch {
+            /* the user may have declined the removal dialog */
+        }
+        return true;
+    }
+    try {
+        execFileSync("security", ["remove-trusted-cert", caPem], { stdio: "inherit" });
+    }
+    catch {
+        /* trust settings may already be gone */
+    }
+    try {
+        execFileSync("security", ["delete-certificate", "-c", CA_NAME, loginKeychain()], { stdio: "ignore" });
+    }
+    catch {
+        /* ignore */
+    }
+    return true;
+}
+function readMeta() {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(configLibraryDir(), "_meta.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+const ENTRY_MARK = "clauderipple";
+export function currentAppProxy() {
+    const meta = readMeta();
+    const id = typeof meta.appliedId === "string" ? meta.appliedId : null;
+    if (!id)
+        return { appliedId: null, egressProxyUrl: null, ours: false };
+    try {
+        const entry = JSON.parse(fs.readFileSync(path.join(configLibraryDir(), `${id}.json`), "utf8"));
+        return { appliedId: id, egressProxyUrl: typeof entry.egressProxyUrl === "string" ? entry.egressProxyUrl : null, ours: meta[ENTRY_MARK]?.ourId === id };
+    }
+    catch {
+        return { appliedId: id, egressProxyUrl: null, ours: false };
+    }
+}
+/** Writes our Config Library entry and applies it. Remembers what was applied before so `off` can restore it. */
+export function applyAppProxy(proxyUrl) {
+    const dir = configLibraryDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const meta = readMeta();
+    const cur = currentAppProxy();
+    if (cur.ours && cur.appliedId) {
+        fs.writeFileSync(path.join(dir, `${cur.appliedId}.json`), JSON.stringify({ egressProxyUrl: proxyUrl }, null, 2) + "\n");
+        return { id: cur.appliedId, replaced: null };
+    }
+    const id = crypto.randomUUID();
+    // Only recognized keys in the entry: the app warns about and ignores unknown ones. Ownership lives in _meta.
+    fs.writeFileSync(path.join(dir, `${id}.json`), JSON.stringify({ egressProxyUrl: proxyUrl }, null, 2) + "\n");
+    const previous = typeof meta.appliedId === "string" ? meta.appliedId : null;
+    const next = { ...meta, appliedId: id, clauderipple: { ourId: id, previousAppliedId: previous } };
+    fs.writeFileSync(path.join(dir, "_meta.json"), JSON.stringify(next, null, 2) + "\n");
+    return { id, replaced: previous };
+}
+export function removeAppProxy() {
+    const dir = configLibraryDir();
+    const meta = readMeta();
+    const cur = currentAppProxy();
+    if (!cur.ours || !cur.appliedId)
+        return false;
+    const previous = meta.clauderipple?.previousAppliedId ?? null;
+    const next = { ...meta };
+    delete next.clauderipple;
+    if (previous)
+        next.appliedId = previous;
+    else
+        delete next.appliedId;
+    fs.writeFileSync(path.join(dir, "_meta.json"), JSON.stringify(next, null, 2) + "\n");
+    fs.rmSync(path.join(dir, `${cur.appliedId}.json`), { force: true });
+    return true;
+}

package/dist/cli/src/probe.js

@@ -0,0 +1,55 @@
+// End-to-end probe: CONNECT through the router, complete TLS against its leaf cert
+// using only our CA, and fetch a cheap Anthropic path. 401 from Anthropic is a pass:
+// it proves termination + passthrough without any credentials.
+import fs from "node:fs";
+import net from "node:net";
+import tls from "node:tls";
+export function probe(opts) {
+    const t0 = Date.now();
+    const path = opts.path ?? "/api/claude_cli/bootstrap";
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (ok, detail) => {
+            if (done)
+                return;
+            done = true;
+            resolve({ ok, detail, ms: Date.now() - t0 });
+            sock.destroy();
+        };
+        const sock = net.connect({ host: opts.host, port: opts.port });
+        const timer = setTimeout(() => finish(false, "timeout"), opts.timeoutMs ?? 8000);
+        sock.on("error", (e) => finish(false, `router unreachable: ${e.message}`));
+        sock.once("connect", () => {
+            sock.write(`CONNECT ${opts.upstream}:443 HTTP/1.1\r\nHost: ${opts.upstream}:443\r\n\r\n`);
+        });
+        sock.once("data", (d) => {
+            const line = d.toString("latin1").split("\r\n")[0] ?? "";
+            if (!/^HTTP\/1\.[01] 200/.test(line))
+                return finish(false, `CONNECT refused: ${line}`);
+            let ca;
+            try {
+                ca = fs.readFileSync(opts.caPem);
+            }
+            catch (e) {
+                return finish(false, `cannot read CA: ${e.message}`);
+            }
+            const t = tls.connect({ socket: sock, servername: opts.upstream, ca }, () => {
+                if (!t.authorized)
+                    return finish(false, `TLS not authorized: ${t.authorizationError}`);
+                t.write(`GET ${path} HTTP/1.1\r\nHost: ${opts.upstream}\r\nConnection: close\r\n\r\n`);
+            });
+            let resp = "";
+            t.on("data", (c) => {
+                resp += c.toString("latin1");
+                const status = resp.split("\r\n")[0] ?? "";
+                if (/^HTTP\/1\.[01] \d{3}/.test(status)) {
+                    clearTimeout(timer);
+                    const code = Number(status.split(" ")[1]);
+                    finish(code === 401 || code === 200, `upstream answered ${status}`);
+                }
+            });
+            t.on("error", (e) => finish(false, `TLS error: ${e.message}`));
+            t.on("end", () => finish(false, "connection closed without a status line"));
+        });
+    });
+}

package/dist/cli/src/runtime.js

@@ -0,0 +1,62 @@
+// One runtime contract for the CLI, router supervisor, app shell, and hooks.
+// Packaged apps execute TypeScript with Electron's bundled Node in type-stripping mode;
+// development keeps using the Node executable that started the CLI.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function appBundlePath(value) {
+    if (!value)
+        return null;
+    const match = value.match(/^(.*\.app)\/Contents(?:\/|$)/);
+    return match?.[1] ?? null;
+}
+export function runtime() {
+    const electronProcess = process;
+    const bundle = appBundlePath(electronProcess.resourcesPath) ?? appBundlePath(process.execPath);
+    if (bundle) {
+        const resources = path.join(bundle, "Contents", "Resources", "clauderipple");
+        return {
+            node: path.join(bundle, "Contents", "MacOS", path.basename(bundle, ".app")),
+            env: { ELECTRON_RUN_AS_NODE: "1" },
+            cli: path.join(resources, "packages", "cli", "src", "index.ts"),
+            router: path.join(resources, "packages", "router", "src", "index.ts"),
+            hookScript: path.join(resources, "packages", "cli", "src", "hooks", "agent-title.ts"),
+            repo: resources,
+            trayMain: "",
+            packaged: true,
+        };
+    }
+    // Windows (and any non-macOS electron-builder layout): the sources sit in resources/clauderipple
+    // next to app.asar, and the app's own executable runs them with ELECTRON_RUN_AS_NODE.
+    const resourcesPath = electronProcess.resourcesPath;
+    if (resourcesPath && fs.existsSync(path.join(resourcesPath, "clauderipple", "packages", "router", "src", "index.ts"))) {
+        const resources = path.join(resourcesPath, "clauderipple");
+        return {
+            node: process.execPath,
+            env: { ELECTRON_RUN_AS_NODE: "1" },
+            cli: path.join(resources, "packages", "cli", "src", "index.ts"),
+            router: path.join(resources, "packages", "router", "src", "index.ts"),
+            hookScript: path.join(resources, "packages", "cli", "src", "hooks", "agent-title.ts"),
+            repo: resources,
+            trayMain: "",
+            packaged: true,
+        };
+    }
+    // Development runs the .ts sources from the checkout; an npm install runs the .js built from
+    // them, in the same shape one level down (dist/cli/src instead of packages/cli/src). This
+    // module's own file answers both: its extension says which, and the rest is the same relative
+    // walk, so `repo` is the checkout root or the installed package root without a special case.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const ext = path.extname(fileURLToPath(import.meta.url));
+    const cli = path.join(here, `index${ext}`);
+    return {
+        node: process.execPath,
+        env: {},
+        cli,
+        router: path.resolve(here, `../../router/src/index${ext}`),
+        hookScript: path.resolve(here, `hooks/agent-title${ext}`),
+        repo: path.resolve(here, "../../.."),
+        trayMain: path.resolve(here, "../../..", ext === ".ts" ? "packages/app/dist/main.js" : "dist/app/dist/main.js"),
+        packaged: false,
+    };
+}

package/dist/cli/src/schtasks.js

@@ -0,0 +1,134 @@
+// Windows supervisor: a per-user scheduled task that starts the router at logon and restarts it
+// if it dies. The launchd counterpart is launchd.ts; supervisor.ts picks between them.
+//
+// Measured in a Windows 11 VM (2026-09-14) as a standard, non-elevated user:
+//   Register-ScheduledTask with LogonType Interactive + RunLevel Limited → "registered OK", no UAC.
+// That is the whole reason this is a scheduled task rather than a Windows service: creating a
+// service needs administrator rights, and a personal proxy should not ask for them.
+//
+// Two things launchd gives us for free need doing by hand here:
+//   * KeepAlive → RestartCount/RestartInterval, which only fire on a *non-zero* exit. That still
+//     covers a crash and the health self-exit (code 75); a clean exit stays exited, which is what
+//     `clauderipple stop` wants anyway.
+//   * A graceful restart → there is no SIGTERM on Windows (process.kill terminates outright and
+//     would cut the drain), so restart asks the router over POST /api/shutdown and waits.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const TASK_NAME = "ClaudeRippleRouter";
+export function taskName() {
+    return process.env.CLAUDERIPPLE_TASK_NAME ?? TASK_NAME;
+}
+/** Single-quoted PowerShell literal; the only escape inside one is a doubled quote. */
+function ps(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function run(script) {
+    try {
+        const out = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        }).toString();
+        return { ok: true, out: out.trim() };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, out: `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}`.trim() };
+    }
+}
+/**
+ * The task runs a PowerShell launcher rather than node directly, for three reasons.
+ *
+ * 1. It pins CLAUDERIPPLE_HOME and any extra environment the installer recorded, which a scheduled
+ *    task cannot carry on its own, and keeps output in a log file the way StandardOutPath does.
+ * 2. `Start-Process` detaches the router from the console: a task started from one inherits it, and
+ *    closing that window sends a Ctrl+C — measured 2026-09-14, the router died with 0xC000013A the
+ *    moment the installer's window closed.
+ * 3. **It is the KeepAlive.** Task Scheduler's RestartCount/RestartInterval only cover failing to
+ *    *start* a task; a process that dies while running just ends the task as complete (measured
+ *    2026-09-14: the router was killed, the task went back to Ready with 0xFFFFFFFF, and nothing
+ *    restarted it for three minutes). So the launcher supervises the router itself, with launchd's
+ *    semantics: a non-zero exit — a crash, or the health self-exit 75 — is relaunched; a clean exit
+ *    is not, because that is `stop` or the drain half of `restart`, which starts the task again.
+ *    A router that keeps dying immediately backs off instead of spinning.
+ */
+function writeLauncher(opts) {
+    const launcher = path.join(opts.home, "clauderipple-router.ps1");
+    const logDir = path.join(opts.home, "logs");
+    fs.mkdirSync(logDir, { recursive: true });
+    const env = { CLAUDERIPPLE_HOME: opts.home, ...(opts.env ?? {}) };
+    const lines = [
+        "# Generated by `clauderipple install`. Supervises the router; see schtasks.ts.",
+        ...Object.entries(env).map(([k, v]) => `$env:${k} = ${ps(v)}`),
+        `$routerArgs = @(${opts.args.map((a) => ps(a)).join(", ")})`,
+        `$out = ${ps(path.join(logDir, "launcher.log"))}`,
+        `$err = ${ps(path.join(logDir, "launcher.err.log"))}`,
+        `$quickFailures = 0`,
+        `while ($true) {`,
+        `  $startedAt = Get-Date`,
+        `  $p = Start-Process -FilePath ${ps(opts.program)} -ArgumentList $routerArgs -WindowStyle Hidden -PassThru -Wait -RedirectStandardOutput $out -RedirectStandardError $err`,
+        `  if ($p.ExitCode -eq 0) { break }`,
+        `  if (((Get-Date) - $startedAt).TotalSeconds -lt 10) { $quickFailures++ } else { $quickFailures = 0 }`,
+        `  Start-Sleep -Seconds $(if ($quickFailures -ge 5) { 60 } else { 2 })`,
+        `}`,
+    ];
+    fs.writeFileSync(launcher, lines.join("\r\n") + "\r\n");
+    return launcher;
+}
+export function installAgent(opts) {
+    const launcher = writeLauncher({ program: opts.program, args: opts.args ?? [], home: opts.home, ...(opts.env ? { env: opts.env } : {}) });
+    const user = `${os.userInfo().username}`;
+    const script = [
+        `$ErrorActionPreference = 'Stop'`,
+        `$a = New-ScheduledTaskAction -Execute ${ps("powershell.exe")} -Argument ${ps(`-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${launcher}"`)}`,
+        `$t = New-ScheduledTaskTrigger -AtLogOn -User ${ps(user)}`,
+        // Limited: the router needs no elevation, and asking for it would put a UAC prompt at every logon.
+        `$p = New-ScheduledTaskPrincipal -UserId ${ps(user)} -LogonType Interactive -RunLevel Limited`,
+        `$s = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -RestartCount 99 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit ([TimeSpan]::Zero) -MultipleInstances IgnoreNew`,
+        `Register-ScheduledTask -TaskName ${ps(taskName())} -Action $a -Trigger $t -Principal $p -Settings $s -Force | Out-Null`,
+        `'ok'`,
+    ].join("; ");
+    const r = run(script);
+    if (!r.ok)
+        throw new Error(`Register-ScheduledTask failed: ${r.out}`);
+    return launcher;
+}
+export function removeAgent() {
+    const r = run(`Unregister-ScheduledTask -TaskName ${ps(taskName())} -Confirm:$false -ErrorAction Stop; 'ok'`);
+    return r.ok;
+}
+export function agentState() {
+    const r = run(`(Get-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction Stop).State`);
+    if (!r.ok)
+        return "not-loaded";
+    return /^Running/im.test(r.out) ? "running" : "loaded";
+}
+/**
+ * The scheduled task starts PowerShell, which starts the runtime, so the task's own pid is the
+ * launcher's. What callers want is the router, so find the process whose command line names our
+ * script. The runtime is `node.exe` for a source checkout and `ClaudeRipple.exe` (Electron as
+ * Node) for the packaged app — until 0.1.2 only `node.exe` was looked for, so on every packaged
+ * install `restart` found no router, skipped the shutdown, and `Start-ScheduledTask` was ignored
+ * by the task already running: "Restart Router" never restarted anything (found 2026-09-16).
+ */
+export function agentPid() {
+    const r = run(
+    // Three layouts run the same router: a checkout (packages\router\src\index.ts), an npm
+    // install (dist\router\src\index.js) and the packaged app (the .ts under resources). Matching
+    // on "router\src\index." covers all three and still cannot match an unrelated process.
+    `(Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='ClaudeRipple.exe'" | Where-Object { $_.CommandLine -like '*router\\src\\index.*' } | Select-Object -First 1).ProcessId`);
+    const n = Number(r.out.trim());
+    return r.ok && Number.isFinite(n) && n > 0 ? n : null;
+}
+export function startAgent() {
+    if (agentPid() !== null)
+        return "already-running";
+    const r = run(`Start-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction Stop; 'ok'`);
+    return r.ok ? "started" : "failed";
+}
+export function stopAgent() {
+    // Stop the task so the supervisor does not immediately start it again, then let the router drain.
+    run(`Stop-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction SilentlyContinue`);
+    return true;
+}

package/dist/cli/src/settings.js

@@ -0,0 +1,142 @@
+// Edit ~/.claude/settings.json: only the two env keys the CLI reads for the proxy.
+// Always backs up first; never touches any other key; refuses to overwrite a foreign proxy unless forced.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function settingsPath() {
+    return process.env.CLAUDE_SETTINGS_PATH ?? path.join(os.homedir(), ".claude", "settings.json");
+}
+function readSettings(file) {
+    if (!fs.existsSync(file))
+        return {};
+    const text = fs.readFileSync(file, "utf8");
+    if (text.trim() === "")
+        return {};
+    return JSON.parse(text);
+}
+function backup(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const ts = new Date().toISOString().replace(/[-:]/g, "").slice(0, 15);
+    const b = `${file}.bak-clauderipple-${ts}`;
+    fs.copyFileSync(file, b);
+    return b;
+}
+function write(file, obj) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(obj, null, 2) + "\n");
+}
+export function applyProxyEnv(opts) {
+    const file = settingsPath();
+    const s = readSettings(file);
+    const env = { ...(s.env ?? {}) };
+    const notes = [];
+    const existing = env.HTTPS_PROXY;
+    if (existing && existing !== opts.proxyUrl && !opts.force) {
+        throw new Error(`settings.json env.HTTPS_PROXY is already "${existing}". Re-run with --force to replace it, or uninstall the other proxy first.`);
+    }
+    if (existing && existing !== opts.proxyUrl)
+        notes.push(`replaced HTTPS_PROXY ${existing}`);
+    const want = { HTTPS_PROXY: opts.proxyUrl, NODE_EXTRA_CA_CERTS: opts.caPath };
+    if (opts.maxContextTokens)
+        want.CLAUDE_CODE_MAX_CONTEXT_TOKENS = String(opts.maxContextTokens);
+    let changed = false;
+    for (const [k, v] of Object.entries(want)) {
+        if (env[k] !== v) {
+            env[k] = v;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return { changed: false, backup: null, notes };
+    const b = backup(file);
+    write(file, { ...s, env });
+    return { changed: true, backup: b, notes };
+}
+export function removeProxyEnv(opts) {
+    const file = settingsPath();
+    const s = readSettings(file);
+    const env = { ...(s.env ?? {}) };
+    const notes = [];
+    let changed = false;
+    if (env.HTTPS_PROXY === opts.proxyUrl) {
+        delete env.HTTPS_PROXY;
+        changed = true;
+    }
+    else if (env.HTTPS_PROXY)
+        notes.push(`left HTTPS_PROXY=${env.HTTPS_PROXY} (not ours)`);
+    if (env.NODE_EXTRA_CA_CERTS === opts.caPath) {
+        delete env.NODE_EXTRA_CA_CERTS;
+        changed = true;
+    }
+    else if (env.NODE_EXTRA_CA_CERTS)
+        notes.push(`left NODE_EXTRA_CA_CERTS=${env.NODE_EXTRA_CA_CERTS} (not ours)`);
+    if (!changed)
+        return { changed: false, backup: null, notes };
+    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 };
+}
+export function currentProxyEnv() {
+    const env = readSettings(settingsPath()).env ?? {};
+    const out = {};
+    if (env.HTTPS_PROXY)
+        out.HTTPS_PROXY = env.HTTPS_PROXY;
+    if (env.NODE_EXTRA_CA_CERTS)
+        out.NODE_EXTRA_CA_CERTS = env.NODE_EXTRA_CA_CERTS;
+    if (env.CLAUDE_CODE_MAX_CONTEXT_TOKENS)
+        out.CLAUDE_CODE_MAX_CONTEXT_TOKENS = env.CLAUDE_CODE_MAX_CONTEXT_TOKENS;
+    return out;
+}
+// ---- Agent-title hook (PreToolUse Agent|Task) -------------------------------------------
+const HOOK_MARK = "_clauderipple";
+/** Adds or removes ClaudeRipple's PreToolUse hook. Only entries carrying our marker are ever touched. */
+function shellQuote(value) {
+    return '"' + value.replace(/(["\\$`])/g, "\\$1") + '"';
+}
+export function setAgentTitleHook(enabled, cmd) {
+    const file = settingsPath();
+    const s = readSettings(file);
+    const hooks = (typeof s.hooks === "object" && s.hooks ? s.hooks : {});
+    const list = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    const kept = list.filter((e) => e[HOOK_MARK] !== "agent-title");
+    const notes = [];
+    if (enabled) {
+        const prefix = Object.entries(cmd.env ?? {})
+            .map(([key, value]) => /^[A-Za-z0-9_./:-]+$/.test(value) ? `${key}=${value}` : `${key}=${shellQuote(value)}`)
+            .join(" ");
+        const command = [prefix, shellQuote(cmd.node), shellQuote(cmd.script)].filter(Boolean).join(" ");
+        kept.push({
+            matcher: "Agent|Task",
+            hooks: [{ type: "command", command, timeout: 10 }],
+            [HOOK_MARK]: "agent-title",
+        });
+        notes.push("hooks.PreToolUse: ClaudeRipple agent-title hook added");
+    }
+    else if (kept.length !== list.length) {
+        notes.push("hooks.PreToolUse: ClaudeRipple agent-title hook removed");
+    }
+    const changed = JSON.stringify(kept) !== JSON.stringify(list);
+    if (!changed)
+        return { changed: false, backup: null, notes };
+    const b = backup(file);
+    hooks.PreToolUse = kept;
+    s.hooks = hooks;
+    write(file, s);
+    return { changed: true, backup: b, notes };
+}
+export function agentTitleHookEnabled() {
+    try {
+        const s = readSettings(settingsPath());
+        const list = s.hooks?.PreToolUse;
+        return Array.isArray(list) && list.some((e) => e[HOOK_MARK] === "agent-title");
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/src/supervisor.js

@@ -0,0 +1,100 @@
+// One supervisor interface, two implementations: launchd on macOS, Task Scheduler on Windows.
+// Everything outside this module talks to the router's lifecycle through here.
+import { execFileSync } from "node:child_process";
+import { ConfigStore, configPath } from "../../router/src/config.js";
+import { adminPort } from "../../router/src/admin.js";
+import * as launchd from "./launchd.js";
+import * as schtasks from "./schtasks.js";
+export const isWindows = process.platform === "win32";
+export const isSupported = isWindows || process.platform === "darwin";
+/** What the supervisor is called on this platform, for messages the user reads. */
+export function supervisorName() {
+    return isWindows ? "scheduled task" : "launchd agent";
+}
+export function installAgent(opts) {
+    return isWindows ? schtasks.installAgent(opts) : launchd.installAgent(opts);
+}
+export function removeAgent() {
+    return isWindows ? schtasks.removeAgent() : launchd.removeAgent();
+}
+export function agentState() {
+    return isWindows ? schtasks.agentState() : launchd.agentState();
+}
+export function agentPid() {
+    return isWindows ? schtasks.agentPid() : launchd.agentPid();
+}
+export function startAgent() {
+    return isWindows ? schtasks.startAgent() : launchd.startAgent();
+}
+export function stopAgent() {
+    if (!isWindows)
+        return launchd.stopAgent();
+    // Ask the router to drain first: a clean exit also ends the launcher's supervision loop, so the
+    // task does not relaunch it. Then stop the task itself to clear anything left behind.
+    askShutdown();
+    waitForExit(schtasks.agentPid(), 120_000);
+    return schtasks.stopAgent();
+}
+/** Blocking POST to the router's shutdown endpoint. Returns false if it did not answer. */
+function askShutdown() {
+    try {
+        execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `Invoke-RestMethod -Method Post -Uri '${adminUrl()}/api/shutdown' -TimeoutSec 10 | Out-Null`], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Waits for `pid` to disappear. Returns true if it exited within the budget. */
+function waitForExit(pid, budgetMs, onProgress) {
+    if (pid === null)
+        return true;
+    const t0 = Date.now();
+    let lastTick = 0;
+    while (Date.now() - t0 < budgetMs) {
+        const now = schtasks.agentPid();
+        if (now === null || now !== pid)
+            return true;
+        const s = Math.floor((Date.now() - t0) / 1000);
+        if (s >= 5 && s !== lastTick && s % 5 === 0) {
+            lastTick = s;
+            onProgress?.(`draining… ${s}s (waiting for in-flight model calls)`);
+        }
+        sleepSync(1000);
+    }
+    return false;
+}
+/** Where the router's admin API is listening, per the current config. */
+function adminUrl() {
+    const cfg = new ConfigStore(configPath()).get();
+    return `http://127.0.0.1:${adminPort(cfg)}`;
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Windows restart. There is no SIGTERM here — `process.kill(pid, "SIGTERM")` terminates the target
+ * outright, which is exactly the drain-cutting behaviour launchd's `kickstart -k` was fixed for on
+ * macOS — so ask the router to drain over its admin API, wait for the process to go, then start the
+ * task again. The launcher's supervision loop treats a clean exit as "stay stopped", so the restart
+ * has to be explicit.
+ */
+function restartWindows(opts) {
+    const pid = schtasks.agentPid();
+    if (pid === null)
+        return schtasks.startAgent() === "failed" ? "failed" : "kickstarted";
+    if (!askShutdown())
+        opts.onProgress?.("router did not answer /api/shutdown; waiting for it to exit anyway");
+    const exited = waitForExit(pid, opts.waitMs ?? 120_000, opts.onProgress);
+    if (!exited)
+        return "failed";
+    // A clean drain ends the launcher loop too, so the task has to be started again.
+    return schtasks.startAgent() === "failed" ? "failed" : "drained";
+}
+export function restartAgent(opts = {}) {
+    return isWindows ? restartWindows(opts) : launchd.restartAgent(opts);
+}
+/** Path to the supervisor's own definition, for status output. */
+export function agentDefinitionPath() {
+    return isWindows ? `Task Scheduler\\${schtasks.taskName()}` : launchd.plistPath();
+}