haltija 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # Changelog
 
+## 1.5.0
+
+Completes the **private-automation** feature (`--private`) begun in 1.4.1 — now for the Electron
+app as well as headless — and adds two **"the instrument must not lie"** guards so a command that
+lands on the wrong or sleeping tab says so instead of returning a plausible-but-wrong answer.
+
+### New: `--private --app` — isolated Electron automation ([#1](https://github.com/tonioloewald/haltija/issues/1))
+
+`--private` gave headless runs an isolated server + browser on an ephemeral port. `--private --app`
+extends that to the desktop app: it spawns its **own** public and internal servers on ephemeral
+ports (never 8700/8701), drives its **own** browser, writes the public address to `--port-file`,
+and never sees, adopts, registers, or touches the shared interactive channel. The app's port
+constants are now resolved *after* the private servers report their ephemeral ports, so every
+downstream use — widget injection, `/status`, content tabs — follows the ephemeral instance.
+
+### New: hidden-tab warning ([#3](https://github.com/tonioloewald/haltija/issues/3))
+
+A backgrounded tab **answers** — `hj eval 'document.querySelectorAll("x").length'` returns `0`, not
+a timeout — because browsers stop `requestAnimationFrame` and throttle timers in a hidden tab, so
+anything mounted by rAF/IntersectionObserver never ran. The page looks broken when it's merely
+asleep. When a command is routed to a tab that reported itself hidden, the result now carries a
+warning that the number can be plausible-but-wrong, with how to target a visible tab.
+
+### New: focus-ambiguity warning ([#2](https://github.com/tonioloewald/haltija/issues/2))
+
+cwd routing gets an untargeted `hj` command to the right shared *server* and then stops — which
+*tab* answers falls back to focus. So two agents each staying in their own project can drive each
+other's pages once both have a tab on the shared server. When a command isn't pinned to a window
+and the server spans more than one origin, the result now warns that *focus*, not your directory,
+chose the tab — and lists the other tabs as `--window` pins. It deliberately does **not** guess
+which tab is "yours" (there's no reliable origin→directory map); ranking waits for one that can
+justify itself.
+
+### Fixed
+
+- **`hj --window <id> <cmd>`** — the documented leading form printed the usage banner instead of
+  targeting the window (`--window` wasn't pre-parsed like `--port`/`--name`). Both positions work now.
+- **Desktop-spawned servers get their port** via the env the server actually reads
+  (`HALTIJA_PORT`/`DEV_CHANNEL_PORT`, not `PORT`) — the app couldn't control its servers' ports before.
+
+## 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

@@ -29,15 +29,27 @@ const { attachNetwork, detachNetwork, getNetworkLog, getNetworkStats, clearNetwo
 process.stdout.on('error', () => {})
 process.stderr.on('error', () => {})
 
+// PRIVATE (isolated automation) mode — the Electron half of issue #1. `bunx haltija --private
+// --app` must be an isolated instance that never sees/adopts/touches the shared servers on
+// 8700/8701: it binds EPHEMERAL ports, discovered after the servers start. So these are `let`,
+// not `const` — reassigned once the private servers report their ports (below), which means every
+// downstream use (widget injection, status checks, help text, content tabs) automatically follows
+// the ephemeral ports with no other edits.
+const IS_PRIVATE = process.env.HALTIJA_PRIVATE === '1'
+// The caller's port-file (from `--port-file`), captured before we repurpose the env for our own
+// per-server discovery. In private mode the app writes the PUBLIC ephemeral address here so the
+// consumer (e.g. a dev-server test lane) can drive this instance.
+const CALLER_PORT_FILE = IS_PRIVATE ? (process.env.HALTIJA_PORT_FILE || null) : null
+
 // Haltija server config
-const HALTIJA_PORT = parseInt(process.env.HALTIJA_PORT || '8700')
-const HALTIJA_SERVER = `http://localhost:${HALTIJA_PORT}`
+let HALTIJA_PORT = IS_PRIVATE ? 0 : parseInt(process.env.HALTIJA_PORT || '8700')
+let HALTIJA_SERVER = `http://localhost:${HALTIJA_PORT}`
 
 // Internal port for the chrome widget (the haltija UI inspecting itself).
 // Lives on a separate server so it never appears in agent-facing window lists
 // — agents see only content tabs unless they explicitly target this port.
-const HALTIJA_INTERNAL_PORT = parseInt(process.env.HALTIJA_INTERNAL_PORT || '8701')
-const HALTIJA_INTERNAL_SERVER = `http://localhost:${HALTIJA_INTERNAL_PORT}`
+let HALTIJA_INTERNAL_PORT = IS_PRIVATE ? 0 : parseInt(process.env.HALTIJA_INTERNAL_PORT || '8701')
+let HALTIJA_INTERNAL_SERVER = `http://localhost:${HALTIJA_INTERNAL_PORT}`
 
 // Unique app instance ID - used to create stable window IDs across navigations
 // Combined with webContents.id to create globally unique tab identifiers
@@ -56,10 +68,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 +86,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 +322,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()
@@ -1168,8 +1200,34 @@ function checkServerRunning() {
  * Stdout/stderr are piped to the desktop app's console with a label, and
  * `__NEED_WINDOW__` from the public server triggers window recreation.
  */
-function spawnHaltijaServer({ port, role, serverPath, useCompiledBinary, componentDir }) {
-  const env = { ...process.env, PORT: port.toString(), HALTIJA_DESKTOP: '1' }
+function spawnHaltijaServer({ port, role, serverPath, useCompiledBinary, componentDir, portFile }) {
+  // Pass the port via the env the SERVER ACTUALLY READS. It was `PORT`, which src/server.ts
+  // never reads (it reads HALTIJA_PORT / DEV_CHANNEL_PORT) — so a spawned server ignored the
+  // port it was given and inherited the app's HALTIJA_PORT instead. The internal chrome server
+  // therefore tried to bind the PUBLIC port, collided, and died: verified by launching the app
+  // on high ports and finding nothing on the internal one.
+  const env = {
+    ...process.env,
+    PORT: port.toString(),            // kept for anything else that may read it
+    HALTIJA_PORT: port.toString(),    // what src/server.ts actually reads
+    DEV_CHANNEL_PORT: port.toString(),
+    HALTIJA_DESKTOP: '1',
+  }
+  if (IS_PRIVATE) {
+    // Isolated instance: this child binds an EPHEMERAL port (HALTIJA_PRIVATE forces PORT=0) and
+    // reports it to `portFile` so we can discover it. Each child gets its OWN port-file — never
+    // the caller's, which we write ourselves once with the public address.
+    env.HALTIJA_PRIVATE = '1'
+    env.HALTIJA_NO_RETIRE = '1'
+    env.HALTIJA_NO_INSTALL = '1'
+    env.HALTIJA_PORT_FILE = portFile
+    delete env.HALTIJA_PORT       // ephemeral, not the app's port
+    delete env.DEV_CHANNEL_PORT
+  } else {
+    // A non-private child must not inherit a private parent's flags (belt and braces).
+    delete env.HALTIJA_PRIVATE
+    delete env.HALTIJA_PORT_FILE
+  }
   let proc
   if (serverPath && useCompiledBinary) {
     proc = spawn(serverPath, [], {
@@ -1272,6 +1330,43 @@ async function startEmbeddedServer() {
     }
   }
 
+  if (IS_PRIVATE) {
+    // Private: both servers bind ephemeral ports we don't know yet. Give each its own port-file,
+    // wait for them to report, then reassign the module ports so everything downstream (injection,
+    // status, tabs, help) follows the ephemeral instance. Never touches 8700/8701.
+    const pubFile = path.join(os.tmpdir(), `haltija-app-pub-${process.pid}.json`)
+    const intFile = path.join(os.tmpdir(), `haltija-app-int-${process.pid}.json`)
+    try { fs.rmSync(pubFile, { force: true }); fs.rmSync(intFile, { force: true }) } catch {}
+
+    spawnHaltijaServer({ port: 0, role: 'public', serverPath, useCompiledBinary, componentDir, portFile: pubFile })
+    spawnHaltijaServer({ port: 0, role: 'internal', serverPath, useCompiledBinary, componentDir, portFile: intFile })
+
+    const readPort = async (file) => {
+      for (let i = 0; i < 50; i++) {
+        try { const d = JSON.parse(fs.readFileSync(file, 'utf8')); if (d && d.port) return d.port } catch {}
+        await new Promise((r) => setTimeout(r, 200))
+      }
+      return null
+    }
+    const pubPort = await readPort(pubFile)
+    const intPort = await readPort(intFile)
+    if (!pubPort) { console.error('[Haltija Desktop] Private public server did not report its port'); return false }
+
+    HALTIJA_PORT = pubPort
+    HALTIJA_SERVER = `http://localhost:${pubPort}`
+    if (intPort) { HALTIJA_INTERNAL_PORT = intPort; HALTIJA_INTERNAL_SERVER = `http://localhost:${intPort}` }
+    try { fs.rmSync(pubFile, { force: true }); fs.rmSync(intFile, { force: true }) } catch {}
+
+    // Hand the PUBLIC address to the consumer that asked for this private instance.
+    if (CALLER_PORT_FILE) {
+      try {
+        fs.writeFileSync(CALLER_PORT_FILE, JSON.stringify({ port: pubPort, url: HALTIJA_SERVER, internalPort: intPort || null, pid: process.pid }))
+      } catch (err) { console.error('[Haltija Desktop] Could not write caller port-file:', err.message) }
+    }
+    console.log(`[Haltija Desktop] Private instance ready — public ${HALTIJA_SERVER}, internal :${intPort || 'n/a'} (8700/8701 untouched)`)
+    return true
+  }
+
   spawnHaltijaServer({ port: HALTIJA_PORT, role: 'public', serverPath, useCompiledBinary, componentDir })
   spawnHaltijaServer({ port: HALTIJA_INTERNAL_PORT, role: 'internal', serverPath, useCompiledBinary, componentDir })
 
@@ -1386,6 +1481,13 @@ async function killZombieServer() {
 }
 
 async function ensureServer() {
+  // Private is isolated by construction: never look for, adopt, or replace a shared server. It
+  // always starts its own on ephemeral ports. `checkServerRunning` would probe 8700 (which we
+  // must ignore), so skip it entirely.
+  if (IS_PRIVATE) {
+    return await startEmbeddedServer()
+  }
+
   const running = await checkServerRunning()
 
   switch (prefs.serverMode) {
@@ -1399,9 +1501,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.5.0",
   "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.5.0";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/bin/cli-subcommand.mjs

@@ -938,6 +938,13 @@ async function doRequest(url, method, body, context = {}) {
     if (contentType.includes('application/json')) {
       const json = await resp.json()
 
+      // A result can be REAL but MISLEADING — e.g. it came from a hidden tab where rAF-driven
+      // content never mounted, so an empty selector means "not mounted", not "broken" (issue #3).
+      // Print it on stderr so it can't be mistaken for output, and so --json stdout stays clean.
+      if (json && typeof json.warning === 'string' && json.warning) {
+        console.error(`hj: warning — ${json.warning}`)
+      }
+
       // Text format for supported subcommands (unless --json)
       if (!jsonOutput && subcommand === 'tree' && json.success && json.data) {
         console.log(formatTree(json.data, 0, { depth: body?.depth }))

package/bin/hj.mjs

@@ -308,6 +308,18 @@ if (noLaunchIdx !== -1) {
   args.splice(noLaunchIdx, 1)
 }
 
+// Parse --window <id> HERE so it works BEFORE the subcommand, like --port/--name/--token do.
+// It was only handled after the subcommand, so the documented form `hj --window <id> eval …`
+// died with "Unknown command: '--window'" — i.e. the escape hatch we tell people to use for a
+// hidden/wrong tab didn't work in the shape the docs gave. Pulled out here and re-appended to
+// the subcommand args below, so BOTH positions work.
+let windowTarget = null
+const windowIdx = args.indexOf('--window')
+if (windowIdx !== -1 && args[windowIdx + 1]) {
+  windowTarget = args[windowIdx + 1]
+  args.splice(windowIdx, 2)
+}
+
 // Did the shell explicitly target a private instance (--port / --name /
 // HALTIJA_PORT / HALTIJA_NAME / DEV_CHANNEL_PORT)? If so, this is a
 // project-owned server with a bring-your-own browser — auto-launching the
@@ -343,7 +355,9 @@ if (args.length === 1 && !isSubcommand(args[0]) && NOUN_DEFAULTS[args[0]]) {
 }
 
 const subcommand = args[0]
-const subArgs = args.slice(1).filter(a => a !== '--window' || true) // keep all args
+let subArgs = args.slice(1)
+// Re-attach a leading --window so cli-subcommand's existing handling sees it (both positions work).
+if (windowTarget) subArgs = [...subArgs, '--window', windowTarget]
 
 // `hj where` — show which haltija server this shell is targeting and what
 // (if anything) is alive there. Pure client-side resolution plus a single

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'
@@ -523,15 +565,12 @@ function launchApp(desktopDir, port) {
 
   // Resolve electron binary directly to avoid npx cache race conditions (ENOTEMPTY)
   const electronBinary = resolveElectronBinary()
+  // A private app run must NOT pin DEV_CHANNEL_PORT — it binds ephemeral ports and never touches
+  // 8700. `env` already carries HALTIJA_PRIVATE=1 / HALTIJA_PORT_FILE from the --private block.
+  const appEnv = privateMode ? { ...env } : { ...env, DEV_CHANNEL_PORT: String(port) }
   const child = electronBinary
-    ? spawn(electronBinary, [desktopDir], {
-        env: { ...env, DEV_CHANNEL_PORT: String(port) },
-        stdio: 'inherit'
-      })
-    : spawn('npx', ['--yes', 'electron', desktopDir], {
-        env: { ...env, DEV_CHANNEL_PORT: String(port) },
-        stdio: 'inherit'
-      })
+    ? spawn(electronBinary, [desktopDir], { env: appEnv, stdio: 'inherit' })
+    : spawn('npx', ['--yes', 'electron', desktopDir], { env: appEnv, stdio: 'inherit' })
 
   child.on('error', (err) => {
     console.error(red('Error:') + ` Failed to launch desktop app: ${err.message}`)
@@ -717,7 +756,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 +795,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 +918,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.5.0'

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.5.0";
 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.5.0";
 
 // 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.5.0";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/focus-ambiguity.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Did *focus* choose this tab, when the caller's *directory* should have?
+ *
+ * From issue #2. cwd routing (see `sessions.resolveByCwd`) gets an untargeted `hj` command to the
+ * right shared **server** — and then stops. Which **tab** on that server answers falls back to
+ * whatever is focused. So two agents, each correctly staying in its own project directory, can
+ * still drive each other's pages the moment both projects have a tab on the same shared 8700
+ * server; a human clicking into a second project's tab causes it solo.
+ *
+ * The obvious fix — rank tabs by "origin matches the cwd project" — has a trap: there is no
+ * reliable map from a tab's origin (a URL like `localhost:8787`) to a project **directory**. The
+ * dev-server port that injected the widget isn't always the project (proxies, multiple ports,
+ * static previews, `about:blank` mid-navigation). A ranking that's *usually* right would pick
+ * confidently and wrongly — reintroducing exactly the silent-misroute class we spent 1.4.0
+ * eliminating. A registry entry's `cwd` is per-**server**, not per-tab, so it can't sharpen this
+ * either.
+ *
+ * So we don't claim a mapping we don't have. We warn only about what is honestly knowable: the
+ * command was **not** pinned to a window, and this server spans **more than one origin**, so
+ * *focus* — not the caller's directory — chose which page answered. That's the honest half of the
+ * issue's "warn when the focused tab's origin doesn't match the cwd server's directory", and it
+ * composes with the hidden-tab warning (issue #3): one says the tab was asleep, this says the
+ * wrong tab may have been picked. Preference/ranking waits for a mapping that can justify itself.
+ */
+/** The bits of a tracked window this decision needs. */
+export interface FocusWindowInfo {
+    id: string;
+    url?: string;
+    title?: string;
+    /** 'tab' | 'popup' | 'iframe' (older widgets may omit it — treated as a tab). */
+    windowType?: string;
+}
+/** A tab's origin for grouping — `about:blank`, opaque, and unparseable URLs fall back to the raw
+ * string so they still form an honest distinct bucket rather than silently collapsing together. */
+export declare function originOf(url: string | undefined | null): string | null;
+/**
+ * A warning to attach when an *untargeted* command was answered by the focused tab while the
+ * server hosts tabs from more than one origin — i.e. focus, not the caller's directory, chose the
+ * page. Returns null when the caller pinned a window, when we don't know what answered, or when
+ * every tab shares one origin (no ambiguity to flag).
+ */
+export declare function ambiguousFocusWarning(opts: {
+    windows: FocusWindowInfo[];
+    sentToId: string | null | undefined;
+    /** True when the caller explicitly targeted a window (`--window` / `?window=`). */
+    wasTargeted: boolean;
+}): string | null;

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.5.0
 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.5.0";
 
 // bin/semver.mjs
 function parseVersion(v) {
@@ -1628,6 +1628,9 @@ async function doRequest(url, method, body, context = {}) {
     const contentType = resp.headers.get("content-type") || "";
     if (contentType.includes("application/json")) {
       const json = await resp.json();
+      if (json && typeof json.warning === "string" && json.warning) {
+        console.error(`hj: warning — ${json.warning}`);
+      }
       if (!jsonOutput && subcommand === "tree" && json.success && json.data) {
         console.log(formatTree(json.data, 0, { depth: body?.depth }));
       } else if (!jsonOutput && subcommand === "events" && (json.events || Array.isArray(json))) {
@@ -2134,6 +2137,12 @@ if (noLaunchIdx !== -1) {
   noLaunch = true;
   args.splice(noLaunchIdx, 1);
 }
+var windowTarget = null;
+var windowIdx = args.indexOf("--window");
+if (windowIdx !== -1 && args[windowIdx + 1]) {
+  windowTarget = args[windowIdx + 1];
+  args.splice(windowIdx, 2);
+}
 var explicitTarget = portSource !== "8700 (default)";
 if (args.length >= 2 && isSubcommand(`${args[0]}-${args[1]}`)) {
   args.splice(0, 2, `${args[0]}-${args[1]}`);
@@ -2152,7 +2161,9 @@ if (args.length === 1 && !isSubcommand(args[0]) && NOUN_DEFAULTS[args[0]]) {
   args[0] = NOUN_DEFAULTS[args[0]];
 }
 var subcommand = args[0];
-var subArgs = args.slice(1).filter((a) => a !== "--window" || true);
+var subArgs = args.slice(1);
+if (windowTarget)
+  subArgs = [...subArgs, "--window", windowTarget];
 if (subcommand === "where") {
   await runWhere(port, portSource, subArgs.includes("--json"));
   process.exit(0);