Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
test(open-knowledge): loopback bind-discipline scans, complementing #1812 (#1784)
Nick Gomez97b72b376dac
diff --git a/packages/app/tests/integration/advisory-warnings.test.ts b/packages/app/tests/integration/advisory-warnings.test.tsindex b1c76ef9c..40d5a028c 100644--- a/packages/app/tests/integration/advisory-warnings.test.ts+++ b/packages/app/tests/integration/advisory-warnings.test.ts@@ -24,7 +24,7 @@ async function writeMd(docName: string,position: 'append' | 'prepend' | 'replace' = 'replace',): Promise<{ status: number; body: WriteResponse }> {- const res = await fetch(`http://localhost:${server.port}/api/agent-write-md`, {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ markdown, position, docName }),@@ -37,7 +37,7 @@ async function patchDoc(find: string,replace: string,): Promise<{ status: number; body: WriteResponse }> {- const res = await fetch(`http://localhost:${server.port}/api/agent-patch`, {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-patch`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ docName, find, replace }),@@ -116,7 +116,7 @@ describe('advisory warnings on POST /api/frontmatter-patch', () => {'---\ntitle: v1\n---\n\n# Doc\n\nbody-v2-native\n','utf-8',);- const res = await fetch(`http://localhost:${server.port}/api/frontmatter-patch`, {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/frontmatter-patch`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ docName, patch: { status: 'draft' } }),diff --git a/packages/app/tests/integration/idle-shutdown-multi-client.test.ts b/packages/app/tests/integration/idle-shutdown-multi-client.test.tsindex 06946c963..a552641a6 100644--- a/packages/app/tests/integration/idle-shutdown-multi-client.test.ts+++ b/packages/app/tests/integration/idle-shutdown-multi-client.test.ts@@ -29,6 +29,7 @@ beforeAll(async () => {writeFileSync(join(okDir, 'config.yml'), '', 'utf-8');writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');booted = await bootServer({+ host: '127.0.0.1',config: ConfigSchema.parse({}),contentDir,port: 0,diff --git a/packages/app/tests/integration/loopback-bind-discipline.test.ts b/packages/app/tests/integration/loopback-bind-discipline.test.tsnew file mode 100644index 000000000..fd55a9ce1--- /dev/null+++ b/packages/app/tests/integration/loopback-bind-discipline.test.ts@@ -0,0 +1,176 @@+import { describe, expect, test } from 'bun:test';+import { readdirSync, readFileSync } from 'node:fs';+import { basename, dirname, join, relative } from 'node:path';+import { fileURLToPath } from 'node:url';++const __dirname = dirname(fileURLToPath(import.meta.url));+const PACKAGE_ROOT = join(__dirname, '..', '..');+const SCAN_ROOTS = [__dirname, join(PACKAGE_ROOT, 'tests', 'stress')];++const SELF_BASENAME = basename(fileURLToPath(import.meta.url));++interface FileLines {+ path: string;+ lines: string[];+}++function listScannedFiles(): FileLines[] {+ const out: FileLines[] = [];+ function walk(dir: string) {+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ const abs = join(dir, entry.name);+ if (entry.isDirectory()) {+ walk(abs);+ continue;+ }+ if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;+ if (entry.name === SELF_BASENAME) continue;+ out.push({+ path: relative(PACKAGE_ROOT, abs),+ lines: readFileSync(abs, 'utf-8').split('\n'),+ });+ }+ }+ for (const root of SCAN_ROOTS) walk(root);+ return out;+}++function isCommentOnlyLine(line: string): boolean {+ const trimmed = line.trim();+ return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');+}++const LOOPBACK_HOST_LITERAL = /['"](?:127\.0\.0\.1|::1)['"]/;++export function findNonLoopbackListenCalls(lines: string[]): Array<{ line: number; text: string }> {+ const violations: Array<{ line: number; text: string }> = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i] ?? '';+ if (isCommentOnlyLine(line)) continue;+ const idx = line.indexOf('.listen(');+ if (idx === -1) continue;+ let window = line.slice(idx);+ for (let j = i + 1; j <= i + 3 && !window.includes(')') && j < lines.length; j++) {+ window += `\n${lines[j] ?? ''}`;+ }+ const paren = window.indexOf(')');+ if (paren !== -1) window = window.slice(0, paren + 1);+ if (!LOOPBACK_HOST_LITERAL.test(window)) {+ violations.push({ line: i + 1, text: line.trim() });+ }+ }+ return violations;+}++const AMBIGUOUS_LOCALHOST_DIAL = /\b(?:https?|wss?):\/\/localhost:\$\{/;++export function findAmbiguousLocalhostDials(+ lines: string[],+): Array<{ line: number; text: string }> {+ const violations: Array<{ line: number; text: string }> = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i] ?? '';+ if (isCommentOnlyLine(line)) continue;+ if (AMBIGUOUS_LOCALHOST_DIAL.test(line)) {+ violations.push({ line: i + 1, text: line.trim() });+ }+ }+ return violations;+}++describe('loopback bind discipline (app test sources)', () => {+ const files = listScannedFiles();++ test('there are test files to scan (sanity)', () => {+ expect(files.length).toBeGreaterThan(0);+ expect(files.some((f) => f.path.endsWith('integration/test-harness.ts'))).toBe(true);+ expect(files.some((f) => f.path.endsWith('_helpers/server-process.ts'))).toBe(true);+ expect(files.some((f) => f.path.endsWith('.e2e.ts'))).toBe(true);+ });++ test('every .listen( call binds an explicit loopback host literal', () => {+ const violations: string[] = [];+ for (const file of files) {+ for (const v of findNonLoopbackListenCalls(file.lines)) {+ violations.push(` ${file.path}:${v.line} ${v.text}`);+ }+ }+ if (violations.length > 0) {+ throw new Error(+ `Hostless rig bind found — a bare listen(0) binds the IPv6 wildcard '::', whose loopback-specific ` ++ `port slots stay silently bindable by foreign processes; their listeners then intercept this rig's ` ++ `localhost dials (the rotating integration-suite flake). Bind a loopback-specific host ` ++ `(e.g. listen(0, '127.0.0.1', cb)) and dial the literal from server.address():\n${violations.join('\n')}`,+ );+ }+ });++ test('no interpolated-port localhost dial URLs', () => {+ const violations: string[] = [];+ for (const file of files) {+ for (const v of findAmbiguousLocalhostDials(file.lines)) {+ violations.push(` ${file.path}:${v.line} ${v.text}`);+ }+ }+ if (violations.length > 0) {+ throw new Error(+ `Ambiguous-name rig dial found — 'localhost' resolves '::1'-first, exactly the loopback-specific slot ` ++ `a foreign process can hold while the rig sits on a wildcard (or single-family) bind. Dial the ` ++ `literal address the rig actually bound (a harness-advertised base URL, or ` ++ `http://127.0.0.1:\${port}):\n${violations.join('\n')}`,+ );+ }+ });++ test('listen predicate fires on planted violations and not on adjacent negatives', () => {+ expect(findNonLoopbackListenCalls([' s.listen(0, () => {']).length).toBe(1);+ expect(+ findNonLoopbackListenCalls([' httpServer.listen(port, () => resolve());']).length,+ ).toBe(1);++ expect(findNonLoopbackListenCalls([" server.listen(0, '127.0.0.1', resolve);"]).length).toBe(+ 0,+ );+ expect(findNonLoopbackListenCalls([" s.listen(port, '::1', cb);"]).length).toBe(0);++ expect(+ findNonLoopbackListenCalls([' server.listen(', ' 0,', " '127.0.0.1',", ' cb)'])+ .length,+ ).toBe(0);++ expect(findNonLoopbackListenCalls([' // before httpServer.listen() resolves']).length).toBe(0);+ expect(+ findNonLoopbackListenCalls([' * boot scan runs BEFORE httpServer.listen().']).length,+ ).toBe(0);++ expect(findNonLoopbackListenCalls([' s.listen(port, host, cb);']).length).toBe(1);++ expect(findNonLoopbackListenCalls([" s.listen(0, '0.0.0.0', cb);"]).length).toBe(1);+ });++ test('dial predicate fires on planted violations and not on adjacent negatives', () => {+ expect(+ findAmbiguousLocalhostDials([+ ` const res = await fetch(\`http://localhost:\${server.port}/api/documents\`);`,+ ]).length,+ ).toBe(1);+ expect(+ findAmbiguousLocalhostDials([` url: \`ws://localhost:\${port}/collab\`,`]).length,+ ).toBe(1);++ expect(+ findAmbiguousLocalhostDials([` const res = await fetch(\`http://127.0.0.1:\${port}/x\`);`])+ .length,+ ).toBe(0);++ expect(+ findAmbiguousLocalhostDials([" expect(url).toBe('ws://localhost:7777/collab');"]).length,+ ).toBe(0);++ expect(findAmbiguousLocalhostDials([` // dials http://localhost:\${port} today`]).length).toBe(+ 0,+ );++ expect(findAmbiguousLocalhostDials([" host: 'localhost:5173',"]).length).toBe(0);+ });+});diff --git a/packages/app/tests/integration/loopback-exclusivity.test.ts b/packages/app/tests/integration/loopback-exclusivity.test.tsnew file mode 100644index 000000000..1ad9f7a80--- /dev/null+++ b/packages/app/tests/integration/loopback-exclusivity.test.ts@@ -0,0 +1,97 @@+import { afterEach, describe, expect, test } from 'bun:test';+import { createServer } from 'node:http';++import { createTestServer } from './test-harness';++interface ForeignMarker {+ host: string;+ close: () => Promise<void>;+}++function tryBindForeignMarker(+ host: '127.0.0.1' | '::1',+ port: number,+ markerToken: string,+): Promise<ForeignMarker | 'rig-owned' | 'family-unavailable'> {+ return new Promise((resolve, reject) => {+ const s = createServer((_req, res) => {+ res.writeHead(200, {+ 'content-type': 'application/json',+ 'x-foreign-marker': markerToken,+ });+ res.end(JSON.stringify({ foreignMarker: markerToken, answeredOn: host }));+ });+ s.on('error', (err: NodeJS.ErrnoException) => {+ if (err.code === 'EADDRINUSE') resolve('rig-owned');+ else if (err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')+ resolve('family-unavailable');+ else reject(err);+ });+ s.listen(port, host === '::1' ? '::1' : '127.0.0.1', () => {+ resolve({+ host,+ close: () => new Promise<void>((r) => s.close(() => r())),+ });+ });+ });+}++function dialedLoopbackAddresses(baseUrl: string): Array<'127.0.0.1' | '::1'> {+ const hostname = new URL(baseUrl).hostname;+ if (hostname === 'localhost') return ['127.0.0.1', '::1'];+ if (hostname === '127.0.0.1') return ['127.0.0.1'];+ if (hostname === '::1' || hostname === '[::1]') return ['::1'];+ throw new Error(`harness advertises a non-loopback dial host: ${hostname}`);+}++describe('test-harness loopback exclusivity', () => {+ const cleanups: Array<() => Promise<void>> = [];+ afterEach(async () => {+ const errors: unknown[] = [];+ while (cleanups.length > 0) {+ const fn = cleanups.pop();+ if (!fn) continue;+ try {+ await fn();+ } catch (err) {+ errors.push(err);+ }+ }+ if (errors.length > 0) throw new AggregateError(errors, 'loopback-exclusivity cleanup failed');+ });++ test('consumer dial reaches the harness server even when a foreign loopback-specific listener squats its port', async () => {+ const server = await createTestServer();+ cleanups.push(server.cleanup);++ const markerToken = `foreign-${crypto.randomUUID()}`;+ for (const host of ['127.0.0.1', '::1'] as const) {+ const marker = await tryBindForeignMarker(host, server.port, markerToken);+ if (typeof marker === 'object') cleanups.push(marker.close);+ }++ const res = await fetch(`${server.baseUrl}/api/documents`);+ const body = (await res.json()) as { documents?: unknown };++ expect(res.headers.get('x-foreign-marker')).toBeNull();+ expect(res.status).toBe(200);+ expect(Array.isArray(body.documents)).toBe(true);+ });++ test('harness server exclusively owns every loopback address its consumer dial URL can resolve to', async () => {+ const server = await createTestServer();+ cleanups.push(server.cleanup);++ const squattable: string[] = [];+ for (const host of dialedLoopbackAddresses(server.baseUrl)) {+ const marker = await tryBindForeignMarker(host, server.port, 'exclusivity-probe');+ if (marker === 'family-unavailable') continue;+ if (typeof marker === 'object') {+ squattable.push(host);+ cleanups.push(marker.close);+ }+ }++ expect(squattable).toEqual([]);+ });+});diff --git a/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts b/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.tsindex 2a9baaace..b94e87edf 100644--- a/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts+++ b/packages/app/tests/integration/stale-idb-lineage-record-absent-doors.test.ts@@ -128,7 +128,7 @@ async function stageStaleRowsAndReseed(opts: {storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;}): Promise<void> {const { server, docName, filePath, storage } = opts;- const poolA = new ProviderPool(3, `ws://localhost:${server.port}/collab`, { storage });+ const poolA = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, { storage });const serverInstanceId = await seedPoolServerInstanceId(server, poolA);poolA.open(docName);poolA.setActive(docName);@@ -193,7 +193,7 @@ describe('client-persisted state meets a re-seeded doc lineage (boot-window fresexpect(envelopeRaw).not.toBeNull();expect(envelopeRaw as string).toContain(docName);- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {storage: sharedStorage,});cleanups.push(() => poolB.dispose());@@ -233,7 +233,7 @@ describe('client-persisted state meets a re-seeded doc lineage (record-absent prawait stageStaleRowsAndReseed({ server, docName, filePath, storage: storageA });const { stub: emptyStorage } = makeStubStorage();- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {storage: emptyStorage,});cleanups.push(() => poolB.dispose());@@ -269,7 +269,7 @@ describe('refusing dead-lineage state is observable (boot-window fresh-pool doorconst capture = captureLineageMismatchWarns();cleanups.push(capture.restore);- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {storage: sharedStorage,});cleanups.push(() => poolB.dispose());@@ -310,7 +310,7 @@ describe('refusing dead-lineage state is observable (record-absent profile door)cleanups.push(capture.restore);const { stub: emptyStorage } = makeStubStorage();- const poolB = new ProviderPool(3, `ws://localhost:${server.port}/collab`, {+ const poolB = new ProviderPool(3, `ws://127.0.0.1:${server.port}/collab`, {storage: emptyStorage,});cleanups.push(() => poolB.dispose());diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.tsindex 5457ff009..6467b225b 100644--- a/packages/app/tests/integration/test-harness.ts+++ b/packages/app/tests/integration/test-harness.ts@@ -63,6 +63,8 @@ async function getFreePort(): Promise<number> {export interface TestServer {port: number;+ baseUrl: string;+ wsUrl: string;contentDir: string;instance: ServerInstance;cleanup: () => Promise<void>;@@ -157,12 +159,22 @@ export async function createTestServer(options: CreateTestServerOptions = {}): PkeepaliveGraceMs: options.keepaliveGraceMs,});- await new Promise<void>((resolve) => {- httpServer.listen(port, '127.0.0.1', () => resolve());+ await new Promise<void>((resolve, reject) => {+ const onErr = (err: Error): void => {+ httpServer.off('error', onErr);+ reject(err);+ };+ httpServer.once('error', onErr);+ httpServer.listen(port, '127.0.0.1', () => {+ httpServer.off('error', onErr);+ resolve();+ });});return {port,+ baseUrl: `http://127.0.0.1:${port}`,+ wsUrl: `ws://127.0.0.1:${port}`,contentDir,instance: srv,cleanup: async () => {@@ -890,7 +902,7 @@ export async function waitForPortFree(port: number, timeoutMs = 2500): Promise<vlastErr = err;resolve(false);});- probe.listen(port, () => {+ probe.listen(port, '127.0.0.1', () => {probe.close(() => resolve(true));});});@@ -964,7 +976,7 @@ export async function createRestartableServer(reject(err);};httpServer.once('error', onErr);- httpServer.listen(port, () => {+ httpServer.listen(port, '127.0.0.1', () => {httpServer.off('error', onErr);resolve();});diff --git a/packages/app/tests/integration/worktree-boot.test.ts b/packages/app/tests/integration/worktree-boot.test.tsindex d679a2079..f349be6e5 100644--- a/packages/app/tests/integration/worktree-boot.test.ts+++ b/packages/app/tests/integration/worktree-boot.test.ts@@ -28,6 +28,7 @@ describe('bootServer in a linked git worktree (FR2)', () => {expect(existsSync(expectedShadowHead)).toBe(false);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,@@ -53,6 +54,7 @@ describe('bootServer pre-listen check in a linked worktree (FR3)', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,@@ -79,6 +81,7 @@ describe('bootServer pre-listen check in a linked worktree (FR3)', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,@@ -113,6 +116,7 @@ describe('bootServer pre-listen check in a linked worktree (FR3)', () => {let booted: Awaited<ReturnType<typeof bootServer>> | null = null;try {booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,@@ -159,6 +163,7 @@ describe('bootServer ok.boot span attributes against a real linked worktree', ()handle = createLinkedWorktree({ seedOkScaffold: true });const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,@@ -215,6 +220,7 @@ describe('bootServer pre-listen check on main worktree (FR3)', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,port: 0,@@ -243,6 +249,7 @@ describe('bootServer pre-listen check on main worktree (FR3)', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,port: 0,diff --git a/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.ts b/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.tsindex e6f4aebc0..bdbfce831 100644--- a/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.ts+++ b/packages/app/tests/integration/worktree-cleanup-and-stale-pointer.test.ts@@ -26,6 +26,7 @@ describe('git worktree remove cleans up the per-worktree shadow (FR6)', () => {const shadowHead = resolve(adminDir, 'ok/HEAD');const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,@@ -67,6 +68,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: projectRoot,port: 0,@@ -90,6 +92,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()handle = createLinkedWorktree({ seedOkScaffold: true });const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,@@ -119,6 +122,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()let firstAttemptError: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: projectRoot,port: 0,@@ -136,6 +140,7 @@ describe('MalformedGitPointerError at boot when .git pointer is stale (FR7)', ()mkdirSync(resolve(projectRoot, '.git'), { recursive: true });const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: projectRoot,port: 0,diff --git a/packages/app/tests/integration/worktree-concurrent.test.ts b/packages/app/tests/integration/worktree-concurrent.test.tsindex 43f72d704..39c8f3269 100644--- a/packages/app/tests/integration/worktree-concurrent.test.ts+++ b/packages/app/tests/integration/worktree-concurrent.test.ts@@ -27,6 +27,7 @@ describe('Two linked worktrees boot in parallel with isolated state (D13)', () =const [bootedA, bootedB] = await Promise.all([bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: a.worktreePath,port: 0,@@ -36,6 +37,7 @@ describe('Two linked worktrees boot in parallel with isolated state (D13)', () =attachUiSibling: false,}),bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: b.worktreePath,port: 0,diff --git a/packages/app/tests/integration/worktree-init.test.ts b/packages/app/tests/integration/worktree-init.test.tsindex c9ed87327..19857798b 100644--- a/packages/app/tests/integration/worktree-init.test.ts+++ b/packages/app/tests/integration/worktree-init.test.ts@@ -49,6 +49,7 @@ describe('initContent in a linked worktree (FR4 / D7)', () => {initContent(handle.worktreePath);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: handle.worktreePath,port: 0,diff --git a/packages/app/tests/stress/_helpers/fixtures.ts b/packages/app/tests/stress/_helpers/fixtures.tsindex 5630f1182..0ae745b13 100644--- a/packages/app/tests/stress/_helpers/fixtures.ts+++ b/packages/app/tests/stress/_helpers/fixtures.ts@@ -96,11 +96,11 @@ export const test = base.extend<TestFixtures, WorkerFixtures>({const contentDir = mkdtempSync(join(tmpdir(), `ok-w${workerInfo.workerIndex}-`));const viteCacheDir = prepareViteCacheDir(`w${workerInfo.workerIndex}`);seedRequiredFixtureFiles(contentDir);- const baseURL = `http://localhost:${port}`;+ const baseURL = `http://127.0.0.1:${port}`;const serverLog = openServerLog(`w${workerInfo.workerIndex}`);- const proc = spawn('bun', ['run', '--silent', 'dev'], {+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '127.0.0.1'], {cwd: APP_PACKAGE_ROOT,env: {...process.env,diff --git a/packages/app/tests/stress/_helpers/global-warm-cache.ts b/packages/app/tests/stress/_helpers/global-warm-cache.tsindex 7d531e2b1..f8722f1bb 100644--- a/packages/app/tests/stress/_helpers/global-warm-cache.ts+++ b/packages/app/tests/stress/_helpers/global-warm-cache.ts@@ -68,7 +68,7 @@ async function buildSeedOnce(key: string): Promise<void> {mkdirSync(join(APP_PACKAGE_ROOT, 'node_modules'), { recursive: true });const buildDir = mkdtempSync(join(APP_PACKAGE_ROOT, 'node_modules', '.vite-e2e-seed-building-'));const log = openServerLog('warm-cache');- const proc = spawn('bun', ['run', '--silent', 'dev'], {+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '127.0.0.1'], {cwd: APP_PACKAGE_ROOT,env: {...process.env,@@ -84,7 +84,7 @@ async function buildSeedOnce(key: string): Promise<void> {});let succeeded = false;try {- await waitForHttpReady(`http://localhost:${port}`, 60_000);+ await waitForHttpReady(`http://127.0.0.1:${port}`, 60_000);const depsDir = join(buildDir, 'deps');const metaPath = join(depsDir, '_metadata.json');const deadline = Date.now() + OPTIMIZER_SETTLE_BUDGET_MS;diff --git a/packages/app/tests/stress/_helpers/server-process.ts b/packages/app/tests/stress/_helpers/server-process.tsindex 54aa38f09..bd5192d45 100644--- a/packages/app/tests/stress/_helpers/server-process.ts+++ b/packages/app/tests/stress/_helpers/server-process.ts@@ -63,10 +63,14 @@ export function tailServerLog(log: ServerLog, lines = 40): string {}}-export async function checkCollabSync(port: number, timeoutMs = 10_000): Promise<void> {+export async function checkCollabSync(+ port: number,+ timeoutMs = 10_000,+ loopbackHost: '127.0.0.1' | '::1' = '127.0.0.1',+): Promise<void> {const doc = new Y.Doc();const provider = new HocuspocusProvider({- url: `ws://localhost:${port}/collab`,+ url: `ws://${loopbackHost === '::1' ? '[::1]' : '127.0.0.1'}:${port}/collab`,name: SYSTEM_DOC_NAME,document: doc,connect: false,@@ -92,11 +96,13 @@ export async function checkCollabSync(port: number, timeoutMs = 10_000): Promise}}-export async function getFreePort(): Promise<number> {+export async function getFreePort(+ loopbackHost: '127.0.0.1' | '::1' = '127.0.0.1',+): Promise<number> {return new Promise((resolve, reject) => {const s = createNetServer();s.once('error', reject);- s.listen(0, () => {+ s.listen(0, loopbackHost === '::1' ? '::1' : '127.0.0.1', () => {const port = (s.address() as AddressInfo).port;s.close(() => resolve(port));});diff --git a/packages/app/tests/stress/create-then-rename-editable.e2e.ts b/packages/app/tests/stress/create-then-rename-editable.e2e.tsindex d125368a2..bcc911c1a 100644--- a/packages/app/tests/stress/create-then-rename-editable.e2e.ts+++ b/packages/app/tests/stress/create-then-rename-editable.e2e.ts@@ -84,6 +84,6 @@ test.describe('create → inline-rename → click → type', () => {const stuckWarmFallbackCount = await page.locator('.tiptap-editor[aria-hidden="true"]').count();expect(stuckWarmFallbackCount).toBe(0);- expect(workerServer.baseURL).toMatch(/^http:\/\/localhost:\d+$/);+ expect(workerServer.baseURL).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);});});diff --git a/packages/app/tests/stress/file-tree-create.e2e.ts b/packages/app/tests/stress/file-tree-create.e2e.tsindex 013f863e9..758011ab2 100644--- a/packages/app/tests/stress/file-tree-create.e2e.ts+++ b/packages/app/tests/stress/file-tree-create.e2e.ts@@ -179,7 +179,7 @@ async function installDelayedDesktopSessionBridge(platform: 'darwin',config: {apiOrigin: baseURL,- collabUrl: `ws://localhost:${port}/collab`,+ collabUrl: `ws://127.0.0.1:${port}/collab`,mode: 'editor',projectName: 'session-restore-test',projectPath: contentDir,diff --git a/packages/app/tests/stress/init-load-byte-stable.e2e.ts b/packages/app/tests/stress/init-load-byte-stable.e2e.tsindex f17e1e8dd..4655190d3 100644--- a/packages/app/tests/stress/init-load-byte-stable.e2e.ts+++ b/packages/app/tests/stress/init-load-byte-stable.e2e.ts@@ -39,7 +39,7 @@ interface OkFixture {const test = base.extend<{ okFixture: OkFixture }>({// biome-ignore lint/correctness/noEmptyPattern: Playwright requires an object-destructuring pattern for the fixtures arg; this fixture has no dependencies so the destructure is empty by design (matches the convention used by the `workerServer` fixture in `_helpers/fixtures.ts`).okFixture: async ({}, use) => {- const port = await getFreePort();+ const port = await getFreePort('::1');const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-init-load-e2e-')));for (const entry of CORPUS) {@@ -52,10 +52,10 @@ const test = base.extend<{ okFixture: OkFixture }>({installUserSkill: async () => 'skip-current',});- const baseURL = `http://localhost:${port}`;+ const baseURL = `http://[::1]:${port}`;const viteCacheDir = prepareViteCacheDir('init-load');const serverLog = openServerLog('init-load');- const proc = spawn('bun', ['run', '--silent', 'dev'], {+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '::1'], {cwd: APP_PACKAGE_ROOT,env: {...process.env,@@ -72,7 +72,7 @@ const test = base.extend<{ okFixture: OkFixture }>({await Promise.race([(async () => {await waitForHttpReady(baseURL, 60_000);- await checkCollabSync(port);+ await checkCollabSync(port, 10_000, '::1');})(),new Promise<never>((_, reject) => {proc.once('error', (err) => reject(err));diff --git a/packages/app/tests/stress/rename-noext-probe.e2e.ts b/packages/app/tests/stress/rename-noext-probe.e2e.tsindex 2e3903bda..8338a3804 100644--- a/packages/app/tests/stress/rename-noext-probe.e2e.ts+++ b/packages/app/tests/stress/rename-noext-probe.e2e.ts@@ -23,7 +23,7 @@ test.describe('PROBE: sidebar rename — no-extension typed', () => {api,workerServer,}) => {- const baseURL = `http://localhost:${workerServer.port}`;+ const baseURL = `http://127.0.0.1:${workerServer.port}`;const suffix = randomUUID().slice(0, 8);const srcName = `probe-src-${suffix}`;const dstName = `probe-dst-${suffix}`;diff --git a/packages/app/tests/stress/single-file-ephemeral.e2e.ts b/packages/app/tests/stress/single-file-ephemeral.e2e.tsindex 0194df592..38ca715a4 100644--- a/packages/app/tests/stress/single-file-ephemeral.e2e.ts+++ b/packages/app/tests/stress/single-file-ephemeral.e2e.ts@@ -45,7 +45,7 @@ interface EphemeralFixture {const test = base.extend<{ ephemeral: EphemeralFixture }>({// biome-ignore lint/correctness/noEmptyPattern: Playwright requires an object-destructuring pattern; this fixture has no dependencies.ephemeral: async ({}, use) => {- const port = await getFreePort();+ const port = await getFreePort('::1');const userDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-sf-e2e-')));const notesDir = join(userDir, 'notes');mkdirSync(notesDir, { recursive: true });@@ -55,10 +55,10 @@ const test = base.extend<{ ephemeral: EphemeralFixture }>({writeFileSync(join(notesDir, 'pic.png'), 'not-a-real-png', 'utf-8');const projectDir = createEphemeralProjectDir(notesDir);- const baseURL = `http://localhost:${port}`;+ const baseURL = `http://[::1]:${port}`;const viteCacheDir = prepareViteCacheDir('sf-ephemeral');const serverLog = openServerLog('sf-ephemeral');- const proc = spawn('bun', ['run', '--silent', 'dev'], {+ const proc = spawn('bun', ['run', '--silent', 'dev', '--host', '::1'], {cwd: APP_PACKAGE_ROOT,env: {...process.env,@@ -77,7 +77,7 @@ const test = base.extend<{ ephemeral: EphemeralFixture }>({await Promise.race([(async () => {await waitForHttpReady(baseURL, 60_000);- await checkCollabSync(port);+ await checkCollabSync(port, 10_000, '::1');})(),new Promise<never>((_, reject) => {proc.once('error', (err) => reject(err));diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.tsindex e3896ba94..2b7616c72 100644--- a/packages/cli/src/commands/start.test.ts+++ b/packages/cli/src/commands/start.test.ts@@ -848,7 +848,7 @@ describe('bootStartServer (integration)', () => {skipUiAutoSpawn: true,});- const ws = new WebSocket(`ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}`);+ const ws = new WebSocket(`ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}`);try {await new Promise<void>((done, fail) => {const onOpen = () => {diff --git a/packages/cli/src/commands/ui-proxy.test.ts b/packages/cli/src/commands/ui-proxy.test.tsindex 94ccd0cd1..5f6ed5744 100644--- a/packages/cli/src/commands/ui-proxy.test.ts+++ b/packages/cli/src/commands/ui-proxy.test.ts@@ -19,7 +19,7 @@ async function rawRequest(opts: {return new Promise((done, fail) => {const req = httpRequest({- host: 'localhost',+ host: '127.0.0.1',port: opts.port,path: opts.path,method: opts.method ?? 'GET',@@ -56,7 +56,7 @@ async function startUpstream(await new Promise<void>((done, fail) => {const onError = (err: Error) => fail(err);server.once('error', onError);- server.listen(0, 'localhost', () => {+ server.listen(0, '127.0.0.1', () => {server.off('error', onError);done();});@@ -95,12 +95,12 @@ describe('startProxyServer', () => {proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});- const response = await fetch(`http://localhost:${proxy.port}/hello`);+ const response = await fetch(`http://127.0.0.1:${proxy.port}/hello`);expect(response.status).toBe(200);expect(await response.text()).toBe('hello world');expect(response.headers.get('content-type')).toContain('text/plain');@@ -120,12 +120,12 @@ describe('startProxyServer', () => {proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});- const response = await fetch(`http://localhost:${proxy.port}/echo`, {+ const response = await fetch(`http://127.0.0.1:${proxy.port}/echo`, {method: 'POST',body: payload,headers: { 'Content-Type': 'text/plain' },@@ -143,12 +143,12 @@ describe('startProxyServer', () => {proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});- const response = await fetch(`http://localhost:${proxy.port}/missing`);+ const response = await fetch(`http://127.0.0.1:${proxy.port}/missing`);expect(response.status).toBe(404);expect(response.headers.get('x-custom')).toBe('not-found');expect(await response.text()).toBe('nope');@@ -163,12 +163,12 @@ describe('startProxyServer', () => {proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});- const response = await fetch(`http://localhost:${proxy.port}/head`, { method: 'HEAD' });+ const response = await fetch(`http://127.0.0.1:${proxy.port}/head`, { method: 'HEAD' });expect(response.status).toBe(200);expect(response.headers.get('x-meta')).toBe('yes');expect(await response.text()).toBe('');@@ -182,12 +182,12 @@ describe('startProxyServer', () => {proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: deadPort,});- const response = await fetch(`http://localhost:${proxy.port}/whatever`);+ const response = await fetch(`http://127.0.0.1:${proxy.port}/whatever`);expect(response.status).toBe(502);expect(response.headers.get('content-type')).toBe('application/problem+json');const body = (await response.json()) as { type: string; title: string; status: number };@@ -199,15 +199,15 @@ describe('startProxyServer', () => {upstream = await startUpstream((_req, res) => res.end('ok'));proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});const port = proxy.port;await proxy.close();proxy = null;- await expect(fetch(`http://localhost:${port}/`)).rejects.toThrow();+ await expect(fetch(`http://127.0.0.1:${port}/`)).rejects.toThrow();});test('rejects requests with non-loopback Host header (DNS-rebind defense)', async () => {@@ -218,8 +218,8 @@ describe('startProxyServer', () => {});proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});@@ -244,8 +244,8 @@ describe('startProxyServer', () => {});proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});@@ -268,8 +268,8 @@ describe('startProxyServer', () => {});proxy = await startProxyServer({listenPort: 0,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});@@ -285,14 +285,14 @@ describe('startProxyServer', () => {upstream = await startUpstream((_req, res) => res.end('ok'));const pickerSrv = createHttpServer();- await new Promise<void>((done) => pickerSrv.listen(0, 'localhost', () => done()));+ await new Promise<void>((done) => pickerSrv.listen(0, '127.0.0.1', () => done()));const requested = (pickerSrv.address() as { port: number }).port;await new Promise<void>((done) => pickerSrv.close(() => done()));proxy = await startProxyServer({listenPort: requested,- host: 'localhost',- upstreamHost: 'localhost',+ host: '127.0.0.1',+ upstreamHost: '127.0.0.1',upstreamPort: upstream.port,});expect(proxy.port).toBe(requested);diff --git a/packages/cli/src/commands/ui.test.ts b/packages/cli/src/commands/ui.test.tsindex bd6e9b40c..5105a6bf9 100644--- a/packages/cli/src/commands/ui.test.ts+++ b/packages/cli/src/commands/ui.test.ts@@ -98,7 +98,7 @@ function config() {}async function get(port: number, path: string) {- const res = await fetch(`http://localhost:${port}${path}`);+ const res = await fetch(`http://127.0.0.1:${port}${path}`);const body = await res.text();return { status: res.status, body, headers: res.headers };}@@ -126,7 +126,7 @@ async function rawRequest(opts: {return new Promise((done, fail) => {const req = httpRequest({- host: 'localhost',+ host: '127.0.0.1',port: opts.port,path: opts.path,method: opts.method ?? 'GET',@@ -157,6 +157,44 @@ async function rawRequest(opts: {});}+type UpstreamSurrogate = { port: number; close: () => Promise<void> };++async function startDualLoopbackUpstream(+ handler: Parameters<typeof createHttpServer>[1],+): Promise<UpstreamSurrogate> {+ const v6 = createHttpServer(handler);+ await new Promise<void>((done, fail) => {+ v6.once('error', fail);+ v6.listen(0, '::1', () => {+ v6.off('error', fail);+ done();+ });+ });+ const port = (v6.address() as { port: number }).port;+ const v4 = createHttpServer(handler);+ try {+ await new Promise<void>((done, fail) => {+ v4.once('error', fail);+ v4.listen(port, '127.0.0.1', () => {+ v4.off('error', fail);+ done();+ });+ });+ } catch (err) {+ await new Promise<void>((r) => v6.close(() => r()));+ throw err;+ }+ return {+ port,+ close: async () => {+ await Promise.all([+ new Promise<void>((r) => v6.close(() => r())),+ new Promise<void>((r) => v4.close(() => r())),+ ]);+ },+ };+}+describe('resolveRequestedPort', () => {test('default is DEFAULT_UI_PORT with kernel-allocated fallback', () => {expect(resolveRequestedPort(undefined, undefined)).toEqual({@@ -198,7 +236,7 @@ describe('resolveRequestedPort', () => {describe('startUiServer', () => {test('binds requested port and writes ui.lock with resolved port', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });expect(handle.port).toBeGreaterThan(0);const lockPath = resolve(lockDir, 'ui.lock');@@ -281,7 +319,7 @@ describe('startUiServer', () => {});test('/api/config returns collabUrl=null when server.lock is absent', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, body, headers } = await get(handle.port, '/api/config');expect(status).toBe(200);expect(headers.get('content-type')).toContain('application/json');@@ -294,11 +332,11 @@ describe('startUiServer', () => {test('/api/config returns an armed paneTarget; DELETE consumes it', async () => {armPaneTarget(lockDir, '#/specs/foo/SPEC');- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const first = JSON.parse((await get(handle.port, '/api/config')).body);expect(first.paneTarget).toBe('#/specs/foo/SPEC');- const del = await fetch(`http://localhost:${handle.port}/api/config`, { method: 'DELETE' });+ const del = await fetch(`http://127.0.0.1:${handle.port}/api/config`, { method: 'DELETE' });expect(del.status).toBe(204);expect(readArmedPaneTarget(lockDir)).toBeNull();@@ -308,15 +346,15 @@ describe('startUiServer', () => {test('base-open GET / 302-redirects to an armed pane target and consumes it', async () => {armPaneTarget(lockDir, '#/specs/foo/SPEC');- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });- const res = await fetch(`http://localhost:${handle.port}/`, { redirect: 'manual' });+ const res = await fetch(`http://127.0.0.1:${handle.port}/`, { redirect: 'manual' });expect(res.status).toBe(302);expect(res.headers.get('location')).toBe('/#/specs/foo/SPEC');expect(res.headers.get('cache-control')).toBe('no-store');expect(readArmedPaneTarget(lockDir)).toBeNull();- const follow = await fetch(`http://localhost:${handle.port}/`, { redirect: 'manual' });+ const follow = await fetch(`http://127.0.0.1:${handle.port}/`, { redirect: 'manual' });expect(follow.status).not.toBe(302);});@@ -326,10 +364,10 @@ describe('startUiServer', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',assetDir: dist,});- const res = await fetch(`http://localhost:${handle.port}/`, { redirect: 'manual' });+ const res = await fetch(`http://127.0.0.1:${handle.port}/`, { redirect: 'manual' });expect(res.status).toBe(200);expect(await res.text()).toContain('id="root"');});@@ -338,41 +376,41 @@ describe('startUiServer', () => {acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });updateServerLockPort(lockDir, 54321);- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { body } = await get(handle.port, '/api/config');const parsed = JSON.parse(body);- expect(parsed.collabUrl).toBe(`ws://localhost:${handle.port}/collab`);+ expect(parsed.collabUrl).toBe(`ws://127.0.0.1:${handle.port}/collab`);});test('/api/config has no-store cache-control', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { headers } = await get(handle.port, '/api/config');expect(headers.get('cache-control')).toBe('no-store');});test('HEAD /api/config returns 200 with no body', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });- const res = await fetch(`http://localhost:${handle.port}/api/config`, { method: 'HEAD' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });+ const res = await fetch(`http://127.0.0.1:${handle.port}/api/config`, { method: 'HEAD' });expect(res.status).toBe(200);const body = await res.text();expect(body).toBe('');});test('unknown path returns 404 when no static assets present (tmp dir has no dist)', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status } = await get(handle.port, '/does-not-exist');expect([200, 404]).toContain(status);});test('GET / serves the SPA shell (rewrites to /index.html)', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const root = await get(handle.port, '/');const indexHtml = await get(handle.port, '/index.html');expect(root.status).toBe(indexHtml.status);});test('release() removes the ui.lock', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const lockPath = resolve(lockDir, 'ui.lock');expect(existsSync(lockPath)).toBe(true);@@ -441,8 +479,8 @@ describe('startUiServer', () => {expect(handle.port).toBeGreaterThan(0);expect(secondHandle.port).toBeGreaterThan(0);expect(handle.port).not.toBe(secondHandle.port);- const a = await fetch(`http://localhost:${handle.port}/api/config`);- const b = await fetch(`http://localhost:${secondHandle.port}/api/config`);+ const a = await fetch(`http://127.0.0.1:${handle.port}/api/config`);+ const b = await fetch(`http://127.0.0.1:${secondHandle.port}/api/config`);expect(a.status).toBe(200);expect(b.status).toBe(200);} finally {@@ -453,7 +491,7 @@ describe('startUiServer', () => {});test('GET /api/pages is proxied to the collab server when server.lock is live', async () => {- const upstream = createHttpServer((req, res) => {+ const upstream = await startDualLoopbackUpstream((req, res) => {if (req.url === '/api/pages') {res.writeHead(200, { 'Content-Type': 'application/json' });res.end(JSON.stringify({ ok: true, source: 'collab', pages: [] }));@@ -462,13 +500,12 @@ describe('startUiServer', () => {res.end();}});- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));- const upstreamPort = (upstream.address() as { port: number }).port;+ const upstreamPort = upstream.port;acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });updateServerLockPort(lockDir, upstreamPort);- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });try {const { status, body, headers } = await get(handle.port, '/api/pages');expect(status).toBe(200);@@ -476,12 +513,12 @@ describe('startUiServer', () => {const parsed = JSON.parse(body);expect(parsed).toEqual({ ok: true, source: 'collab', pages: [] });} finally {- await new Promise<void>((done) => upstream.close(() => done()));+ await upstream.close();}});test('GET /api/anything returns RFC 9457 problem+json 503 when server.lock is absent', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, body, headers } = await get(handle.port, '/api/pages');expect(status).toBe(503);expect(headers.get('content-type')).toContain('application/problem+json');@@ -499,7 +536,7 @@ describe('startUiServer', () => {test('POST /api/create-page forwards method + body to the collab server', async () => {const receivedRequests: Array<{ method: string; body: string; contentType: string }> = [];- const upstream = createHttpServer((req, res) => {+ const upstream = await startDualLoopbackUpstream((req, res) => {if (req.url === '/api/create-page' && req.method === 'POST') {let body = '';req.setEncoding('utf-8');@@ -520,14 +557,13 @@ describe('startUiServer', () => {res.end();}});- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));- const upstreamPort = (upstream.address() as { port: number }).port;+ const upstreamPort = upstream.port;acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });updateServerLockPort(lockDir, upstreamPort);- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });try {- const res = await fetch(`http://localhost:${handle.port}/api/create-page`, {+ const res = await fetch(`http://127.0.0.1:${handle.port}/api/create-page`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ docName: 'notes/test', content: '# hi' }),@@ -541,21 +577,21 @@ describe('startUiServer', () => {const sent = JSON.parse(receivedRequests[0]?.body ?? '{}');expect(sent).toEqual({ docName: 'notes/test', content: '# hi' });} finally {- await new Promise<void>((done) => upstream.close(() => done()));+ await upstream.close();}});test('/api/* proxy returns 502 when upstream connection fails', async () => {const probe = createHttpServer();- await new Promise<void>((done) => probe.listen(0, 'localhost', () => done()));+ await new Promise<void>((done) => probe.listen(0, '127.0.0.1', () => done()));const deadPort = (probe.address() as { port: number }).port;await new Promise<void>((done) => probe.close(() => done()));acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });updateServerLockPort(lockDir, deadPort);- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });- const res = await fetch(`http://localhost:${handle.port}/api/pages`);+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });+ const res = await fetch(`http://127.0.0.1:${handle.port}/api/pages`);expect(res.status).toBe(502);});@@ -578,7 +614,7 @@ describe('startUiServer', () => {test('starts when the content root contains a broken symlink', async () => {symlinkSync(resolve(tmpDir, 'missing-target'), resolve(tmpDir, 'broken-link'));- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status } = await get(handle.port, '/api/config');expect(status).toBe(200);});@@ -588,7 +624,7 @@ describe('startUiServer', () => {const seedFile = resolve(tmpDir, 'doc.md');fs.writeFileSync(seedFile, '# seed', 'utf-8');- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, headers } = await get(handle.port, '/missing.m4v');expect(status).toBe(404);expect(headers.get('content-type') ?? '').not.toMatch(/^text\/html/);@@ -601,7 +637,7 @@ describe('startUiServer', () => {const seedAsset = resolve(tmpDir, 'photo.png');fs.writeFileSync(seedAsset, 'fake-png', 'binary');- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, headers } = await get(handle.port, '/photo.png');expect(status).toBe(200);expect(headers.get('content-disposition')).toBe('inline');@@ -614,7 +650,7 @@ describe('startUiServer', () => {const fontFile = readdirSync(distAssets).find((name) => name.endsWith('.woff2'));if (!fontFile) return; // Build emitted no fonts — nothing to assert.- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, headers } = await get(handle.port, `/assets/${fontFile}`);expect(status).toBe(200);expect(headers.get('content-disposition')).toBeNull();@@ -626,7 +662,7 @@ describe('startUiServer', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',assetDir: distDir,});@@ -651,7 +687,7 @@ describe('startUiServer', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',assetDir: distDir,});@@ -670,17 +706,17 @@ describe('startUiServer', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',assetDir: distDir,});- const first = await fetch(`http://localhost:${handle.port}/assets/app-AAAA.js`);+ const first = await fetch(`http://127.0.0.1:${handle.port}/assets/app-AAAA.js`);expect(first.status).toBe(200);const etag = first.headers.get('etag');expect(etag).toBeTruthy();expect(first.headers.get('cache-control') ?? '').not.toBe('no-store');- const second = await fetch(`http://localhost:${handle.port}/assets/app-AAAA.js`, {+ const second = await fetch(`http://127.0.0.1:${handle.port}/assets/app-AAAA.js`, {headers: { 'If-None-Match': etag as string },});expect(second.status).toBe(304);@@ -693,7 +729,7 @@ describe('startUiServer', () => {fs.writeFileSync(resolve(tmpDir, 'doc.md'), '# seed', 'utf-8');fs.writeFileSync(resolve(assetsDir, 'user-upload.png'), 'fake-png', 'binary');- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, headers } = await get(handle.port, '/assets/user-upload.png');expect(status).toBe(200);expect(headers.get('content-disposition')).toBe('inline');@@ -707,7 +743,7 @@ describe('startUiServer', () => {const seedHtml = resolve(tmpDir, 'viewer.html');fs.writeFileSync(seedHtml, '<h1>viewer</h1><script>alert(1)</script>', 'utf-8');- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, headers } = await get(handle.port, '/viewer.html');expect(status).toBe(200);expect(headers.get('content-disposition')).toBe('inline');@@ -723,7 +759,7 @@ describe('startUiServer', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',assetDir: dist,});const { status, headers } = await get(handle.port, '/index.html');@@ -733,7 +769,7 @@ describe('startUiServer', () => {});test('/api/* gate rejects requests with non-loopback Host header (DNS-rebind defense)', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const res = await rawRequest({port: handle.port,path: '/api/config',@@ -747,7 +783,7 @@ describe('startUiServer', () => {});test('/api/* gate rejects requests with non-loopback Origin (CSRF defense)', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const res = await rawRequest({port: handle.port,path: '/api/config',@@ -759,7 +795,7 @@ describe('startUiServer', () => {});test('/api/* gate accepts loopback Origin (legitimate Vite dev server)', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const res = await rawRequest({port: handle.port,path: '/api/config',@@ -769,7 +805,7 @@ describe('startUiServer', () => {});test('/api/* gate accepts Origin: null (Electron packaged renderer)', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const res = await rawRequest({port: handle.port,path: '/api/config',@@ -780,17 +816,16 @@ describe('startUiServer', () => {test('/api/* proxy gate rejects DNS-rebind Host even when collab server is up', async () => {let upstreamHits = 0;- const upstream = createHttpServer((_req, res) => {+ const upstream = await startDualLoopbackUpstream((_req, res) => {upstreamHits++;res.writeHead(200, { 'Content-Type': 'application/json' });res.end(JSON.stringify({ ok: true }));});- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));- const upstreamPort = (upstream.address() as { port: number }).port;+ const upstreamPort = upstream.port;acquireServerLock(lockDir, { port: 0, worktreeRoot: tmpDir });updateServerLockPort(lockDir, upstreamPort);- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });try {const res = await rawRequest({port: handle.port,@@ -805,12 +840,12 @@ describe('startUiServer', () => {expect(body.type).toBe('urn:ok:error:host-not-allowed');expect(upstreamHits).toBe(0);} finally {- await new Promise<void>((done) => upstream.close(() => done()));+ await upstream.close();}});test('non-/api/* paths are NOT subject to the gate (Host check would harm SPA)', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const res = await rawRequest({port: handle.port,path: '/missing.png',@@ -826,7 +861,7 @@ describe('startUiServer', () => {const seedZip = resolve(tmpDir, 'archive.zip');fs.writeFileSync(seedZip, 'fake-zip-bytes', 'binary');- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const { status, headers } = await get(handle.port, '/archive.zip');expect(status).toBe(200);expect(headers.get('content-disposition')).toBe('attachment');@@ -845,7 +880,7 @@ describe('startUiServer — D-025 12h safety-net', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',safetyNetMs: 60_000,scheduler,});@@ -859,7 +894,7 @@ describe('startUiServer — D-025 12h safety-net', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',safetyNetMs: 60_000,scheduler,onSafetyNet: () => {@@ -878,7 +913,7 @@ describe('startUiServer — D-025 12h safety-net', () => {if (handle) await closeHttpServers(handle.httpServers);let connectError: unknown = null;try {- await fetch(`http://localhost:${port}/api/config`);+ await fetch(`http://127.0.0.1:${port}/api/config`);} catch (err) {connectError = err;}@@ -893,7 +928,7 @@ describe('startUiServer — D-025 12h safety-net', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',safetyNetMs: 60_000,scheduler,onSafetyNet: () => {@@ -915,7 +950,7 @@ describe('startUiServer — D-025 12h safety-net', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',safetyNetMs: 60_000,scheduler,});@@ -928,7 +963,7 @@ describe('startUiServer — D-025 12h safety-net', () => {});test('release() is idempotent — second call is a no-op', async () => {- handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: 'localhost' });+ handle = await startUiServer({ config: config(), cwd: tmpDir, port: 0, host: '127.0.0.1' });const lockPath = resolve(lockDir, 'ui.lock');handle.release();@@ -946,7 +981,7 @@ describe('startUiServer — D-025 12h safety-net', () => {config: config(),cwd: tmpDir,port: 0,- host: 'localhost',+ host: '127.0.0.1',safetyNetMs: 0,scheduler,});@@ -968,7 +1003,7 @@ describe('resolveUiLockCollision', () => {test('same port as holder → already-running', async () => {const result = await resolveUiLockCollision({requestedPort: 3000,- host: 'localhost',+ host: '127.0.0.1',lockDir,readLock: () => fakeLock(3000),});@@ -980,7 +1015,7 @@ describe('resolveUiLockCollision', () => {await expect(resolveUiLockCollision({requestedPort: 3000,- host: 'localhost',+ host: '127.0.0.1',lockDir,readLock: () => null,}),@@ -988,16 +1023,15 @@ describe('resolveUiLockCollision', () => {});test('different port + live upstream → proxy mode forwards correctly', async () => {- const upstream = createHttpServer((_req, res) => {+ const upstream = await startDualLoopbackUpstream((_req, res) => {res.writeHead(200, { 'Content-Type': 'text/plain' });res.end('upstream ok');});- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));- const upstreamPort = (upstream.address() as { port: number }).port;+ const upstreamPort = upstream.port;const result = await resolveUiLockCollision({requestedPort: 0, // kernel-allocated so we don't conflict with anything- host: 'localhost',+ host: '127.0.0.1',lockDir,readLock: () => fakeLock(upstreamPort),});@@ -1007,31 +1041,31 @@ describe('resolveUiLockCollision', () => {expect(result.upstreamPort).toBe(upstreamPort);try {- const response = await fetch(`http://localhost:${result.handle.port}/`);+ const response = await fetch(`http://127.0.0.1:${result.handle.port}/`);expect(response.status).toBe(200);expect(await response.text()).toBe('upstream ok');} finally {await result.handle.close();- await new Promise<void>((done) => upstream.close(() => done()));+ await upstream.close();}});test('proxy returns 502 when upstream dies', async () => {const probe = createHttpServer();- await new Promise<void>((done) => probe.listen(0, 'localhost', () => done()));+ await new Promise<void>((done) => probe.listen(0, '127.0.0.1', () => done()));const deadPort = (probe.address() as { port: number }).port;await new Promise<void>((done) => probe.close(() => done()));const result = await resolveUiLockCollision({requestedPort: 0,- host: 'localhost',+ host: '127.0.0.1',lockDir,readLock: () => fakeLock(deadPort),});if (result.mode !== 'proxy') throw new Error('unreachable');try {- const response = await fetch(`http://localhost:${result.handle.port}/`);+ const response = await fetch(`http://127.0.0.1:${result.handle.port}/`);expect(response.status).toBe(502);} finally {await result.handle.close();@@ -1039,9 +1073,8 @@ describe('resolveUiLockCollision', () => {});test('lock port=0 that becomes live within deadline → proxy mode', async () => {- const upstream = createHttpServer((_req, res) => res.end('late upstream'));- await new Promise<void>((done) => upstream.listen(0, 'localhost', () => done()));- const upstreamPort = (upstream.address() as { port: number }).port;+ const upstream = await startDualLoopbackUpstream((_req, res) => res.end('late upstream'));+ const upstreamPort = upstream.port;let calls = 0;const readLock = () => {@@ -1051,7 +1084,7 @@ describe('resolveUiLockCollision', () => {const result = await resolveUiLockCollision({requestedPort: 0,- host: 'localhost',+ host: '127.0.0.1',lockDir,readLock,pollIntervalMs: 10,@@ -1063,14 +1096,14 @@ describe('resolveUiLockCollision', () => {expect(result.upstreamPort).toBe(upstreamPort);await result.handle.close();- await new Promise<void>((done) => upstream.close(() => done()));+ await upstream.close();});test('lock port=0 that stays 0 → throws timeout error', async () => {await expect(resolveUiLockCollision({requestedPort: 3000,- host: 'localhost',+ host: '127.0.0.1',lockDir,readLock: () => fakeLock(0),pollIntervalMs: 5,@@ -1088,7 +1121,7 @@ describe('resolveUiLockCollision', () => {const result = await resolveUiLockCollision({requestedPort: 4321,- host: 'localhost',+ host: '127.0.0.1',lockDir,readLock,pollIntervalMs: 5,diff --git a/packages/cli/src/loopback-bind-discipline.test.ts b/packages/cli/src/loopback-bind-discipline.test.tsnew file mode 100644index 000000000..b4081b1fd--- /dev/null+++ b/packages/cli/src/loopback-bind-discipline.test.ts@@ -0,0 +1,175 @@+import { describe, expect, test } from 'bun:test';+import { readdirSync, readFileSync } from 'node:fs';+import { basename, dirname, join, relative } from 'node:path';+import { fileURLToPath } from 'node:url';++const __dirname = dirname(fileURLToPath(import.meta.url));+const PACKAGE_ROOT = join(__dirname, '..');+const SCAN_ROOT = __dirname; // packages/cli/src++const SELF_BASENAME = basename(fileURLToPath(import.meta.url));++interface FileLines {+ path: string;+ lines: string[];+}++function listScannedTestFiles(): FileLines[] {+ const out: FileLines[] = [];+ function walk(dir: string) {+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ const abs = join(dir, entry.name);+ if (entry.isDirectory()) {+ walk(abs);+ continue;+ }+ if (!entry.isFile() || !entry.name.endsWith('.test.ts')) continue;+ if (entry.name === SELF_BASENAME) continue;+ out.push({+ path: relative(PACKAGE_ROOT, abs),+ lines: readFileSync(abs, 'utf-8').split('\n'),+ });+ }+ }+ walk(SCAN_ROOT);+ return out;+}++function isCommentOnlyLine(line: string): boolean {+ const trimmed = line.trim();+ return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');+}++const LOOPBACK_HOST_LITERAL = /['"](?:127\.0\.0\.1|::1)['"]/;++export function findNonLoopbackListenCalls(lines: string[]): Array<{ line: number; text: string }> {+ const violations: Array<{ line: number; text: string }> = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i] ?? '';+ if (isCommentOnlyLine(line)) continue;+ const idx = line.indexOf('.listen(');+ if (idx === -1) continue;+ let window = line.slice(idx);+ for (let j = i + 1; j <= i + 3 && !window.includes(')') && j < lines.length; j++) {+ window += `\n${lines[j] ?? ''}`;+ }+ const paren = window.indexOf(')');+ if (paren !== -1) window = window.slice(0, paren + 1);+ if (!LOOPBACK_HOST_LITERAL.test(window)) {+ violations.push({ line: i + 1, text: line.trim() });+ }+ }+ return violations;+}++const AMBIGUOUS_LOCALHOST_DIAL = /\b(?:https?|wss?):\/\/localhost:\$\{/;++export function findAmbiguousLocalhostDials(+ lines: string[],+): Array<{ line: number; text: string }> {+ const violations: Array<{ line: number; text: string }> = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i] ?? '';+ if (isCommentOnlyLine(line)) continue;+ if (AMBIGUOUS_LOCALHOST_DIAL.test(line)) {+ violations.push({ line: i + 1, text: line.trim() });+ }+ }+ return violations;+}++describe('loopback bind discipline (cli test sources)', () => {+ const files = listScannedTestFiles();++ test('there are test files to scan (sanity)', () => {+ expect(files.length).toBeGreaterThan(0);+ expect(files.some((f) => f.path.endsWith('commands/ui.test.ts'))).toBe(true);+ expect(files.some((f) => f.path.endsWith('commands/ui-proxy.test.ts'))).toBe(true);+ });++ test('every .listen( call binds an explicit loopback host literal', () => {+ const violations: string[] = [];+ for (const file of files) {+ for (const v of findNonLoopbackListenCalls(file.lines)) {+ violations.push(` ${file.path}:${v.line} ${v.text}`);+ }+ }+ if (violations.length > 0) {+ throw new Error(+ `Hostless rig bind found — a bare listen(0) binds the IPv6 wildcard '::', whose loopback-specific ` ++ `port slots stay silently bindable by foreign processes; their listeners then intercept this rig's ` ++ `localhost dials (the rotating integration-suite flake). Bind a loopback-specific host ` ++ `(e.g. listen(0, '127.0.0.1', cb)) and dial the literal from server.address():\n${violations.join('\n')}`,+ );+ }+ });++ test('no interpolated-port localhost dial URLs', () => {+ const violations: string[] = [];+ for (const file of files) {+ for (const v of findAmbiguousLocalhostDials(file.lines)) {+ violations.push(` ${file.path}:${v.line} ${v.text}`);+ }+ }+ if (violations.length > 0) {+ throw new Error(+ `Ambiguous-name rig dial found — 'localhost' resolves '::1'-first, exactly the loopback-specific slot ` ++ `a foreign process can hold while the rig sits on a wildcard (or single-family) bind. Dial the ` ++ `literal address the rig actually bound (a rig-advertised base URL, or ` ++ `http://127.0.0.1:\${port}):\n${violations.join('\n')}`,+ );+ }+ });++ test('listen predicate fires on planted violations and not on adjacent negatives', () => {+ expect(findNonLoopbackListenCalls([' s.listen(0, () => {']).length).toBe(1);+ expect(+ findNonLoopbackListenCalls([' httpServer.listen(port, () => resolve());']).length,+ ).toBe(1);++ expect(findNonLoopbackListenCalls([" server.listen(0, 'localhost', cb);"]).length).toBe(1);++ expect(findNonLoopbackListenCalls([" server.listen(0, '127.0.0.1', resolve);"]).length).toBe(+ 0,+ );+ expect(findNonLoopbackListenCalls([" s.listen(port, '::1', cb);"]).length).toBe(0);++ expect(+ findNonLoopbackListenCalls([' server.listen(', ' 0,', " '127.0.0.1',", ' cb)'])+ .length,+ ).toBe(0);++ expect(findNonLoopbackListenCalls([' // before httpServer.listen() resolves']).length).toBe(0);+ expect(+ findNonLoopbackListenCalls([' * boot scan runs BEFORE httpServer.listen().']).length,+ ).toBe(0);++ expect(findNonLoopbackListenCalls([' s.listen(port, host, cb);']).length).toBe(1);++ expect(findNonLoopbackListenCalls([" s.listen(0, '0.0.0.0', cb);"]).length).toBe(1);+ });++ test('dial predicate fires on planted violations and not on adjacent negatives', () => {+ expect(+ findAmbiguousLocalhostDials([+ ` const res = await fetch(\`http://localhost:\${handle.port}/api/config\`);`,+ ]).length,+ ).toBe(1);+ expect(+ findAmbiguousLocalhostDials([` url: \`ws://localhost:\${port}/collab\`,`]).length,+ ).toBe(1);++ expect(+ findAmbiguousLocalhostDials([` const res = await fetch(\`http://127.0.0.1:\${port}/x\`);`])+ .length,+ ).toBe(0);++ expect(findAmbiguousLocalhostDials([" origin: 'http://localhost:5173',"]).length).toBe(0);++ expect(findAmbiguousLocalhostDials([` // dials http://localhost:\${port} today`]).length).toBe(+ 0,+ );++ expect(findAmbiguousLocalhostDials([" host: 'localhost:5173',"]).length).toBe(0);+ });+});diff --git a/packages/server/src/api-asset.test.ts b/packages/server/src/api-asset.test.tsindex 77f56d398..035b57e2f 100644--- a/packages/server/src/api-asset.test.ts+++ b/packages/server/src/api-asset.test.ts@@ -6,6 +6,7 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import { createApiExtension } from './api-extension.ts';import type { ContentFilter } from './content-filter.ts';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';interface Harness {baseURL: string;@@ -30,14 +31,10 @@ async function startHarness(contentDir: string, contentFilter?: ContentFilter):).onRequest({ request: req, response: res });});- await new Promise<void>((resolve) => server.listen(0, resolve));- const address = server.address();- if (typeof address !== 'object' || address === null) {- throw new Error('server did not bind to a port');- }+ const { baseUrl } = await listenOnLoopback(server);return {- baseURL: `http://127.0.0.1:${address.port}`,+ baseURL: baseUrl,close: () =>new Promise<void>((resolve, reject) => {server.close((err) => (err ? reject(err) : resolve()));diff --git a/packages/server/src/api-extension.branch-info.test.ts b/packages/server/src/api-extension.branch-info.test.tsindex 4e9b30d3e..79b5b576d 100644--- a/packages/server/src/api-extension.branch-info.test.ts+++ b/packages/server/src/api-extension.branch-info.test.ts@@ -4,6 +4,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';import type { Server } from 'node:http';import { tmpdir } from 'node:os';import { join } from 'node:path';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';interface TestRig {port: number;@@ -71,12 +72,7 @@ async function bootRig(});hocuspocus.configuration.extensions.push(ext);- const port = await new Promise<number>((resolveListen) => {- server.listen(0, () => {- const addr = server.address();- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);- });- });+ const { port } = await listenOnLoopback(server);return {port,@@ -92,7 +88,7 @@ async function bootRig(function buildUrl(port: number, branch: string, path: string, kind?: 'doc' | 'folder'): string {const params = new URLSearchParams({ branch, path });if (kind) params.set('kind', kind);- return `http://localhost:${port}/api/git/branch-info?${params.toString()}`;+ return `http://127.0.0.1:${port}/api/git/branch-info?${params.toString()}`;}async function getBranchInfo(@@ -272,7 +268,7 @@ describe('GET /api/git/branch-info', () => {commitAll(projectDir, 'init');});- const res = await fetch(`http://localhost:${rig.port}/api/git/branch-info?branch=main`);+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/branch-info?branch=main`);expect(res.status).toBe(400);});@@ -283,7 +279,7 @@ describe('GET /api/git/branch-info', () => {commitAll(projectDir, 'init');});- const res = await fetch(`http://localhost:${rig.port}/api/git/branch-info?path=a.md`);+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/branch-info?path=a.md`);expect(res.status).toBe(400);});@@ -387,7 +383,7 @@ describe('GET /api/git/branch-info', () => {});const res = await fetch(- `http://localhost:${rig.port}/api/git/branch-info?branch=main&path=&kind=folder`,+ `http://127.0.0.1:${rig.port}/api/git/branch-info?branch=main&path=&kind=folder`,);expect(res.status).toBe(200);const json = (await res.json()) as Record<string, unknown>;@@ -401,7 +397,7 @@ describe('GET /api/git/branch-info', () => {commitAll(projectDir, 'init');});- const res = await fetch(`http://localhost:${rig.port}/api/git/branch-info?branch=main&path=`);+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/branch-info?branch=main&path=`);expect(res.status).toBe(400);});diff --git a/packages/server/src/api-extension.checkout.test.ts b/packages/server/src/api-extension.checkout.test.tsindex a00073c02..5837d3d72 100644--- a/packages/server/src/api-extension.checkout.test.ts+++ b/packages/server/src/api-extension.checkout.test.ts@@ -4,6 +4,7 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'nodimport type { Server } from 'node:http';import { tmpdir } from 'node:os';import { join } from 'node:path';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';interface TestRig {port: number;@@ -75,12 +76,7 @@ async function bootRig(});hocuspocus.configuration.extensions.push(ext);- const port = await new Promise<number>((resolveListen) => {- server.listen(0, () => {- const addr = server.address();- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);- });- });+ const { port } = await listenOnLoopback(server);return {port,@@ -97,7 +93,7 @@ async function postCheckout(port: number,body: Record<string, unknown>,): Promise<{ status: number; json: Record<string, unknown> }> {- const res = await fetch(`http://localhost:${port}/api/git/checkout`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/git/checkout`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify(body),@@ -341,7 +337,7 @@ describe('POST /api/git/checkout', () => {commitAll(projectDir, 'init');});- const res = await fetch(`http://localhost:${rig.port}/api/git/checkout`);+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/git/checkout`);expect(res.status).toBe(405);});diff --git a/packages/server/src/api-extension.ok-init.test.ts b/packages/server/src/api-extension.ok-init.test.tsindex 006279818..2f78e7a67 100644--- a/packages/server/src/api-extension.ok-init.test.ts+++ b/packages/server/src/api-extension.ok-init.test.ts@@ -12,6 +12,7 @@ import {import type { Server } from 'node:http';import { homedir, tmpdir } from 'node:os';import { join } from 'node:path';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';function extractHandlerBlock(src: string, handlerNameConst: string): string {const anchorRe = new RegExp(`const\\s+${handlerNameConst}\\s*=`);@@ -78,12 +79,7 @@ async function bootRig(): Promise<TestRig> {});hocuspocus.configuration.extensions.push(ext);- const port = await new Promise<number>((resolveListen) => {- server.listen(0, () => {- const addr = server.address();- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);- });- });+ const { port } = await listenOnLoopback(server);return {port,@@ -101,7 +97,7 @@ async function postOkInit(port: number,body: Record<string, unknown>,): Promise<{ status: number; json: Record<string, unknown> }> {- const res = await fetch(`http://localhost:${port}/api/local-op/ok-init`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/local-op/ok-init`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify(body),diff --git a/packages/server/src/api-extension.test.ts b/packages/server/src/api-extension.test.tsindex 13dae834d..c7432e5c2 100644--- a/packages/server/src/api-extension.test.ts+++ b/packages/server/src/api-extension.test.ts@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';import { join, resolve } from 'node:path';import { resumeSyncOnAuthEvent, safeSubdir, sanitizeFilename } from './api-extension.ts';import type { AuthEvent } from './local-ops/types.ts';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';import type { SyncEngine } from './sync-engine.ts';describe('safeSubdir', () => {@@ -190,12 +191,7 @@ describe('handleUploadAsset', () => {hocuspocus.configuration.extensions.push(ext);- port = await new Promise<number>((res) => {- server.listen(0, () => {- const addr = server.address();- res(typeof addr === 'object' && addr ? addr.port : 0);- });- });+ ({ port } = await listenOnLoopback(server));});afterEach(async () => {@@ -224,7 +220,7 @@ describe('handleUploadAsset', () => {const formData = new FormData();formData.append('parentDocName', parentDocName);formData.append('file', new Blob([file]), filename);- return fetch(`http://localhost:${port}/api/upload`, {+ return fetch(`http://127.0.0.1:${port}/api/upload`, {method: 'POST',body: formData,});@@ -245,7 +241,7 @@ describe('handleUploadAsset', () => {test('rejects missing parentDocName', async () => {const formData = new FormData();formData.append('file', new Blob([createPngBuffer()]), 'test.png');- const res = await fetch(`http://localhost:${port}/api/upload`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {method: 'POST',body: formData,});@@ -353,7 +349,7 @@ describe('handleUploadAsset', () => {const formData = new FormData();formData.append('parentDocName', 'docs/guide.md');formData.append('file', new Blob([createPngBuffer()]), 'screenshot.png');- const res = await fetch(`http://localhost:${port}/api/upload`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {method: 'POST',body: formData,});@@ -369,7 +365,7 @@ describe('handleUploadAsset', () => {const formData = new FormData();formData.append('parentDocName', 'docs/guide.md');formData.append('file', new Blob([pdfBuffer]), 'draft.pdf');- const res = await fetch(`http://localhost:${port}/api/upload`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {method: 'POST',body: formData,});@@ -384,7 +380,7 @@ describe('handleUploadAsset', () => {const formData = new FormData();formData.append('parentDocName', 'docs/guide.md');formData.append('file', new Blob([csvBuffer]), 'data.csv');- const res = await fetch(`http://localhost:${port}/api/upload`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {method: 'POST',body: formData,});@@ -449,12 +445,7 @@ describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {hocuspocus.configuration.extensions.push(ext);- port = await new Promise<number>((res) => {- server.listen(0, () => {- const addr = server.address();- res(typeof addr === 'object' && addr ? addr.port : 0);- });- });+ ({ port } = await listenOnLoopback(server));});afterEach(async () => {@@ -473,7 +464,7 @@ describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {const formData = new FormData();formData.append('parentDocName', parent);formData.append('file', new Blob([buf]), filename);- return fetch(`http://localhost:${port}/api/upload`, { method: 'POST', body: formData });+ return fetch(`http://127.0.0.1:${port}/api/upload`, { method: 'POST', body: formData });}test('second upload of identical bytes into same dir → deduped:true, single file on disk', async () => {diff --git a/packages/server/src/asset-serve-middleware.integration.test.ts b/packages/server/src/asset-serve-middleware.integration.test.tsindex 20f84a8e6..7b8e9b03c 100644--- a/packages/server/src/asset-serve-middleware.integration.test.ts+++ b/packages/server/src/asset-serve-middleware.integration.test.ts@@ -11,6 +11,7 @@ import {import sirv from 'sirv';import { createAssetServeMiddleware } from './asset-serve-middleware.ts';import { createContentFilter } from './content-filter.ts';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';interface Harness {baseURL: string;@@ -38,12 +39,7 @@ async function startHarness(contentDir: string): Promise<Harness> {});});- await new Promise<void>((resolve) => server.listen(0, resolve));- const address = server.address();- if (typeof address !== 'object' || address === null) {- throw new Error('server did not bind to a port');- }- const baseURL = `http://127.0.0.1:${address.port}`;+ const { baseUrl: baseURL } = await listenOnLoopback(server);return {baseURL,diff --git a/packages/server/src/boot.test.ts b/packages/server/src/boot.test.tsindex dfd189479..4f879c4fe 100644--- a/packages/server/src/boot.test.ts+++ b/packages/server/src/boot.test.ts@@ -48,6 +48,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,port: 0,@@ -79,6 +80,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,port: 0,@@ -109,6 +111,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {let booted: Awaited<ReturnType<typeof bootServer>> | null = null;try {booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,projectDir,@@ -134,6 +137,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,projectDir,@@ -168,6 +172,7 @@ describe('bootServer — MissingOkConfigError pre-listen check', () => {let booted: Awaited<ReturnType<typeof bootServer>> | null = null;try {booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,port: 0,@@ -196,6 +201,7 @@ describe('bootServer — runtime state lives at projectDir, not contentDir', ()mkdirSync(contentDir, { recursive: true });const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,projectDir,contentDir,@@ -264,6 +270,7 @@ describe('bootServer — idle-shutdown runs full destroy', () => {seedOkScaffold(projectDir);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: projectDir,port: 0,@@ -297,6 +304,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {writeFileSync(resolve(shellDistDir, 'index.html'), '<html>shell</html>', 'utf-8');const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,projectDir,contentDir: projectDir,@@ -327,6 +335,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {seedOkScaffold(projectDir);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: projectDir,port: 0,@@ -366,6 +375,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {writeFileSync(resolve(lockDir, 'ui.lock'), JSON.stringify(peerSnapshot), 'utf-8');const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,projectDir,contentDir: projectDir,@@ -424,6 +434,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,projectDir,contentDir: projectDir,@@ -457,6 +468,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {writeFileSync(resolve(shellDistDir, 'index.html'), '<html>shell</html>', 'utf-8');const booted1 = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,projectDir,contentDir: projectDir,@@ -474,6 +486,7 @@ describe('bootServer — reactShellDistDir + ui.lock advertisement', () => {expect(existsSync(uiLockPath)).toBe(false);const booted2 = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,projectDir,contentDir: projectDir,@@ -523,6 +536,7 @@ describe('bootServer — reactShellDistDir end-to-end HTTP shape', () => {writeFileSync(resolve(projectDir, 'assets', 'upload.png'), uploadBytes);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,projectDir,contentDir: projectDir,@@ -536,7 +550,7 @@ describe('bootServer — reactShellDistDir end-to-end HTTP shape', () => {});try {await booted.ready;- const base = `http://localhost:${booted.port}`;+ const base = `http://127.0.0.1:${booted.port}`;const rootRes = await fetch(`${base}/`);expect(rootRes.status).toBe(200);@@ -620,6 +634,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {seedOkScaffold(contentDir);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,port: 0,@@ -664,6 +679,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {seedOkScaffold(wtPath);const booted = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: wtPath,port: 0,@@ -692,6 +708,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {let caught: unknown;try {await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir,port: 0,@@ -716,6 +733,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {await execFileAsync('git', ['init', '--initial-branch=main', mainDir]);seedOkScaffold(mainDir);const bootedMain = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: mainDir,port: 0,@@ -746,6 +764,7 @@ describe('bootServer — ok.boot OTel span attributes', () => {]);seedOkScaffold(wtPath);const bootedLinked = await bootServer({+ host: '127.0.0.1',config: TEST_CONFIG,contentDir: wtPath,port: 0,diff --git a/packages/server/src/collab-message-limit.test.ts b/packages/server/src/collab-message-limit.test.tsindex 692f606bf..c2d7cbb3c 100644--- a/packages/server/src/collab-message-limit.test.ts+++ b/packages/server/src/collab-message-limit.test.ts@@ -19,6 +19,7 @@ async function bootTestServer(): Promise<{ booted: BootedServer; contentDir: strwriteFileSync(join(okDir, 'config.yml'), '', 'utf-8');writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');const booted = await bootServer({+ host: '127.0.0.1',contentDir,attachUiSibling: false,idleShutdownMs: null,@@ -97,7 +98,7 @@ describe('collab WebSocket message size limits', () => {const frame = makeOversizedSyncUpdate('test-doc', payloadBytes);expect(frame.byteLength).toBe(MAX); // validates the layout constant above- const ws = new WsClient(`ws://localhost:${booted.port}/collab`);+ const ws = new WsClient(`ws://127.0.0.1:${booted.port}/collab`);await new Promise<void>((resolve, reject) => {ws.once('open', resolve);ws.once('error', reject);@@ -114,7 +115,7 @@ describe('collab WebSocket message size limits', () => {expect(closedEarly).toBe(false);expect(getMetrics().collabMessageTooLargeCount).toBe(0);- const response = await fetch(`http://localhost:${booted.port}/api/server-info`, {+ const response = await fetch(`http://127.0.0.1:${booted.port}/api/server-info`, {signal: AbortSignal.timeout(1_000),});expect(response.ok).toBe(true);@@ -132,13 +133,13 @@ describe('collab WebSocket message size limits', () => {const { booted } = s;const beforeRead = await fetch(- `http://localhost:${booted.port}/api/document?docName=test-doc`,+ `http://127.0.0.1:${booted.port}/api/document?docName=test-doc`,{ signal: AbortSignal.timeout(1_000) },);expect(beforeRead.ok).toBe(true);expect((await beforeRead.json()).content).toBe('# Test doc\n');- const ws = new WsClient(`ws://localhost:${booted.port}/collab`);+ const ws = new WsClient(`ws://127.0.0.1:${booted.port}/collab`);await new Promise<void>((resolve, reject) => {ws.once('open', resolve);ws.once('error', reject);@@ -152,13 +153,13 @@ describe('collab WebSocket message size limits', () => {expect(close.code).toBe(1009);expect(getMetrics().collabMessageTooLargeCount).toBe(1);- const response = await fetch(`http://localhost:${booted.port}/api/server-info`, {+ const response = await fetch(`http://127.0.0.1:${booted.port}/api/server-info`, {signal: AbortSignal.timeout(1_000),});expect(response.ok).toBe(true);const afterRead = await fetch(- `http://localhost:${booted.port}/api/document?docName=test-doc`,+ `http://127.0.0.1:${booted.port}/api/document?docName=test-doc`,{signal: AbortSignal.timeout(1_000),},diff --git a/packages/server/src/handoff-api.test.ts b/packages/server/src/handoff-api.test.tsindex 75113ad48..f459f9692 100644--- a/packages/server/src/handoff-api.test.ts+++ b/packages/server/src/handoff-api.test.ts@@ -1,5 +1,4 @@import { afterEach, beforeEach, describe, expect, test } from 'bun:test';-import type { AddressInfo } from 'node:net';import { setTimeout as wait } from 'node:timers/promises';import {createInstalledAgentsProbe,@@ -11,6 +10,7 @@ import {type InstalledAgentScheme,isLocalWebHost,} from './handoff-api.ts';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';describe('createInstalledAgentsProbe', () => {test('returns a record with exactly claude/codex/cursor keys', async () => {@@ -445,12 +445,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiEhocuspocus.configuration.extensions.push(ext);- port = await new Promise<number>((resolve) => {- server.listen(0, () => {- const addr = server.address();- resolve(addr && typeof addr === 'object' ? (addr as AddressInfo).port : 0);- });- });+ ({ port } = await listenOnLoopback(server));});afterEach(async () => {@@ -460,7 +455,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE});test('GET returns 200 + flat boolean record matching injected probe', async () => {- const res = await fetch(`http://localhost:${port}/api/installed-agents`);+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`);expect(res.status).toBe(200);expect(res.headers.get('content-type')).toContain('application/json');const body = await res.json();@@ -469,14 +464,14 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiEtest('3 GETs within cache TTL trigger exactly 1 probe per scheme', async () => {for (let i = 0; i < 3; i++) {- const res = await fetch(`http://localhost:${port}/api/installed-agents`);+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`);expect(res.status).toBe(200);}expect(probeCalls).toEqual({ claude: 1, codex: 1, cursor: 1 });});test('POST returns 405 + RFC 9457 problem+json with Allow: GET', async () => {- const res = await fetch(`http://localhost:${port}/api/installed-agents`, { method: 'POST' });+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, { method: 'POST' });expect(res.status).toBe(405);expect(res.headers.get('Content-Type')).toBe('application/problem+json');expect(res.headers.get('Allow')).toBe('GET');@@ -491,7 +486,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE});test('rejects cross-origin requests (DNS-rebinding / malicious-page defense)', async () => {- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {headers: { Origin: 'https://evil.example.com' },});expect(res.status).toBe(403);@@ -501,9 +496,9 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiEexpect(body.status).toBe(403);});- test('accepts same-origin browser requests (Origin: http://localhost)', async () => {- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {- headers: { Origin: `http://localhost:${port}` },+ test('accepts same-origin browser requests (Origin: http://127.0.0.1)', async () => {+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {+ headers: { Origin: `http://127.0.0.1:${port}` },});expect(res.status).toBe(200);const body = await res.json();@@ -511,7 +506,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE});test('remote-web (Host: example.com) → all-true and probe NOT called', async () => {- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {headers: {Host: 'example.com:5173',},@@ -523,7 +518,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE});test('remote-web (Host: 192.168.1.100) → all-true (LAN-bound dev server case)', async () => {- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {headers: { Host: '192.168.1.100:5173' },});expect(res.status).toBe(200);@@ -532,7 +527,7 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE});test('local-web Host: 127.0.0.1 → real probe results', async () => {- const res = await fetch(`http://localhost:${port}/api/installed-agents`, {+ const res = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {headers: { Host: `127.0.0.1:${port}` },});expect(res.status).toBe(200);@@ -541,13 +536,13 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE});test('remote-web requests are NOT cached against later local-web requests', async () => {- const remote = await fetch(`http://localhost:${port}/api/installed-agents`, {+ const remote = await fetch(`http://127.0.0.1:${port}/api/installed-agents`, {headers: { Host: 'example.com:5173' },});expect(await remote.json()).toEqual({ claude: true, codex: true, cursor: true });expect(probeCalls).toEqual({});- const local = await fetch(`http://localhost:${port}/api/installed-agents`);+ const local = await fetch(`http://127.0.0.1:${port}/api/installed-agents`);expect(await local.json()).toEqual({ claude: true, codex: false, cursor: true });expect(probeCalls).toEqual({ claude: 1, codex: 1, cursor: 1 });});diff --git a/packages/server/src/keepalive-presence-bootstrap.test.ts b/packages/server/src/keepalive-presence-bootstrap.test.tsindex 5315c80da..78c89c1eb 100644--- a/packages/server/src/keepalive-presence-bootstrap.test.ts+++ b/packages/server/src/keepalive-presence-bootstrap.test.ts@@ -32,6 +32,7 @@ async function bootTestServer(): Promise<{ booted: BootedServer; contentDir: strwriteFileSync(join(okDir, 'config.yml'), '', 'utf-8');writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');const booted = await bootServer({+ host: '127.0.0.1',contentDir,attachUiSibling: false,idleShutdownMs: null,@@ -156,7 +157,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {expect(broadcaster.getPresenceMap()[presenceKey]).toBeUndefined();const ws = new WsClient(- `ws://localhost:${booted.port}/collab/keepalive` ++ `ws://127.0.0.1:${booted.port}/collab/keepalive` +`?pid=${process.pid}` +`&connectionId=${connectionId}` +`&displayName=${encodeURIComponent('Claude')}` +@@ -197,7 +198,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {const presenceKey = toBroadcasterKey(connectionId);const ws = new WsClient(- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,);await new Promise<void>((resolve, reject) => {ws.once('open', () => resolve());@@ -217,7 +218,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {const presenceKey = toBroadcasterKey(connectionId);const ws = new WsClient(- `ws://localhost:${booted.port}/collab/keepalive` ++ `ws://127.0.0.1:${booted.port}/collab/keepalive` +`?pid=${process.pid}` +`&connectionId=${connectionId}` +`&displayName=${encodeURIComponent('Claude')}` +@@ -246,7 +247,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {`&clientName=${encodeURIComponent('claude')}` +`&colorSeed=${encodeURIComponent('Claude')}`;- const ws1 = new WsClient(`ws://localhost:${booted.port}/collab/keepalive${baseQuery}`);+ const ws1 = new WsClient(`ws://127.0.0.1:${booted.port}/collab/keepalive${baseQuery}`);await new Promise<void>((resolve, reject) => {ws1.once('open', () => resolve());ws1.once('error', (err) => reject(err));@@ -261,7 +262,7 @@ describe('keepalive WS upgrade → setPresence bootstrap', () => {ws1.close();await wait(30);- const ws2 = new WsClient(`ws://localhost:${booted.port}/collab/keepalive${baseQuery}`);+ const ws2 = new WsClient(`ws://127.0.0.1:${booted.port}/collab/keepalive${baseQuery}`);await new Promise<void>((resolve, reject) => {ws2.once('open', () => resolve());ws2.once('error', (err) => reject(err));diff --git a/packages/server/src/keepalive-presence-cleanup.test.ts b/packages/server/src/keepalive-presence-cleanup.test.tsindex 26f75c196..319043628 100644--- a/packages/server/src/keepalive-presence-cleanup.test.ts+++ b/packages/server/src/keepalive-presence-cleanup.test.ts@@ -33,6 +33,7 @@ async function bootTestServer(writeFileSync(join(okDir, 'config.yml'), '', 'utf-8');writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');const booted = await bootServer({+ host: '127.0.0.1',contentDir,attachUiSibling: false,idleShutdownMs: null,@@ -87,7 +88,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>expect(broadcaster.getPresenceMap()[presenceKey]).toBeDefined();const ws = new WsClient(- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,);await new Promise<void>((resolve, reject) => {ws.once('open', () => resolve());@@ -123,7 +124,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>});const ws1 = new WsClient(- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,);await new Promise<void>((resolve, reject) => {ws1.once('open', () => resolve());@@ -133,7 +134,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>await wait(50);const ws2 = new WsClient(- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,);await new Promise<void>((resolve, reject) => {ws2.once('open', () => resolve());@@ -162,7 +163,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>ts: Date.now(),});- const ws = new WsClient(`ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}`);+ const ws = new WsClient(`ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}`);await new Promise<void>((resolve, reject) => {ws.once('open', () => resolve());ws.once('error', (err) => reject(err));@@ -181,7 +182,7 @@ describe('keepalive WS close → grace timer → clearPresence (US-004)', () =>const presenceKey = toBroadcasterKey(connectionId);const ws = new WsClient(- `ws://localhost:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,+ `ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}&connectionId=${connectionId}`,);await new Promise<void>((resolve, reject) => {ws.once('open', () => resolve());diff --git a/packages/server/src/loopback-bind-discipline.test.ts b/packages/server/src/loopback-bind-discipline.test.tsnew file mode 100644index 000000000..b0dc9a40c--- /dev/null+++ b/packages/server/src/loopback-bind-discipline.test.ts@@ -0,0 +1,176 @@+import { describe, expect, test } from 'bun:test';+import { readdirSync, readFileSync } from 'node:fs';+import { basename, dirname, join, relative } from 'node:path';+import { fileURLToPath } from 'node:url';++const __dirname = dirname(fileURLToPath(import.meta.url));+const PACKAGE_ROOT = join(__dirname, '..');+const SCAN_ROOT = __dirname; // packages/server/src++const SELF_BASENAME = basename(fileURLToPath(import.meta.url));++interface FileLines {+ path: string;+ lines: string[];+}++function listScannedTestFiles(): FileLines[] {+ const out: FileLines[] = [];+ function walk(dir: string) {+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ const abs = join(dir, entry.name);+ if (entry.isDirectory()) {+ walk(abs);+ continue;+ }+ if (!entry.isFile() || !entry.name.endsWith('.test.ts')) continue;+ if (entry.name === SELF_BASENAME) continue;+ out.push({+ path: relative(PACKAGE_ROOT, abs),+ lines: readFileSync(abs, 'utf-8').split('\n'),+ });+ }+ }+ walk(SCAN_ROOT);+ return out;+}++function isCommentOnlyLine(line: string): boolean {+ const trimmed = line.trim();+ return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');+}++const LOOPBACK_HOST_LITERAL = /['"](?:127\.0\.0\.1|::1)['"]/;++export function findNonLoopbackListenCalls(lines: string[]): Array<{ line: number; text: string }> {+ const violations: Array<{ line: number; text: string }> = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i] ?? '';+ if (isCommentOnlyLine(line)) continue;+ const idx = line.indexOf('.listen(');+ if (idx === -1) continue;+ let window = line.slice(idx);+ for (let j = i + 1; j <= i + 3 && !window.includes(')') && j < lines.length; j++) {+ window += `\n${lines[j] ?? ''}`;+ }+ const paren = window.indexOf(')');+ if (paren !== -1) window = window.slice(0, paren + 1);+ if (!LOOPBACK_HOST_LITERAL.test(window)) {+ violations.push({ line: i + 1, text: line.trim() });+ }+ }+ return violations;+}++const AMBIGUOUS_LOCALHOST_DIAL = /\b(?:https?|wss?):\/\/localhost:\$\{/;++export function findAmbiguousLocalhostDials(+ lines: string[],+): Array<{ line: number; text: string }> {+ const violations: Array<{ line: number; text: string }> = [];+ for (let i = 0; i < lines.length; i++) {+ const line = lines[i] ?? '';+ if (isCommentOnlyLine(line)) continue;+ if (AMBIGUOUS_LOCALHOST_DIAL.test(line)) {+ violations.push({ line: i + 1, text: line.trim() });+ }+ }+ return violations;+}++describe('loopback bind discipline (server test sources)', () => {+ const files = listScannedTestFiles();++ test('there are test files to scan (sanity)', () => {+ expect(files.length).toBeGreaterThan(0);+ expect(files.some((f) => f.path.endsWith('share/publish.integration.test.ts'))).toBe(true);+ });++ test('every .listen( call binds an explicit loopback host literal', () => {+ const violations: string[] = [];+ for (const file of files) {+ for (const v of findNonLoopbackListenCalls(file.lines)) {+ violations.push(` ${file.path}:${v.line} ${v.text}`);+ }+ }+ if (violations.length > 0) {+ throw new Error(+ `Hostless rig bind found — a bare listen(0) binds the IPv6 wildcard '::', whose loopback-specific ` ++ `port slots stay silently bindable by foreign processes; their listeners then intercept this rig's ` ++ `localhost dials (the rotating share/git-context flake). Bind a loopback-specific host ` ++ `(e.g. listen(0, '127.0.0.1', cb)) and dial the literal from server.address():\n${violations.join('\n')}`,+ );+ }+ });++ test('no interpolated-port localhost dial URLs', () => {+ const violations: string[] = [];+ for (const file of files) {+ for (const v of findAmbiguousLocalhostDials(file.lines)) {+ violations.push(` ${file.path}:${v.line} ${v.text}`);+ }+ }+ if (violations.length > 0) {+ throw new Error(+ `Ambiguous-name rig dial found — 'localhost' resolves '::1'-first, exactly the loopback-specific slot ` ++ `a foreign process can hold while the rig sits on a wildcard (or single-family) bind. Dial the ` ++ `literal address the rig actually bound (e.g. http://127.0.0.1:\${port}):\n${violations.join('\n')}`,+ );+ }+ });++ test('listen predicate fires on planted violations and not on adjacent negatives', () => {+ expect(findNonLoopbackListenCalls([' server.listen(0, () => {']).length).toBe(1);+ expect(findNonLoopbackListenCalls([' await new Promise((r) => s.listen(0, r));']).length).toBe(+ 1,+ );+ expect(+ findNonLoopbackListenCalls([' httpServer.listen(port, () => resolve());']).length,+ ).toBe(1);++ expect(findNonLoopbackListenCalls([" server.listen(0, '127.0.0.1', resolve);"]).length).toBe(+ 0,+ );+ expect(findNonLoopbackListenCalls([" s.listen(port, '::1', cb);"]).length).toBe(0);++ expect(+ findNonLoopbackListenCalls([' server.listen(', ' 0,', " '127.0.0.1',", ' cb)'])+ .length,+ ).toBe(0);++ expect(findNonLoopbackListenCalls([' // before httpServer.listen() resolves']).length).toBe(0);+ expect(+ findNonLoopbackListenCalls([' * boot scan runs BEFORE httpServer.listen().']).length,+ ).toBe(0);++ expect(findNonLoopbackListenCalls([' s.listen(port, host, cb);']).length).toBe(1);++ expect(findNonLoopbackListenCalls([" s.listen(0, '0.0.0.0', cb);"]).length).toBe(1);+ });++ test('dial predicate fires on planted violations and not on adjacent negatives', () => {+ expect(+ findAmbiguousLocalhostDials([+ ` const res = await fetch(\`http://localhost:\${port}\${path}\`);`,+ ]).length,+ ).toBe(1);+ expect(+ findAmbiguousLocalhostDials([` url: \`ws://localhost:\${port}/collab\`,`]).length,+ ).toBe(1);++ expect(+ findAmbiguousLocalhostDials([` const res = await fetch(\`http://127.0.0.1:\${port}/x\`);`])+ .length,+ ).toBe(0);++ expect(+ findAmbiguousLocalhostDials([" expect(url).toBe('ws://localhost:7777/collab');"]).length,+ ).toBe(0);++ expect(findAmbiguousLocalhostDials([` // dials http://localhost:\${port} today`]).length).toBe(+ 0,+ );++ expect(findAmbiguousLocalhostDials([" host: 'localhost:5173',"]).length).toBe(0);+ });+});diff --git a/packages/server/src/loopback-rig-test-helpers.ts b/packages/server/src/loopback-rig-test-helpers.tsnew file mode 100644index 000000000..848bfad11--- /dev/null+++ b/packages/server/src/loopback-rig-test-helpers.ts@@ -0,0 +1,44 @@+import type { Server } from 'node:http';+import { createServer } from 'node:http';++export interface LoopbackListenResult {+ port: number;+ baseUrl: string;+}++export function listenOnLoopback(server: Server): Promise<LoopbackListenResult> {+ return new Promise((resolve, reject) => {+ server.once('error', reject);+ server.listen(0, '127.0.0.1', () => {+ const addr = server.address();+ if (typeof addr !== 'object' || addr === null) {+ server.removeListener('error', reject);+ server.close(() =>+ reject(new Error('listenOnLoopback: server.address() returned no port')),+ );+ return;+ }+ server.removeListener('error', reject);+ resolve({ port: addr.port, baseUrl: `http://127.0.0.1:${addr.port}` });+ });+ });+}++export function getFreeLoopbackPort(): Promise<number> {+ return new Promise((resolve, reject) => {+ const probe = createServer();+ probe.once('error', reject);+ probe.listen(0, '127.0.0.1', () => {+ const addr = probe.address();+ if (typeof addr !== 'object' || addr === null) {+ probe.removeListener('error', reject);+ probe.close(() =>+ reject(new Error('getFreeLoopbackPort: probe.address() returned no port')),+ );+ return;+ }+ const { port } = addr;+ probe.close(() => resolve(port));+ });+ });+}diff --git a/packages/server/src/mcp-http.test.ts b/packages/server/src/mcp-http.test.tsindex 2a86ea789..ea7846fee 100644--- a/packages/server/src/mcp-http.test.ts+++ b/packages/server/src/mcp-http.test.ts@@ -1,11 +1,11 @@import { afterEach, beforeEach, expect, test } from 'bun:test';import { mkdtempSync, rmSync } from 'node:fs';import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';-import { type AddressInfo, createServer as createNetServer } from 'node:net';import { tmpdir } from 'node:os';import { join } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';import { type Config, ConfigSchema } from './config/schema.ts';+import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';import { MCP_CONNECTION_ID_HEADER } from './mcp/agent-identity.ts';import {createMcpHttpHandler,@@ -21,22 +21,12 @@ interface SessionHarness {cleanup: () => Promise<void>;}-async function getFreePort(): Promise<number> {- return new Promise((res) => {- const s = createNetServer();- s.listen(0, () => {- const port = (s.address() as AddressInfo).port;- s.close(() => res(port));- });- });-}-async function bootHandler(config: Config,handlerOptions: Partial<Pick<McpHttpHandlerOptions, 'log' | 'maxSessions' | 'sessionTtlMs'>> = {},): Promise<SessionHarness> {const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cfg-'));- const port = await getFreePort();+ const port = await getFreeLoopbackPort();let handler: McpHttpHandler | null = null;let httpServer: HttpServer | null = null;try {@@ -44,7 +34,7 @@ async function bootHandler(contentDir,projectDir: contentDir,config,- getServerUrl: () => `http://localhost:${port}`,+ getServerUrl: () => `http://127.0.0.1:${port}`,...handlerOptions,});@@ -65,7 +55,7 @@ async function bootHandler(});await new Promise<void>((res) => {// biome-ignore lint/style/noNonNullAssertion: httpServer is set inside the try- httpServer!.listen(port, () => res());+ httpServer!.listen(port, '127.0.0.1', () => res());});} catch (err) {if (httpServer) await new Promise<void>((res) => httpServer?.close(() => res()));@@ -93,7 +83,7 @@ interface InitializedSession {}async function openMcpSession(port: number): Promise<InitializedSession> {- const init = await fetch(`http://localhost:${port}/mcp`, {+ const init = await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -118,7 +108,7 @@ async function openMcpSession(port: number): Promise<InitializedSession> {};const protocolVersion = initBody.result?.protocolVersion ?? MCP_PROTOCOL_VERSION;- const initialized = await fetch(`http://localhost:${port}/mcp`, {+ const initialized = await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -151,7 +141,7 @@ test('active MCP session cap refuses new sessions before allocation', async () =await openMcpSession(harness.port);- const second = await fetch(`http://localhost:${harness.port}/mcp`, {+ const second = await fetch(`http://127.0.0.1:${harness.port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -181,7 +171,7 @@ test('mcp-tool-path-traversal: explicit cwd outside configured project root is rconst session = await openMcpSession(harness.port);const callExec = async (cwd: string) =>- fetch(`http://localhost:${harness.port}/mcp`, {+ fetch(`http://127.0.0.1:${harness.port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -217,7 +207,7 @@ test('PRD-6659: tools/call write with an invalid position returns field name + aconst session = await openMcpSession(harness.port);- const callRes = await fetch(`http://localhost:${harness.port}/mcp`, {+ const callRes = await fetch(`http://127.0.0.1:${harness.port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -254,7 +244,7 @@ test('PRD-6659: tools/call write with an invalid position returns field name + atest('forwarded connectionId header reaches /api/agent-write-md as agentId', async () => {const config: Config = ConfigSchema.parse({});const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cid-'));- const port = await getFreePort();+ const port = await getFreeLoopbackPort();let handler: McpHttpHandler | null = null;let httpServer: HttpServer | null = null;let capturedAgentId: string | undefined;@@ -264,7 +254,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asycontentDir,projectDir: contentDir,config,- getServerUrl: () => `http://localhost:${port}`,+ getServerUrl: () => `http://127.0.0.1:${port}`,});httpServer = createHttpServer((req, res) => {@@ -299,12 +289,12 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy});await new Promise<void>((res) => {// biome-ignore lint/style/noNonNullAssertion: httpServer set above- httpServer!.listen(port, () => res());+ httpServer!.listen(port, '127.0.0.1', () => res());});const forwarded = 'forwarded-keepalive-id-1234';- const init = await fetch(`http://localhost:${port}/mcp`, {+ const init = await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -328,7 +318,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asyconst initBody = (await init.json()) as { result?: { protocolVersion?: string } };const protocolVersion = initBody.result?.protocolVersion ?? MCP_PROTOCOL_VERSION;- const initialized = await fetch(`http://localhost:${port}/mcp`, {+ const initialized = await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -340,7 +330,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy});expect(initialized.status).toBe(202);- const call = await fetch(`http://localhost:${port}/mcp`, {+ const call = await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -376,7 +366,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asytest('invalid connectionId header is ignored — session falls back to a fresh UUID', async () => {const config: Config = ConfigSchema.parse({});const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cid-bad-'));- const port = await getFreePort();+ const port = await getFreeLoopbackPort();let handler: McpHttpHandler | null = null;let httpServer: HttpServer | null = null;let capturedAgentId: string | undefined;@@ -387,7 +377,7 @@ test('invalid connectionId header is ignored — session falls back to a fresh UcontentDir,projectDir: contentDir,config,- getServerUrl: () => `http://localhost:${port}`,+ getServerUrl: () => `http://127.0.0.1:${port}`,log: {warn: (obj, msg) => {warnCalls.push({ obj, msg });@@ -427,12 +417,12 @@ test('invalid connectionId header is ignored — session falls back to a fresh U});await new Promise<void>((res) => {// biome-ignore lint/style/noNonNullAssertion: httpServer set above- httpServer!.listen(port, () => res());+ httpServer!.listen(port, '127.0.0.1', () => res());});const forwarded = 'bad value with spaces!';- const init = await fetch(`http://localhost:${port}/mcp`, {+ const init = await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -454,7 +444,7 @@ test('invalid connectionId header is ignored — session falls back to a fresh Uconst sessionId = init.headers.get('mcp-session-id') as string;const initBody = (await init.json()) as { result?: { protocolVersion?: string } };const protocolVersion = initBody.result?.protocolVersion ?? MCP_PROTOCOL_VERSION;- await fetch(`http://localhost:${port}/mcp`, {+ await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -465,7 +455,7 @@ test('invalid connectionId header is ignored — session falls back to a fresh Ubody: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),});- const call = await fetch(`http://localhost:${port}/mcp`, {+ const call = await fetch(`http://127.0.0.1:${port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',@@ -516,7 +506,7 @@ test('inactive MCP sessions expire and return 404 on later use', async () => {const session = await openMcpSession(harness.port);await wait(350);- const expired = await fetch(`http://localhost:${harness.port}/mcp`, {+ const expired = await fetch(`http://127.0.0.1:${harness.port}/mcp`, {method: 'POST',headers: {accept: 'application/json, text/event-stream',diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.tsindex 2bdb7835d..4d9ace0f4 100644--- a/packages/server/src/mcp-mount.test.ts+++ b/packages/server/src/mcp-mount.test.ts@@ -1,11 +1,7 @@import { afterEach, describe, expect, test } from 'bun:test';import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';import { createServer, type Server as HttpServer, request as httpRequest } from 'node:http';-import {- type AddressInfo,- connect as createNetConnection,- createServer as createNetServer,-} from 'node:net';+import { connect as createNetConnection } from 'node:net';import { tmpdir } from 'node:os';import { join } from 'node:path';import type { Hocuspocus } from '@hocuspocus/server';@@ -16,6 +12,7 @@ import {} from '@inkeep/open-knowledge-core';import sirv from 'sirv';import { createAssetServeMiddleware } from './asset-serve-middleware.ts';+import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';import type { McpHttpHandler } from './mcp-http.ts';import {type MountMcpAndApiHandle,@@ -41,16 +38,6 @@ const hocuspocus = {let servers: Array<{ httpServer: HttpServer; mount: MountMcpAndApiHandle }> = [];-async function getFreePort(): Promise<number> {- return new Promise((resolve) => {- const server = createNetServer();- server.listen(0, () => {- const port = (server.address() as AddressInfo).port;- server.close(() => resolve(port));- });- });-}-async function startMountedServer(handler: McpHttpHandler): Promise<{ port: number }> {const httpServer = createServer();const mount = mountMcpAndApi({@@ -59,7 +46,7 @@ async function startMountedServer(handler: McpHttpHandler): Promise<{ port: numbmcpHttpHandler: handler,log,});- const port = await getFreePort();+ const port = await getFreeLoopbackPort();await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));servers.push({ httpServer, mount });return { port };@@ -279,7 +266,7 @@ describe('mountMcpAndApi content-asset middleware', () => {blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,}),});- const port = await getFreePort();+ const port = await getFreeLoopbackPort();await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));servers.push({ httpServer, mount });return { port };@@ -334,7 +321,7 @@ describe('mountMcpAndApi content-asset middleware', () => {throw new Error('simulated EMFILE');},});- const port = await getFreePort();+ const port = await getFreeLoopbackPort();await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));servers.push({ httpServer, mount });@@ -377,7 +364,7 @@ describe('mountMcpAndApi ephemeral content-asset gate', () => {blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,}),});- const port = await getFreePort();+ const port = await getFreeLoopbackPort();await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));servers.push({ httpServer, mount });return { port };@@ -440,7 +427,7 @@ describe('mountMcpAndApi react-shell middleware', () => {immutable: true,}),});- const port = await getFreePort();+ const port = await getFreeLoopbackPort();await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));servers.push({ httpServer, mount });return { port, shellDir };diff --git a/packages/server/src/mcp/tools/checkpoint.test.ts b/packages/server/src/mcp/tools/checkpoint.test.tsindex fcd9ca563..6dee2e505 100644--- a/packages/server/src/mcp/tools/checkpoint.test.ts+++ b/packages/server/src/mcp/tools/checkpoint.test.ts@@ -57,6 +57,7 @@ const seenBodies: Array<Record<string, unknown>> = [];beforeAll(() => {testServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',async fetch(req) {const url = new URL(req.url);const body = req.method === 'POST' ? ((await req.json()) as Record<string, unknown>) : {};@@ -70,7 +71,7 @@ beforeAll(() => {return new Response('Not found', { status: 404 });},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => testServer.stop());beforeEach(async () => {diff --git a/packages/server/src/mcp/tools/conflicts.test.ts b/packages/server/src/mcp/tools/conflicts.test.tsindex 9582203c8..a15785e83 100644--- a/packages/server/src/mcp/tools/conflicts.test.ts+++ b/packages/server/src/mcp/tools/conflicts.test.ts@@ -39,6 +39,7 @@ const cwd = mkdtempSync(join(tmpdir(), 'ok-conflicts-test-'));beforeAll(() => {testServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',fetch(req) {const url = new URL(req.url);if (url.pathname === '/api/sync/conflicts') {@@ -61,7 +62,7 @@ beforeAll(() => {return new Response('Not found', { status: 404 });},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => testServer.stop());diff --git a/packages/server/src/mcp/tools/history.test.ts b/packages/server/src/mcp/tools/history.test.tsindex 4d98ffea3..dfbf211aa 100644--- a/packages/server/src/mcp/tools/history.test.ts+++ b/packages/server/src/mcp/tools/history.test.ts@@ -52,6 +52,7 @@ let baseUrl: string;beforeAll(() => {testServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',fetch(req) {const url = new URL(req.url);if (url.pathname === '/api/history') {@@ -74,7 +75,7 @@ beforeAll(() => {return new Response('Not found', { status: 404 });},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => {diff --git a/packages/server/src/mcp/tools/links.test.ts b/packages/server/src/mcp/tools/links.test.tsindex b6a4e49ed..e0f8d8379 100644--- a/packages/server/src/mcp/tools/links.test.ts+++ b/packages/server/src/mcp/tools/links.test.ts@@ -84,6 +84,7 @@ const seenRequests: string[] = [];beforeAll(() => {testServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',fetch(req) {const url = new URL(req.url);seenRequests.push(`${url.pathname}?${url.searchParams.toString()}`);@@ -154,7 +155,7 @@ beforeAll(() => {}},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => {diff --git a/packages/server/src/mcp/tools/restore-version.test.ts b/packages/server/src/mcp/tools/restore-version.test.tsindex f74d63a9d..8845f1ba0 100644--- a/packages/server/src/mcp/tools/restore-version.test.ts+++ b/packages/server/src/mcp/tools/restore-version.test.ts@@ -65,6 +65,7 @@ let mockRollbackWarning: Record<string, unknown> | undefined;beforeAll(() => {testServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',async fetch(req) {const url = new URL(req.url);const body = req.method === 'POST' ? ((await req.json()) as Record<string, unknown>) : {};@@ -84,7 +85,7 @@ beforeAll(() => {return new Response('Not found', { status: 404 });},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => testServer.stop());beforeEach(async () => {diff --git a/packages/server/src/mcp/tools/share-link.test.ts b/packages/server/src/mcp/tools/share-link.test.tsindex 82244597f..fb39fd0e9 100644--- a/packages/server/src/mcp/tools/share-link.test.ts+++ b/packages/server/src/mcp/tools/share-link.test.ts@@ -69,6 +69,7 @@ let mockRawResponse: Response | null = null;beforeAll(() => {testServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',async fetch(req) {const url = new URL(req.url);const body = req.method === 'POST' ? ((await req.json()) as Record<string, unknown>) : {};@@ -83,7 +84,7 @@ beforeAll(() => {return new Response('Not found', { status: 404 });},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => {diff --git a/packages/server/src/mcp/tools/shared.test.ts b/packages/server/src/mcp/tools/shared.test.tsindex 40155e84a..dd08cf9b6 100644--- a/packages/server/src/mcp/tools/shared.test.ts+++ b/packages/server/src/mcp/tools/shared.test.ts@@ -313,6 +313,7 @@ let baseUrl: string;beforeAll(() => {testServer = Bun.serve({port: 0, // random available port+ hostname: '127.0.0.1',fetch(req) {const url = new URL(req.url);@@ -395,7 +396,7 @@ beforeAll(() => {return new Response('Not found', { status: 404 });},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => {@@ -538,10 +539,11 @@ describe('normalizeResponse — RFC 9457 + flat success', () => {test('non-RFC-9457 5xx with no error/message → generic HTTP-status sentence', async () => {const stripeServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',fetch: () => Response.json({ unrelated: true }, { status: 503 }),});try {- const result = await httpGet(`http://localhost:${stripeServer.port}`, '/anything');+ const result = await httpGet(`http://127.0.0.1:${stripeServer.port}`, '/anything');expect(result.ok).toBe(false);expect(result.error).toBe('Server returned HTTP 503');expect(result.unrelated).toBe(true);@@ -553,10 +555,11 @@ describe('normalizeResponse — RFC 9457 + flat success', () => {test('non-RFC-9457 4xx with body.error string → `error` ← body.error', async () => {const stubServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',fetch: () => Response.json({ error: 'rate limited', message: 'try again' }, { status: 429 }),});try {- const result = await httpGet(`http://localhost:${stubServer.port}`, '/anything');+ const result = await httpGet(`http://127.0.0.1:${stubServer.port}`, '/anything');expect(result.ok).toBe(false);expect(result.error).toBe('rate limited');} finally {diff --git a/packages/server/src/mcp/tools/summary-passthrough.test.ts b/packages/server/src/mcp/tools/summary-passthrough.test.tsindex f5986d094..8a6e9cafb 100644--- a/packages/server/src/mcp/tools/summary-passthrough.test.ts+++ b/packages/server/src/mcp/tools/summary-passthrough.test.ts@@ -78,6 +78,7 @@ let tmpDir: string;beforeAll(() => {testServer = Bun.serve({port: 0,+ hostname: '127.0.0.1',async fetch(req) {const url = new URL(req.url);if (req.method === 'GET') {@@ -100,7 +101,7 @@ beforeAll(() => {});},});- baseUrl = `http://localhost:${testServer.port}`;+ baseUrl = `http://127.0.0.1:${testServer.port}`;});afterAll(() => {diff --git a/packages/server/src/rig-loopback-exclusivity.test.ts b/packages/server/src/rig-loopback-exclusivity.test.tsnew file mode 100644index 000000000..077e940ad--- /dev/null+++ b/packages/server/src/rig-loopback-exclusivity.test.ts@@ -0,0 +1,115 @@+import { afterEach, describe, expect, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { createServer, type RequestListener, type Server } from 'node:http';+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';++interface RigSeam {+ server: Server;+ port: number;+ baseUrl: string;+}++async function bootRigSeam(handler: RequestListener): Promise<RigSeam> {+ const server = createServer(handler);+ const { port, baseUrl } = await listenOnLoopback(server);+ return { server, port, baseUrl };+}++interface ForeignMarker {+ host: string;+ close: () => Promise<void>;+}++function tryBindForeignMarker(+ host: '127.0.0.1' | '::1',+ port: number,+ markerToken: string,+): Promise<ForeignMarker | 'rig-owned' | 'family-unavailable'> {+ return new Promise((resolve, reject) => {+ const s = createServer((_req, res) => {+ res.writeHead(200, {+ 'content-type': 'application/json',+ 'x-foreign-marker': markerToken,+ });+ res.end(JSON.stringify({ foreignMarker: markerToken, answeredOn: host }));+ });+ s.on('error', (err: NodeJS.ErrnoException) => {+ if (err.code === 'EADDRINUSE') resolve('rig-owned');+ else if (err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')+ resolve('family-unavailable');+ else reject(err);+ });+ s.listen(port, host === '::1' ? '::1' : '127.0.0.1', () => {+ resolve({+ host,+ close: () => new Promise<void>((r) => s.close(() => r())),+ });+ });+ });+}++function dialedLoopbackAddresses(baseUrl: string): Array<'127.0.0.1' | '::1'> {+ const hostname = new URL(baseUrl).hostname;+ if (hostname === 'localhost') return ['127.0.0.1', '::1'];+ if (hostname === '127.0.0.1') return ['127.0.0.1'];+ if (hostname === '::1' || hostname === '[::1]') return ['::1'];+ throw new Error(`rig advertises a non-loopback dial host: ${hostname}`);+}++describe('rig loopback exclusivity', () => {+ const cleanups: Array<() => Promise<void>> = [];+ afterEach(async () => {+ const errors: unknown[] = [];+ while (cleanups.length > 0) {+ const fn = cleanups.pop();+ if (!fn) continue;+ try {+ await fn();+ } catch (err) {+ errors.push(err);+ }+ }+ if (errors.length > 0)+ throw new AggregateError(errors, 'rig-loopback-exclusivity cleanup failed');+ });++ test('client dial reaches the rig even when a foreign loopback-specific listener squats the rig port', async () => {+ const rigToken = randomUUID();+ const { server, port, baseUrl } = await bootRigSeam((_req, res) => {+ res.writeHead(200, { 'content-type': 'application/json' });+ res.end(JSON.stringify({ rigToken }));+ });+ cleanups.push(() => new Promise<void>((r) => server.close(() => r())));++ const markerToken = `foreign-${randomUUID()}`;+ for (const host of ['127.0.0.1', '::1'] as const) {+ const marker = await tryBindForeignMarker(host, port, markerToken);+ if (typeof marker === 'object') cleanups.push(marker.close);+ }++ const res = await fetch(`${baseUrl}/whoami`);+ const body = (await res.json()) as Record<string, unknown>;++ expect(res.headers.get('x-foreign-marker')).toBeNull();+ expect(body).toEqual({ rigToken });+ });++ test('rig exclusively owns every loopback address its client URL can resolve to', async () => {+ const { server, port, baseUrl } = await bootRigSeam((_req, res) => {+ res.end('ok');+ });+ cleanups.push(() => new Promise<void>((r) => server.close(() => r())));++ const squattable: string[] = [];+ for (const host of dialedLoopbackAddresses(baseUrl)) {+ const marker = await tryBindForeignMarker(host, port, 'exclusivity-probe');+ if (marker === 'family-unavailable') continue;+ if (typeof marker === 'object') {+ squattable.push(host);+ cleanups.push(marker.close);+ }+ }++ expect(squattable).toEqual([]);+ });+});diff --git a/packages/server/src/share/construct-url.test.ts b/packages/server/src/share/construct-url.test.tsindex 04a23a94a..e210969b9 100644--- a/packages/server/src/share/construct-url.test.ts+++ b/packages/server/src/share/construct-url.test.ts@@ -298,7 +298,7 @@ describe('POST /api/share/construct-url', () => {branchesOnOrigin: ['main'],});});- const res = await fetch(`http://localhost:${rig.port}/api/share/construct-url`);+ const res = await fetch(`http://127.0.0.1:${rig.port}/api/share/construct-url`);expect(res.status).toBe(405);});diff --git a/packages/server/src/share/publish.integration.test.ts b/packages/server/src/share/publish.integration.test.tsindex 7c9f930a1..5ceb7c634 100644--- a/packages/server/src/share/publish.integration.test.ts+++ b/packages/server/src/share/publish.integration.test.ts@@ -4,6 +4,7 @@ import { mkdtemp, rm } from 'node:fs/promises';import type { Server } from 'node:http';import { tmpdir } from 'node:os';import { join } from 'node:path';+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';import type { SyncEngine } from '../sync-engine.ts';function makeFakeSyncEngine(): { engine: SyncEngine; refreshRemoteCalls: () => number } {@@ -21,6 +22,7 @@ function makeFakeSyncEngine(): { engine: SyncEngine; refreshRemoteCalls: () => ninterface TestRig {port: number;+ baseUrl: string;projectDir: string;server: Server;cleanup: () => Promise<void>;@@ -72,15 +74,11 @@ async function bootRig(options: RigOptions): Promise<TestRig> {});hocuspocus.configuration.extensions.push(ext);- const port = await new Promise<number>((resolveListen) => {- server.listen(0, () => {- const addr = server.address();- resolveListen(typeof addr === 'object' && addr ? addr.port : 0);- });- });+ const { port, baseUrl } = await listenOnLoopback(server);return {port,+ baseUrl,projectDir,server,cleanup: async () => {@@ -91,7 +89,7 @@ async function bootRig(options: RigOptions): Promise<TestRig> {}async function getJson(port: number, path: string): Promise<{ status: number; body: unknown }> {- const res = await fetch(`http://localhost:${port}${path}`);+ const res = await fetch(`http://127.0.0.1:${port}${path}`);return { status: res.status, body: await res.json() };}@@ -100,7 +98,7 @@ async function postJson(path: string,body: unknown,): Promise<{ status: number; body: unknown }> {- const res = await fetch(`http://localhost:${port}${path}`, {+ const res = await fetch(`http://127.0.0.1:${port}${path}`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify(body),@@ -157,7 +155,7 @@ describe('GET /api/share/publish/owners', () => {test('rejects POST with 405', async () => {rig = await bootRig({ cliArgs: fixtureCliArgs('{}') });- const res = await fetch(`http://localhost:${rig.port}/api/share/publish/owners`, {+ const res = await fetch(`${rig.baseUrl}/api/share/publish/owners`, {method: 'POST',});expect(res.status).toBe(405);@@ -202,9 +200,7 @@ describe('GET /api/share/publish/name-check', () => {`process.stderr.write("FIXTURE INVOKED — should not happen for invalid owner");process.exit(99);`,],});- const res = await fetch(- `http://localhost:${rig.port}/api/share/publish/name-check?owner=-bad&name=foo`,- );+ const res = await fetch(`${rig.baseUrl}/api/share/publish/name-check?owner=-bad&name=foo`);expect(res.status).toBe(400);});@@ -213,7 +209,7 @@ describe('GET /api/share/publish/name-check', () => {cliArgs: [process.execPath, '-e', `process.exit(99);`],});const res = await fetch(- `http://localhost:${rig.port}/api/share/publish/name-check?owner=alice&name=with%2Fslash`,+ `${rig.baseUrl}/api/share/publish/name-check?owner=alice&name=with%2Fslash`,);expect(res.status).toBe(400);});@@ -322,7 +318,7 @@ describe('POST /api/share/publish', () => {rig = await bootRig({cliArgs: [process.execPath, '-e', `process.exit(99);`],});- const res = await fetch(`http://localhost:${rig.port}/api/share/publish`, {+ const res = await fetch(`${rig.baseUrl}/api/share/publish`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ owner: 'alice', name: 'demo', visibility: 'lobster' }),@@ -334,7 +330,7 @@ describe('POST /api/share/publish', () => {rig = await bootRig({cliArgs: [process.execPath, '-e', `process.exit(99);`],});- const res = await fetch(`http://localhost:${rig.port}/api/share/publish`, {+ const res = await fetch(`${rig.baseUrl}/api/share/publish`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ owner: 'alice', name: 'with space', visibility: 'private' }),@@ -344,7 +340,7 @@ describe('POST /api/share/publish', () => {test('GET method rejected with 405', async () => {rig = await bootRig({ cliArgs: fixtureCliArgs('{}') });- const res = await fetch(`http://localhost:${rig.port}/api/share/publish`);+ const res = await fetch(`${rig.baseUrl}/api/share/publish`);expect(res.status).toBe(405);});