Fix SSH callback URL selection for LAN and private networks (#4799)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - Agents can run on remote hosts via SSH environments
> - When a remote agent needs to call back to the Paperclip API, it
needs a reachable URL
> - But the runtime API URL candidate builder did not account for
private network topologies where the server is only reachable via LAN or
VPN addresses
> - Agents on SSH hosts were failing to connect because the callback URL
pointed to localhost or an unreachable address
> - This PR fixes callback URL selection to honor `PAPERCLIP_API_URL`,
prefer LAN-reachable candidates, filter unreachable link-local
addresses, and include interface hosts in onboarding invite URLs
> - The benefit is SSH-based agents can reliably reach the Paperclip API
on private networks without manual URL configuration

## What Changed

- `runtime-api.ts`: Added `PAPERCLIP_API_URL` as a first-priority
candidate in `buildRuntimeApiCandidateUrls`; extracted
`collectReachableInterfaceHosts` to enumerate non-loopback,
non-link-local network interface IPs with IPv4 preference
- `server/src/index.ts`: Export `PAPERCLIP_API_URL` from the server
environment so it is available to callback candidate resolution
- `server/src/routes/access.ts`: Include LAN interface hosts in
onboarding invite connection candidates
- `server/src/config.ts`: Attempted auto-allowing LAN interface hosts,
then reverted to the per-instance allowlist approach (both commits
included for history clarity)

## Verification

- `pnpm test` — all existing and new tests pass, including new tests for
LAN candidate ordering and link-local filtering
- `pnpm typecheck` — clean
- Manual: start a Paperclip server on a machine with a LAN IP, create an
SSH environment pointing to another host on the same LAN, verify the
agent's callback URL uses the LAN IP rather than localhost

## Risks

- Low-medium. The candidate list now includes more addresses (all
non-loopback LAN interfaces). These are candidates for the agent to try,
not an allowlist — the server's allowed hostnames still gate which
origins are accepted. Ordering change (LAN preferred over loopback)
could affect existing setups where localhost was intentionally
preferred.

## Model Used

Codex GPT 5.4 high via Paperclip.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

server/src/runtime-api.ts

@@ -14,6 +14,14 @@ function isWildcardHost(host: string): boolean {
   return normalized === "0.0.0.0" || normalized === "::";
 }
 
+function isLinkLocalHost(host: string): boolean {
+  const normalized = normalizeHost(host).toLowerCase();
+  if (normalized.startsWith("169.254.")) return true;
+  // IPv6 link-local block is fe80::/10 (fe80:: through febf::)
+  if (/^fe[89ab][0-9a-f]:/.test(normalized)) return true;
+  return false;
+}
+
 function formatOrigin(protocol: string, host: string, port: number): string {
   const normalizedHost = host.includes(":") && !host.startsWith("[") && !host.endsWith("]")
     ? `[${host}]`
@@ -68,7 +76,36 @@ export function choosePrimaryRuntimeApiUrl(input: {
   return formatOrigin("http:", "localhost", input.port);
 }
 
+export function collectReachableInterfaceHosts(input: {
+  networkInterfacesMap?: NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+} = {}): string[] {
+  const interfaces = input.networkInterfacesMap ?? os.networkInterfaces();
+  const rankedHosts: Array<{ host: string; rank: number; index: number }> = [];
+  const seen = new Set<string>();
+  let index = 0;
+
+  for (const entries of Object.values(interfaces)) {
+    for (const entry of entries ?? []) {
+      if (entry.internal) continue;
+      const host = normalizeHost(entry.address);
+      if (!host || isLoopbackHost(host) || isWildcardHost(host) || isLinkLocalHost(host)) continue;
+      if (seen.has(host)) continue;
+      seen.add(host);
+      rankedHosts.push({
+        host,
+        rank: entry.family === "IPv4" ? 0 : 1,
+        index: index++,
+      });
+    }
+  }
+
+  return rankedHosts
+    .sort((left, right) => left.rank - right.rank || left.index - right.index)
+    .map((entry) => entry.host);
+}
+
 export function buildRuntimeApiCandidateUrls(input: {
+  preferredApiUrl?: string | null;
   authPublicBaseUrl?: string | null;
   allowedHostnames: string[];
   bindHost: string;
@@ -88,6 +125,7 @@ export function buildRuntimeApiCandidateUrls(input: {
   })();
   const protocol = explicitOrigin ? new URL(explicitOrigin).protocol : "http:";
 
+  pushCandidate(candidates, seen, input.preferredApiUrl);
   pushCandidate(candidates, seen, explicitOrigin);
 
   for (const rawHost of input.allowedHostnames) {
@@ -108,14 +146,8 @@ export function buildRuntimeApiCandidateUrls(input: {
     }
   }
 
-  const interfaces = input.networkInterfacesMap ?? os.networkInterfaces();
-  for (const entries of Object.values(interfaces)) {
-    for (const entry of entries ?? []) {
-      if (entry.internal) continue;
-      const host = normalizeHost(entry.address);
-      if (!host || isLoopbackHost(host) || isWildcardHost(host)) continue;
-      pushCandidate(candidates, seen, formatOrigin(protocol, host, input.port));
-    }
+  for (const host of collectReachableInterfaceHosts({ networkInterfacesMap: input.networkInterfacesMap })) {
+    pushCandidate(candidates, seen, formatOrigin(protocol, host, input.port));
   }
 
   if (candidates.length === 0) {