clauderipple 0.9.5 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.10.0 — 2026-10-20
+
+### Added
+
+- **Code tab sessions on an SSH host route through Ripple.** Claude Code on a remote host went
+  straight to Anthropic and could not find the GPT workers, because Claude Desktop opens that
+  connection itself and never reads `RemoteForward` (#67). `clauderipple remote add <host>` copies
+  the CA and the generated agent files over plain `sh`, points the host's `settings.json` at a
+  router-held reverse tunnel on `127.0.0.1:18791`, re-syncs the agents whenever they change, and
+  `remote hosts` / `remote remove` manage them. It needs key-based `ssh` with no password prompt;
+  the mod is not on the remote host yet.
+- **The logs page shows token usage for any period, and every provider.** The chips covered only
+  the last hour. A period control (1 hour, today, 7 days, 30 days, this month, all time, custom
+  dates) now reads an hourly history that survives restarts, a per-model table shows where the
+  tokens went, and the provider menu lists every configured provider instead of only the ones in
+  the last 200 requests, filtering the chips, the table and the recent requests together. A figure
+  too wide for a narrow pane or a 1,024px window steps its type down instead of being cut.
+- **The band's limits row shows every provider.** Claude, ChatGPT, Antigravity (Gemini), OpenCode
+  Go and a Grok subscription each draw a group in their provider's colour, from one
+  `/api/limits` read; before, only Claude and ChatGPT did. At about 100 columns four providers
+  took roughly 207 cells as gauges against 96, so the row picks the roomiest of three densities
+  and gives up later groups only when none fits. Each provider can be kept off the status bar.
+- **The Agents pane gives each agent a card.** The pane showed "no agents running · 2 done" over
+  an empty panel. Each card now holds the state, title, the model that answered and the effort it
+  was sent at, the API's real token counts with cache share, the tool count, and the elapsed time,
+  and keeps its size steady while the agent runs. Opening a card shows its conversation in the
+  pane, with a run of tool calls collapsed into one summary line ("3 files read, 1 command run"),
+  as the Claude app draws it.
+- **The dashboard's Phone view pairs Ripple Remote and manages the connection.** Pairing used to
+  mean running `npm run remote -- pair` in a source checkout. The view now shows the host's state,
+  a pairing QR on request, the mode, the phones seen and a key rotation, answered on a
+  loopback-only `/local` API with a secret from a `0600` file. The published CLI and dashboard now
+  install the phone host, which runs under Windows and Linux user supervisors as well as launchd.
+- **Ripple Remote tells you which session finished and what it did.** Notifications carried one
+  fixed line for every session; the host now sends the title and the last answer, approval request
+  or failure reason inside an encrypted blob, leaving Expo, APNs and FCM with only the fallback
+  text. Mac sessions push when a turn ends while the Mac is away, Claude app sessions send and
+  receive photos, a subagent shows its model and opens its own chat, and thinking no longer
+  splits a run (one real session went from 1,442 rows to 549).
+- **The desktop has two skins, deep and flat.** A `skin` setting picks them on the quick settings
+  panel and the dashboard's Look card; deep stays the default. Flat follows the app's own surface
+  and quiet text colour, keeps one accent, and the band's labels, counts and controls carry the
+  right colour.
+
+### Fixed
+
+- **Google and Antigravity prompt refusals are retried instead of failing the turn.** A refusal is
+  now returned unwritten and retried once along a configured fallback route with the original
+  request, and an Antigravity 429 is called a real limit only when fresh account and project quota
+  evidence says so.
+- **Parallel tool results with images stay together on the OpenAI-compatible wire.** Three image
+  Reads used to interleave `tool|user|tool|user`, and DeepSeek refused them
+  ("insufficient tool messages following tool_calls", #64). Images now wait until the run of tool
+  results ends.
+- **A slow reasoning model passes the connection check.** Hive answers a streamed request in 0.3
+  seconds but a whole one in 3–23, past the 8-second probe, so a working key read as "could not
+  connect"; the check now streams and drops the body once the status is in.
+- **A provider named in Hangul is named after its domain.** "하이브" slugged to nothing and showed
+  as "provider"; it now falls back to the URL's domain ("thehive").
+- **A failed restart no longer ends the Windows supervisor loop.** One `Start-Process` error, such
+  as a locked log file, stopped the script and left the router and host unsupervised until logon.
+- **A dark-mode select's options are readable.** Native options and optgroups now get opaque,
+  theme-aware backgrounds.
+- **Slash commands stay available when settings fail to load.** A throw while loading settings
+  took `/ripple`, `/ripple-log` and `/ripple-bar` with it (#62); the settings step now has its own
+  catch, so the commands register either way.
+
 ## 0.9.5 — 2026-10-14
 
 ### Fixed

package/README.md

@@ -495,6 +495,37 @@ same ChatGPT provider as the search backend in `config.json`:
 This is opt-in. With no `webSearch` setting, Claude Code's existing search path
 is unchanged.
 
+### Remote (SSH) sessions
+
+Claude Desktop's Code tab can run a session on a remote Linux host over SSH.
+Claude Code then runs **on that host**, where ClaudeRipple is not, so routed
+models are unknown there (`Agent type 'gpt-6-1-sol' not found`). Connect the
+host once from the machine ClaudeRipple runs on:
+
+```bash
+clauderipple remote add my-server            # an ssh alias or user@host; --port N (default 18791)
+clauderipple remote hosts                    # tunnel state per host (also in `remote status`)
+clauderipple remote remove my-server         # undo it
+```
+
+`remote add` needs key-based `ssh my-server` to work without a password prompt.
+It copies the router's CA certificate (the public certificate only) to
+`~/.clauderipple-remote/` on the host, points the host's
+`~/.claude/settings.json` at the tunnel (`HTTPS_PROXY=http://127.0.0.1:18791`,
+`NODE_EXTRA_CA_CERTS`; the original is kept as
+`settings.json.clauderipple-backup`; a different proxy already there is refused
+without `--force`), and copies the generated agent files. The router then keeps
+a reverse SSH tunnel open from the host's `127.0.0.1:18791` to itself, restarts
+it when it drops, and copies the agent files again whenever they change. The
+host needs only `sh` — no Node and no ClaudeRipple.
+
+While the tunnel is down, Claude Code on the host gets *connection refused*
+rather than going to Anthropic around the router. The remote session only exists
+while this machine's Claude Desktop is connected to it anyway. The tunnel
+listens on the host's loopback only, but on a shared host every user there can
+reach that port, and through it your router. The status mod and image
+generation are not available on remote hosts yet.
+
 ### Codex app and Codex CLI
 
 ```bash

package/dist/app/package.json

@@ -1,5 +1,5 @@
 {
   "private": true,
-  "version": "0.9.5",
+  "version": "0.10.0",
   "type": "commonjs"
 }

package/dist/cli/src/hooks/agent-title.js

@@ -25,13 +25,16 @@ import { fileURLToPath } from "node:url";
 const MARKER = /^\s*\[\[\s*(?:ripple|gpt)\s*:\s*([A-Za-z0-9.\-]+)\s*(?:@\s*([A-Za-z]+))?\s*\]\]/;
 const REMINDER = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
 const OUR_PREFIX = /^[^\s·]+(?:·[a-z]+)? · /;
-const CLAUDE_ID = /^claude-(opus|sonnet|haiku|fable)-(\d+(?:-\d+)*?)(?:-\d{8})?$/;
+const CLAUDE_ID = /^claude-(opus|sonnet|haiku|fable|mythos)-(\d+(?:-\d+)*?)(?:-\d{8})?$/;
 /** The router's default `effortClamp` (config.ts), for when config.json cannot be read. */
 const DEFAULT_CLAMP = { ultra: "max" };
-/** A model's name in a title: the last word of its display name ("GPT-6.1 Sol" → "Sol"). */
+/**
+ * A model's name in a title: the last word of its display name ("GPT-6.1 Sol" → "Sol"), without
+ * the vendor path a hosted id carries ("deepseek-ai/deepseek-v4.1-flash-1017" → "deepseek-v4.1-flash-1017").
+ */
 export function shortName(name) {
     const words = name.trim().split(/\s+/);
-    return words[words.length - 1];
+    return words[words.length - 1].replace(/^.*\//, "");
 }
 function titleConfig() {
     const names = { "gpt-5.6-terra": "Terra", "gpt-5.6-sol": "Sol", "gpt-5.6-luna": "Luna", "gpt-6-astra": "Astra", "gpt-6-sol": "Sol", "gpt-6-luna": "Luna" };
@@ -84,7 +87,7 @@ export function fromAgentFile(subagentType, dirs) {
 }
 export function claudePretty(modelId) {
     const v = (modelId ?? "").trim().toLowerCase();
-    if (["opus", "sonnet", "haiku", "fable"].includes(v))
+    if (["opus", "sonnet", "haiku", "fable", "mythos"].includes(v))
         return v[0].toUpperCase() + v.slice(1);
     const m = CLAUDE_ID.exec(v);
     return m ? m[1][0].toUpperCase() + m[1].slice(1) + m[2].replace(/-/g, ".") : null;

package/dist/cli/src/index.js

@@ -451,6 +451,12 @@ function help() {
   status
   start | stop | restart
   logs [-n N] [-f]
+  remote [install|uninstall|status|pair]  run or manage the phone host (macOS, Windows, Linux systemd)
+  remote add <ssh-host> [--port N] [--force]
+                    route Claude Desktop sessions that run on a remote (SSH) host through ClaudeRipple:
+                    sets up the host over your key-based ssh and keeps a reverse tunnel open (remote port, default 18791)
+  remote remove <ssh-host>   undo "remote add" on that host and stop its tunnel
+  remote hosts      list remote (SSH) hosts and their tunnels (also shown by "remote status")
   config            print the config file path
   ui                open the dashboard in your browser
   tray [--install]  start the menu-bar / tray app (--install fetches Electron, ~270MB, once)
@@ -473,6 +479,43 @@ Home directory: ${homeDir()}  (override with CLAUDERIPPLE_HOME)`);
 }
 try {
     switch (cmd) {
+        case "remote": {
+            const sub = args[1];
+            // Remote (SSH) hosts for Claude Desktop sessions; every other `remote` verb is the phone host's.
+            if (sub === "add" || sub === "remove" || sub === "hosts") {
+                const { remoteAdd, remoteRemove, remoteHosts, REMOTE_SSH_USAGE } = await import("./remote.js");
+                const host = args[2];
+                if (sub === "hosts")
+                    await remoteHosts();
+                else if (!host || host.startsWith("--"))
+                    throw new Error(REMOTE_SSH_USAGE);
+                else if (sub === "add") {
+                    const port = opt("port");
+                    await remoteAdd(host, { ...(port !== undefined ? { port: Number(port) } : {}), force: flag("force") });
+                }
+                else
+                    await remoteRemove(host);
+                break;
+            }
+            const script = path.resolve(here, "../../remote/src/main" + path.extname(fileURLToPath(import.meta.url)));
+            const { spawn } = await import("node:child_process");
+            const child = spawn(installedRuntime.node, [script, ...args.slice(1)], { stdio: "inherit", env: { ...process.env, ...installedRuntime.env } });
+            for (const signal of ["SIGTERM", "SIGINT"])
+                process.on(signal, () => child.kill(signal));
+            process.exitCode = await new Promise((resolve, reject) => {
+                child.once("error", reject);
+                child.once("exit", code => resolve(code ?? 1));
+            });
+            if (sub === "status") {
+                // Only when there are any, so the phone host's status reads exactly as before otherwise.
+                const { configuredHosts, remoteHosts } = await import("./remote.js");
+                if (configuredHosts(configPath()).length > 0) {
+                    console.log("\nremote (SSH) hosts:");
+                    await remoteHosts();
+                }
+            }
+            break;
+        }
         case "install":
             await install();
             break;

package/dist/cli/src/remote.js

@@ -0,0 +1,263 @@
+// clauderipple remote add|remove|hosts — Claude Desktop sessions on a remote (SSH) host (issue #67).
+//
+// `add` prepares the remote over the user's own key-based ssh (CA certificate, settings.json env,
+// agent files; remote-host.ts), records the host in config.json, and asks the running router to
+// open the reverse tunnel (remote-tunnel.ts). `remove` undoes exactly that. The phone host keeps
+// `remote install|uninstall|status|pair` and the bare `remote`; these verbs are new beside them.
+import fs from "node:fs";
+import { defaultAgentDir } from "../../router/src/agents.js";
+import { ConfigStore, adminPort, configPath, homeDir } from "../../router/src/config.js";
+import { DEFAULT_REMOTE_PORT, REMOTE_DIR, SETTINGS_BACKUP_SUFFIX, SshConnectError, assetLines, hostProblem, inspectRemote, planAgents, portProblem, readLocalAssets, remoteCaPath, remoteProxyUrl, runRemoteScript, script, settingsGuardLine, settingsWriteLines, spawnSsh, } from "../../router/src/remote-host.js";
+import { refuseForeignProxy } from "./settings.js";
+function parseSettings(text, host) {
+    if (text === null || text.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${host}:~/.claude/settings.json is not valid JSON (${e.message}); fix it first — nothing was changed`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error(`${host}:~/.claude/settings.json is not a JSON object; nothing was changed`);
+    return parsed;
+}
+function envOf(s) {
+    return { ...(s.env ?? {}) };
+}
+/**
+ * The remote settings.json with our two env keys set, or null when it already has them. Same rule
+ * as the local install (settings.ts): every other key is kept, and a different HTTPS_PROXY is
+ * refused unless forced.
+ */
+export function mergeRemoteSettings(text, host, want, force) {
+    const s = parseSettings(text, host);
+    const env = envOf(s);
+    try {
+        refuseForeignProxy(env.HTTPS_PROXY, want.proxyUrl, force);
+    }
+    catch (e) {
+        throw new Error(`${host}: ${e.message}`);
+    }
+    const notes = [];
+    if (env.HTTPS_PROXY && env.HTTPS_PROXY !== want.proxyUrl)
+        notes.push(`replaced HTTPS_PROXY ${env.HTTPS_PROXY}`);
+    if (env.NODE_EXTRA_CA_CERTS && env.NODE_EXTRA_CA_CERTS !== want.caPath)
+        notes.push(`replaced NODE_EXTRA_CA_CERTS ${env.NODE_EXTRA_CA_CERTS}`);
+    if (env.HTTPS_PROXY === want.proxyUrl && env.NODE_EXTRA_CA_CERTS === want.caPath)
+        return { content: null, notes };
+    env.HTTPS_PROXY = want.proxyUrl;
+    env.NODE_EXTRA_CA_CERTS = want.caPath;
+    return { content: JSON.stringify({ ...s, env }, null, 2) + "\n", notes };
+}
+/** The remote settings.json without our two keys (only where they still hold our values), or null when unchanged. */
+export function unmergeRemoteSettings(text, host, ours) {
+    if (text === null)
+        return { content: null, notes: [] };
+    const s = parseSettings(text, host);
+    const env = envOf(s);
+    const notes = [];
+    let changed = false;
+    for (const [key, value] of [["HTTPS_PROXY", ours.proxyUrl], ["NODE_EXTRA_CA_CERTS", ours.caPath]]) {
+        if (env[key] === value) {
+            delete env[key];
+            changed = true;
+        }
+        else if (env[key])
+            notes.push(`left ${key}=${env[key]} (not ours)`);
+    }
+    if (!changed)
+        return { content: null, notes };
+    const next = { ...s };
+    if (Object.keys(env).length === 0)
+        delete next.env;
+    else
+        next.env = env;
+    return { content: JSON.stringify(next, null, 2) + "\n", notes };
+}
+export function configuredHosts(configFile) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(configFile, "utf8"));
+        const hosts = raw.remote?.hosts;
+        return Array.isArray(hosts) ? hosts.filter((h) => !!h && typeof h.host === "string" && typeof h.port === "number") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Rewrite `remote.hosts` in config.json, everything else as it was; atomic, as the router hot-reloads it. */
+function updateHosts(configFile, mutate) {
+    if (!fs.existsSync(configFile))
+        throw new Error(`no config at ${configFile}; run \`clauderipple install\` first`);
+    const raw = JSON.parse(fs.readFileSync(configFile, "utf8"));
+    const remote = (raw.remote && typeof raw.remote === "object" ? raw.remote : {});
+    const hosts = mutate(Array.isArray(remote.hosts) ? remote.hosts : []);
+    if (hosts.length > 0)
+        raw.remote = { ...remote, hosts };
+    else
+        delete raw.remote;
+    const tmp = `${configFile}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, JSON.stringify(raw, null, 2) + "\n");
+    fs.renameSync(tmp, configFile);
+}
+async function routerCall(adminUrl, method, pathname) {
+    if (adminUrl === null)
+        return { ok: false, why: "not asked" };
+    try {
+        const res = await fetch(`${adminUrl}${pathname}`, { method, signal: AbortSignal.timeout(5_000) });
+        if (res.status === 404 || res.status === 501)
+            return { ok: false, why: "the running router does not manage remote tunnels (an older version?); restart it with `clauderipple restart`" };
+        if (!res.ok)
+            return { ok: false, why: `the router answered HTTP ${res.status}` };
+        return { ok: true, hosts: (await res.json()).hosts ?? [] };
+    }
+    catch {
+        return { ok: false, why: "the router is not answering; the tunnel starts when it does (`clauderipple start`)" };
+    }
+}
+function defaultAdminUrl(configFile) {
+    return `http://127.0.0.1:${adminPort(new ConfigStore(configFile).get())}`;
+}
+function describe(s) {
+    return `${s.state}${s.state === "up" ? ` since ${s.since}` : ""}${s.lastError ? ` — ${s.lastError}` : ""}`;
+}
+function resolved(opts) {
+    const configFile = opts.configFile ?? configPath();
+    return {
+        run: opts.run ?? spawnSsh,
+        home: opts.home ?? homeDir(),
+        agentDir: opts.agentDir ?? defaultAgentDir(),
+        configFile,
+        adminUrl: opts.adminUrl === undefined ? defaultAdminUrl(configFile) : opts.adminUrl,
+        print: opts.print ?? ((line) => console.log(line)),
+        waitMs: opts.waitMs ?? 20_000,
+    };
+}
+function reachError(host, e) {
+    if (e instanceof SshConnectError) {
+        return new Error(`${e.message}\nClaudeRipple uses your own ssh with key-based login and never asks for a password. Set that up first ` +
+            `(for example \`ssh-copy-id ${host}\`), check that \`ssh ${host} true\` runs without a prompt, then run this again.`);
+    }
+    return e;
+}
+// ---- commands ------------------------------------------------------------------------------
+export async function remoteAdd(host, o = {}) {
+    const problem = hostProblem(host);
+    if (problem)
+        throw new Error(problem);
+    const port = o.port ?? DEFAULT_REMOTE_PORT;
+    const portError = portProblem(port);
+    if (portError)
+        throw new Error(`--port: ${portError}`);
+    const r = resolved(o);
+    const assets = readLocalAssets({ home: r.home, agentDir: r.agentDir });
+    if (!fs.existsSync(r.configFile))
+        throw new Error(`no config at ${r.configFile}; run \`clauderipple install\` first`);
+    let state;
+    try {
+        state = await inspectRemote(r.run, host);
+    }
+    catch (e) {
+        throw reachError(host, e);
+    }
+    r.print(`✓ ${host}: key-based ssh works (home ${state.home})`);
+    const want = { proxyUrl: remoteProxyUrl(port), caPath: remoteCaPath(state.home) };
+    const settings = mergeRemoteSettings(state.settings, host, want, o.force === true);
+    const plan = planAgents(assets.agents.map((a) => a.name), state);
+    // The CA goes before the env that names it; the guard before both, so a refusal changes nothing.
+    const lines = settings.content !== null
+        ? [settingsGuardLine(state), ...assetLines(assets, plan, want), ...settingsWriteLines(state, settings.content)]
+        : assetLines(assets, plan, want);
+    await runRemoteScript(r.run, host, script(lines));
+    r.print(`✓ CA certificate copied to ${want.caPath} (the public certificate only)`);
+    if (settings.content !== null) {
+        r.print(`✓ ${host}:~/.claude/settings.json env: HTTPS_PROXY=${want.proxyUrl}, NODE_EXTRA_CA_CERTS=${want.caPath}`);
+        if (state.settings !== null && !state.backup)
+            r.print(`  backup: ~/.claude/settings.json${SETTINGS_BACKUP_SUFFIX}`);
+    }
+    else
+        r.print(`✓ ${host}:~/.claude/settings.json already points at the tunnel`);
+    for (const n of settings.notes)
+        r.print(`  note: ${n}`);
+    r.print(`✓ ${plan.write.length} agent file${plan.write.length === 1 ? "" : "s"} copied to ~/.claude/agents${plan.remove.length ? `, ${plan.remove.length} no longer generated removed` : ""}`);
+    for (const n of plan.skipped)
+        r.print(`  note: ~/.claude/agents/${n}.md on ${host} is not ours; left alone`);
+    updateHosts(r.configFile, (hosts) => [...hosts.filter((h) => h.host !== host), { host, port }]);
+    r.print(`✓ ${host} saved in ${r.configFile}`);
+    const reload = await routerCall(r.adminUrl, "POST", "/api/remote/reload");
+    if (!reload.ok) {
+        if (r.adminUrl !== null)
+            r.print(`  ${reload.why}`);
+        return;
+    }
+    // The tunnel comes up asynchronously; say how it went rather than that it was asked for.
+    const deadline = Date.now() + r.waitMs;
+    let last = reload.hosts.find((h) => h.host === host);
+    while (last?.state !== "up" && Date.now() < deadline) {
+        await new Promise((res) => setTimeout(res, 500));
+        const now = await routerCall(r.adminUrl, "GET", "/api/remote");
+        if (now.ok)
+            last = now.hosts.find((h) => h.host === host);
+    }
+    if (last?.state === "up")
+        r.print(`✓ tunnel up: 127.0.0.1:${port} on ${host} reaches ClaudeRipple. New Claude Desktop sessions on ${host} go through it.`);
+    else {
+        r.print(`✗ tunnel ${last ? describe(last) : "not started"}. The router keeps retrying; \`clauderipple remote hosts\` shows its state.`);
+        process.exitCode = 1;
+    }
+}
+export async function remoteRemove(host, o = {}) {
+    const problem = hostProblem(host);
+    if (problem)
+        throw new Error(problem);
+    const r = resolved(o);
+    const entry = configuredHosts(r.configFile).find((h) => h.host === host);
+    // The tunnel goes first, so nothing re-copies files while they are being removed.
+    if (entry) {
+        updateHosts(r.configFile, (hosts) => hosts.filter((h) => h.host !== host));
+        r.print(`✓ ${host} removed from ${r.configFile}`);
+        const reload = await routerCall(r.adminUrl, "POST", "/api/remote/reload");
+        r.print(reload.ok ? "✓ tunnel stopped" : `  ${reload.why}`);
+    }
+    else
+        r.print(`  ${host} was not in ${r.configFile}; cleaning up the host anyway`);
+    let state;
+    try {
+        state = await inspectRemote(r.run, host);
+    }
+    catch (e) {
+        const err = reachError(host, e);
+        throw new Error(`${err.message}\nNothing on ${host} was changed. Run \`clauderipple remote remove ${host}\` again once it is reachable.`);
+    }
+    const record = state.record ?? { agents: [] };
+    const ours = { proxyUrl: record.proxyUrl ?? remoteProxyUrl(entry?.port ?? DEFAULT_REMOTE_PORT), caPath: record.caPath ?? remoteCaPath(state.home) };
+    const settings = unmergeRemoteSettings(state.settings, host, ours);
+    const lines = [];
+    if (settings.content !== null)
+        lines.push(...settingsWriteLines(state, settings.content));
+    lines.push(...planAgents([], { record, agentFiles: state.agentFiles }).remove.map((n) => `rm -f "$HOME/.claude/agents/${n}.md"`));
+    lines.push(`if [ -n "$HOME" ] && [ "$HOME" != "/" ]; then rm -rf "$HOME/${REMOTE_DIR}"; fi`);
+    await runRemoteScript(r.run, host, script(lines));
+    r.print(settings.content !== null ? `✓ ${host}:~/.claude/settings.json: HTTPS_PROXY and NODE_EXTRA_CA_CERTS removed (everything else kept)` : `✓ ${host}:~/.claude/settings.json had no ClaudeRipple keys`);
+    for (const n of settings.notes)
+        r.print(`  note: ${n}`);
+    r.print(`✓ ${record.agents.length} agent file${record.agents.length === 1 ? "" : "s"} we copied removed, and ~/${REMOTE_DIR}`);
+    if (state.backup)
+        r.print(`  the original settings.json is still in ~/.claude/settings.json${SETTINGS_BACKUP_SUFFIX}`);
+}
+export async function remoteHosts(o = {}) {
+    const r = resolved(o);
+    const hosts = configuredHosts(r.configFile);
+    if (hosts.length === 0) {
+        r.print("no remote (SSH) hosts. Add one with: clauderipple remote add <ssh-host> [--port N]");
+        return;
+    }
+    const live = await routerCall(r.adminUrl, "GET", "/api/remote");
+    const w = Math.max(...hosts.map((h) => h.host.length));
+    for (const h of hosts) {
+        const s = live.ok ? live.hosts.find((x) => x.host === h.host) : undefined;
+        r.print(`${h.host.padEnd(w)}  127.0.0.1:${h.port}  ${s ? describe(s) : live.ok ? "not started" : live.why}`);
+    }
+}
+export const REMOTE_SSH_USAGE = "usage: clauderipple remote add <ssh-host> [--port N] [--force] | remote remove <ssh-host> | remote hosts";

package/dist/cli/src/schtasks.js

@@ -94,27 +94,32 @@ export function taskDefinitionMatches(value, expected) {
  *    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");
+export function renderLauncher(opts) {
     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.",
+    const quoteArg = (arg) => ps(`"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`);
+    // No `$ErrorActionPreference = 'Stop'`: one failed Start-Process (a locked log file, say) would end
+    // the loop and leave the router or host unsupervised; the loop retries instead.
+    return [
         ...Object.entries(env).map(([k, v]) => `$env:${k} = ${ps(v)}`),
-        `$routerArgs = @(${opts.args.map((a) => ps(a)).join(", ")})`,
+        `$routerArgs = @(${opts.args.map(quoteArg).join(", ")})`,
         `$out = ${ps(path.join(logDir, "launcher.log"))}`,
         `$err = ${ps(path.join(logDir, "launcher.err.log"))}`,
-        `$quickFailures = 0`,
-        `while ($true) {`,
-        `  $startedAt = Get-Date`,
+        "$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");
+        "  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 })",
+        "}",
+    ].join("\r\n") + "\r\n";
+}
+function writeLauncher(opts) {
+    const launcher = path.join(opts.home, `${opts.name ?? "clauderipple-router"}.ps1`);
+    const logDir = path.join(opts.home, "logs");
+    fs.mkdirSync(logDir, { recursive: true });
+    fs.writeFileSync(launcher, renderLauncher(opts));
     return launcher;
 }
 /**
@@ -123,9 +128,9 @@ function writeLauncher(opts) {
  * 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() {
+export function existingTaskDefinition(name = taskName()) {
     const existing = run([
-        `$t = Get-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction SilentlyContinue`,
+        `$t = Get-ScheduledTask -TaskName ${ps(name)} -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`,
@@ -141,7 +146,8 @@ export function existingTaskDefinition() {
     }
 }
 export function installAgent(opts) {
-    const launcher = writeLauncher({ program: opts.program, args: opts.args ?? [], home: opts.home, ...(opts.env ? { env: opts.env } : {}) });
+    const name = opts.name ?? taskName();
+    const launcher = writeLauncher({ ...opts, args: opts.args ?? [] });
     const user = taskUser();
     const powershellArgs = `-NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -File "${launcher}"`;
     // PowerShell is started inside a headless console host. Started directly, it gets a console from
@@ -151,39 +157,41 @@ export function installAgent(opts) {
     // for `powershell.exe`, none for `conhost.exe --headless powershell.exe`, and both ran the script).
     const execute = "conhost.exe";
     const actionArgs = `--headless powershell.exe ${powershellArgs}`;
-    const existing = existingTaskDefinition();
+    const existing = existingTaskDefinition(name);
     // 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.
     if (taskDefinitionMatches(existing, { execute, arguments: actionArgs, userId: user }))
         return launcher;
-    const script = [
+    const script = renderTaskRegistration(name, user, execute, actionArgs);
+    const r = run(script);
+    if (!r.ok) {
+        // Retain the pre-headless task only when its entire definition matches.
+        if (taskDefinitionMatches(existing, { execute: "powershell.exe", arguments: powershellArgs, userId: user }))
+            return launcher;
+        throw new Error(`Register-ScheduledTask failed: ${r.out}`);
+    }
+    return launcher;
+}
+export function renderTaskRegistration(name, user, execute, actionArgs) {
+    return [
         `$ErrorActionPreference = 'Stop'`,
         `$a = New-ScheduledTaskAction -Execute ${ps(execute)} -Argument ${ps(actionArgs)}`,
         `$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`,
+        `Register-ScheduledTask -TaskName ${ps(name)} -Action $a -Trigger $t -Principal $p -Settings $s -Force | Out-Null`,
         `'ok'`,
     ].join("; ");
-    const r = run(script);
-    if (!r.ok) {
-        // The task from before #49 still starts and supervises the router, only with a window. On an
-        // install that cannot re-register it (E_ACCESSDENIED, above), keeping it beats failing the update.
-        if (taskDefinitionMatches(existing, { execute: "powershell.exe", arguments: powershellArgs, userId: user }))
-            return launcher;
-        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'`);
+export function removeAgent(name = taskName()) {
+    const r = run(`Unregister-ScheduledTask -TaskName ${ps(name)} -Confirm:$false -ErrorAction Stop; 'ok'`);
     return r.ok;
 }
-export function agentState() {
-    const r = run(`(Get-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction Stop).State`);
+export function agentState(name = taskName()) {
+    const r = run(`(Get-ScheduledTask -TaskName ${ps(name)} -ErrorAction Stop).State`);
     if (!r.ok)
         return "not-loaded";
     return /^Running/im.test(r.out) ? "running" : "loaded";
@@ -205,14 +213,14 @@ export function agentPid() {
     const n = Number(r.out.trim());
     return r.ok && Number.isFinite(n) && n > 0 ? n : null;
 }
-export function startAgent() {
-    if (agentPid() !== null)
+export function startAgent(name = taskName()) {
+    if (name === taskName() ? agentPid() !== null : agentState(name) === "running")
         return "already-running";
-    const r = run(`Start-ScheduledTask -TaskName ${ps(taskName())} -ErrorAction Stop; 'ok'`);
+    const r = run(`Start-ScheduledTask -TaskName ${ps(name)} -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`);
+export function stopAgent(name = taskName()) {
+    // Host callers first request authenticated graceful shutdown and wait for its clean exit.
+    run(`Stop-ScheduledTask -TaskName ${ps(name)} -ErrorAction SilentlyContinue`);
     return true;
 }

package/dist/cli/src/settings.js

@@ -36,7 +36,8 @@ export const MODEL_SLOT_ENV = {
     smallFast: "ANTHROPIC_SMALL_FAST_MODEL",
     subagent: "CLAUDE_CODE_SUBAGENT_MODEL",
 };
-function refuseForeignProxy(existing, proxyUrl, force) {
+/** Also applied to a remote host's settings.json (remote.ts): one rule for whose proxy wins. */
+export 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.`);
     }