Prefer loopback runtime API URL for local agents (#5102)

## Thinking Path

> - Paperclip is the open-source app that manages AI agents and their
work coordination
> - The server subsystem exposes a control-plane HTTP API that agents
read and write task state against at runtime
> - On local development machines, Paperclip binds to loopback
(`127.0.0.1:3100`) but also advertises LAN hostnames via
`allowedHostnames` for multi-device setups
> - Agents inherit their API URL from `PAPERCLIP_API_URL` /
`PAPERCLIP_RUNTIME_API_URL` env vars exported during server startup
> - `choosePrimaryRuntimeApiUrl` was selecting the first entry in
`allowedHostnames` (the LAN IP) before the loopback bind host, so agents
on the same machine tried to connect to an unreachable LAN address
(NEE-327)
> - This PR fixes the chooser to return the normalized loopback bind
host first, before considering LAN `allowedHostnames`
> - The benefit is that local agents reliably reach the control plane
regardless of `allowedHostnames` configuration

## What's going on

Local Paperclip agents were sometimes inheriting
`PAPERCLIP_API_URL=http://192.168.1.50:3100` even when the server was
bound to loopback, which made the control plane unreachable from this
workspace. This keeps the runtime API on the loopback bind host for
local startup while still preserving LAN candidates for other callers.

## Problem

`choosePrimaryRuntimeApiUrl` preferred the first allowed hostname over
the actual loopback bind host. In the failing setup from NEE-327, that
exported `http://192.168.1.50:3100` into agent env even though
`http://127.0.0.1:3100` was the reachable control-plane URL.

## Solution

The primary runtime URL chooser now returns the normalized loopback bind
host before considering `allowedHostnames`. I added a focused unit test
for the chooser and a startup regression that verifies
`PAPERCLIP_RUNTIME_API_URL` / `PAPERCLIP_API_URL` stay on `127.0.0.1`
while the candidate list still includes the LAN hostname.

## Testing

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/runtime-api.test.ts
src/__tests__/server-startup-feedback-export.test.ts`
- Result: `2` files passed, `13` tests passed
- Runtime check: `curl -sS http://127.0.0.1:3100/api/health` returned
`{"status":"ok",...}` during this heartbeat

## Notes

Already-running local Paperclip servers need a restart to export the
corrected `PAPERCLIP_API_URL` into new agent runs. Rollback is revert
`df8d7fcf`.

## Model Used

Claude Sonnet 4.6 (`claude-sonnet-4-6`), 1M context window, via the
Paperclip Founding Engineer agent harness. Capabilities used: extended
tool use, code editing, test execution, shell commands.

## 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 searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [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
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Neeraj Kumar Singh <b.nirajkumarsingh@hotmail.com>

server/src/__tests__/runtime-api.test.ts

@@ -17,6 +17,17 @@ describe("runtime API discovery", () => {
     ).toBe("https://paperclip.example.com");
   });
 
+  it("prefers the loopback bind host over allowed hostnames for the primary runtime URL", () => {
+    expect(
+      choosePrimaryRuntimeApiUrl({
+        authPublicBaseUrl: null,
+        allowedHostnames: ["192.168.1.50"],
+        bindHost: "127.0.0.1",
+        port: 3100,
+      }),
+    ).toBe("http://127.0.0.1:3100");
+  });
+
   it("builds ordered callback candidates from explicit, allowed, bind, and interface hosts", () => {
     expect(
       buildRuntimeApiCandidateUrls({

server/src/__tests__/server-startup-feedback-export.test.ts

@@ -347,6 +347,21 @@ describe("startServer PAPERCLIP_API_URL handling", () => {
     expect(process.env.PAPERCLIP_API_URL).toBe("http://127.0.0.1:3210");
   });
 
+  it("keeps loopback as the runtime API URL when allowed hostnames are present", async () => {
+    loadConfigMock.mockReturnValueOnce(buildTestConfig({
+      allowedHostnames: ["192.168.1.50"],
+    }));
+
+    const started = await startServer();
+
+    expect(started.apiUrl).toBe("http://127.0.0.1:3210");
+    expect(process.env.PAPERCLIP_RUNTIME_API_URL).toBe("http://127.0.0.1:3210");
+    expect(process.env.PAPERCLIP_API_URL).toBe("http://127.0.0.1:3210");
+    expect(JSON.parse(process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON ?? "[]")).toEqual(
+      expect.arrayContaining(["http://127.0.0.1:3210", "http://192.168.1.50:3210"]),
+    );
+  });
+
   it("rewrites explicit-port auth public URLs when detect-port selects a new port", async () => {
     loadConfigMock.mockReturnValueOnce(buildTestConfig({
       port: 3100,

server/src/runtime-api.ts

@@ -61,6 +61,11 @@ export function choosePrimaryRuntimeApiUrl(input: {
     }
   }
 
+  const bindHost = normalizeHost(input.bindHost);
+  if (bindHost && !isWildcardHost(bindHost) && isLoopbackHost(bindHost)) {
+    return formatOrigin("http:", bindHost, input.port);
+  }
+
   const allowedHostname = input.allowedHostnames
     .map((value) => value.trim())
     .find(Boolean);
@@ -68,7 +73,6 @@ export function choosePrimaryRuntimeApiUrl(input: {
     return formatOrigin("http:", allowedHostname, input.port);
   }
 
-  const bindHost = normalizeHost(input.bindHost);
   if (bindHost && !isWildcardHost(bindHost)) {
     return formatOrigin("http:", bindHost, input.port);
   }