fix: cross-platform build and document auth server timing

- Fix pgai/package.json sed command for macOS compatibility
- Add JSDoc documentation for auth server async stop behavior

Author: claude

cli/lib/auth-server.ts

@@ -32,10 +32,17 @@ function escapeHtml(str: string | null): string {
 
 /**
  * Create and start callback server using Bun.serve
+ *
  * @param port - Port to listen on (0 for random available port)
  * @param expectedState - Expected state parameter for CSRF protection
  * @param timeoutMs - Timeout in milliseconds
  * @returns Server object with promise and getPort function
+ *
+ * @remarks
+ * The server stops asynchronously ~100ms after the callback resolves/rejects.
+ * This delay ensures the HTTP response is fully sent before closing the connection.
+ * Callers should not attempt to reuse the same port immediately after the promise
+ * resolves - wait at least 200ms or use a different port.
  */
 export function createCallbackServer(
   port: number = 0,

pgai/package.json

@@ -20,7 +20,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "bun build ./bin/pgai.ts --outdir ./dist/bin --target node && sed -i '1s|#!/usr/bin/env bun|#!/usr/bin/env node|' ./dist/bin/pgai.js",
+    "build": "bun build ./bin/pgai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/pgai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\"",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {