rechrome 1.38.0 → 1.38.2

package/listeners.js

@@ -15,6 +15,7 @@ import { createHash, randomBytes } from "crypto";
 import { homedir } from "os";
 import { join } from "path";
 import { mkdir, readFile, rename, writeFile } from "fs/promises";
+var MAX_RETIRED_PORTS = 32;
 var LISTENERS_FILE = join(homedir(), ".rechrome", "listeners.json");
 var isLoopback = (host) => host === "::1" || /^127\./.test(host);
 var listenerAddress = (l) => `${l.host.includes(":") ? `[${l.host}]` : l.host}:${l.port}`;
@@ -73,6 +74,8 @@ function validateListeners(value) {
     addresses.add(address);
     keys.add(l.key);
   }
+  if (config.retiredPorts !== undefined && (!Array.isArray(config.retiredPorts) || config.retiredPorts.some((p) => !Number.isInteger(p) || p < 1 || p > 65535)))
+    throw new Error("listeners.json retiredPorts must be a list of ports");
   return config;
 }
 async function readListeners() {
@@ -86,8 +89,20 @@ async function readListeners() {
   }
   return validateListeners(JSON.parse(raw));
 }
+function retirePorts(previous, next) {
+  const inUse = new Set(next.listeners.map((l) => l.port));
+  const freed = (previous?.listeners ?? []).map((l) => l.port).filter((p) => !inUse.has(p));
+  const merged = [...previous?.retiredPorts ?? [], ...next.retiredPorts ?? [], ...freed].filter((p) => !inUse.has(p));
+  return [...new Set(merged.reverse())].reverse().slice(-MAX_RETIRED_PORTS);
+}
 async function writeListeners(config) {
   validateListeners(config);
+  const previous = await readListeners().catch(() => null);
+  const retired = retirePorts(previous, config);
+  if (retired.length)
+    config.retiredPorts = retired;
+  else
+    delete config.retiredPorts;
   await mkdir(join(homedir(), ".rechrome"), { recursive: true });
   const temp = `${LISTENERS_FILE}.${randomBytes(6).toString("hex")}.tmp`;
   await writeFile(temp, JSON.stringify(config, null, 2) + `
@@ -219,6 +234,7 @@ export {
   profileOutputPrefix,
   readListeners,
   resolveAllowedProfile,
+  retirePorts,
   rotateListenerKey,
   serviceUrl,
   setPublicUrl,

package/listeners.ts

@@ -7,7 +7,10 @@ import { mkdir, readFile, rename, writeFile } from "fs/promises";
 
 // publicUrl: where a reverse proxy (Tailscale Serve, Caddy, nginx, ...) exposes this listener.
 export type Listener = { name: string; host: string; port: number; key: string; profiles: string[] | "*"; prefix?: string; publicUrl?: string; uploads?: UploadPolicy };
-export type ListenerConfig = { version: 1; listeners: Listener[] };
+// retiredPorts: ports of removed listeners, newest last. New listeners skip them so a link
+// saved for a removed listener gets "connection refused", not some other listener's answer.
+export type ListenerConfig = { version: 1; listeners: Listener[]; retiredPorts?: number[] };
+const MAX_RETIRED_PORTS = 32;
 export const LISTENERS_FILE = join(homedir(), ".rechrome", "listeners.json");
 export const isLoopback = (host: string) => host === "::1" || /^127\./.test(host);
 export const listenerAddress = (l: Listener) => `${l.host.includes(":") ? `[${l.host}]` : l.host}:${l.port}`;
@@ -60,6 +63,8 @@ export function validateListeners(value: unknown): ListenerConfig {
     if (names.has(l.name) || addresses.has(address) || keys.has(l.key)) throw new Error("Listener names, addresses, and credentials must be unique");
     names.add(l.name); addresses.add(address); keys.add(l.key);
   }
+  if (config.retiredPorts !== undefined && (!Array.isArray(config.retiredPorts) || config.retiredPorts.some(p => !Number.isInteger(p) || p < 1 || p > 65535)))
+    throw new Error("listeners.json retiredPorts must be a list of ports");
   return config;
 }
 
@@ -70,8 +75,19 @@ export async function readListeners(): Promise<ListenerConfig | null> {
   return validateListeners(JSON.parse(raw));
 }
 
+/** `previous`'s retired ports plus the ports its listeners used that `next` no longer does. */
+export function retirePorts(previous: ListenerConfig | null, next: ListenerConfig): number[] {
+  const inUse = new Set(next.listeners.map(l => l.port));
+  const freed = (previous?.listeners ?? []).map(l => l.port).filter(p => !inUse.has(p));
+  const merged = [...(previous?.retiredPorts ?? []), ...(next.retiredPorts ?? []), ...freed].filter(p => !inUse.has(p));
+  return [...new Set(merged.reverse())].reverse().slice(-MAX_RETIRED_PORTS);
+}
+
 export async function writeListeners(config: ListenerConfig): Promise<void> {
   validateListeners(config);
+  const previous = await readListeners().catch(() => null);
+  const retired = retirePorts(previous, config);
+  if (retired.length) config.retiredPorts = retired; else delete config.retiredPorts;
   await mkdir(join(homedir(), ".rechrome"), { recursive: true });
   const temp = `${LISTENERS_FILE}.${randomBytes(6).toString("hex")}.tmp`;
   await writeFile(temp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rechrome",
-  "version": "1.38.0",
+  "version": "1.38.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/rechrome.git"

package/rechrome.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { prepareStdinUpload, type UploadPayload } from "./scoped-upload.js";
-import { readListeners, writeListeners, listenerAddress, isLoopback, normalizePrefix, serviceUrl, allowProfiles, denyProfiles, rotateListenerKey, setPublicUrl, canonicalProfileKeys, planProfileRemoval, type Listener } from "./listeners.js";
+import { readListeners, writeListeners as writeListenersFile, listenerAddress, isLoopback, normalizePrefix, serviceUrl, allowProfiles, denyProfiles, rotateListenerKey, setPublicUrl, canonicalProfileKeys, planProfileRemoval, type Listener, type ListenerConfig } from "./listeners.js";
 
 import { file } from "bun";
 import yargs from "yargs";
@@ -1493,13 +1493,69 @@ export function chooseShareListener(profile: string, listeners: Listener[]): str
   ].filter(Boolean).join("\n"), "none", scoped);
 }
 
-/** A loopback port no listener uses and nothing else is bound to, from the management port + 2. */
-function freeListenerPort(listeners: Listener[]): number {
-  const used = new Set(listeners.map(l => l.port));
-  for (let port = DEFAULT_PORT + 2; port < 65536; port++) {
-    if (used.has(port)) continue;
-    try { Bun.serve({ hostname: "127.0.0.1", port, fetch: () => new Response() }).stop(true); return port; } catch { /* taken */ }
-  }
+/**
+ * Why a saved link to one of this machine's listeners stopped working, with the command that
+ * replaces it; null when it still matches its listener or points at another machine.
+ * A removed listener's port goes to the next one created (`freeListenerPort`), so a stale
+ * link can reach a different listener: its path is not served there and its key is unknown.
+ */
+export function staleLinkHint(url: string, listeners: Listener[], source?: string): string | null {
+  let parsed: ReturnType<typeof parseUrl>;
+  try { parsed = parseUrl(url); } catch { return null; }
+  const loopback = (host: string) => isLoopback(host) || host === "localhost";
+  const urlHost = parsed.host.replace(/^\[|\]$/g, "");
+  // Direct: the link names a listener's own address. Proxied: it names a recorded public URL.
+  const at = listeners.find(l => l.port === parsed.port && (l.host === urlHost || loopback(l.host) && loopback(urlHost)));
+  const direct = !!at || loopback(urlHost);
+  const viaProxy = (l: Listener) => {
+    if (!l.publicUrl) return false;
+    const pub = parseUrl(l.publicUrl);
+    return pub.host === parsed.host && pub.port === parsed.port && pub.prefix === parsed.prefix;
+  };
+  const proxied = listeners.find(viaProxy);
+  const owner = listeners.find(l => l.key === parsed.key);
+  if (!direct && !proxied && !owner) return null; // another machine's daemon: only its owner knows
+  const profile = parsed.profileDirectory;
+  const allows = (l: Listener) => l.profiles === "*" || !profile || l.profiles.includes(profile);
+  // Through a proxy rech knows nothing about, only the key and the allowlist can be checked.
+  const reachesOwner = owner && (direct ? owner === at && normalizePrefix(owner.prefix) === parsed.prefix : !proxied || owner === proxied);
+  if (owner && reachesOwner && allows(owner)) return null;
+  let fix = profile ? `rech share ${JSON.stringify(profile)} --save` : "rech share --save";
+  if (profile) {
+    try {
+      const name = owner && owner.profiles !== "*" && allows(owner) ? owner.name : chooseShareListener(profile, listeners);
+      fix = `rech share ${JSON.stringify(profile)} --listener ${name}${direct ? " --local" : ""} --save`;
+    } catch { /* no single listener shares it: the default creates a fresh link */ }
+  }
+  const lines = [!owner
+    ? `this link's key matches no listener on this machine: its listener was removed or its key rotated.${at ? ` ${listenerAddress(at)} belongs to listener "${at.name}" (${normalizePrefix(at.prefix)}), which this link is not for.` : ""}`
+    : !reachesOwner
+      ? `this link's listener "${owner.name}" moved: it now serves ${owner.publicUrl && !direct ? owner.publicUrl : `${listenerAddress(owner)}${normalizePrefix(owner.prefix)}`}, not ${parsed.host}:${parsed.port}${parsed.prefix}.`
+      : `this link's listener "${owner.name}" no longer allows "${profile}" (it serves: ${(owner.profiles as string[]).join(", ")}).`];
+  if (source && source !== "environment") lines.push(`The stale RECHROME_URL is saved in ${source}.`);
+  lines.push(`Replace it with a current link:  ${fix}`);
+  return lines.join("\n  ");
+}
+
+/** staleLinkHint against this machine's listeners.json; null when it can't be read. */
+async function localStaleLinkHint(url: string): Promise<string | null> {
+  const config = await readListeners().catch(() => null);
+  return config ? staleLinkHint(url, config.listeners, url === process.env[ENV_KEY] ? rechromeUrlSource : undefined) : null;
+}
+
+const loopbackPortIsFree = (port: number) => {
+  try { Bun.serve({ hostname: "127.0.0.1", port, fetch: () => new Response() }).stop(true); return true; } catch { return false; }
+};
+
+/**
+ * A loopback port no listener uses and nothing else is bound to, from the management port + 2.
+ * A removed listener's port is skipped: reusing it would route that listener's saved links to
+ * this one, a confusing wrong answer instead of a plain "connection refused".
+ */
+export function freeListenerPort(config: Pick<ListenerConfig, "listeners" | "retiredPorts">, isFree = loopbackPortIsFree): number {
+  const used = new Set(config.listeners.map(l => l.port)), retired = new Set(config.retiredPorts ?? []);
+  for (let port = DEFAULT_PORT + 2; port < 65536; port++) if (!used.has(port) && !retired.has(port) && isFree(port)) return port;
+  for (const port of config.retiredPorts ?? []) if (!used.has(port) && isFree(port)) return port; // oldest first, as a last resort
   throw new Error("No free port for the share-all listener; pass one with rech listener add");
 }
 
@@ -1521,9 +1577,10 @@ function canonicalKeyFor(registry: Record<string, TokenEntry>, key: string): str
 }
 
 /**
- * `rech share a b c`: one link for exactly these profiles, on one listener. With --listener it
- * sets that listener's profiles to the list (e.g. one that already has a proxy route); otherwise
- * it reuses a listener with exactly this set, or creates one with its own key.
+ * `rech share a b c`: one link for these profiles, on one listener. With --listener it adds
+ * them to that listener (e.g. one that already has a proxy route) and never removes any:
+ * that is rech listener deny. Otherwise it reuses a listener with exactly this set, or
+ * creates one with its own key.
  */
 async function shareProfiles(selectors: string[], opts: { listener?: string; local?: boolean; save?: boolean }): Promise<void> {
   const registry = await readTokenRegistry(), cache = await readChromeProfileCache();
@@ -1536,11 +1593,11 @@ async function shareProfiles(selectors: string[], opts: { listener?: string; loc
   const config = await requireListeners();
   const same = config.listeners.find(l => l.profiles !== "*" && l.profiles.length === keys.length && keys.every(k => (l.profiles as string[]).includes(k)));
   const id = createHash("sha256").update([...keys].sort().join("\0")).digest("hex").slice(0, 6);
-  return shareSet(keys, { ...opts, listener: opts.listener ?? same?.name, defaultName: `share-${id}`, prefix: `/rechrome-${id}/`, again: `rech share ${selectors.map(s => JSON.stringify(s)).join(" ")}` });
+  return shareSet(keys, { ...opts, merge: !!opts.listener, listener: opts.listener ?? same?.name, defaultName: `share-${id}`, prefix: `/rechrome-${id}/`, again: `rech share ${selectors.map(s => JSON.stringify(s)).join(" ")}` });
 }
 
 /** Put exactly `snapshot` on one scoped listener (created if missing) and print its link. */
-async function shareSet(snapshot: string[], opts: { listener?: string; local?: boolean; save?: boolean; defaultName: string; prefix: string; again: string; host?: string; tailscaleServe?: boolean }): Promise<void> {
+async function shareSet(snapshot: string[], opts: { listener?: string; local?: boolean; save?: boolean; defaultName: string; prefix: string; again: string; host?: string; tailscaleServe?: boolean; merge?: boolean }): Promise<void> {
   const config = await requireListeners();
   const name = opts.listener ?? opts.defaultName;
   let listener = config.listeners.find(l => l.name === name);
@@ -1549,11 +1606,14 @@ async function shareSet(snapshot: string[], opts: { listener?: string; local?: b
   let changes = "";
   if (!listener) {
     if (opts.listener) throw new Error(`Unknown listener "${name}". See rech listener ls.`);
-    listener = { name, host: opts.host ?? "127.0.0.1", port: freeListenerPort(config.listeners), prefix: opts.prefix, key: randomBytes(24).toString("base64url"), profiles: snapshot };
+    listener = { name, host: opts.host ?? "127.0.0.1", port: freeListenerPort(config), prefix: opts.prefix, key: randomBytes(24).toString("base64url"), profiles: snapshot };
     config.listeners.push(listener);
     changes = `created listener "${name}" on ${listenerAddress(listener)}${listener.prefix}`;
   } else {
     const before = listener.profiles as string[];
+    // Merging (a listener named with --listener) only adds: profiles shared there for someone
+    // else stay. Removing one is explicit: rech listener deny.
+    if (opts.merge) snapshot = [...before, ...snapshot.filter(p => !before.includes(p))];
     const added = snapshot.filter(p => !before.includes(p)), removed = before.filter(p => !snapshot.includes(p));
     listener.profiles = snapshot;
     changes = added.length || removed.length ? [added.length && `added ${added.join(", ")}`, removed.length && `removed ${removed.join(", ")}`].filter(Boolean).join("; ") : "no changes";
@@ -1918,8 +1978,9 @@ async function callServe(
     process.exit(1);
   });
   if (res.status === 401) {
-    if (throwOnFailure) throw new Error("The daemon rejected its connection key. Run setup again to refresh it.");
-    console.error(`[rech] rech-client -> rech-server[ok]\n  -x: bearer key rejected (used: ${key.slice(0, 4)}...) -> playwright[unknown]`);
+    const stale = await localStaleLinkHint(url);
+    if (throwOnFailure) throw new Error(stale ? `The daemon rejected this link's key: ${stale}` : "The daemon rejected its connection key. Run setup again to refresh it.");
+    console.error(`[rech] rech-client -> rech-server[ok]\n  -x: bearer key rejected (used: ${key.slice(0, 4)}...) -> playwright[unknown]${stale ? `\n  ${stale}` : ""}`);
     process.exit(1);
   }
   const text = await res.text();
@@ -1930,6 +1991,8 @@ async function callServe(
     let detail = `HTTP ${res.status} from ${serviceUrl(url, "run")} is not a rechrome daemon response: ${text.slice(0, 200).trim()}`;
     if (res.status === 502 || res.status === 503 || res.status === 504)
       detail += `\n  The proxy is up but nothing answers behind it: this link's listener was likely removed or moved. Ask its owner for a fresh link (\`rech share\`), then \`rechrome connect <link>\`.`;
+    const stale = await localStaleLinkHint(url);
+    if (stale) detail += `\n  ${stale}`;
     if (throwOnFailure) throw new Error(detail);
     console.error(`[rech] rech-client -> ${serviceUrl(url, "run")}\n  -x: ${detail}`);
     process.exit(1);
@@ -3346,9 +3409,53 @@ async function writeEnvUrl(envPath: string, url: string): Promise<string> {
   const lines = (await file(envPath).text().catch(() => "")).split("\n").filter(l => l.trim() && !l.startsWith(`${ENV_KEY}=`));
   await writeFile(envPath, [...lines, envAssignment(ENV_KEY, url), ""].join("\n"), { mode: 0o600 });
   await chmod(envPath, 0o600);
+  await recordSavedLink(envPath).catch(() => {}); // only bookkeeping for later warnings
   return envPath;
 }
 
+/** Env files rech saved a RECHROME_URL into: paths only, never the URLs (they hold keys). */
+export const SAVED_LINKS_FILE = join(RECH_DIR, "saved-links.json");
+
+async function readSavedLinks(): Promise<string[]> {
+  const value = await file(SAVED_LINKS_FILE).json().catch(() => []);
+  return Array.isArray(value) ? value.filter((p): p is string => typeof p === "string") : [];
+}
+
+async function recordSavedLink(envPath: string): Promise<void> {
+  const path = resolve(envPath), known = await readSavedLinks();
+  if (known.includes(path)) return;
+  mkdirSync(dirname(SAVED_LINKS_FILE), { recursive: true });
+  await writeFile(SAVED_LINKS_FILE, JSON.stringify([...known, path], null, 2) + "\n", { mode: 0o600 });
+}
+
+/** The RECHROME_URL an env file sets, or null. */
+function savedUrlIn(envPath: string): string | null {
+  try { return parseBunEnvFile(readFileSync(envPath, "utf8"))[ENV_KEY] || null; } catch { return null; }
+}
+
+/**
+ * One warning per saved link that worked with `before`'s listeners and is stale with `after`'s:
+ * a listener change (rm, rotate-key, deny, setup moving a profile) that breaks a link rech
+ * saved says so, with the fix, instead of the link failing later in some other project.
+ * Links that were already stale stay quiet: this change didn't break them.
+ */
+export function savedLinksBrokenBy(before: Listener[], after: Listener[], saved: { path: string; url: string }[]): string[] {
+  return saved.flatMap(({ path, url }) => {
+    if (staleLinkHint(url, before)) return [];
+    const hint = staleLinkHint(url, after, path);
+    return hint ? [`[rech] warning: a saved link stops working: ${hint}`] : [];
+  });
+}
+
+/** writeListeners, then warn about saved links the write broke (see savedLinksBrokenBy). */
+async function writeListeners(config: ListenerConfig): Promise<void> {
+  const before = await readListeners().catch(() => null);
+  await writeListenersFile(config);
+  if (!before) return;
+  const saved = (await readSavedLinks()).flatMap(path => { const url = savedUrlIn(path); return url ? [{ path, url }] : []; });
+  for (const line of savedLinksBrokenBy(before.listeners, config.listeners, saved)) console.error(line);
+}
+
 /**
  * What would shadow the machine-wide RECHROME_URL from `cwd`: the shell's own RECHROME_URL, or the
  * nearest project env file that sets one (searched the way loadNearestEnv walks). Null when none does.
@@ -3841,7 +3948,7 @@ async function shareTransportListener(selector: string, profiles: string[], labe
   const address = chooseListenAddress(await detectListenChoices(), selector);
   const existing = config.listeners.find(l => l.host === address && l.profiles !== "*" && normalizePrefix(l.prefix) === "/");
   if (existing) return existing.name;
-  const listener: Listener = { name: `share-${label}`.slice(0, 40), host: address, port: freeListenerPort(config.listeners), key: randomBytes(24).toString("base64url"), profiles };
+  const listener: Listener = { name: `share-${label}`.slice(0, 40), host: address, port: freeListenerPort(config), key: randomBytes(24).toString("base64url"), profiles };
   config.listeners.push(listener);
   await writeListeners(config);
   if (!(await waitForListener(listener))) console.error(`[rech] warning: the daemon has not opened ${listenerAddress(listener)} yet; is it running? (rech status)`);
@@ -4135,7 +4242,8 @@ async function status(): Promise<void> {
   // Show the URL this client connects to; through a proxy, the daemon's bind is on another port.
   const details = [pingBody?.listener && `listener ${pingBody.listener}`, pingBody?.bind && `bind ${pingBody.bind}`].filter(Boolean).join(", ");
   // Any HTTP answer is not the daemon: a proxy's 404/502 means the link's listener is gone or moved.
-  const answered = pingResponse?.ok || pingResponse?.status === 401 || (pingResponse?.status === 403 && !!pingBody?.error);
+  // A 200 that isn't the /ping JSON is another listener's catch-all: its port was reused.
+  const answered = (pingResponse?.ok && !!pingBody) || pingResponse?.status === 401 || (pingResponse?.status === 403 && !!pingBody?.error);
   console.log(`serve:    ${!ping ? `not reachable at ${serviceUrl(url)}`
     : answered ? `running  ${serviceUrl(url)}${details ? `  (${details})` : ""}`
     : `✗ ${serviceUrl(url)} answers HTTP ${pingResponse?.status ?? ping.status}, not a rechrome daemon — this link's listener was likely removed or moved; ask its host for a fresh link (\`rech share <profile>\`), then \`rech connect '<url>'\``}`);
@@ -4147,6 +4255,8 @@ async function status(): Promise<void> {
   if (pingResponse?.status === 403 && pingBody?.error) console.log(`auth:     ✗ ${pingBody.error}`);
   if (pingResponse?.status === 401)
     console.log(`auth:     ✗ key rejected — ask the host for a fresh URL (\`rech share <profile>\`), then \`rech connect '<url>'\``);
+  const stale = ping && !pingBody ? await localStaleLinkHint(url) : null;
+  if (stale) console.log(`stale:    ✗ ${stale}`);
   // daemonManager().id — there is no PM_BIN constant. Referencing one threw a
   // ReferenceError that took down the whole of `rech status`, so the one command
   // that reports "the relay is wedged" died exactly when the relay was wedged,

package/rechrome.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { prepareStdinUpload, type UploadPayload } from "./scoped-upload.ts";
-import { readListeners, writeListeners, listenerAddress, isLoopback, normalizePrefix, serviceUrl, allowProfiles, denyProfiles, rotateListenerKey, setPublicUrl, canonicalProfileKeys, planProfileRemoval, type Listener } from "./listeners.ts";
+import { readListeners, writeListeners as writeListenersFile, listenerAddress, isLoopback, normalizePrefix, serviceUrl, allowProfiles, denyProfiles, rotateListenerKey, setPublicUrl, canonicalProfileKeys, planProfileRemoval, type Listener, type ListenerConfig } from "./listeners.ts";
 
 import { file } from "bun";
 import yargs from "yargs";
@@ -1493,13 +1493,69 @@ export function chooseShareListener(profile: string, listeners: Listener[]): str
   ].filter(Boolean).join("\n"), "none", scoped);
 }
 
-/** A loopback port no listener uses and nothing else is bound to, from the management port + 2. */
-function freeListenerPort(listeners: Listener[]): number {
-  const used = new Set(listeners.map(l => l.port));
-  for (let port = DEFAULT_PORT + 2; port < 65536; port++) {
-    if (used.has(port)) continue;
-    try { Bun.serve({ hostname: "127.0.0.1", port, fetch: () => new Response() }).stop(true); return port; } catch { /* taken */ }
-  }
+/**
+ * Why a saved link to one of this machine's listeners stopped working, with the command that
+ * replaces it; null when it still matches its listener or points at another machine.
+ * A removed listener's port goes to the next one created (`freeListenerPort`), so a stale
+ * link can reach a different listener: its path is not served there and its key is unknown.
+ */
+export function staleLinkHint(url: string, listeners: Listener[], source?: string): string | null {
+  let parsed: ReturnType<typeof parseUrl>;
+  try { parsed = parseUrl(url); } catch { return null; }
+  const loopback = (host: string) => isLoopback(host) || host === "localhost";
+  const urlHost = parsed.host.replace(/^\[|\]$/g, "");
+  // Direct: the link names a listener's own address. Proxied: it names a recorded public URL.
+  const at = listeners.find(l => l.port === parsed.port && (l.host === urlHost || loopback(l.host) && loopback(urlHost)));
+  const direct = !!at || loopback(urlHost);
+  const viaProxy = (l: Listener) => {
+    if (!l.publicUrl) return false;
+    const pub = parseUrl(l.publicUrl);
+    return pub.host === parsed.host && pub.port === parsed.port && pub.prefix === parsed.prefix;
+  };
+  const proxied = listeners.find(viaProxy);
+  const owner = listeners.find(l => l.key === parsed.key);
+  if (!direct && !proxied && !owner) return null; // another machine's daemon: only its owner knows
+  const profile = parsed.profileDirectory;
+  const allows = (l: Listener) => l.profiles === "*" || !profile || l.profiles.includes(profile);
+  // Through a proxy rech knows nothing about, only the key and the allowlist can be checked.
+  const reachesOwner = owner && (direct ? owner === at && normalizePrefix(owner.prefix) === parsed.prefix : !proxied || owner === proxied);
+  if (owner && reachesOwner && allows(owner)) return null;
+  let fix = profile ? `rech share ${JSON.stringify(profile)} --save` : "rech share --save";
+  if (profile) {
+    try {
+      const name = owner && owner.profiles !== "*" && allows(owner) ? owner.name : chooseShareListener(profile, listeners);
+      fix = `rech share ${JSON.stringify(profile)} --listener ${name}${direct ? " --local" : ""} --save`;
+    } catch { /* no single listener shares it: the default creates a fresh link */ }
+  }
+  const lines = [!owner
+    ? `this link's key matches no listener on this machine: its listener was removed or its key rotated.${at ? ` ${listenerAddress(at)} belongs to listener "${at.name}" (${normalizePrefix(at.prefix)}), which this link is not for.` : ""}`
+    : !reachesOwner
+      ? `this link's listener "${owner.name}" moved: it now serves ${owner.publicUrl && !direct ? owner.publicUrl : `${listenerAddress(owner)}${normalizePrefix(owner.prefix)}`}, not ${parsed.host}:${parsed.port}${parsed.prefix}.`
+      : `this link's listener "${owner.name}" no longer allows "${profile}" (it serves: ${(owner.profiles as string[]).join(", ")}).`];
+  if (source && source !== "environment") lines.push(`The stale RECHROME_URL is saved in ${source}.`);
+  lines.push(`Replace it with a current link:  ${fix}`);
+  return lines.join("\n  ");
+}
+
+/** staleLinkHint against this machine's listeners.json; null when it can't be read. */
+async function localStaleLinkHint(url: string): Promise<string | null> {
+  const config = await readListeners().catch(() => null);
+  return config ? staleLinkHint(url, config.listeners, url === process.env[ENV_KEY] ? rechromeUrlSource : undefined) : null;
+}
+
+const loopbackPortIsFree = (port: number) => {
+  try { Bun.serve({ hostname: "127.0.0.1", port, fetch: () => new Response() }).stop(true); return true; } catch { return false; }
+};
+
+/**
+ * A loopback port no listener uses and nothing else is bound to, from the management port + 2.
+ * A removed listener's port is skipped: reusing it would route that listener's saved links to
+ * this one, a confusing wrong answer instead of a plain "connection refused".
+ */
+export function freeListenerPort(config: Pick<ListenerConfig, "listeners" | "retiredPorts">, isFree = loopbackPortIsFree): number {
+  const used = new Set(config.listeners.map(l => l.port)), retired = new Set(config.retiredPorts ?? []);
+  for (let port = DEFAULT_PORT + 2; port < 65536; port++) if (!used.has(port) && !retired.has(port) && isFree(port)) return port;
+  for (const port of config.retiredPorts ?? []) if (!used.has(port) && isFree(port)) return port; // oldest first, as a last resort
   throw new Error("No free port for the share-all listener; pass one with rech listener add");
 }
 
@@ -1521,9 +1577,10 @@ function canonicalKeyFor(registry: Record<string, TokenEntry>, key: string): str
 }
 
 /**
- * `rech share a b c`: one link for exactly these profiles, on one listener. With --listener it
- * sets that listener's profiles to the list (e.g. one that already has a proxy route); otherwise
- * it reuses a listener with exactly this set, or creates one with its own key.
+ * `rech share a b c`: one link for these profiles, on one listener. With --listener it adds
+ * them to that listener (e.g. one that already has a proxy route) and never removes any:
+ * that is rech listener deny. Otherwise it reuses a listener with exactly this set, or
+ * creates one with its own key.
  */
 async function shareProfiles(selectors: string[], opts: { listener?: string; local?: boolean; save?: boolean }): Promise<void> {
   const registry = await readTokenRegistry(), cache = await readChromeProfileCache();
@@ -1536,11 +1593,11 @@ async function shareProfiles(selectors: string[], opts: { listener?: string; loc
   const config = await requireListeners();
   const same = config.listeners.find(l => l.profiles !== "*" && l.profiles.length === keys.length && keys.every(k => (l.profiles as string[]).includes(k)));
   const id = createHash("sha256").update([...keys].sort().join("\0")).digest("hex").slice(0, 6);
-  return shareSet(keys, { ...opts, listener: opts.listener ?? same?.name, defaultName: `share-${id}`, prefix: `/rechrome-${id}/`, again: `rech share ${selectors.map(s => JSON.stringify(s)).join(" ")}` });
+  return shareSet(keys, { ...opts, merge: !!opts.listener, listener: opts.listener ?? same?.name, defaultName: `share-${id}`, prefix: `/rechrome-${id}/`, again: `rech share ${selectors.map(s => JSON.stringify(s)).join(" ")}` });
 }
 
 /** Put exactly `snapshot` on one scoped listener (created if missing) and print its link. */
-async function shareSet(snapshot: string[], opts: { listener?: string; local?: boolean; save?: boolean; defaultName: string; prefix: string; again: string; host?: string; tailscaleServe?: boolean }): Promise<void> {
+async function shareSet(snapshot: string[], opts: { listener?: string; local?: boolean; save?: boolean; defaultName: string; prefix: string; again: string; host?: string; tailscaleServe?: boolean; merge?: boolean }): Promise<void> {
   const config = await requireListeners();
   const name = opts.listener ?? opts.defaultName;
   let listener = config.listeners.find(l => l.name === name);
@@ -1549,11 +1606,14 @@ async function shareSet(snapshot: string[], opts: { listener?: string; local?: b
   let changes = "";
   if (!listener) {
     if (opts.listener) throw new Error(`Unknown listener "${name}". See rech listener ls.`);
-    listener = { name, host: opts.host ?? "127.0.0.1", port: freeListenerPort(config.listeners), prefix: opts.prefix, key: randomBytes(24).toString("base64url"), profiles: snapshot };
+    listener = { name, host: opts.host ?? "127.0.0.1", port: freeListenerPort(config), prefix: opts.prefix, key: randomBytes(24).toString("base64url"), profiles: snapshot };
     config.listeners.push(listener);
     changes = `created listener "${name}" on ${listenerAddress(listener)}${listener.prefix}`;
   } else {
     const before = listener.profiles as string[];
+    // Merging (a listener named with --listener) only adds: profiles shared there for someone
+    // else stay. Removing one is explicit: rech listener deny.
+    if (opts.merge) snapshot = [...before, ...snapshot.filter(p => !before.includes(p))];
     const added = snapshot.filter(p => !before.includes(p)), removed = before.filter(p => !snapshot.includes(p));
     listener.profiles = snapshot;
     changes = added.length || removed.length ? [added.length && `added ${added.join(", ")}`, removed.length && `removed ${removed.join(", ")}`].filter(Boolean).join("; ") : "no changes";
@@ -1918,8 +1978,9 @@ async function callServe(
     process.exit(1);
   });
   if (res.status === 401) {
-    if (throwOnFailure) throw new Error("The daemon rejected its connection key. Run setup again to refresh it.");
-    console.error(`[rech] rech-client -> rech-server[ok]\n  -x: bearer key rejected (used: ${key.slice(0, 4)}...) -> playwright[unknown]`);
+    const stale = await localStaleLinkHint(url);
+    if (throwOnFailure) throw new Error(stale ? `The daemon rejected this link's key: ${stale}` : "The daemon rejected its connection key. Run setup again to refresh it.");
+    console.error(`[rech] rech-client -> rech-server[ok]\n  -x: bearer key rejected (used: ${key.slice(0, 4)}...) -> playwright[unknown]${stale ? `\n  ${stale}` : ""}`);
     process.exit(1);
   }
   const text = await res.text();
@@ -1930,6 +1991,8 @@ async function callServe(
     let detail = `HTTP ${res.status} from ${serviceUrl(url, "run")} is not a rechrome daemon response: ${text.slice(0, 200).trim()}`;
     if (res.status === 502 || res.status === 503 || res.status === 504)
       detail += `\n  The proxy is up but nothing answers behind it: this link's listener was likely removed or moved. Ask its owner for a fresh link (\`rech share\`), then \`rechrome connect <link>\`.`;
+    const stale = await localStaleLinkHint(url);
+    if (stale) detail += `\n  ${stale}`;
     if (throwOnFailure) throw new Error(detail);
     console.error(`[rech] rech-client -> ${serviceUrl(url, "run")}\n  -x: ${detail}`);
     process.exit(1);
@@ -3346,9 +3409,53 @@ async function writeEnvUrl(envPath: string, url: string): Promise<string> {
   const lines = (await file(envPath).text().catch(() => "")).split("\n").filter(l => l.trim() && !l.startsWith(`${ENV_KEY}=`));
   await writeFile(envPath, [...lines, envAssignment(ENV_KEY, url), ""].join("\n"), { mode: 0o600 });
   await chmod(envPath, 0o600);
+  await recordSavedLink(envPath).catch(() => {}); // only bookkeeping for later warnings
   return envPath;
 }
 
+/** Env files rech saved a RECHROME_URL into: paths only, never the URLs (they hold keys). */
+export const SAVED_LINKS_FILE = join(RECH_DIR, "saved-links.json");
+
+async function readSavedLinks(): Promise<string[]> {
+  const value = await file(SAVED_LINKS_FILE).json().catch(() => []);
+  return Array.isArray(value) ? value.filter((p): p is string => typeof p === "string") : [];
+}
+
+async function recordSavedLink(envPath: string): Promise<void> {
+  const path = resolve(envPath), known = await readSavedLinks();
+  if (known.includes(path)) return;
+  mkdirSync(dirname(SAVED_LINKS_FILE), { recursive: true });
+  await writeFile(SAVED_LINKS_FILE, JSON.stringify([...known, path], null, 2) + "\n", { mode: 0o600 });
+}
+
+/** The RECHROME_URL an env file sets, or null. */
+function savedUrlIn(envPath: string): string | null {
+  try { return parseBunEnvFile(readFileSync(envPath, "utf8"))[ENV_KEY] || null; } catch { return null; }
+}
+
+/**
+ * One warning per saved link that worked with `before`'s listeners and is stale with `after`'s:
+ * a listener change (rm, rotate-key, deny, setup moving a profile) that breaks a link rech
+ * saved says so, with the fix, instead of the link failing later in some other project.
+ * Links that were already stale stay quiet: this change didn't break them.
+ */
+export function savedLinksBrokenBy(before: Listener[], after: Listener[], saved: { path: string; url: string }[]): string[] {
+  return saved.flatMap(({ path, url }) => {
+    if (staleLinkHint(url, before)) return [];
+    const hint = staleLinkHint(url, after, path);
+    return hint ? [`[rech] warning: a saved link stops working: ${hint}`] : [];
+  });
+}
+
+/** writeListeners, then warn about saved links the write broke (see savedLinksBrokenBy). */
+async function writeListeners(config: ListenerConfig): Promise<void> {
+  const before = await readListeners().catch(() => null);
+  await writeListenersFile(config);
+  if (!before) return;
+  const saved = (await readSavedLinks()).flatMap(path => { const url = savedUrlIn(path); return url ? [{ path, url }] : []; });
+  for (const line of savedLinksBrokenBy(before.listeners, config.listeners, saved)) console.error(line);
+}
+
 /**
  * What would shadow the machine-wide RECHROME_URL from `cwd`: the shell's own RECHROME_URL, or the
  * nearest project env file that sets one (searched the way loadNearestEnv walks). Null when none does.
@@ -3841,7 +3948,7 @@ async function shareTransportListener(selector: string, profiles: string[], labe
   const address = chooseListenAddress(await detectListenChoices(), selector);
   const existing = config.listeners.find(l => l.host === address && l.profiles !== "*" && normalizePrefix(l.prefix) === "/");
   if (existing) return existing.name;
-  const listener: Listener = { name: `share-${label}`.slice(0, 40), host: address, port: freeListenerPort(config.listeners), key: randomBytes(24).toString("base64url"), profiles };
+  const listener: Listener = { name: `share-${label}`.slice(0, 40), host: address, port: freeListenerPort(config), key: randomBytes(24).toString("base64url"), profiles };
   config.listeners.push(listener);
   await writeListeners(config);
   if (!(await waitForListener(listener))) console.error(`[rech] warning: the daemon has not opened ${listenerAddress(listener)} yet; is it running? (rech status)`);
@@ -4135,7 +4242,8 @@ async function status(): Promise<void> {
   // Show the URL this client connects to; through a proxy, the daemon's bind is on another port.
   const details = [pingBody?.listener && `listener ${pingBody.listener}`, pingBody?.bind && `bind ${pingBody.bind}`].filter(Boolean).join(", ");
   // Any HTTP answer is not the daemon: a proxy's 404/502 means the link's listener is gone or moved.
-  const answered = pingResponse?.ok || pingResponse?.status === 401 || (pingResponse?.status === 403 && !!pingBody?.error);
+  // A 200 that isn't the /ping JSON is another listener's catch-all: its port was reused.
+  const answered = (pingResponse?.ok && !!pingBody) || pingResponse?.status === 401 || (pingResponse?.status === 403 && !!pingBody?.error);
   console.log(`serve:    ${!ping ? `not reachable at ${serviceUrl(url)}`
     : answered ? `running  ${serviceUrl(url)}${details ? `  (${details})` : ""}`
     : `✗ ${serviceUrl(url)} answers HTTP ${pingResponse?.status ?? ping.status}, not a rechrome daemon — this link's listener was likely removed or moved; ask its host for a fresh link (\`rech share <profile>\`), then \`rech connect '<url>'\``}`);
@@ -4147,6 +4255,8 @@ async function status(): Promise<void> {
   if (pingResponse?.status === 403 && pingBody?.error) console.log(`auth:     ✗ ${pingBody.error}`);
   if (pingResponse?.status === 401)
     console.log(`auth:     ✗ key rejected — ask the host for a fresh URL (\`rech share <profile>\`), then \`rech connect '<url>'\``);
+  const stale = ping && !pingBody ? await localStaleLinkHint(url) : null;
+  if (stale) console.log(`stale:    ✗ ${stale}`);
   // daemonManager().id — there is no PM_BIN constant. Referencing one threw a
   // ReferenceError that took down the whole of `rech status`, so the one command
   // that reports "the relay is wedged" died exactly when the relay was wedged,

package/serve.js

@@ -800,7 +800,9 @@ export async function serve() {
       // #fragment, which browsers never send, so the page is static and the key never reaches here.
       if (reqUrl.pathname === "/" && req.method === "GET" && (req.headers.get("accept") ?? "").includes("text/html"))
         return new Response(landingPage(), { headers: LANDING_HEADERS });
-      if (reqUrl.pathname !== "/run") return new Response("rech server\n");
+      // Unknown paths are a 404, not the banner: a stale link (its listener removed, the port
+      // reused by another with a different prefix) must fail loudly, not look like a live daemon.
+      if (reqUrl.pathname !== "/run") return reqUrl.pathname === "/" ? new Response("rech server\n") : new Response("rech server: nothing at this path\n", { status: 404 });
       const denied = authCheck(req, key);
       if (denied) return denied;
       markActivity(); // a real command: this serve is not idle

package/serve.ts

@@ -800,7 +800,9 @@ export async function serve() {
       // #fragment, which browsers never send, so the page is static and the key never reaches here.
       if (reqUrl.pathname === "/" && req.method === "GET" && (req.headers.get("accept") ?? "").includes("text/html"))
         return new Response(landingPage(), { headers: LANDING_HEADERS });
-      if (reqUrl.pathname !== "/run") return new Response("rech server\n");
+      // Unknown paths are a 404, not the banner: a stale link (its listener removed, the port
+      // reused by another with a different prefix) must fail loudly, not look like a live daemon.
+      if (reqUrl.pathname !== "/run") return reqUrl.pathname === "/" ? new Response("rech server\n") : new Response("rech server: nothing at this path\n", { status: 404 });
       const denied = authCheck(req, key);
       if (denied) return denied;
       markActivity(); // a real command: this serve is not idle