@openparachute/hub 0.5.2 → 0.5.7

package/src/__tests__/port-assign.test.ts

@@ -74,103 +74,92 @@ describe("assignPort (pure)", () => {
   });
 });
 
-describe("assignServicePort (.env round-trip)", () => {
-  test("preserves an existing PORT in .env (idempotent re-install)", () => {
+describe("assignServicePort (hub#206 — services.json is authoritative)", () => {
+  // Post-hub#206 assignServicePort is a thin wrapper over assignPort: the
+  // install path no longer touches the service's .env, since services.json
+  // is the single source of truth and the duplicate state caused drift on
+  // re-install. These tests pin the new contract:
+  //   1. The function returns the assigned port + source/warning.
+  //   2. It does not write to .env. Pre-existing .env files are untouched
+  //      (no PORT line added, no PORT line removed, no other lines mutated).
+  //   3. There's no "preserved" source — a stale .env PORT does NOT survive
+  //      a re-install (operators edit services.json now).
+
+  test("returns canonical when free, does not touch .env", () => {
     const { dir, cleanup } = makeTempDir();
     try {
-      const envPath = join(dir, ".env");
-      writeFileSync(envPath, "PORT=1944\nOTHER=keepme\n");
+      const envPath = join(dir, "subdir", ".env");
       const result = assignServicePort({
-        envPath,
         canonical: 1940,
-        // Even though canonical is free, the existing .env wins.
         occupied: [],
       });
-      expect(result.port).toBe(1944);
-      expect(result.source).toBe("preserved");
-      expect(result.written).toBe(false);
-      // File untouched — no rewrite means OTHER stays as-is.
-      const text = readFileSync(envPath, "utf8");
-      expect(text).toContain("PORT=1944");
-      expect(text).toContain("OTHER=keepme");
+      expect(result.port).toBe(1940);
+      expect(result.source).toBe("canonical");
+      expect(result.warning).toBeUndefined();
+      // No .env file gets created — subdir doesn't even exist.
+      expect(existsSync(envPath)).toBe(false);
     } finally {
       cleanup();
     }
   });
 
-  test("writes PORT into a fresh .env when canonical is free", () => {
+  test("does NOT preserve a pre-existing PORT in .env (services.json is authoritative)", () => {
+    // Pre-hub#206 a stale `.env` PORT survived a re-install — operators
+    // editing services.json would get re-stamped by the .env. Post-#206
+    // services.json wins; the .env PORT is ignored at install time and
+    // also at boot (per the 4-tier ladder in scribe/agent).
     const { dir, cleanup } = makeTempDir();
     try {
-      const envPath = join(dir, "subdir", ".env");
+      const envPath = join(dir, ".env");
+      const before = "PORT=1944\nOTHER=keepme\n";
+      writeFileSync(envPath, before);
       const result = assignServicePort({
-        envPath,
         canonical: 1940,
         occupied: [],
       });
+      // We assigned the canonical port, NOT the stale 1944 from .env.
       expect(result.port).toBe(1940);
       expect(result.source).toBe("canonical");
-      expect(result.written).toBe(true);
-      expect(result.warning).toBeUndefined();
-      expect(existsSync(envPath)).toBe(true);
-      expect(readFileSync(envPath, "utf8")).toContain("PORT=1940");
+      // The .env file is bit-for-bit untouched — PORT line and other lines
+      // both stay. (No new PORT line written, no existing PORT rewritten.)
+      const after = readFileSync(envPath, "utf8");
+      expect(after).toBe(before);
     } finally {
       cleanup();
     }
   });
 
-  test("writes a fallback PORT and surfaces the warning when canonical is occupied", () => {
+  test("returns fallback port and warning when canonical is occupied; .env untouched", () => {
     const { dir, cleanup } = makeTempDir();
     try {
       const envPath = join(dir, ".env");
+      // Pre-existing .env with non-PORT content.
+      const before = "FOO=bar\n";
+      writeFileSync(envPath, before);
       const result = assignServicePort({
-        envPath,
         canonical: 1940,
         occupied: [1940],
       });
       expect(result.port).toBe(1944);
       expect(result.source).toBe("fallback-in-range");
-      expect(result.written).toBe(true);
       expect(result.warning).toMatch(/canonical port 1940 is in use/);
-      expect(readFileSync(envPath, "utf8")).toContain("PORT=1944");
-    } finally {
-      cleanup();
-    }
-  });
-
-  test("ignores a non-numeric PORT and assigns a fresh one", () => {
-    const { dir, cleanup } = makeTempDir();
-    try {
-      const envPath = join(dir, ".env");
-      writeFileSync(envPath, "PORT=garbage\n");
-      const result = assignServicePort({
-        envPath,
-        canonical: 1940,
-        occupied: [],
-      });
-      expect(result.port).toBe(1940);
-      expect(result.written).toBe(true);
-      // The garbage value got upserted to a real number.
-      expect(readFileSync(envPath, "utf8")).toContain("PORT=1940");
+      // .env stays bit-for-bit identical.
+      expect(readFileSync(envPath, "utf8")).toBe(before);
     } finally {
       cleanup();
     }
   });
 
-  test("preserves surrounding lines on rewrite", () => {
+  test("third-party (no canonical) gets first reservation slot; no .env created", () => {
     const { dir, cleanup } = makeTempDir();
     try {
       const envPath = join(dir, ".env");
-      writeFileSync(envPath, "FOO=bar\nBAZ=qux\n");
       const result = assignServicePort({
-        envPath,
-        canonical: 1940,
         occupied: [],
       });
-      expect(result.written).toBe(true);
-      const text = readFileSync(envPath, "utf8");
-      expect(text).toContain("FOO=bar");
-      expect(text).toContain("BAZ=qux");
-      expect(text).toContain("PORT=1940");
+      expect(result.port).toBe(1944);
+      expect(result.source).toBe("fallback-in-range");
+      expect(existsSync(envPath)).toBe(false);
     } finally {
       cleanup();
     }

package/src/__tests__/rate-limit.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  MAX_ATTEMPTS,
+  UNKNOWN_IP_SENTINEL,
+  WINDOW_MS,
+  __resetForTests,
+  checkAndRecord,
+  clientIpFromRequest,
+} from "../rate-limit.ts";
+
+afterEach(() => {
+  __resetForTests();
+});
+
+describe("checkAndRecord — bucket fill / drain", () => {
+  test("admits the first MAX_ATTEMPTS attempts; denies the next one with Retry-After", () => {
+    const now = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      const r = checkAndRecord("ip-a", now);
+      expect(r.allowed).toBe(true);
+      expect(r.retryAfterSeconds).toBeUndefined();
+    }
+    const denied = checkAndRecord("ip-a", now);
+    expect(denied.allowed).toBe(false);
+    expect(denied.retryAfterSeconds).toBeDefined();
+    // 5 attempts at the same instant; window length 15 min = 900s. Reset is
+    // exactly WINDOW_MS later, so retry-after === WINDOW_MS / 1000.
+    expect(denied.retryAfterSeconds).toBe(WINDOW_MS / 1000);
+  });
+
+  test("bucket drains: attempt is admitted again once the window passes", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    const stillDenied = checkAndRecord("ip-a", new Date(t0.getTime() + WINDOW_MS - 1000));
+    expect(stillDenied.allowed).toBe(false);
+
+    // Advance past the window — all five timestamps fall off, slot opens.
+    const past = new Date(t0.getTime() + WINDOW_MS + 1000);
+    const allowed = checkAndRecord("ip-a", past);
+    expect(allowed.allowed).toBe(true);
+  });
+
+  test("partial drain: oldest entry falling off opens exactly one slot", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    // Spread 5 attempts 1 minute apart so they fall off the window
+    // individually rather than as a cohort.
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", new Date(t0.getTime() + i * 60_000));
+    }
+    // Right at the 5th-minute mark, all 5 are in window → denied.
+    const denied = checkAndRecord("ip-a", new Date(t0.getTime() + 5 * 60_000));
+    expect(denied.allowed).toBe(false);
+
+    // Step past WINDOW_MS from the *first* attempt (t0) → that one falls
+    // off, so we should be admitted.
+    const partial = new Date(t0.getTime() + WINDOW_MS + 1000);
+    const r = checkAndRecord("ip-a", partial);
+    expect(r.allowed).toBe(true);
+  });
+
+  test("denied attempts do not push the reset further into the future", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    // Five denials over 30 seconds. The reset moment must be anchored to the
+    // 5 admitted attempts at t0, NOT to the latest denial.
+    for (let i = 1; i <= 5; i++) {
+      checkAndRecord("ip-a", new Date(t0.getTime() + i * 6000));
+    }
+    const finalCheck = checkAndRecord("ip-a", new Date(t0.getTime() + 30_000));
+    expect(finalCheck.allowed).toBe(false);
+    // 30 seconds elapsed; expected ~870s remaining. Tolerance ±2s for
+    // ceil-rounding edge.
+    const expected = Math.ceil((WINDOW_MS - 30_000) / 1000);
+    expect(finalCheck.retryAfterSeconds).toBe(expected);
+  });
+
+  test("Retry-After is always at least 1 second at the boundary", () => {
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    // Exactly at the moment the oldest attempt would fall off — clamp to 1.
+    const r = checkAndRecord("ip-a", new Date(t0.getTime() + WINDOW_MS));
+    // At exactly WINDOW_MS, the oldest is gone → admitted, not denied.
+    expect(r.allowed).toBe(true);
+  });
+
+  test("Retry-After natural value is always >= 1 in the deny branch (1ms-remaining case)", () => {
+    // The `Math.max(1, ...)` clamp at rate-limit.ts:90 is defense-in-depth:
+    // the deny branch requires `pruned.length >= MAX_ATTEMPTS`, which means
+    // every retained timestamp is strictly inside the window, so
+    // `resetAtMs - now > 0` strictly, so `Math.ceil(positive / 1000) >= 1`.
+    // This test pins that invariant: at `WINDOW_MS - 1ms` after the cohort,
+    // 1ms remains until the oldest falls off → unclamped value is
+    // `Math.ceil(1 / 1000) = 1`, the minimum natural value.
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    const denied = checkAndRecord("ip-a", new Date(t0.getTime() + WINDOW_MS - 1));
+    expect(denied.allowed).toBe(false);
+    expect(denied.retryAfterSeconds).toBe(1);
+  });
+
+  test("Retry-After is >= 1 across every denied step from t0 to the boundary", () => {
+    // Belt-and-suspenders sweep: walk `now` from t0 up to (but not including)
+    // the boundary in 100ms steps and assert every denied response has
+    // `retryAfterSeconds >= 1`. Locks in the "natural value never drops to
+    // zero in the deny branch" invariant the clamp guards.
+    const t0 = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      checkAndRecord("ip-a", t0);
+    }
+    for (let dt = 0; dt < WINDOW_MS; dt += 100) {
+      const r = checkAndRecord("ip-a", new Date(t0.getTime() + dt));
+      expect(r.allowed).toBe(false);
+      expect(r.retryAfterSeconds).toBeDefined();
+      expect(r.retryAfterSeconds as number).toBeGreaterThanOrEqual(1);
+    }
+  });
+});
+
+describe("checkAndRecord — multi-IP independence", () => {
+  test("exhausting one IP's bucket does not affect another IP", () => {
+    const now = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) checkAndRecord("ip-a", now);
+    expect(checkAndRecord("ip-a", now).allowed).toBe(false);
+
+    // Different IP — fresh bucket.
+    expect(checkAndRecord("ip-b", now).allowed).toBe(true);
+    expect(checkAndRecord("ip-c", now).allowed).toBe(true);
+  });
+
+  test("IPv4 / IPv6 / sentinel are all distinct keys", () => {
+    const now = new Date("2026-05-08T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) checkAndRecord("203.0.113.7", now);
+    expect(checkAndRecord("203.0.113.7", now).allowed).toBe(false);
+    expect(checkAndRecord("2001:db8::42", now).allowed).toBe(true);
+    expect(checkAndRecord(UNKNOWN_IP_SENTINEL, now).allowed).toBe(true);
+  });
+});
+
+describe("clientIpFromRequest — header priority", () => {
+  test("CF-Connecting-IP wins over X-Forwarded-For", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: {
+        "cf-connecting-ip": "203.0.113.7",
+        "x-forwarded-for": "198.51.100.99, 10.0.0.1",
+      },
+    });
+    expect(clientIpFromRequest(req)).toBe("203.0.113.7");
+  });
+
+  test("X-Forwarded-For first hop is used when CF-Connecting-IP is absent", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "x-forwarded-for": "198.51.100.99, 10.0.0.1, 10.0.0.2" },
+    });
+    expect(clientIpFromRequest(req)).toBe("198.51.100.99");
+  });
+
+  test("X-Forwarded-For with whitespace is trimmed", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "x-forwarded-for": "  198.51.100.99  , 10.0.0.1" },
+    });
+    expect(clientIpFromRequest(req)).toBe("198.51.100.99");
+  });
+
+  test("falls through to UNKNOWN_IP_SENTINEL when no headers are set", () => {
+    const req = new Request("http://hub.test/admin/login");
+    expect(clientIpFromRequest(req)).toBe(UNKNOWN_IP_SENTINEL);
+  });
+
+  test("empty / whitespace-only header values are treated as absent", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "cf-connecting-ip": "   ", "x-forwarded-for": "" },
+    });
+    expect(clientIpFromRequest(req)).toBe(UNKNOWN_IP_SENTINEL);
+  });
+
+  test("empty CF-Connecting-IP falls through to X-Forwarded-For first hop", () => {
+    const req = new Request("http://hub.test/admin/login", {
+      headers: { "cf-connecting-ip": "", "x-forwarded-for": "198.51.100.99" },
+    });
+    expect(clientIpFromRequest(req)).toBe("198.51.100.99");
+  });
+});

package/src/__tests__/services-manifest.test.ts

@@ -222,6 +222,347 @@ describe("services-manifest", () => {
       cleanup();
     }
   });
+
+  // Duplicate-port detection (hub#195). The original collision had
+  // parachute-scribe and agent both at 1944 in services.json with no
+  // operator-visible warning. The OS lets only one service bind, the
+  // hub reverse-proxy quietly routes everyone to whoever won the race,
+  // and `/agent` requests silently land on scribe. Reject at parse time
+  // so the same shape can't recur silently. Underlying overwrite bugs
+  // were fixed in parachute-scribe#41 + parachute-agent#146; this is
+  // the hub-side gate.
+  describe("duplicate port rejection", () => {
+    test("rejects manifest where two entries share a port", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        writeFileSync(
+          path,
+          JSON.stringify({
+            services: [
+              {
+                name: "parachute-scribe",
+                port: 1944,
+                paths: ["/scribe"],
+                health: "/scribe/health",
+                version: "0.4.0",
+              },
+              {
+                name: "agent",
+                port: 1944,
+                paths: ["/agent"],
+                health: "/agent/health",
+                version: "0.1.0",
+              },
+            ],
+          }),
+        );
+        expect(() => readManifest(path)).toThrow(ServicesManifestError);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("error message names both conflicting services and the colliding port", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        writeFileSync(
+          path,
+          JSON.stringify({
+            services: [
+              {
+                name: "parachute-scribe",
+                port: 1944,
+                paths: ["/scribe"],
+                health: "/scribe/health",
+                version: "0.4.0",
+              },
+              {
+                name: "agent",
+                port: 1944,
+                paths: ["/agent"],
+                health: "/agent/health",
+                version: "0.1.0",
+              },
+            ],
+          }),
+        );
+        // The error names the conflicting port (so an operator scanning
+        // services.json knows where to look) and both service names (so
+        // they know which two rows to reconcile).
+        expect(() => readManifest(path)).toThrow(/duplicate port 1944/);
+        expect(() => readManifest(path)).toThrow(/parachute-scribe/);
+        expect(() => readManifest(path)).toThrow(/agent/);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("accepts manifest with all unique ports", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        writeFileSync(
+          path,
+          JSON.stringify({
+            services: [
+              {
+                name: "parachute-vault",
+                port: 1940,
+                paths: ["/"],
+                health: "/health",
+                version: "0.2.4",
+              },
+              {
+                name: "parachute-scribe",
+                port: 1943,
+                paths: ["/scribe"],
+                health: "/scribe/health",
+                version: "0.4.0",
+              },
+            ],
+          }),
+        );
+        const m = readManifest(path);
+        expect(m.services).toHaveLength(2);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("allows multi-vault: parachute-vault-default + parachute-vault-techne on the same port", () => {
+      // Multi-vault is the deliberate exception. One parachute-vault process
+      // serves N vault instances on a single port at distinct mount paths.
+      // The duplicate-port gate must not break that shape.
+      const { path, cleanup } = makeTempPath();
+      try {
+        writeFileSync(
+          path,
+          JSON.stringify({
+            services: [
+              {
+                name: "parachute-vault-default",
+                port: 1940,
+                paths: ["/vault/default"],
+                health: "/vault/default/health",
+                version: "0.4.0",
+              },
+              {
+                name: "parachute-vault-techne",
+                port: 1940,
+                paths: ["/vault/techne"],
+                health: "/vault/techne/health",
+                version: "0.4.0",
+              },
+            ],
+          }),
+        );
+        const m = readManifest(path);
+        expect(m.services).toHaveLength(2);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("rejects vault sharing a port with a non-vault service", () => {
+      // The vault exception is narrow: same-port is allowed only between
+      // multi-vault rows. A vault sharing a port with anything else is the
+      // same silent-miswire shape we're guarding against.
+      const { path, cleanup } = makeTempPath();
+      try {
+        writeFileSync(
+          path,
+          JSON.stringify({
+            services: [
+              {
+                name: "parachute-vault-default",
+                port: 1940,
+                paths: ["/vault/default"],
+                health: "/vault/default/health",
+                version: "0.4.0",
+              },
+              {
+                name: "parachute-scribe",
+                port: 1940,
+                paths: ["/scribe"],
+                health: "/scribe/health",
+                version: "0.4.0",
+              },
+            ],
+          }),
+        );
+        expect(() => readManifest(path)).toThrow(/duplicate port 1940/);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("three-way collision still surfaces (first pair caught)", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        writeFileSync(
+          path,
+          JSON.stringify({
+            services: [
+              {
+                name: "a",
+                port: 9000,
+                paths: ["/a"],
+                health: "/a/health",
+                version: "0.1.0",
+              },
+              {
+                name: "b",
+                port: 9000,
+                paths: ["/b"],
+                health: "/b/health",
+                version: "0.1.0",
+              },
+              {
+                name: "c",
+                port: 9000,
+                paths: ["/c"],
+                health: "/c/health",
+                version: "0.1.0",
+              },
+            ],
+          }),
+        );
+        expect(() => readManifest(path)).toThrow(/duplicate port 9000/);
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  // Write-time port collision rejection (hub#205). The read-time gate above
+  // catches duplicate ports on the next `readManifest`, but without a
+  // matching write-side check `upsertService` happily writes a corrupt
+  // manifest to disk and only the next read surfaces the fault. A buggy
+  // service boot calling `upsertService({ name: "agent", port: 1944 })`
+  // while scribe is already at 1944 must fail before `writeManifest` runs.
+  // Same multi-vault carve-out applies.
+  describe("upsertService duplicate-port rejection (hub#205)", () => {
+    const scribe: ServiceEntry = {
+      name: "parachute-scribe",
+      port: 1944,
+      paths: ["/scribe"],
+      health: "/scribe/health",
+      version: "0.4.0",
+    };
+    const agent: ServiceEntry = {
+      name: "agent",
+      port: 1944,
+      paths: ["/agent"],
+      health: "/agent/health",
+      version: "0.1.0",
+    };
+
+    test("succeeds when adding a service at a non-conflicting port", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(scribe, path);
+        const m = upsertService({ ...agent, port: 1945 }, path);
+        expect(m.services).toHaveLength(2);
+        expect(m.services.map((s) => s.port).sort()).toEqual([1944, 1945]);
+        // And it actually wrote: a fresh read sees both rows.
+        expect(readManifest(path).services).toHaveLength(2);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("throws ServicesManifestError when adding a service at a port already claimed by a non-vault service", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(scribe, path);
+        expect(() => upsertService(agent, path)).toThrow(ServicesManifestError);
+        // Error names the colliding port and both services so an operator
+        // scanning logs knows which two rows to reconcile.
+        expect(() => upsertService(agent, path)).toThrow(/duplicate port 1944/);
+        expect(() => upsertService(agent, path)).toThrow(/parachute-scribe/);
+        expect(() => upsertService(agent, path)).toThrow(/agent/);
+        // Crucially: services.json was NOT corrupted on the failed write.
+        // The pre-existing row stays, and the agent row never lands.
+        const m = readManifest(path);
+        expect(m.services).toHaveLength(1);
+        expect(m.services[0]?.name).toBe("parachute-scribe");
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("succeeds when adding a vault row at a port already used by another vault row (multi-vault carve-out)", () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        const vaultDefault: ServiceEntry = {
+          name: "parachute-vault-default",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/vault/default/health",
+          version: "0.4.0",
+        };
+        const vaultTechne: ServiceEntry = {
+          name: "parachute-vault-techne",
+          port: 1940,
+          paths: ["/vault/techne"],
+          health: "/vault/techne/health",
+          version: "0.4.0",
+        };
+        upsertService(vaultDefault, path);
+        const m = upsertService(vaultTechne, path);
+        expect(m.services).toHaveLength(2);
+        expect(m.services.map((s) => s.port)).toEqual([1940, 1940]);
+        // And persisted: a fresh read sees both vault rows on the same port,
+        // confirming readManifest's multi-vault carve-out matches the write
+        // side's.
+        expect(readManifest(path).services).toHaveLength(2);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("succeeds when UPDATING an existing entry's port to a non-conflicting port", () => {
+      // The update path (idx >= 0 in upsertService) replaces the row in-place
+      // before the duplicate-port check. Updating an entry's port to a value
+      // that collides with a DIFFERENT row must still throw, but moving an
+      // entry to a free port must succeed — including off canonical, which is
+      // a legitimate operator move (e.g., to dodge a third-party clash).
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(scribe, path); // port 1944
+        upsertService({ ...agent, port: 1945 }, path); // port 1945
+        // Move scribe from 1944 to 1948 (free): succeeds.
+        const m = upsertService({ ...scribe, port: 1948 }, path);
+        expect(m.services).toHaveLength(2);
+        const scribeRow = m.services.find((s) => s.name === "parachute-scribe");
+        expect(scribeRow?.port).toBe(1948);
+        // Fresh read: persisted state matches.
+        const persisted = readManifest(path);
+        expect(persisted.services.find((s) => s.name === "parachute-scribe")?.port).toBe(1948);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("throws when UPDATING an existing entry's port to one that collides with another row", () => {
+      // Companion to the above: the update path must NOT bypass the gate
+      // when the moved row's new port now collides with a different row.
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(scribe, path); // port 1944
+        upsertService({ ...agent, port: 1945 }, path); // port 1945
+        // Move scribe to 1945, where agent already lives: must throw.
+        expect(() => upsertService({ ...scribe, port: 1945 }, path)).toThrow(ServicesManifestError);
+        expect(() => upsertService({ ...scribe, port: 1945 }, path)).toThrow(/duplicate port 1945/);
+        // And the on-disk state stayed coherent — scribe at 1944, agent at
+        // 1945 — because the gate fires before writeManifest.
+        const persisted = readManifest(path);
+        expect(persisted.services.find((s) => s.name === "parachute-scribe")?.port).toBe(1944);
+        expect(persisted.services.find((s) => s.name === "agent")?.port).toBe(1945);
+      } finally {
+        cleanup();
+      }
+    });
+  });
 });
 
 describe("claw → agent migration", () => {