clauderipple 0.9.5 → 0.11.0

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

@@ -31,6 +31,8 @@ function run(script) {
             env: windowsPowerShellEnv(),
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
+            // A hung PowerShell must not hang doctor/repair, which the menu-bar app waits on.
+            timeout: 60_000,
         }).toString();
         return { ok: true, out: out.trim() };
     }
@@ -94,27 +96,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 +130,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 +148,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 +159,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 +215,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.`);
     }
@@ -156,6 +157,30 @@ export function removeProxyEnv(opts) {
     write(file, next);
     return { changed: true, backup: b, notes, wroteSlots: [] };
 }
+/**
+ * Applies `mutate` to a copy of settings.json's env block and writes it back (with a backup) only
+ * when it reports a change. Every other key in the file is kept as it was; an emptied env block is
+ * dropped. For callers that own a precise set of keys, such as `direct on|off`.
+ */
+export function editSettingsEnv(mutate) {
+    const file = settingsPath();
+    const s = readSettings(file);
+    const env = { ...(s.env ?? {}) };
+    if (!mutate(env))
+        return { changed: false, backup: null, notes: [], wroteSlots: [] };
+    const b = backup(file);
+    const next = { ...s };
+    if (Object.keys(env).length === 0)
+        delete next.env;
+    else
+        next.env = env;
+    write(file, next);
+    return { changed: true, backup: b, notes: [], wroteSlots: [] };
+}
+/** settings.json's whole env block (empty when the file or the block is missing). */
+export function settingsEnv() {
+    return { ...(readSettings(settingsPath()).env ?? {}) };
+}
 export function currentProxyEnv() {
     const env = readSettings(settingsPath()).env ?? {};
     const out = {};

package/dist/cli/src/tray.js

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