clauderipple 0.4.1 → 0.5.1

package/dist/cli/src/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // clauderipple — install / uninstall / status / start / stop / restart / logs / config
 //
-// install:   generates the local CA + leaf, writes a starter config, points
-//            ~/.claude/settings.json env at the router, registers the launchd agent,
-//            then probes the whole chain end to end.
+// install:   generates the local CA + leaf, writes a starter config, registers the supervisor
+//            (launchd / Task Scheduler / systemd), probes the whole chain end to end, and only
+//            then points ~/.claude/settings.json env at the router.
 // uninstall: reverses exactly that. Home dir is kept unless --purge.
 import fs from "node:fs";
 import net from "node:net";
@@ -13,10 +13,10 @@ import { execFileSync } from "node:child_process";
 import { ConfigStore, DEFAULTS, homeDir, configPath } from "../../router/src/config.js";
 import { adminPort } from "../../router/src/admin.js";
 import { certsExist, certPaths, generateCerts } from "./certs.js";
-import { applyProxyEnv, currentProxyEnv, removeProxyEnv, settingsPath } from "./settings.js";
-import { agentDefinitionPath, agentState, installAgent, isSupported, isWindows, removeAgent, restartAgent, startAgent, stopAgent, supervisorName } from "./supervisor.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 { applyAppProxy, caTrusted, currentAppProxy, removeAppProxy, trustCa, untrustCa } from "./picker.js";
+import { applyAppProxy, caTrusted, currentAppProxy, nssDb, removeAppProxy, trustCa, untrustCa } from "./picker.js";
 import { runtime } from "./runtime.js";
 import { codexOff, codexOn } from "./codex.js";
 import { ingressModels } from "../../router/src/ingress/models.js";
@@ -36,14 +36,21 @@ async function pickerOn() {
     const caPem = certPaths(home).caPem;
     if (!fs.existsSync(path.join(home, "ca.key")))
         throw new Error("ca.key missing; run `clauderipple install` first");
+    // With picker mode on, every byte Claude Desktop sends goes through the router (ARCHITECTURE §5):
+    // pointing the app at one that is not answering leaves it a blank page, so check first.
+    const ready = await probe({ host: cfg.listen.host, port: cfg.listen.port, caPem, upstream: cfg.upstream });
+    if (!ready.ok)
+        throw new Error(`the router is not answering (${ready.detail}); picker mode not enabled. Start it with \`clauderipple start\` and try again.`);
     console.log("Picker mode makes Claude Desktop's own claude.ai traffic go through ClaudeRipple so the model picker can list your GPT models.");
     console.log(isWindows
         ? "Step 1/3: trusting the ClaudeRipple CA for your Windows user account. Windows will show a confirmation dialog with the certificate fingerprint — answer Yes. No administrator rights are needed."
-        : "Step 1/3: trusting the ClaudeRipple CA in your login keychain. macOS will ask for your password (ClaudeRipple never sees it).");
+        : isLinux
+            ? `Step 1/3: trusting the ClaudeRipple CA in your NSS database (${nssDb()}), which Chromium and so Claude Desktop reads. Your user only; no password, no sudo.`
+            : "Step 1/3: trusting the ClaudeRipple CA in your login keychain. macOS will ask for your password (ClaudeRipple never sees it).");
     trustCa(caPem);
-    if (!caTrusted())
+    if (!caTrusted(caPem))
         throw new Error("CA is not trusted; picker mode not enabled");
-    console.log(isWindows ? "✓ CA trusted (current user only)" : "✓ CA trusted (login keychain only)");
+    console.log(isWindows || isLinux ? "✓ CA trusted (current user only)" : "✓ CA trusted (login keychain only)");
     const proxyUrl = proxyUrlFor(cfg.listen.port);
     const r = applyAppProxy(proxyUrl);
     console.log(`✓ Claude Desktop config library entry applied (${r.id}${r.replaced ? `, previous entry ${r.replaced} remembered` : ""}): egressProxyUrl=${proxyUrl}`);
@@ -72,7 +79,7 @@ function pickerOff() {
     }
     if (isWindows)
         console.log("Removing the CA: Windows will ask you to confirm once more.");
-    const store = isWindows ? "your user certificate store" : "the login keychain";
+    const store = isWindows ? "your user certificate store" : isLinux ? `your NSS database (${nssDb()})` : "the login keychain";
     console.log(untrustCa(certPaths(home).caPem) ? `✓ CA removed from ${store}` : `✓ CA was not in ${store}`);
     console.log("\nQuit and reopen Claude Desktop to apply.");
 }
@@ -119,7 +126,7 @@ async function install() {
     const home = homeDir();
     const port = Number(opt("port") ?? DEFAULTS.listen.port);
     if (!isSupported)
-        throw new Error(`install supports macOS and Windows; on ${process.platform} run the router manually.`);
+        throw new Error(`install supports macOS, Windows and Linux (systemd); on ${process.platform} run the router manually.`);
     fs.mkdirSync(home, { recursive: true, mode: 0o700 });
     if (!certsExist(home)) {
         generateCerts(home, DEFAULTS.upstream);
@@ -137,10 +144,10 @@ async function install() {
     const proxyUrl = proxyUrlFor(cfg.listen.port);
     const caPath = certPaths(home).caPem;
     const maxCtx = opt("max-context-tokens");
-    const edit = applyProxyEnv({ proxyUrl, caPath, force: flag("force"), ...(maxCtx ? { maxContextTokens: Number(maxCtx) } : {}), models: cfg.cli.models ?? {} });
-    console.log(edit.changed ? `✓ ${settingsPath()} updated (backup: ${edit.backup ?? "none"})` : `✓ ${settingsPath()} already correct`);
-    for (const n of edit.notes)
-        console.log(`  note: ${n}`);
+    // settings.json is written last, after the probe: from that write on, every new Claude Code
+    // session sends everything to this router, so it must not point at one that never came up.
+    // A foreign proxy is still refused here, before anything is registered.
+    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({
@@ -151,9 +158,9 @@ async function install() {
         hookScript: installedRuntime.hookScript,
         repo: installedRuntime.repo,
     }, null, 2) + "\n");
-    // Windows registers 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) {
+    // 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],
@@ -161,7 +168,7 @@ async function install() {
             home,
             env: { ...installedRuntime.env, ...(process.env.CLAUDE_SETTINGS_PATH ? { CLAUDE_SETTINGS_PATH: process.env.CLAUDE_SETTINGS_PATH } : {}) },
         });
-        console.log(`✓ ${supervisorName()} registered: ${plist} (shows as "ClaudeRipple" in Login Items)`);
+        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 });
@@ -180,10 +187,16 @@ async function install() {
     console.log(started === "failed" ? `✗ could not start the router (${supervisorName()})` : `✓ router ${started === "already-running" ? "already running" : "started"}`);
     const p = await probeWithRetry({ host: cfg.listen.host, port: cfg.listen.port, caPem: caPath, upstream: cfg.upstream });
     console.log(p.ok ? `✓ end-to-end probe passed (${p.detail}, ${p.ms}ms)` : `✗ probe failed: ${p.detail}`);
-    if (!p.ok)
+    if (!p.ok) {
         process.exitCode = 1;
-    else
-        console.log("\nDone. New Claude Desktop Code sessions go through ClaudeRipple. Existing sessions pick up settings.json env changes on their next request.");
+        console.log(`${settingsPath()} was left as it was, so Claude Code does not depend on a router that is not answering. Fix the router, then run install again.`);
+        return;
+    }
+    const edit = applyProxyEnv({ proxyUrl, caPath, force: flag("force"), ...(maxCtx ? { maxContextTokens: Number(maxCtx) } : {}), models: cfg.cli.models ?? {} });
+    console.log(edit.changed ? `✓ ${settingsPath()} updated (backup: ${edit.backup ?? "none"})` : `✓ ${settingsPath()} already correct`);
+    for (const n of edit.notes)
+        console.log(`  note: ${n}`);
+    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() {
     const home = homeDir();
@@ -238,7 +251,7 @@ async function status() {
     rows.push(["settings.json", env.HTTPS_PROXY === proxyUrl && env.NODE_EXTRA_CA_CERTS === caPath ? "points at ClaudeRipple" : `HTTPS_PROXY=${env.HTTPS_PROXY ?? "-"} NODE_EXTRA_CA_CERTS=${env.NODE_EXTRA_CA_CERTS ?? "-"}`]);
     rows.push([supervisorName(), agentState()]);
     const ap = currentAppProxy();
-    rows.push(["picker mode", cfg.picker?.enabled ? `on · CA ${caTrusted() ? "trusted" : "NOT trusted"} · app proxy ${ap.ours ? ap.egressProxyUrl : "NOT set"}` : `off${ap.ours ? " (app proxy entry still present — run `picker off`)" : ""}`]);
+    rows.push(["picker mode", cfg.picker?.enabled ? `on · CA ${caTrusted(caPath) ? "trusted" : "NOT trusted"} · app proxy ${ap.ours ? ap.egressProxyUrl : "NOT set"}` : `off${ap.ours ? " (app proxy entry still present — run `picker off`)" : ""}`]);
     const p = await probe({ host: cfg.listen.host, port: cfg.listen.port, caPem: caPath, upstream: cfg.upstream });
     rows.push(["probe", `${p.ok ? "ok" : "FAIL"}: ${p.detail} (${p.ms}ms)`]);
     for (const [name, p2] of Object.entries(cfg.providers)) {

package/dist/cli/src/picker.js

@@ -1,6 +1,8 @@
 // `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)
+// on:  1. trust our CA for this user: login keychain (macOS asks for the password; we never see it),
+//         Cert:\CurrentUser\Root (Windows shows a confirmation dialog), or the NSS database Chromium
+//         reads on Linux (~/.pki/nssdb; no prompt, no sudo)
 //      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)
@@ -8,10 +10,11 @@
 //      → the user restarts Claude Desktop.
 // off: reverse all three.
 import { execFileSync } from "node:child_process";
-import crypto from "node:crypto";
+import crypto, { X509Certificate } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { windowsPowerShellEnv } from "./windows-powershell.js";
 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.
@@ -22,6 +25,10 @@ function appSupport() {
     if (process.platform === "win32") {
         return path.join(process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"), "Claude-3p");
     }
+    // Linux userData is $XDG_CONFIG_HOME/Claude, so the same "-3p" rule gives ~/.config/Claude-3p
+    // (Claude Desktop 2.2553.13's bundle: `${app.getPath("userData")}-3p`, no Linux special case).
+    if (process.platform === "linux")
+        return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "Claude-3p");
     return path.join(os.homedir(), "Library", "Application Support", "Claude-3p");
 }
 export function configLibraryDir() {
@@ -31,6 +38,84 @@ function loginKeychain() {
     return path.join(os.homedir(), "Library", "Keychains", "login.keychain-db");
 }
 const isWindows = process.platform === "win32";
+const isLinux = process.platform === "linux";
+// ---- Linux: the NSS database ------------------------------------------------------------
+//
+// Chromium on Linux takes locally added roots from the user's NSS database, not from /etc/ssl,
+// and Claude Desktop is Chromium: a CA only in the system bundle would leave the app a blank page
+// behind the router. certutil comes from libnss3-tools, which a desktop install does not always have.
+/** Test-only override; production always uses the database Chromium reads. */
+export function nssDb() {
+    return process.env.CLAUDERIPPLE_NSS_DB ?? path.join(os.homedir(), ".pki", "nssdb");
+}
+/**
+ * The fingerprint is part of the name so a CA from an earlier install is never taken for the
+ * current one: trusting the old one would pass a check by name and still fail every handshake.
+ */
+export function nssNickname(caPem) {
+    return `${CA_NAME} ${new X509Certificate(fs.readFileSync(caPem)).fingerprint256.replace(/:/g, "").slice(0, 24)}`;
+}
+function certutil(args) {
+    return execFileSync("certutil", ["-d", `sql:${nssDb()}`, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+/** Every ClaudeRipple CA in the database, including ones left by an earlier install. */
+function nssOurNicknames() {
+    let out;
+    try {
+        out = certutil(["-L"]);
+    }
+    catch {
+        return [];
+    }
+    // One line per certificate: the nickname, then its trust flags ("C,,") as the last column.
+    return out
+        .split("\n")
+        .map((line) => /^(.*\S)\s+\S*,\S*,\S*\s*$/.exec(line)?.[1])
+        .filter((name) => !!name && name.startsWith(CA_NAME));
+}
+export function nssTrusted(caPem) {
+    try {
+        const name = nssNickname(caPem);
+        const installed = new X509Certificate(certutil(["-L", "-n", name, "-a"]));
+        if (installed.fingerprint256 !== new X509Certificate(fs.readFileSync(caPem)).fingerprint256)
+            return false;
+        // Validated as an SSL CA (-u L): that is the trust a handshake needs, not mere presence.
+        certutil(["-V", "-n", name, "-u", "L"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function nssTrust(caPem) {
+    if (nssTrusted(caPem))
+        return;
+    try {
+        fs.mkdirSync(nssDb(), { recursive: true, mode: 0o700 });
+        if (!fs.existsSync(path.join(nssDb(), "cert9.db")))
+            certutil(["-N", "--empty-password"]);
+        certutil(["-A", "-n", nssNickname(caPem), "-t", "C,,", "-i", caPem]);
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            throw new Error("certutil not found. Install it (Ubuntu/Debian: `sudo apt install libnss3-tools`, Fedora: `sudo dnf install nss-tools`), then run `clauderipple picker on` again");
+        }
+        throw e;
+    }
+}
+/** Removes every ClaudeRipple CA, current or left over from an earlier install. */
+export function nssUntrust() {
+    const names = nssOurNicknames();
+    for (const name of names) {
+        try {
+            certutil(["-D", "-n", name]);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    return names.length > 0;
+}
 /** Single-quoted PowerShell literal; the only escape inside one is a doubled quote. */
 function ps(value) {
     return `'${value.replace(/'/g, "''")}'`;
@@ -45,19 +130,23 @@ function powershell(script, opts = {}) {
     const stdio = opts.stdio ?? "pipe";
     const args = ["-NoProfile", ...(opts.interactive ? [] : ["-NonInteractive"]), "-Command", script];
     return execFileSync("powershell.exe", args, {
+        env: windowsPowerShellEnv(),
         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
+ * Every platform trusts 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.
+ *   Linux   : the user's NSS database (see nssDb), with no prompt at all.
  * 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() {
+export function caTrusted(caPem) {
+    if (isLinux)
+        return nssTrusted(caPem);
     try {
         if (isWindows) {
             const out = powershell(`@(Get-ChildItem Cert:\\CurrentUser\\Root | Where-Object { $_.Subject -eq 'CN=${CA_NAME}' }).Count`);
@@ -72,7 +161,9 @@ export function caTrusted() {
 }
 /** 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())
+    if (isLinux)
+        return nssTrust(caPem);
+    if (caTrusted(caPem))
         return;
     if (isWindows) {
         // stdio inherit: the confirmation dialog is the OS's, but errors should reach the user's terminal.
@@ -82,7 +173,9 @@ export function trustCa(caPem) {
     execFileSync("security", ["add-trusted-cert", "-r", "trustRoot", "-k", loginKeychain(), caPem], { stdio: "inherit" });
 }
 export function untrustCa(caPem) {
-    if (!caTrusted())
+    if (isLinux)
+        return nssUntrust();
+    if (!caTrusted(caPem))
         return false;
     if (isWindows) {
         try {

package/dist/cli/src/schtasks.js

@@ -16,6 +16,7 @@ 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 TASK_NAME = "ClaudeRippleRouter";
 export function taskName() {
     return process.env.CLAUDERIPPLE_TASK_NAME ?? TASK_NAME;
@@ -27,6 +28,7 @@ function ps(value) {
 function run(script) {
     try {
         const out = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+            env: windowsPowerShellEnv(),
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
         }).toString();
@@ -37,6 +39,25 @@ function run(script) {
         return { ok: false, out: `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}`.trim() };
     }
 }
+/**
+ * The account the task runs as, qualified with its domain. A bare name is looked up as a machine
+ * name too, so on a local account named after its computer (user X on host X) it resolves to
+ * nothing and Register-ScheduledTask fails with 0x80070057 (#38). `X\X` names the user.
+ */
+export function taskUser(username = os.userInfo().username, domain = process.env.USERDOMAIN) {
+    return domain ? `${domain}\\${username}` : username;
+}
+/**
+ * Windows stores the qualified name as given on the trigger but the bare one on the principal
+ * (reported in #38), and a task registered before that fix carries the bare name on both, so
+ * either spelling of the same account is a match.
+ */
+function sameAccount(stored, expected) {
+    if (stored === undefined)
+        return false;
+    const bare = expected.slice(expected.lastIndexOf("\\") + 1);
+    return [expected, bare].some((name) => name.toLowerCase() === stored.toLowerCase());
+}
 export function taskDefinitionMatches(value, expected) {
     if (!value || typeof value !== "object")
         return false;
@@ -44,12 +65,12 @@ export function taskDefinitionMatches(value, expected) {
     return (task.actionCount === 1 &&
         task.execute?.toLowerCase() === "powershell.exe" &&
         task.arguments === expected.arguments &&
-        task.userId?.toLowerCase() === expected.userId.toLowerCase() &&
+        sameAccount(task.userId, expected.userId) &&
         task.runLevel === 0 &&
         task.logonType === 3 &&
         task.triggerCount === 1 &&
         task.triggerType === "MSFT_TaskLogonTrigger" &&
-        task.triggerUserId?.toLowerCase() === expected.userId.toLowerCase() &&
+        sameAccount(task.triggerUserId, expected.userId) &&
         task.restartCount === 99 &&
         task.restartInterval === "PT1M" &&
         task.executionTimeLimit === "PT0S" &&
@@ -96,30 +117,38 @@ function writeLauncher(opts) {
     fs.writeFileSync(launcher, lines.join("\r\n") + "\r\n");
     return launcher;
 }
+/**
+ * The registered task in the shape taskDefinitionMatches reads, or null. The settings object has
+ * no AllowStartIfOnBatteries/DontStopIfGoingOnBatteries — the switches of the same names set
+ * DisallowStartIfOnBatteries/StopIfGoingOnBatteries to false — so reading the switch names gave
+ * null, and until #38 no existing task ever matched: every install re-registered.
+ */
+export function existingTaskDefinition() {
+    const existing = run([
+        `$t = Get-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction SilentlyContinue`,
+        `if ($null -eq $t) { 'null'; exit 0 }`,
+        `$a = @($t.Actions); $p = $t.Principal; $tr = @($t.Triggers); $s = $t.Settings`,
+        `[pscustomobject]@{ actionCount = $a.Count; execute = $a[0].Execute; arguments = $a[0].Arguments; userId = $p.UserId; runLevel = [int]$p.RunLevel; logonType = [int]$p.LogonType; triggerCount = $tr.Count; triggerType = $tr[0].CimClass.CimClassName; triggerUserId = $tr[0].UserId; restartCount = $s.RestartCount; restartInterval = [string]$s.RestartInterval; executionTimeLimit = [string]$s.ExecutionTimeLimit; multipleInstances = [int]$s.MultipleInstances; allowStartIfOnBatteries = $s.DisallowStartIfOnBatteries -eq $false; dontStopIfGoingOnBatteries = $s.StopIfGoingOnBatteries -eq $false } | ConvertTo-Json -Compress`,
+    ].join("; "));
+    if (!existing.ok)
+        return null;
+    try {
+        return JSON.parse(existing.out);
+    }
+    catch {
+        // A malformed inspection result is not trusted; the caller falls through to registration.
+        return null;
+    }
+}
 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 user = taskUser();
     const actionArgs = `-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${launcher}"`;
     // Updating the generated launcher does not require re-registering an otherwise correct task.
     // Some Windows installations protect an existing per-user task's security descriptor so that
     // even the same unelevated user gets E_ACCESSDENIED from Register-ScheduledTask -Force. Treat the
     // verified existing definition as success; never silently accept a same-named foreign task.
-    const existing = run([
-        `$t = Get-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction SilentlyContinue`,
-        `if ($null -eq $t) { 'null'; exit 0 }`,
-        `$a = @($t.Actions); $p = $t.Principal; $tr = @($t.Triggers); $s = $t.Settings`,
-        `[pscustomobject]@{ actionCount = $a.Count; execute = $a[0].Execute; arguments = $a[0].Arguments; userId = $p.UserId; runLevel = [int]$p.RunLevel; logonType = [int]$p.LogonType; triggerCount = $tr.Count; triggerType = $tr[0].CimClass.CimClassName; triggerUserId = $tr[0].UserId; restartCount = $s.RestartCount; restartInterval = [string]$s.RestartInterval; executionTimeLimit = [string]$s.ExecutionTimeLimit; multipleInstances = [int]$s.MultipleInstances; allowStartIfOnBatteries = $s.AllowStartIfOnBatteries; dontStopIfGoingOnBatteries = $s.DontStopIfGoingOnBatteries } | ConvertTo-Json -Compress`,
-    ].join("; "));
-    let definition = null;
-    if (existing.ok) {
-        try {
-            definition = JSON.parse(existing.out);
-        }
-        catch {
-            // A malformed inspection result is not trusted; fall through to registration.
-        }
-    }
-    if (taskDefinitionMatches(definition, { arguments: actionArgs, userId: user }))
+    if (taskDefinitionMatches(existingTaskDefinition(), { arguments: actionArgs, userId: user }))
         return launcher;
     const script = [
         `$ErrorActionPreference = 'Stop'`,

package/dist/cli/src/settings.js

@@ -36,15 +36,22 @@ export const MODEL_SLOT_ENV = {
     smallFast: "ANTHROPIC_SMALL_FAST_MODEL",
     subagent: "CLAUDE_CODE_SUBAGENT_MODEL",
 };
+function refuseForeignProxy(existing, proxyUrl, force) {
+    if (existing && existing !== proxyUrl && !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.`);
+    }
+}
+/** The refusal `applyProxyEnv` would give, without writing: lets `install` fail before it registers anything. */
+export function checkProxyEnv(opts) {
+    refuseForeignProxy(currentProxyEnv().HTTPS_PROXY, opts.proxyUrl, opts.force);
+}
 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.`);
-    }
+    refuseForeignProxy(existing, opts.proxyUrl, opts.force);
     if (existing && existing !== opts.proxyUrl)
         notes.push(`replaced HTTPS_PROXY ${existing}`);
     const want = { HTTPS_PROXY: opts.proxyUrl, NODE_EXTRA_CA_CERTS: opts.caPath };

package/dist/cli/src/supervisor.js

@@ -1,32 +1,38 @@
-// One supervisor interface, two implementations: launchd on macOS, Task Scheduler on Windows.
+// One supervisor interface, three implementations: launchd on macOS, Task Scheduler on Windows,
+// a systemd user service on Linux.
 // 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";
+import * as systemd from "./systemd.js";
+import { windowsPowerShellEnv } from "./windows-powershell.js";
 export const isWindows = process.platform === "win32";
-export const isSupported = isWindows || process.platform === "darwin";
+export const isLinux = process.platform === "linux";
+export const isSupported = isWindows || isLinux || 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";
+    return isWindows ? "scheduled task" : isLinux ? "systemd user service" : "launchd agent";
 }
 export function installAgent(opts) {
-    return isWindows ? schtasks.installAgent(opts) : launchd.installAgent(opts);
+    return isWindows ? schtasks.installAgent(opts) : isLinux ? systemd.installAgent(opts) : launchd.installAgent(opts);
 }
 export function removeAgent() {
-    return isWindows ? schtasks.removeAgent() : launchd.removeAgent();
+    return isWindows ? schtasks.removeAgent() : isLinux ? systemd.removeAgent() : launchd.removeAgent();
 }
 export function agentState() {
-    return isWindows ? schtasks.agentState() : launchd.agentState();
+    return isWindows ? schtasks.agentState() : isLinux ? systemd.agentState() : launchd.agentState();
 }
 export function agentPid() {
-    return isWindows ? schtasks.agentPid() : launchd.agentPid();
+    return isWindows ? schtasks.agentPid() : isLinux ? systemd.agentPid() : launchd.agentPid();
 }
 export function startAgent() {
-    return isWindows ? schtasks.startAgent() : launchd.startAgent();
+    return isWindows ? schtasks.startAgent() : isLinux ? systemd.startAgent() : launchd.startAgent();
 }
 export function stopAgent() {
+    if (isLinux)
+        return systemd.stopAgent();
     if (!isWindows)
         return launchd.stopAgent();
     // Ask the router to drain first: a clean exit also ends the launcher's supervision loop, so the
@@ -38,7 +44,7 @@ export function 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 });
+        execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `Invoke-RestMethod -Method Post -Uri '${adminUrl()}/api/shutdown' -TimeoutSec 10 | Out-Null`], { env: windowsPowerShellEnv(), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
         return true;
     }
     catch {
@@ -92,9 +98,9 @@ function restartWindows(opts) {
     return schtasks.startAgent() === "failed" ? "failed" : "drained";
 }
 export function restartAgent(opts = {}) {
-    return isWindows ? restartWindows(opts) : launchd.restartAgent(opts);
+    return isWindows ? restartWindows(opts) : isLinux ? systemd.restartAgent(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();
+    return isWindows ? `Task Scheduler\\${schtasks.taskName()}` : isLinux ? systemd.unitPath() : launchd.plistPath();
 }

package/dist/cli/src/systemd.js

@@ -0,0 +1,126 @@
+// Linux supervisor: a per-user systemd service that keeps the router alive. No sudo, nothing
+// machine-wide. Restart=always + RestartSec=2 is launchd's KeepAlive + ThrottleInterval 2: a
+// self-exit (code 75) is followed by a fresh process two seconds later, and StartLimitIntervalSec=0
+// keeps systemd from giving up on it after a burst of those.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const HEADER = "[Unit]\nDescription=ClaudeRipple local model router\n";
+/** Test-only override; production always uses clauderipple.service. */
+export function unitName() {
+    const name = process.env.CLAUDERIPPLE_SYSTEMD_UNIT ?? "clauderipple.service";
+    if (!/^[A-Za-z0-9_.-]+\.service$/.test(name))
+        throw new Error(`invalid systemd unit name: ${name}`);
+    return name;
+}
+export function unitPath() {
+    const config = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    return path.join(config, "systemd", "user", unitName());
+}
+/**
+ * One quoted unit-file word. `%` is a specifier and `$` an environment substitution in ExecStart
+ * (systemd.service(5)), so a path containing either has to be escaped or it runs something else.
+ */
+function quote(value, dollar) {
+    if (/[\r\n\0]/.test(value))
+        throw new Error("newlines and NUL cannot appear in a systemd unit value");
+    let s = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%");
+    if (dollar)
+        s = s.replace(/\$/g, "$$$$");
+    return `"${s}"`;
+}
+export function renderUnit(opts) {
+    if (!path.isAbsolute(opts.program))
+        throw new Error("the service program must be an absolute path");
+    const env = { CLAUDERIPPLE_HOME: opts.home, ...(opts.env ?? {}) };
+    const envLines = Object.entries(env).map(([k, v]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
+            throw new Error(`invalid environment name: ${k}`);
+        return `Environment=${quote(`${k}=${v}`, false)}`;
+    });
+    // TimeoutStopSec covers the router's 90s drain on SIGTERM (ARCHITECTURE §5) with room to spare;
+    // KillMode=mixed sends that SIGTERM to the router alone and SIGKILLs only what outlives the budget.
+    return `${HEADER}StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+ExecStart=${[opts.program, ...(opts.args ?? [])].map((a) => quote(a, true)).join(" ")}
+${envLines.join("\n")}
+Restart=always
+RestartSec=2
+KillSignal=SIGTERM
+KillMode=mixed
+TimeoutStopSec=120
+UMask=0077
+
+[Install]
+WantedBy=default.target
+`;
+}
+function systemctl(args) {
+    try {
+        const out = execFileSync("systemctl", ["--user", ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 150_000 });
+        return { ok: true, out };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, out: err.stderr?.toString().trim() || err.message || "systemctl failed" };
+    }
+}
+function mustSystemctl(args) {
+    const r = systemctl(args);
+    if (!r.ok)
+        throw new Error(`systemctl --user ${args.join(" ")} failed: ${r.out}`);
+}
+export function installAgent(opts) {
+    // No user manager (an ssh login without lingering, a container) means nothing would ever start
+    // the router: fail here, before any file is written.
+    mustSystemctl(["show-environment"]);
+    const file = unitPath();
+    if (fs.existsSync(file) && !fs.readFileSync(file, "utf8").startsWith(HEADER)) {
+        throw new Error(`${file} exists and is not ClaudeRipple's; refusing to replace it`);
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, renderUnit(opts), { mode: 0o600 });
+    mustSystemctl(["daemon-reload"]);
+    mustSystemctl(["enable", unitName()]);
+    return file;
+}
+export function removeAgent() {
+    const file = unitPath();
+    if (!fs.existsSync(file))
+        return false;
+    mustSystemctl(["disable", "--now", unitName()]);
+    fs.unlinkSync(file);
+    mustSystemctl(["daemon-reload"]);
+    return true;
+}
+export function agentState() {
+    const r = systemctl(["show", unitName(), "--property=ActiveState", "--value"]);
+    if (r.ok && r.out.trim() === "active")
+        return "running";
+    return fs.existsSync(unitPath()) ? "loaded" : "not-loaded";
+}
+export function agentPid() {
+    const r = systemctl(["show", unitName(), "--property=MainPID", "--value"]);
+    const pid = Number(r.out.trim());
+    return r.ok && Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+/** Idempotent, like launchd's: a running router is left alone (ARCHITECTURE §5, "Start Router"). */
+export function startAgent() {
+    if (agentState() === "running")
+        return "already-running";
+    return systemctl(["start", unitName()]).ok ? "started" : "failed";
+}
+export function stopAgent() {
+    return systemctl(["stop", unitName()]).ok;
+}
+/**
+ * systemd sends the SIGTERM, waits for the process to exit (up to TimeoutStopSec) and then starts
+ * a new one, so the drain is never cut the way `launchctl kickstart -k` cut it.
+ */
+export function restartAgent(opts = {}) {
+    opts.onProgress?.("waiting for in-flight model calls to finish (up to 120s)…");
+    return systemctl(["restart", unitName()]).ok ? "drained" : "failed";
+}

package/dist/cli/src/windows-powershell.js

@@ -0,0 +1,13 @@
+// Environment for every powershell.exe (Windows PowerShell 5.1) the CLI and router start.
+//
+// PowerShell 7 puts its own module directories at the front of PSModulePath. pwsh strips them
+// when it starts powershell.exe itself, but not when another process sits in between: from a pwsh
+// terminal the chain pwsh → node → powershell.exe hands 5.1 the PowerShell 7 copy of
+// Microsoft.PowerShell.Security, which fails to load, and the Cert: drive goes with it.
+// `picker on` then stopped at "Cannot find drive 'Cert'" and `status` read a trusted CA as
+// untrusted (measured on Windows 11 with PowerShell 7.6.6, issue #35). Without the variable,
+// Windows PowerShell rebuilds its own default from the registry.
+/** process.env minus PSModulePath, matched without regard to case as Windows does. */
+export function windowsPowerShellEnv() {
+    return Object.fromEntries(Object.entries(process.env).filter(([k]) => k.toLowerCase() !== "psmodulepath"));
+}