haltija 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 1.4.1
+
+Five cross-project bugs, all of the same shape: **haltija reaching out and disrupting a healthy
+peer.** If you run more than one project on a machine, this is the release that stops your
+browser channel vanishing.
+
+### Behavior changes (no API breaks)
+
+Nothing was removed or renamed — no endpoint, export, or flag — so nothing should fail to compile
+or resolve. Two *runtime* behaviors changed, and in both the old behavior was the bug:
+
+- **The desktop app attaches to an existing server instead of replacing it.** If you relied on a
+  launch always giving you a pristine embedded server, set `HALTIJA_SERVER_MODE=builtin`.
+- **`--https` (https-only) now exits if it cannot bind its port**, instead of silently starting on
+  an ephemeral one. The old "success" produced a channel no widget could reach.
+
+### New: `--private` — isolated automation instances ([#1](https://github.com/tonioloewald/haltija/issues/1))
+
+haltija plays two roles that were conflated. A **shared interactive** browser on the default port
+is a feature — whatever window is focused is what `hj` drives, across projects. But **ephemeral
+automation** (a test lane that spawns a browser, drives fixed pages, and exits) was consulting
+that shared server and, if any was reachable, *adopting and navigating it* — so one project's
+doc-test lane yanked another project's live browser to different pages, and then failed on a
+timeout. Intermittent and baffling, because it only bit when a foreign haltija happened to be up.
+
+`haltija --private` (pair with `--headless`) is isolated by construction:
+
+- binds an **ephemeral port, never 8700** — it can't collide with or be mistaken for the shared server;
+- is **not registered** in the shared registry, so interactive `hj` / cwd-routing can't adopt it;
+- **never reaches out** — it retires nothing and touches no other server;
+- **reports its address** on stdout (`HALTIJA_PRIVATE_READY {json}`) and to `--port-file` — since
+  it's not in the registry, that's how you find it.
+
+A consumer's test lane should request a private instance and drive *that* by the port it reports,
+instead of an unscoped `hj windows` check that races whatever else is on the machine.
+
+### Fixed: the desktop app killed other projects' channels
+
+Its default was to stop any server on 8700/8701 and start fresh — so launching the app (`bunx
+haltija`, an `hj` auto-launch, `--ci`, the integration test) silently took down a live channel
+another project was using, and made its widget vanish. It now **attaches to a healthy existing
+server and says so**. Force the old behavior with `HALTIJA_SERVER_MODE=builtin`.
+
+### Fixed: a half-dead `--both` channel (HTTPS silently on the wrong port)
+
+When the HTTPS port was busy (a fast restart racing the previous server), the HTTPS side quietly
+fell back to an **ephemeral** port. But a widget on an https page connects to the *known* port —
+so 8701 sat empty, the page couldn't connect, and the server looked healthy because HTTP was fine.
+HTTPS now retries its intended port and, failing that, **fails loudly** rather than relocating;
+the startup banner never advertises a port it didn't bind.
+
+### Fixed: silent HTTP port relocation
+
+When the wanted HTTP port was taken, the server bound an ephemeral one without a word — so a
+caller probing a fixed port had no idea why nothing was there. It now says
+`<port> was taken; bound HTTP on <n> instead. Find it with \`hj where\`.`
+
+### Fixed: the test suite disrupted other servers
+
+`bun test` bound fixed 87xx ports — the range real servers live in — and on a collision would
+`POST /shutdown` whatever was there, including another project's channel. The suite now uses
+high, per-process-unique ports and can never stop a server it didn't start.
+
+### Docs
+
+A "tab that reads as unreachable" troubleshooting section in `DOCS.md` and `llms.txt`: a hidden,
+backgrounded, minimized, or occluded tab (and an active WebXR session) suspends
+`requestAnimationFrame` and throttles timers, so the tab can stop answering even though the page
+is fine. Bring it forward, or target it explicitly with `hj --window <id>`.
+
+
 ## 1.4.0
 
 **`hj` now routes to the server that owns your current directory.** If you run more than one

package/apps/desktop/main.js

@@ -56,10 +56,17 @@ let navigateRequestId = 0
 
 const DEFAULT_PREFS = {
   // Server startup behavior:
-  // 'builtin'  - Always kill existing server and start fresh (default)
-  // 'external' - Never start server, expect one running externally
-  // 'auto'     - Use existing if found, else start embedded
-  serverMode: 'builtin',
+  // 'auto'     - Use an existing healthy server if one is on the port, else start embedded (DEFAULT)
+  // 'builtin'  - Always stop any existing server and start fresh (the old default)
+  // 'external' - Never start a server, expect one running externally
+  //
+  // Default is 'auto', NOT 'builtin'. On a machine running more than one project, 8700/8701 are
+  // shared: another project may legitimately have a live channel there (e.g. `haltija --server
+  // --both`). 'builtin' treated that channel as a "zombie" and killed it to start fresh — so
+  // launching the desktop app (or `bunx haltija`, or an `hj` auto-launch) silently took down
+  // another project's channel and made its widget vanish. 'auto' reuses a healthy server instead.
+  // Force the old behavior with HALTIJA_SERVER_MODE=builtin when you specifically want your own.
+  serverMode: process.env.HALTIJA_SERVER_MODE || 'auto',
 }
 
 // Active prefs (will be overwritten by persisted prefs when IPC is wired up)
@@ -67,6 +74,10 @@ const prefs = { ...DEFAULT_PREFS }
 
 let mainWindow = null
 const embeddedServers = []
+// True when this app attached to a server it did not start (auto mode found one already on the
+// port). Surfaced to the window so the user knows they're driving a reused, possibly-foreign server.
+let reusedExternalServer = false
+let reusedServerBanner = ''
 
 // ============================================
 // MCP Setup for Claude Desktop
@@ -299,6 +310,15 @@ function createWindow() {
   // Load the shell UI
   mainWindow.loadFile('index.html')
 
+  // If we attached to a server we didn't start, tell the renderer so it can surface it in the
+  // UI. Best-effort: harmless if the renderer doesn't handle 'server-reused' yet (that UI is a
+  // filed follow-up); the reuse is also announced on the app's console output regardless.
+  if (reusedExternalServer) {
+    mainWindow.webContents.once('did-finish-load', () => {
+      try { mainWindow.webContents.send('server-reused', reusedServerBanner) } catch {}
+    })
+  }
+
   // Open DevTools in development
   if (process.env.NODE_ENV === 'development') {
     mainWindow.webContents.openDevTools()
@@ -1399,9 +1419,15 @@ async function ensureServer() {
       return false
 
     case 'auto':
-      // Use existing if found, else start embedded
+      // Use existing if found, else start embedded. Reusing is the whole point: it means the
+      // app does NOT kill a channel another project may be running on 8700/8701.
       if (running) {
-        console.log('[Haltija Desktop] Using existing server at', HALTIJA_SERVER)
+        // Surface this prominently — the user should know the app attached to a server it did
+        // NOT start (possibly a different version/config), rather than silently assuming its own.
+        const banner = `Attached to an existing haltija server at ${HALTIJA_SERVER} (did not start my own; set HALTIJA_SERVER_MODE=builtin to force a fresh one)`
+        console.log(`[Haltija Desktop] ${banner}`)
+        reusedExternalServer = true
+        reusedServerBanner = banner
         return true
       }
       console.log('[Haltija Desktop] No server found, starting embedded')

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "private": true,
   "description": "Haltija Desktop - God Mode Browser for AI Agents",
   "homepage": "https://github.com/tonioloewald/haltija",

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.4.0";
+  var VERSION = "1.4.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/bin/tosijs-dev.mjs

@@ -59,6 +59,11 @@ Options:
                   HALTIJA_NAME=foo hj <cmd> can resolve back to its port
   --force, -f     Restart even if server already running
   --wait-ready    Block until server + browser are ready (for scripts)
+  --private       Isolated automation instance: own server on an EPHEMERAL port (never
+                  8700), own browser, torn down with the run. Never sees/adopts/navigates
+                  the shared interactive browser. Reports its address on stdout
+                  (HALTIJA_PRIVATE_READY {json}) and to --port-file. Pair with --headless.
+  --port-file <p> Write the (private) server's bound address as JSON to <p> when ready.
   --setup-mcp     Configure Claude Desktop MCP integration
   --setup-mcp-check  Check MCP configuration status
   --setup-mcp-remove Remove Haltija from Claude Desktop config
@@ -408,6 +413,43 @@ const explicitServer = args.includes('--server')
 const explicitApp = args.includes('--app') || ciMode  // CI mode uses Electron app
 const waitReady = args.includes('--wait-ready') || ciMode
 
+// --private: the "ephemeral automation" role (issue #1). An isolated instance — own server on an
+// EPHEMERAL port (never 8700), its own browser, torn down with the run — that must never see,
+// adopt, or navigate the shared interactive browser. It reports its address on stdout
+// (HALTIJA_PRIVATE_READY {json}) and to --port-file, so the caller drives THAT, with no `hj
+// windows` race against whatever else is on the machine. Sets the isolation env for the server.
+const privateMode = args.includes('--private')
+const portFileIdx = args.indexOf('--port-file')
+let privatePortFile = null
+if (privateMode) {
+  // Mutate `env` (the object passed to the spawned server), NOT process.env — `env` was already
+  // snapshotted above, so setting process.env here would never reach the server.
+  env.HALTIJA_PRIVATE = '1'
+  env.HALTIJA_NO_RETIRE = '1'   // never touch another server
+  env.HALTIJA_NO_INSTALL = '1'  // never rewrite the shared ~/.local/bin/hj
+  delete env.HALTIJA_PORT       // force ephemeral — never bind the shared default
+  delete env.DEV_CHANNEL_PORT
+  // The server writes its actual (ephemeral) address here on ready; we read it back to point our
+  // own browser at it, and the caller can read it too. Default to a temp file if none was given.
+  privatePortFile = (portFileIdx !== -1 && args[portFileIdx + 1])
+    ? args[portFileIdx + 1]
+    : join(tmpdir(), `haltija-private-${process.pid}.json`)
+  env.HALTIJA_PORT_FILE = privatePortFile
+}
+
+/** Poll the private instance's port-file until it reports its ephemeral port. */
+async function discoverPrivatePort(portFile, timeout = 30000) {
+  const start = Date.now()
+  while (Date.now() - start < timeout) {
+    try {
+      const data = JSON.parse(readFileSync(portFile, 'utf-8'))
+      if (data && data.port) return data.port
+    } catch {}
+    await new Promise((r) => setTimeout(r, 200))
+  }
+  return null
+}
+
 // CI mode sets ELECTRON_DISABLE_SANDBOX automatically (needed for containerized CI)
 if (ciMode && !process.env.ELECTRON_DISABLE_SANDBOX) {
   process.env.ELECTRON_DISABLE_SANDBOX = '1'
@@ -717,7 +759,13 @@ const tryBun = () => {
   // Start headless browser after server is ready
   if (headlessMode) {
     (async () => {
-      const serverPort = env.DEV_CHANNEL_PORT || 8700
+      const serverPort = privateMode
+        ? await discoverPrivatePort(privatePortFile)
+        : (env.DEV_CHANNEL_PORT || 8700)
+      if (!serverPort) {
+        console.error('[tosijs-dev] Private server did not report its port within timeout')
+        process.exit(1)
+      }
       console.log('[tosijs-dev] Waiting for server to be ready...')
       const serverReady = await waitForServer(serverPort)
       if (serverReady) {
@@ -750,7 +798,13 @@ const tryNode = () => {
   // Start headless browser after server is ready
   if (headlessMode) {
     (async () => {
-      const serverPort = env.DEV_CHANNEL_PORT || 8700
+      const serverPort = privateMode
+        ? await discoverPrivatePort(privatePortFile)
+        : (env.DEV_CHANNEL_PORT || 8700)
+      if (!serverPort) {
+        console.error('[tosijs-dev] Private server did not report its port within timeout')
+        process.exit(1)
+      }
       console.log('[tosijs-dev] Waiting for server to be ready...')
       const serverReady = await waitForServer(serverPort)
       if (serverReady) {
@@ -867,8 +921,10 @@ function killOnPort(port) {
 const port = env.DEV_CHANNEL_PORT || '8700'
 const forceRestart = args.includes('--force') || args.includes('-f')
 
-// Check for existing server before launching
-const existingServer = await checkExistingServer(port)
+// A PRIVATE instance NEVER consults or adopts the shared server — that adoption is the exact
+// bug issue #1 is about, and it lived right here in our own launcher (it saw the shared 8700
+// server and exited, "already running"). Private always starts its own on an ephemeral port.
+const existingServer = privateMode ? { running: false } : await checkExistingServer(port)
 if (existingServer.running && !forceRestart) {
   console.log('')
   console.log(green('✓') + ` Haltija is already running on port ${port}` + 

package/bin/version.mjs

@@ -3,4 +3,4 @@
  * ⚠️  To change the version, update package.json and run: bun run build
  */
 
-export const HJ_VERSION = '1.4.0'
+export const HJ_VERSION = '1.4.1'

package/dist/component.d.ts

@@ -20,7 +20,7 @@
  * - Option+Tab toggles visibility (but active state always shows briefly)
  * - Localhost only by default
  */
-export declare const VERSION = "1.4.0";
+export declare const VERSION = "1.4.1";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;

package/dist/component.esm.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "1.4.0";
+var VERSION = "1.4.1";
 
 // src/text-selector.ts
 var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.4.0";
+  var VERSION = "1.4.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/hj.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// haltija-cli:do-not-edit v1.4.0
+// haltija-cli:do-not-edit v1.4.1
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -756,7 +756,7 @@ function substituteGeneratedVars(text, seed) {
 }
 
 // bin/version.mjs
-var HJ_VERSION = "1.4.0";
+var HJ_VERSION = "1.4.1";
 
 // bin/semver.mjs
 function parseVersion(v) {

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.4.0";
+var VERSION = "1.4.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2897,6 +2897,18 @@ breaking; do not chase a page bug that isn't there. Known causes:
   e.g. write the values you care about somewhere your test/agent can read them (an
   in-page debug source, an in-headset stats panel), rather than issuing \`hj eval\` that
   round-trips through the suspended heartbeat.
+- **A tab that isn't visible on screen** \u2014 the common everyday case, and the one
+  people hit without realizing. A backgrounded tab, a minimized window, or a window
+  that is *maximized on another Space or fully occluded* (e.g. on macOS) all count as
+  **hidden** (\`document.visibilityState === "hidden"\`). While hidden, browsers stop
+  \`requestAnimationFrame\` entirely and throttle timers \u2014 and, on top of that, the
+  Haltija widget deliberately **deactivates** a hidden tab so untargeted commands
+  route to whichever tab is actually in front (focus-follows-visible-tab). So a page
+  you can't see may not answer an untargeted \`hj eval\`/\`hj tree\`, and any
+  \`rAF\`-driven state (scroll progress, animation frames) is frozen even if it does.
+  Fixes: **bring the tab to the front**, or **target it explicitly** \u2014
+  \`hj --window <id> eval \u2026\` (get the id from \`hj windows\`) reaches a specific tab
+  regardless of visibility. Don't rely on rAF-driven values while a tab is hidden.
 - **A heavily throttled background tab, or a long blocking task** on the main thread \u2014
   same shape: the heartbeat can't run, so the tab looks dead until the thread frees up.
 
@@ -2925,6 +2937,13 @@ hj tree --no-launch       # Skip auto-launch
 hj status                 # Info commands never trigger auto-launch
 \`\`\`
 
+**The desktop app REUSES an existing server rather than replacing it.** If a
+haltija server is already running on the port (e.g. another project started one
+with \`haltija --server --both\`), the app attaches to it and says so, instead of
+killing it to start its own \u2014 so launching the app (or an \`hj\` auto-launch) no
+longer takes down another project's channel. Set \`HALTIJA_SERVER_MODE=builtin\` to
+force the app to run its own fresh server instead.
+
 ## CI / Headless
 
 \`\`\`bash
@@ -3020,6 +3039,7 @@ Or via a script tag (auto-injecting IIFE bundle served by the running server):
 
 ## Gotcha: a tab can read as unreachable while its main thread is suspended
 - The widget proves liveness with a heartbeat. If the page's main thread or its \`requestAnimationFrame\` loop is suspended, the heartbeat stalls and commands time out or report "no browser connected" \u2014 even though the PAGE is fine. It's the instrument going quiet, not a page bug.
+- **A tab that is not visible on screen** \u2014 backgrounded, minimized, or maximized on another Space / fully occluded (macOS) \u2014 counts as \`hidden\`. Browsers stop \`requestAnimationFrame\` and throttle timers while hidden, AND the widget deliberately deactivates a hidden tab so untargeted commands go to the front tab. So a page you can't see may not answer an untargeted \`hj eval\`/\`hj tree\`, and rAF-driven state (scroll/animation) is frozen. Fix: bring it to the front, or **target it explicitly** \u2014 \`hj --window <id> eval \u2026\` (id from \`hj windows\`) reaches a specific tab regardless of visibility.
 - **WebXR / immersive sessions suspend \`window.requestAnimationFrame\`** (the XR compositor drives frames instead), so a tab is unreachable *while immersive*. Drive state out through your own channel \u2014 write the values you care about somewhere your agent can read (a debug source, an in-headset stats panel) \u2014 rather than \`hj eval\` round-trips through the suspended heartbeat. A heavily throttled background tab or a long blocking task has the same shape.
 - A command hitting the WRONG page (not a dead one) is targeting, not liveness: run \`hj where\`.
 
@@ -3077,7 +3097,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.4.0";
+  var VERSION = "1.4.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -16000,10 +16020,11 @@ function getMcpStatus() {
 var PRODUCT_NAME2 = "Haltija";
 var TAG_NAME = "haltija-dev";
 var LOG_PREFIX = "[haltija]";
+var IS_PRIVATE = process.env.HALTIJA_PRIVATE === "1";
 var PORT_PREFERENCE = process.env.HALTIJA_PORT || process.env.DEV_CHANNEL_PORT;
-var PORT_IS_STRICT = !!PORT_PREFERENCE;
-var PORT = parseInt(PORT_PREFERENCE || "8700");
-var HTTPS_PORT = parseInt(process.env.DEV_CHANNEL_HTTPS_PORT || "8701");
+var PORT_IS_STRICT = !!PORT_PREFERENCE && !IS_PRIVATE;
+var PORT = IS_PRIVATE ? 0 : parseInt(PORT_PREFERENCE || "8700");
+var HTTPS_PORT = IS_PRIVATE ? 0 : parseInt(process.env.DEV_CHANNEL_HTTPS_PORT || "8701");
 var INSTANCE_NAME = process.env.HALTIJA_NAME || "";
 var SNAPSHOTS_DIR = process.env.DEV_CHANNEL_SNAPSHOTS_DIR || null;
 var DOCS_DIR = process.env.DEV_CHANNEL_DOCS_DIR || null;
@@ -18993,6 +19014,8 @@ var serverConfig = {
   }
 };
 async function freePort(port) {
+  if (process.env.HALTIJA_NO_RETIRE === "1")
+    return false;
   if (listenerPidsOnPort(port).length === 0)
     return false;
   const probe = await probePort(port);
@@ -19080,6 +19103,8 @@ async function probePort(port) {
 async function retireLegacyServers() {
   if (process.env.HALTIJA_NO_RETIRE === "1")
     return;
+  if (IS_PRIVATE)
+    return;
   const registryPorts = list().map((e) => e.port);
   const ports = candidatePorts({ defaults: [8700, 8701, PORT], registryPorts });
   let stopped = false;
@@ -19118,14 +19143,20 @@ if (USE_HTTP) {
     });
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
+      const wantedHttpPort = PORT;
       if (PORT_IS_STRICT) {
         if (await freePort(PORT)) {
           httpServer = Bun.serve({ port: PORT, ...serverConfig });
         } else {
+          console.error("");
+          console.error(`  \u26A0\uFE0F  Could not bind the HTTP port ${wantedHttpPort} you asked for \u2014 it is in use.`);
+          console.error(`      Free it, or start on another port (--port N / HALTIJA_PORT).`);
+          console.error("");
           throw err;
         }
       } else {
         httpServer = Bun.serve({ port: 0, ...serverConfig });
+        console.warn(`  [port] ${wantedHttpPort} was taken; bound HTTP on ${httpServer.port} instead. Find it with \`hj where\` (or read ~/.haltija/servers/).`);
       }
     } else {
       throw err;
@@ -19138,29 +19169,63 @@ if (USE_HTTPS) {
     cert: readFileSync5(certPath),
     key: readFileSync5(keyPath)
   };
+  const wantedHttpsPort = HTTPS_PORT;
+  const bindHttps = () => Bun.serve({ port: wantedHttpsPort, tls, ...serverConfig });
   try {
-    httpsServer = Bun.serve({ port: HTTPS_PORT, tls, ...serverConfig });
+    httpsServer = bindHttps();
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
-      if (PORT_IS_STRICT) {
-        if (await freePort(HTTPS_PORT)) {
-          httpsServer = Bun.serve({ port: HTTPS_PORT, tls, ...serverConfig });
-        } else {
-          throw err;
-        }
+      if (PORT_IS_STRICT && await freePort(wantedHttpsPort)) {
+        httpsServer = bindHttps();
       } else {
-        httpsServer = Bun.serve({ port: 0, tls, ...serverConfig });
+        for (let attempt = 0;attempt < 5 && !httpsServer; attempt++) {
+          Bun.sleepSync(400);
+          try {
+            httpsServer = bindHttps();
+          } catch {}
+        }
+        if (!httpsServer) {
+          console.error("");
+          console.error(`  \u26A0\uFE0F  HTTPS could not bind its port ${wantedHttpsPort} \u2014 it is still in use`);
+          console.error(`      (a previous server in TIME_WAIT, or another process holding it).`);
+          console.error(`      A widget on an https page connects to :${wantedHttpsPort}, so it will`);
+          console.error(`      NOT connect until this is free. Haltija is NOT silently relocating it.`);
+          console.error(`      Fix: wait a few seconds and restart, or free port ${wantedHttpsPort}.`);
+          console.error("");
+          if (!USE_HTTP) {
+            throw err;
+          }
+        }
       }
     } else {
       throw err;
     }
   }
-  HTTPS_PORT = httpsServer.port ?? HTTPS_PORT;
+  if (httpsServer)
+    HTTPS_PORT = httpsServer.port ?? HTTPS_PORT;
 }
-var httpUrl = USE_HTTP ? `http://localhost:${PORT}` : null;
-var httpsUrl = USE_HTTPS ? `https://localhost:${HTTPS_PORT}` : null;
+var httpUrl = httpServer ? `http://localhost:${PORT}` : null;
+var httpsUrl = httpsServer ? `https://localhost:${HTTPS_PORT}` : null;
 var primaryUrl = httpsUrl || httpUrl;
-var CAN_BE_REGISTERED = USE_HTTP;
+if (IS_PRIVATE) {
+  const ready = {
+    port: PORT,
+    httpsPort: httpsServer ? HTTPS_PORT : null,
+    url: httpUrl,
+    httpsUrl,
+    pid: process.pid
+  };
+  console.log(`HALTIJA_PRIVATE_READY ${JSON.stringify(ready)}`);
+  const portFile = process.env.HALTIJA_PORT_FILE;
+  if (portFile) {
+    try {
+      writeFileSync3(portFile, JSON.stringify(ready));
+    } catch (err) {
+      console.error(`${LOG_PREFIX} could not write HALTIJA_PORT_FILE ${portFile}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+}
+var CAN_BE_REGISTERED = USE_HTTP && !IS_PRIVATE;
 var REGISTRY_NAME = !CAN_BE_REGISTERED ? "" : INSTANCE_NAME || (isDesktopApp ? "" : autoNameFor(PORT));
 if (!CAN_BE_REGISTERED && (INSTANCE_NAME || !isDesktopApp)) {
   console.log(`${LOG_PREFIX} HTTPS-only: not registering an instance (hj speaks HTTP; cwd routing and --name need an HTTP port)`);
@@ -19367,8 +19432,14 @@ if (USE_HTTPS && !httpUrl) {
 `);
 }
 if (MODE === "both") {
-  console.log(`  Mode: both - Use HTTP (${PORT}) for HTTP sites, HTTPS (${HTTPS_PORT}) for HTTPS sites.
+  if (httpsServer) {
+    console.log(`  Mode: both - Use HTTP (${PORT}) for HTTP sites, HTTPS (${HTTPS_PORT}) for HTTPS sites.
 `);
+  } else {
+    console.log(`  Mode: both - \u26A0\uFE0F  HTTP (${PORT}) is up but HTTPS is DOWN (see the warning above).`);
+    console.log(`              Pages served over https will not connect until HTTPS binds.
+`);
+  }
 }
 var server = httpsServer || httpServer;
 // src/client.ts

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.4.0";
+var VERSION = "1.4.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2897,6 +2897,18 @@ breaking; do not chase a page bug that isn't there. Known causes:
   e.g. write the values you care about somewhere your test/agent can read them (an
   in-page debug source, an in-headset stats panel), rather than issuing \`hj eval\` that
   round-trips through the suspended heartbeat.
+- **A tab that isn't visible on screen** \u2014 the common everyday case, and the one
+  people hit without realizing. A backgrounded tab, a minimized window, or a window
+  that is *maximized on another Space or fully occluded* (e.g. on macOS) all count as
+  **hidden** (\`document.visibilityState === "hidden"\`). While hidden, browsers stop
+  \`requestAnimationFrame\` entirely and throttle timers \u2014 and, on top of that, the
+  Haltija widget deliberately **deactivates** a hidden tab so untargeted commands
+  route to whichever tab is actually in front (focus-follows-visible-tab). So a page
+  you can't see may not answer an untargeted \`hj eval\`/\`hj tree\`, and any
+  \`rAF\`-driven state (scroll progress, animation frames) is frozen even if it does.
+  Fixes: **bring the tab to the front**, or **target it explicitly** \u2014
+  \`hj --window <id> eval \u2026\` (get the id from \`hj windows\`) reaches a specific tab
+  regardless of visibility. Don't rely on rAF-driven values while a tab is hidden.
 - **A heavily throttled background tab, or a long blocking task** on the main thread \u2014
   same shape: the heartbeat can't run, so the tab looks dead until the thread frees up.
 
@@ -2925,6 +2937,13 @@ hj tree --no-launch       # Skip auto-launch
 hj status                 # Info commands never trigger auto-launch
 \`\`\`
 
+**The desktop app REUSES an existing server rather than replacing it.** If a
+haltija server is already running on the port (e.g. another project started one
+with \`haltija --server --both\`), the app attaches to it and says so, instead of
+killing it to start its own \u2014 so launching the app (or an \`hj\` auto-launch) no
+longer takes down another project's channel. Set \`HALTIJA_SERVER_MODE=builtin\` to
+force the app to run its own fresh server instead.
+
 ## CI / Headless
 
 \`\`\`bash
@@ -3020,6 +3039,7 @@ Or via a script tag (auto-injecting IIFE bundle served by the running server):
 
 ## Gotcha: a tab can read as unreachable while its main thread is suspended
 - The widget proves liveness with a heartbeat. If the page's main thread or its \`requestAnimationFrame\` loop is suspended, the heartbeat stalls and commands time out or report "no browser connected" \u2014 even though the PAGE is fine. It's the instrument going quiet, not a page bug.
+- **A tab that is not visible on screen** \u2014 backgrounded, minimized, or maximized on another Space / fully occluded (macOS) \u2014 counts as \`hidden\`. Browsers stop \`requestAnimationFrame\` and throttle timers while hidden, AND the widget deliberately deactivates a hidden tab so untargeted commands go to the front tab. So a page you can't see may not answer an untargeted \`hj eval\`/\`hj tree\`, and rAF-driven state (scroll/animation) is frozen. Fix: bring it to the front, or **target it explicitly** \u2014 \`hj --window <id> eval \u2026\` (id from \`hj windows\`) reaches a specific tab regardless of visibility.
 - **WebXR / immersive sessions suspend \`window.requestAnimationFrame\`** (the XR compositor drives frames instead), so a tab is unreachable *while immersive*. Drive state out through your own channel \u2014 write the values you care about somewhere your agent can read (a debug source, an in-headset stats panel) \u2014 rather than \`hj eval\` round-trips through the suspended heartbeat. A heavily throttled background tab or a long blocking task has the same shape.
 - A command hitting the WRONG page (not a dead one) is targeting, not liveness: run \`hj where\`.
 
@@ -3077,7 +3097,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.4.0";
+  var VERSION = "1.4.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -16000,10 +16020,11 @@ function getMcpStatus() {
 var PRODUCT_NAME2 = "Haltija";
 var TAG_NAME = "haltija-dev";
 var LOG_PREFIX = "[haltija]";
+var IS_PRIVATE = process.env.HALTIJA_PRIVATE === "1";
 var PORT_PREFERENCE = process.env.HALTIJA_PORT || process.env.DEV_CHANNEL_PORT;
-var PORT_IS_STRICT = !!PORT_PREFERENCE;
-var PORT = parseInt(PORT_PREFERENCE || "8700");
-var HTTPS_PORT = parseInt(process.env.DEV_CHANNEL_HTTPS_PORT || "8701");
+var PORT_IS_STRICT = !!PORT_PREFERENCE && !IS_PRIVATE;
+var PORT = IS_PRIVATE ? 0 : parseInt(PORT_PREFERENCE || "8700");
+var HTTPS_PORT = IS_PRIVATE ? 0 : parseInt(process.env.DEV_CHANNEL_HTTPS_PORT || "8701");
 var INSTANCE_NAME = process.env.HALTIJA_NAME || "";
 var SNAPSHOTS_DIR = process.env.DEV_CHANNEL_SNAPSHOTS_DIR || null;
 var DOCS_DIR = process.env.DEV_CHANNEL_DOCS_DIR || null;
@@ -18993,6 +19014,8 @@ var serverConfig = {
   }
 };
 async function freePort(port) {
+  if (process.env.HALTIJA_NO_RETIRE === "1")
+    return false;
   if (listenerPidsOnPort(port).length === 0)
     return false;
   const probe = await probePort(port);
@@ -19080,6 +19103,8 @@ async function probePort(port) {
 async function retireLegacyServers() {
   if (process.env.HALTIJA_NO_RETIRE === "1")
     return;
+  if (IS_PRIVATE)
+    return;
   const registryPorts = list().map((e) => e.port);
   const ports = candidatePorts({ defaults: [8700, 8701, PORT], registryPorts });
   let stopped = false;
@@ -19118,14 +19143,20 @@ if (USE_HTTP) {
     });
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
+      const wantedHttpPort = PORT;
       if (PORT_IS_STRICT) {
         if (await freePort(PORT)) {
           httpServer = Bun.serve({ port: PORT, ...serverConfig });
         } else {
+          console.error("");
+          console.error(`  \u26A0\uFE0F  Could not bind the HTTP port ${wantedHttpPort} you asked for \u2014 it is in use.`);
+          console.error(`      Free it, or start on another port (--port N / HALTIJA_PORT).`);
+          console.error("");
           throw err;
         }
       } else {
         httpServer = Bun.serve({ port: 0, ...serverConfig });
+        console.warn(`  [port] ${wantedHttpPort} was taken; bound HTTP on ${httpServer.port} instead. Find it with \`hj where\` (or read ~/.haltija/servers/).`);
       }
     } else {
       throw err;
@@ -19138,29 +19169,63 @@ if (USE_HTTPS) {
     cert: readFileSync5(certPath),
     key: readFileSync5(keyPath)
   };
+  const wantedHttpsPort = HTTPS_PORT;
+  const bindHttps = () => Bun.serve({ port: wantedHttpsPort, tls, ...serverConfig });
   try {
-    httpsServer = Bun.serve({ port: HTTPS_PORT, tls, ...serverConfig });
+    httpsServer = bindHttps();
   } catch (err) {
     if (err && typeof err === "object" && "code" in err && err.code === "EADDRINUSE") {
-      if (PORT_IS_STRICT) {
-        if (await freePort(HTTPS_PORT)) {
-          httpsServer = Bun.serve({ port: HTTPS_PORT, tls, ...serverConfig });
-        } else {
-          throw err;
-        }
+      if (PORT_IS_STRICT && await freePort(wantedHttpsPort)) {
+        httpsServer = bindHttps();
       } else {
-        httpsServer = Bun.serve({ port: 0, tls, ...serverConfig });
+        for (let attempt = 0;attempt < 5 && !httpsServer; attempt++) {
+          Bun.sleepSync(400);
+          try {
+            httpsServer = bindHttps();
+          } catch {}
+        }
+        if (!httpsServer) {
+          console.error("");
+          console.error(`  \u26A0\uFE0F  HTTPS could not bind its port ${wantedHttpsPort} \u2014 it is still in use`);
+          console.error(`      (a previous server in TIME_WAIT, or another process holding it).`);
+          console.error(`      A widget on an https page connects to :${wantedHttpsPort}, so it will`);
+          console.error(`      NOT connect until this is free. Haltija is NOT silently relocating it.`);
+          console.error(`      Fix: wait a few seconds and restart, or free port ${wantedHttpsPort}.`);
+          console.error("");
+          if (!USE_HTTP) {
+            throw err;
+          }
+        }
       }
     } else {
       throw err;
     }
   }
-  HTTPS_PORT = httpsServer.port ?? HTTPS_PORT;
+  if (httpsServer)
+    HTTPS_PORT = httpsServer.port ?? HTTPS_PORT;
 }
-var httpUrl = USE_HTTP ? `http://localhost:${PORT}` : null;
-var httpsUrl = USE_HTTPS ? `https://localhost:${HTTPS_PORT}` : null;
+var httpUrl = httpServer ? `http://localhost:${PORT}` : null;
+var httpsUrl = httpsServer ? `https://localhost:${HTTPS_PORT}` : null;
 var primaryUrl = httpsUrl || httpUrl;
-var CAN_BE_REGISTERED = USE_HTTP;
+if (IS_PRIVATE) {
+  const ready = {
+    port: PORT,
+    httpsPort: httpsServer ? HTTPS_PORT : null,
+    url: httpUrl,
+    httpsUrl,
+    pid: process.pid
+  };
+  console.log(`HALTIJA_PRIVATE_READY ${JSON.stringify(ready)}`);
+  const portFile = process.env.HALTIJA_PORT_FILE;
+  if (portFile) {
+    try {
+      writeFileSync3(portFile, JSON.stringify(ready));
+    } catch (err) {
+      console.error(`${LOG_PREFIX} could not write HALTIJA_PORT_FILE ${portFile}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+}
+var CAN_BE_REGISTERED = USE_HTTP && !IS_PRIVATE;
 var REGISTRY_NAME = !CAN_BE_REGISTERED ? "" : INSTANCE_NAME || (isDesktopApp ? "" : autoNameFor(PORT));
 if (!CAN_BE_REGISTERED && (INSTANCE_NAME || !isDesktopApp)) {
   console.log(`${LOG_PREFIX} HTTPS-only: not registering an instance (hj speaks HTTP; cwd routing and --name need an HTTP port)`);
@@ -19367,8 +19432,14 @@ if (USE_HTTPS && !httpUrl) {
 `);
 }
 if (MODE === "both") {
-  console.log(`  Mode: both - Use HTTP (${PORT}) for HTTP sites, HTTPS (${HTTPS_PORT}) for HTTPS sites.
+  if (httpsServer) {
+    console.log(`  Mode: both - Use HTTP (${PORT}) for HTTP sites, HTTPS (${HTTPS_PORT}) for HTTPS sites.
 `);
+  } else {
+    console.log(`  Mode: both - \u26A0\uFE0F  HTTP (${PORT}) is up but HTTPS is DOWN (see the warning above).`);
+    console.log(`              Pages served over https will not connect until HTTPS binds.
+`);
+  }
 }
 var server = httpsServer || httpServer;
 export {

package/dist/version.d.ts

@@ -8,4 +8,4 @@
  * ⚠️  AUTO-GENERATED FROM package.json - DO NOT EDIT THIS FILE
  * ⚠️  To change the version, update package.json and run: bun run build
  */
-export declare const VERSION = "1.4.0";
+export declare const VERSION = "1.4.1";

package/llms.txt

@@ -59,6 +59,7 @@ Or via a script tag (auto-injecting IIFE bundle served by the running server):
 
 ## Gotcha: a tab can read as unreachable while its main thread is suspended
 - The widget proves liveness with a heartbeat. If the page's main thread or its `requestAnimationFrame` loop is suspended, the heartbeat stalls and commands time out or report "no browser connected" — even though the PAGE is fine. It's the instrument going quiet, not a page bug.
+- **A tab that is not visible on screen** — backgrounded, minimized, or maximized on another Space / fully occluded (macOS) — counts as `hidden`. Browsers stop `requestAnimationFrame` and throttle timers while hidden, AND the widget deliberately deactivates a hidden tab so untargeted commands go to the front tab. So a page you can't see may not answer an untargeted `hj eval`/`hj tree`, and rAF-driven state (scroll/animation) is frozen. Fix: bring it to the front, or **target it explicitly** — `hj --window <id> eval …` (id from `hj windows`) reaches a specific tab regardless of visibility.
 - **WebXR / immersive sessions suspend `window.requestAnimationFrame`** (the XR compositor drives frames instead), so a tab is unreachable *while immersive*. Drive state out through your own channel — write the values you care about somewhere your agent can read (a debug source, an in-headset stats panel) — rather than `hj eval` round-trips through the suspended heartbeat. A heavily throttled background tab or a long blocking task has the same shape.
 - A command hitting the WRONG page (not a dead one) is targeting, not liveness: run `hj where`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Browser control for AI agents - query DOM, click, type, run JS, watch mutations",
   "type": "module",
   "main": "dist/index.js",