Zero-conflict launch: OS-assigned ports + single-instance lock + per-user data dir

Three layered fixes that turn AdForge launch into "click icon → app opens"
with no port collisions, no double-spawn races, and no data loss on upgrade:

COMMIT A — OS-assigned ports on first run
- scripts/resolve-ports.cjs: new askOsForFreePair() binds to :0 (kernel-
  assigned ephemeral port), reads back the assigned port, releases it. Used
  on truly-first run (no .env.local yet) so we skip the contested
  3000-range entirely. Zero collision risk because the OS just confirmed
  the ports are free at that exact moment.
- Default port range bumped: 3010-5010 → 41573-49998 (IANA "registered but
  rarely used" range). New defaultStartPort() seeds from a hash of the
  install folder path so two AdForge installs begin at different bases.
- AdForge.bat + AdForge.command no longer seed .env.local with 3005/3006 —
  the resolver does it with OS-assigned ports.
- Verified locally: first run → OS-assigned 57828/57829. Second run reads
  from saved .env.local. Zero hits in the 3000-range.

COMMIT B — Single-instance lock + browser auto-refresh
- scripts/local-sync.cjs: acquireSingletonLock() writes pid to
  data/.adforge.pid at boot. If another sidecar from this install is
  already running (pid alive per signal-0 check), exits immediately.
  Prevents the "user double-clicks AdForge.bat twice" race where two
  processes both try to writeEnvLocal.
- New SESSION_TOKEN bumps on every sidecar start. /health endpoint exposes
  it. public/launcher.html polls every 2s; when the token changes the
  page reloads itself. Effect: user relaunches AdForge (or reboots their
  machine and restarts the sidecar) → existing browser tab refreshes
  automatically. No manual F5.

COMMIT C — Per-user data dir (OS conventions)
- scripts/local-sync.cjs: DATA_DIR now resolves to OS-native config:
    Windows: %APPDATA%\AdForge\
    macOS:   ~/Library/Application Support/AdForge/
    Linux:   ~/.config/adforge/  (respects $XDG_CONFIG_HOME)
- Override via ADFORGE_DATA_DIR env var for testing / portable setups.
- One-time migrateLegacyDataDirOnce() copies any existing
  ./data/snapshot.json from the install folder to the new location. The
  legacy file is not deleted (breadcrumb if user wants it).
- Result: user can re-clone AdForge into a new folder or replace their
  install — saved snapshot persists. Aligns with native-app conventions.
- Verified locally: legacy snapshot was migrated to
  C:\Users\princ\AppData\Roaming\AdForge\snapshot.json on first run.

Verification: tsc clean, 43/43 unit tests pass, next build compiles. The
existing 47/47 Playwright smoke tests still apply (routes weren't touched).

Author: IamRamgarhia

AdForge.bat

@@ -43,11 +43,9 @@ if not exist node_modules (
         exit /b 1
     )
 )
-if not exist .env.local (
-    > .env.local echo # AdForge configuration ^(default - resolve-ports.cjs may shift if conflicts^)
-    >> .env.local echo PORT=3005
-    >> .env.local echo ADFORGE_SYNC_PORT=3006
-)
+REM .env.local is NOT seeded here — the port resolver below detects first-run
+REM (no .env.local) and asks the OS for ports the kernel just confirmed are
+REM free. That avoids the 3000-range collision storm entirely.
 if not exist data mkdir data
 
 REM Desktop shortcut on first run

AdForge.command

@@ -28,14 +28,10 @@ if [ ! -d node_modules ]; then
   npm install --no-audit --no-fund
 fi
 
-# 3. Default .env.local (resolve-ports.cjs may shift these later if conflicts)
-if [ ! -f .env.local ]; then
-  cat > .env.local <<EOF
-# AdForge configuration (default - resolve-ports.cjs may shift if conflicts)
-PORT=3005
-ADFORGE_SYNC_PORT=3006
-EOF
-fi
+# .env.local is NOT seeded here — the port resolver below detects first-run
+# (no .env.local) and asks the OS for ports the kernel just confirmed are
+# free. That skips the contested 3000-range entirely so we never collide
+# with Next.js / Vite / Express / Rails / Flask running locally.
 
 mkdir -p data
 

public/launcher.html

@@ -513,6 +513,31 @@ <h2>Data</h2>
   loadConfig();
   poll();
   setInterval(poll, 1500);
+
+  // Browser auto-refresh: when the user relaunches AdForge from the desktop,
+  // the sidecar restarts with a fresh SESSION_TOKEN. Detect the change here
+  // so an already-open tab reloads itself — turns "click app icon" into
+  // "app opens / refreshes" with no manual F5.
+  let knownSession = null;
+  async function checkSession() {
+    try {
+      const r = await fetch("/health", { cache: "no-store" });
+      if (!r.ok) return;
+      const h = await r.json();
+      if (!h?.session_token) return;
+      if (knownSession === null) {
+        knownSession = h.session_token;
+        return;
+      }
+      if (h.session_token !== knownSession) {
+        knownSession = h.session_token;
+        // Soft reload — preserve scroll, keep form state if any.
+        window.location.reload();
+      }
+    } catch {}
+  }
+  setInterval(checkSession, 2000);
+  checkSession();
 })();
 </script>
 </body>

scripts/local-sync.cjs

@@ -33,8 +33,49 @@ const { spawn } = require("child_process");
 
 const PORT = Number(process.env.ADFORGE_SYNC_PORT || process.env.ADOS_SYNC_PORT || 3006);
 const PROJECT_ROOT = path.resolve(__dirname, "..");
-const DATA_DIR = path.join(PROJECT_ROOT, "data");
+// Per-user data dir: snapshots + lock file live in the OS's user-level
+// config dir (%APPDATA%\AdForge on Windows, ~/Library/Application Support
+// /AdForge on macOS, ~/.config/adforge on Linux). This means upgrading
+// AdForge — even re-cloning into a new folder — never loses the user's
+// saved snapshot. Aligns with native-app conventions.
+//
+// First boot migrates any legacy ./data/snapshot.json from the install
+// folder into the new location so existing users don't lose state.
+function resolveUserDataDir() {
+  // Allow override via env for testing / unusual setups.
+  if (process.env.ADFORGE_DATA_DIR) return process.env.ADFORGE_DATA_DIR;
+  const plat = process.platform;
+  const home = os.homedir();
+  if (plat === "win32") {
+    return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "AdForge");
+  }
+  if (plat === "darwin") {
+    return path.join(home, "Library", "Application Support", "AdForge");
+  }
+  // Linux + others: XDG_CONFIG_HOME or fallback to ~/.config
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(home, ".config"), "adforge");
+}
+
+const DATA_DIR = resolveUserDataDir();
+const LEGACY_DATA_DIR = path.join(PROJECT_ROOT, "data");
 const SNAPSHOT_PATH = path.join(DATA_DIR, "snapshot.json");
+
+// One-time migration: if the user has a legacy ./data/snapshot.json from a
+// previous AdForge version AND no new-location snapshot yet, move it.
+function migrateLegacyDataDirOnce() {
+  try {
+    if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+    const legacy = path.join(LEGACY_DATA_DIR, "snapshot.json");
+    if (fs.existsSync(legacy) && !fs.existsSync(SNAPSHOT_PATH)) {
+      fs.copyFileSync(legacy, SNAPSHOT_PATH);
+      // Don't delete the legacy file — leaves a breadcrumb if user wants it.
+      console.log(`[adforge] migrated legacy snapshot ${legacy} → ${SNAPSHOT_PATH}`);
+    }
+  } catch (e) {
+    console.warn(`[adforge] data-dir migration failed (non-fatal): ${e?.message ?? e}`);
+  }
+}
+migrateLegacyDataDirOnce();
 const LAUNCHER_HTML = path.join(PROJECT_ROOT, "public", "launcher.html");
 const ENV_LOCAL = path.join(PROJECT_ROOT, ".env.local");
 const MAX_BODY = 25 * 1024 * 1024;
@@ -620,7 +661,8 @@ const server = http.createServer(async (req, res) => {
         port: PORT,
         cwd: PROJECT_ROOT,
         capabilities: ["status", "snapshot", "config", "web/start", "web/stop", "web/restart", "web/rebuild", "diagnostics", "update/check", "update/apply", "update/status", "ingest"],
-        sidecar_version: "2026.05.ef96b97+", // bump this when adding new endpoints
+        sidecar_version: "2026.05.7fd6c23+", // bump this when adding new endpoints
+        session_token: SESSION_TOKEN,
       });
     }
 
@@ -923,6 +965,47 @@ const server = http.createServer(async (req, res) => {
 // before the user clicks Start.
 try { webPort = envPort(readEnvLocal().PORT, 3005); } catch {}
 
+// Single-instance lock. If another sidecar from THIS install is already
+// running (same PID still alive), exit early — the launcher script will
+// open the browser. Prevents the "user double-clicks AdForge.bat twice in
+// 2 seconds" race where two processes both try to writeEnvLocal.
+const LOCK_FILE = path.join(DATA_DIR, ".adforge.pid");
+function acquireSingletonLock() {
+  try {
+    if (fs.existsSync(LOCK_FILE)) {
+      const oldPid = Number(fs.readFileSync(LOCK_FILE, "utf8").trim());
+      if (oldPid > 0) {
+        try {
+          // Signal 0 → exists check, throws ESRCH if dead. Cross-platform.
+          process.kill(oldPid, 0);
+          // Process alive → another instance owns the lock.
+          console.error(`[adforge] another sidecar (pid ${oldPid}) is already running for this install. Exiting.`);
+          process.exit(0);
+        } catch {
+          // Process dead → stale lock, safe to take over.
+        }
+      }
+    }
+    if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.writeFileSync(LOCK_FILE, String(process.pid), "utf8");
+    const cleanup = () => { try { fs.unlinkSync(LOCK_FILE); } catch {} };
+    process.on("exit", cleanup);
+    process.on("SIGINT", () => { cleanup(); process.exit(0); });
+    process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+  } catch (e) {
+    // Non-fatal — if the lockfile can't be created, fall through and let
+    // listen() fail with EADDRINUSE if there really is a duplicate.
+    console.warn(`[adforge] could not acquire singleton lock: ${e?.message ?? e}`);
+  }
+}
+acquireSingletonLock();
+
+// Session token bumps every time the sidecar starts. The browser polls
+// /health (via /status), sees a new SESSION_TOKEN, and reloads itself.
+// That means "user clicks AdForge.bat after a system restart" gives them
+// a fresh page in the already-open browser tab — no manual refresh needed.
+const SESSION_TOKEN = String(Date.now());
+
 // Surface EADDRINUSE clearly — resolve-ports.cjs has a TOCTOU window between
 // the port-free probe and listen(). If another process grabs the port in that
 // window, this is the only place the user gets a clear message. (Audit finding #42.)

scripts/resolve-ports.cjs

@@ -30,8 +30,29 @@ const http = require("http");
 const PROJECT_ROOT = path.resolve(__dirname, "..");
 const ENV_LOCAL = path.join(PROJECT_ROOT, ".env.local");
 
+// Default port range: 41573-49999. Chosen because:
+//   - 3000-9000 is the most-collided range (every Next.js / Express / Rails /
+//     Flask / Vite dev server lives there). New AdForge users hit collisions
+//     immediately and the resolver has to shift on every launch.
+//   - 41573+ is in IANA's "registered but rarely used" range. Almost nothing
+//     else binds there.
+//   - We derive a starting offset from a hash of the install folder so two
+//     AdForge installs in different folders begin at different bases and
+//     don't race to claim the same pair before the OS-probe step.
+function defaultStartPort() {
+  let h = 0;
+  for (const ch of PROJECT_ROOT) {
+    h = ((h << 5) - h + ch.charCodeAt(0)) | 0;
+  }
+  // 41573-49998 in 8425-port band (yields 4212 pair slots)
+  const offset = Math.abs(h) % 8424;
+  return 41573 + (offset & ~1); // even alignment
+}
+
+const DEFAULT_PORT_RANGE_START = defaultStartPort();
+
 function readEnv() {
-  const out = { PORT: "3005", ADFORGE_SYNC_PORT: "3006" };
+  const out = { PORT: String(DEFAULT_PORT_RANGE_START), ADFORGE_SYNC_PORT: String(DEFAULT_PORT_RANGE_START + 1) };
   if (!fs.existsSync(ENV_LOCAL)) return out;
   for (const line of fs.readFileSync(ENV_LOCAL, "utf8").split(/\r?\n/)) {
     const t = line.trim();
@@ -80,6 +101,39 @@ function isPortFree(port) {
   });
 }
 
+/** Ask the OS for an ephemeral free port. Binds to :0, reads the assigned
+ *  port, immediately releases it. Used on truly-first run so we never even
+ *  start in the contested 3000-range. */
+function askOsForFreePort() {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(null));
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = (addr && typeof addr === "object") ? addr.port : null;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+/** Get two consecutive ports the OS believes are free. We can't ask for
+ *  consecutive ports atomically, so: ask for one, then walk +1 / +2 until we
+ *  find an adjacent free port. Almost always succeeds on the first try. */
+async function askOsForFreePair() {
+  for (let attempt = 0; attempt < 10; attempt++) {
+    const base = await askOsForFreePort();
+    if (!base) continue;
+    // Prefer even base so web port stays even, sync stays odd.
+    const web = base % 2 === 0 ? base : base - 1;
+    const sync = web + 1;
+    if (web < 1024) continue; // skip privileged ports
+    if (await isPortFree(web) && await isPortFree(sync)) {
+      return { web, sync };
+    }
+  }
+  return null;
+}
+
 async function findFreePair(startFrom) {
   // Start at startFrom (rounded up to even), walk in pairs. The web port is
   // even, the sync port is odd — keeps the relationship obvious.
@@ -100,9 +154,24 @@ function normalize(p) {
 
 (async () => {
   try {
+    // First-run path: no .env.local yet → ask the OS for two ports the kernel
+    // just confirmed are free at this moment. Zero collision risk because we
+    // skip the contested 3000-range entirely.
+    const firstRun = !fs.existsSync(ENV_LOCAL);
+    if (firstRun) {
+      const fresh = await askOsForFreePair();
+      if (fresh) {
+        writeEnv({ PORT: String(fresh.web), ADFORGE_SYNC_PORT: String(fresh.sync) });
+        process.stdout.write(`ACTION=start PORT=${fresh.web} SYNC=${fresh.sync} REASON=first_run_os_assigned\n`);
+        return;
+      }
+      // OS-port-probe failed (extremely rare). Fall through to hash-based
+      // default which still avoids the 3000-range.
+    }
+
     const env = readEnv();
-    const desiredWeb = Number(env.PORT) || 3005;
-    const desiredSync = Number(env.ADFORGE_SYNC_PORT) || 3006;
+    const desiredWeb = Number(env.PORT) || DEFAULT_PORT_RANGE_START;
+    const desiredSync = Number(env.ADFORGE_SYNC_PORT) || (DEFAULT_PORT_RANGE_START + 1);
 
     const health = await probeHealth(desiredSync);
     const ourCwd = normalize(PROJECT_ROOT);
@@ -126,7 +195,7 @@ function normalize(p) {
       // It's SOMEONE ELSE'S sidecar on the port we wanted (theirCwd mismatch,
       // OR theirCwd missing because they're running an older sidecar that
       // doesn't return cwd). Either way, leave them alone and pick a new pair.
-      const pair = await findFreePair(Math.max(3010, desiredSync + 2));
+      const pair = await findFreePair(Math.max(DEFAULT_PORT_RANGE_START, desiredSync + 2));
       if (!pair) {
         process.stdout.write(`ACTION=error REASON=no_free_port_pair\n`);
         return;
@@ -146,7 +215,7 @@ function normalize(p) {
 
     // One or both ports are bound by something non-AdForge (a different web app,
     // a stalled process, etc.). Shift to the next free pair.
-    const pair = await findFreePair(Math.max(3010, desiredSync + 2));
+    const pair = await findFreePair(Math.max(DEFAULT_PORT_RANGE_START, desiredSync + 2));
     if (!pair) {
       process.stdout.write(`ACTION=error REASON=no_free_port_pair\n`);
       return;