haltija 1.3.4 → 1.4.1

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# 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
+project, this changes where your commands go — for the better, but read the first section.
+
+### Fixed: `hj` drove the wrong browser across projects
+
+`hj` never looked at your working directory. Every invocation, in every project, fell back to
+port 8700 and drove whatever browser was focused there — silently, with no error. The only way
+to target a project's own server was per-shell environment variables that agents spawning fresh
+shells routinely lose.
+
+Servers now record the directory they were started in, and `hj` picks the live server whose
+directory is the nearest ancestor of your cwd. Inside a project with its own server, plain
+`hj tree` just works — no flags, no env vars.
+
+- Falling back to the shared default port while other servers are running now **warns** on
+  stderr instead of quietly misrouting.
+- **`hj where`** tells you which port you're targeting, *why* it was chosen, and what's alive
+  there. Reach for it first when a command seems to hit the wrong page.
+- Precedence is unchanged and still wins: `--port` > `--name`/`HALTIJA_NAME` > `HALTIJA_PORT` >
+  `DEV_CHANNEL_PORT` > cwd match > port 8700.
+
+### Fixed: a stale server could hand every project an old `hj`
+
+`hj` is a single binary on your `PATH`, and every haltija server used to overwrite it on
+startup — so the last server to boot decided which `hj` *every project on the machine* ran. One
+forgotten `bunx haltija@beta` could silently downgrade the CLI for an unrelated, up-to-date
+project.
+
+- A **symlinked `hj` is never touched.** Point it at your own build and it stays put.
+- Servers **only bootstrap or repair** `hj` — they write it when nothing is there, or when
+  what's there is strictly older. They never downgrade it, and never rewrite it just because
+  the bytes differ. To find out what's installed they ask it (`hj --version`).
+- **`hj --version`**, and `hj` now warns when its version differs from the server it's driving.
+- `HALTIJA_NO_INSTALL=1` opts out of the install entirely.
+
+### New: pre-1.4.0 servers are retired on startup
+
+Older servers have none of the guards above and cannot be fixed in code that already shipped, so
+a 1.4.0+ server **asks** any haltija server **below 1.4.0** to stop when it starts, and says what
+it did. Retirement is `POST /shutdown` — an endpoint every haltija has understood since 0.1.7 —
+so it needs no process IDs and does no killing.
+
+This is deliberately narrow: it never stops a peer (1.4.0 and 1.4.1 coexist, and once 1.3.x is
+gone it never fires again), never touches a running desktop app, and never touches anything it
+cannot identify as haltija. When it can't stop a server, it complains rather than failing
+silently.
+
+`HALTIJA_NO_RETIRE=1` opts out. See "Housekeeping" in the README.
+
+### Also
+
+- HTTPS-only servers no longer advertise an HTTP port they aren't listening on.
+- Every REST response carries `X-Haltija-Version`.
+- **`hj` exits non-zero when an operation fails** (`success:false`) — not just with `--json`, but on action commands too (`hj click`, `navigate`, `key`, …). A click that didn't land, or any command with no browser connected, now exits 1 instead of 0, so an agent checking the exit code can't read a failed step as success. (Commands with their own human formatting were already this way; this closes the gap for the rest.)
+- `HALTIJA_REGISTRY_DIR` overrides the instance-registry location.
+- `hj` no longer auto-spawns a server against an **explicitly targeted** port (`--port`/`--name`/`HALTIJA_PORT`) or under `--no-launch` — a read-only command against a server you manage will not start a colliding one; it errors instead. Auto-spawn remains only for the bare default port.
+
+### Platform
+
+macOS and Linux. Native Windows is not supported — use WSL, where all of this works unmodified.

package/README.md

@@ -249,7 +249,11 @@ export HALTIJA_PORT=9123
 hj tree
 ```
 
-If you don't pass `--port`, haltija tries 8700 first and falls back to a kernel-assigned ephemeral port — `--name` records whichever port it ends up on so `hj` can find it. A different shell can target a different project; there's no global state, just one named instance per haltija server.
+If you don't pass `--port`, haltija tries 8700 first and falls back to a kernel-assigned ephemeral port.
+
+**You usually don't need `--name` at all.** A server records the directory it was started in, so **plain `hj` inside a project reaches that project's server** — no flags, no environment variables. `--name` and `--port` are overrides for when you want to address a server from *outside* its directory. `hj where` shows which server a shell is targeting and why.
+
+Haltija does keep a little state outside your project — a shared `hj` on your PATH and a registry of running servers. That's deliberate, and it's all logged: see [Housekeeping](#housekeeping--what-haltija-does-to-your-machine) below.
 
 **Production embedding.** When haltija is reachable beyond loopback, gate it with a shared-secret token:
 
@@ -302,6 +306,50 @@ app also exists but isn't required for either.
 
 ---
 
+## Housekeeping — what Haltija does to your machine
+
+Haltija acts at **machine** scope on purpose. "Which `hj` does every shell on this box
+run?" is not a question a per-project fix can answer — so a few things live outside your
+project directory. All of it is opt-out, and **all of it leaves a receipt.**
+
+**Everything Haltija does outside its own project is logged to
+`~/.haltija/machine-actions.log`** (timestamped, with the version and the *directory of the
+project that triggered it*) and announced on **stderr**. That matters because Haltija is
+often a transitive dependency: if some other project's `test-browser` script spawned it,
+you may not know what Haltija even is. The receipt tells you what happened, when, and which
+project caused it.
+
+**It installs `hj` into `~/.local/bin`.** One CLI, shared by every project. It will
+**never overwrite a symlink** (if you point `hj` at your own build, that's yours) and
+**never downgrade** a newer `hj` than the one it carries. `HALTIJA_NO_INSTALL=1` disables it.
+
+**It registers itself in `~/.haltija/servers/`,** recording the directory it was started
+in. That's what lets plain `hj` inside a project reach *that project's* server instead of
+whichever browser happens to be focused somewhere else. The entry is removed on shutdown.
+`hj where` shows what your shell is targeting and why.
+
+**It stops haltija servers older than 1.4.0.** Those versions overwrite the shared
+`~/.local/bin/hj` on every boot, so one stale server left running quietly hands every
+project on your machine an old CLI. A 1.4.0+ server **asks** them to stop on startup
+(`POST /shutdown`, which every haltija has understood since 0.1.7) and says so. It does
+not go hunting for processes to kill. It is deliberately narrow:
+
+- It only stops servers **below 1.4.0** — never a peer. Two projects on 1.4.0 and 1.4.1
+  coexist; nothing kills anything once 1.3.x is gone.
+- It **will not touch a running desktop app** (that would orphan a window you can see) —
+  it tells you to quit and update it instead.
+- It **asks rather than kills.** Retirement is an HTTP request to a server that already
+  told us what it is — no process IDs, no `kill`. (An earlier draft resolved a port to a
+  pid with `lsof` and signalled it; `lsof -i :PORT` also matches connected *clients*, so
+  that would have killed your **browser**. Asking makes that whole class of mistake
+  impossible.)
+- On the rare fallback paths that must free a port without waiting, it signals only
+  **listeners** that `ps` confirms are haltija — never something it cannot identify.
+
+`HALTIJA_NO_RETIRE=1` disables it.
+
+---
+
 ## Use Cases
 
 - **AI pair programming** — Agent sees your actual app, not a description of it

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()
@@ -1292,39 +1312,90 @@ async function startEmbeddedServer() {
 /**
  * Ensure Haltija server is available
  */
-async function killZombieOnPort(port) {
-  if (os.platform() === 'win32') return true
-
+/** Is anything listening on this port? Listeners only — never connected clients. */
+function listenerPidsOnPort(port) {
   const { execSync } = require('child_process')
+  try {
+    // `-sTCP:LISTEN` is load-bearing. `lsof -i :PORT` matches sockets whose local OR
+    // REMOTE port is PORT, so without it this also returns every connected CLIENT —
+    // i.e. the user's browser, holding a WebSocket to this very server. Browsers open
+    // since login have the lower pid and sort first, so killing what this returns used
+    // to kill the browser and leave the server running.
+    const out = execSync(`lsof -ti:${port} -sTCP:LISTEN 2>/dev/null`, { encoding: 'utf-8' }).trim()
+    if (!out) return []
+    return out.split('\n').filter(Boolean).map(Number)
+      .filter(pid => Number.isFinite(pid) && pid !== process.pid)
+  } catch {
+    return []
+  }
+}
 
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    try {
-      const pids = execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: 'utf-8' }).trim()
-      if (!pids) {
-        console.log(`[Haltija Desktop] Port ${port} is free`)
-        return true
-      }
-
-      console.log(`[Haltija Desktop] Attempt ${attempt}: Killing process(es) on port ${port}: ${pids.replace(/\n/g, ', ')}`)
+/** Only signal something we can positively identify as haltija. */
+function isHaltijaProcess(pid) {
+  const { execSync } = require('child_process')
+  try {
+    const cmd = execSync(`ps -p ${pid} -o command= 2>/dev/null`, { encoding: 'utf-8' }).trim()
+    return !!cmd && /haltija|tosijs-dev/i.test(cmd)
+  } catch {
+    return false
+  }
+}
 
-      const signal = attempt < 3 ? '' : '-9'
-      execSync(`lsof -ti:${port} | xargs kill ${signal} 2>/dev/null`, { encoding: 'utf-8' })
+/**
+ * Free a port held by an old haltija server.
+ *
+ * ASK FIRST. `POST /shutdown` has shipped since 0.1.7, so any haltija server on this
+ * port can stop itself — cleanly, and with no pid involved. That matters: this used to
+ * run `lsof -ti:PORT | xargs kill -9`, which kills every pid matching the port
+ * INCLUDING connected clients, i.e. the user's browser. It ran on the default launch
+ * path, whenever a server was already up — exactly when browsers are attached.
+ *
+ * Signalling is now the fallback only, restricted to LISTENERS that `ps` confirms are
+ * haltija, and it never escalates to -9 against something it could not identify.
+ */
+async function killZombieOnPort(port) {
+  if (os.platform() === 'win32') return true
 
-      await new Promise(r => setTimeout(r, 500 * attempt))
+  if (listenerPidsOnPort(port).length === 0) {
+    console.log(`[Haltija Desktop] Port ${port} is free`)
+    return true
+  }
 
-      try {
-        execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: 'utf-8' })
-      } catch {
-        console.log(`[Haltija Desktop] Port ${port} freed successfully`)
-        return true
-      }
-    } catch {
-      console.log(`[Haltija Desktop] Port ${port} is free`)
+  // 1. Ask.
+  try {
+    await fetch(`http://localhost:${port}/shutdown`, {
+      method: 'POST',
+      signal: AbortSignal.timeout(1500),
+    })
+  } catch {
+    // Dying mid-response is a success; the liveness check below decides.
+  }
+  for (let i = 0; i < 20; i++) {
+    if (listenerPidsOnPort(port).length === 0) {
+      console.log(`[Haltija Desktop] Server on port ${port} shut down cleanly`)
       return true
     }
+    await new Promise(r => setTimeout(r, 100))
+  }
+
+  // 2. It didn't answer. Signal only what we can identify.
+  for (const pid of listenerPidsOnPort(port)) {
+    if (!isHaltijaProcess(pid)) {
+      console.error(`[Haltija Desktop] Port ${port} is held by pid ${pid}, which is not a haltija server — leaving it alone`)
+      continue
+    }
+    try {
+      process.kill(pid, 'SIGTERM')
+      console.log(`[Haltija Desktop] Stopped unresponsive haltija (pid ${pid}) on port ${port}`)
+    } catch {}
   }
+  await new Promise(r => setTimeout(r, 500))
 
-  console.error(`[Haltija Desktop] Warning: Could not free port ${port} after 3 attempts`)
+  if (listenerPidsOnPort(port).length === 0) {
+    console.log(`[Haltija Desktop] Port ${port} freed`)
+    return true
+  }
+  console.error(`[Haltija Desktop] Warning: could not free port ${port}`)
   return false
 }
 
@@ -1348,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.3.4",
+  "version": "1.4.1",
   "private": true,
   "description": "Haltija Desktop - God Mode Browser for AI Agents",
   "homepage": "https://github.com/tonioloewald/haltija",
@@ -10,12 +10,12 @@
   },
   "main": "main.js",
   "scripts": {
-    "start": "cd ../.. && bun run build && cd apps/desktop && electron .",
+    "start": "cd ../.. && bun run build && rm -f apps/desktop/resources/haltija-server-* && cd apps/desktop && electron .",
     "start:quick": "electron .",
     "icons": "electron scripts/generate-icons.js",
     "sync-version": "node -e \"const root = require('../../package.json'); const pkg = require('./package.json'); pkg.version = root.version; require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2) + '\\n')\"",
     "prebuild": "npm run sync-version && npm run icons && npm run compile:server",
-    "compile:server": "cd ../.. && bun run build && bun build --compile --target=bun-darwin-arm64 src/server.ts --outfile apps/desktop/resources/haltija-server-arm64 && bun build --compile --target=bun-darwin-x64 src/server.ts --outfile apps/desktop/resources/haltija-server-x64 && bun build --compile --target=bun-darwin-arm64 bin/hj.mjs --outfile apps/desktop/resources/hj-arm64 && bun build --compile --target=bun-darwin-x64 bin/hj.mjs --outfile apps/desktop/resources/hj-x64 && cp dist/component.js apps/desktop/resources/component.js && cp haltija-icon.svg apps/desktop/resources/icon.svg",
+    "compile:server": "cd ../.. && bun run build && bun build --compile --target=bun-darwin-arm64 src/server.ts --outfile apps/desktop/resources/haltija-server-arm64 && bun build --compile --target=bun-darwin-x64 src/server.ts --outfile apps/desktop/resources/haltija-server-x64 && cp dist/component.js apps/desktop/resources/component.js && cp haltija-icon.svg apps/desktop/resources/icon.svg",
     "compile:server:win": "cd ../.. && bun build --compile --target=bun-windows-x64 src/server.ts --outfile apps/desktop/resources/haltija-server-x64.exe",
     "compile:server:linux": "cd ../.. && bun build --compile --target=bun-linux-x64 src/server.ts --outfile apps/desktop/resources/haltija-server-x64 && bun build --compile --target=bun-linux-arm64 src/server.ts --outfile apps/desktop/resources/haltija-server-arm64",
     "build": "electron-builder",
@@ -94,8 +94,8 @@
         "to": "haltija-server-${arch}"
       },
       {
-        "from": "resources/hj-${arch}",
-        "to": "hj-${arch}"
+        "from": "resources/hj.mjs",
+        "to": "hj.mjs"
       },
       {
         "from": "resources/component.js",

package/apps/desktop/resources/component.js

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

package/bin/cli-subcommand.mjs

@@ -26,6 +26,8 @@ import { formatEvents } from './format-events.mjs'
 import { formatTestResult, formatSuiteResult } from './format-test.mjs'
 import { formatNetwork, formatNetworkStats } from './format-network.mjs'
 import { substituteGeneratedVars } from './test-data.mjs'
+import { HJ_VERSION } from './version.mjs'
+import { differsBeyondPatch } from './semver.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -34,6 +36,37 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 const hintsPath = join(__dirname, 'hints.json')
 export const COMMAND_HINTS = existsSync(hintsPath) ? JSON.parse(readFileSync(hintsPath, 'utf-8')) : {}
 
+let warnedAboutSkew = false
+
+/**
+ * Warn when this hj is meaningfully out of step with the server it just talked to.
+ *
+ * `hj` is ONE global binary driving MANY per-project servers, so some version skew is
+ * the normal steady state, not a fault: a project pinned to haltija 1.4.0 while the
+ * CLI is 1.4.2 is fine, and no action the user takes can make those numbers match.
+ *
+ * So warn only when the versions differ by more than a patch — that's when hj can
+ * actually lack a resolution rule or response shape the server assumes. Warning on
+ * exact mismatch would fire forever, on every command, with a remedy
+ * (`bun install -g haltija@latest`) that cannot fix it. And a warning that always
+ * fires is one that gets ignored — including the times it's real. SKILL.md tells
+ * agents to *trust* this warning, so it has to be worth trusting.
+ *
+ * Once per process, on stderr (so `--json` stdout stays machine-readable).
+ * `HALTIJA_NO_SKEW_WARN=1` silences it.
+ */
+function warnOnVersionSkew(resp) {
+  if (warnedAboutSkew) return
+  if (process.env.HALTIJA_NO_SKEW_WARN === '1') return
+  const serverVersion = resp.headers?.get?.('X-Haltija-Version')
+  if (!serverVersion) return
+  if (!differsBeyondPatch(serverVersion, HJ_VERSION)) return
+  warnedAboutSkew = true
+  console.error(`hj: warning — hj ${HJ_VERSION} is driving haltija server ${serverVersion}.`)
+  console.error(`hj: that gap is wide enough to route or format wrongly. This hj is ${process.argv[1]}`)
+  console.error(`hj: silence with HALTIJA_NO_SKEW_WARN=1`)
+}
+
 // Endpoints that use GET (everything else is POST)
 export const GET_ENDPOINTS = new Set([
   'location', 'events', 'console', 'windows', 'recordings',
@@ -778,14 +811,38 @@ export async function runSubcommand(subcommand, subArgs, port = '8700', options
     warnUnknownFlags(subcommand, filteredArgs)
   }
 
-  // Check if server is running, auto-start if not
+  // Check if a server is answering; auto-start one only if it's safe to.
   if (!(await isServerRunning(port))) {
+    // NEVER auto-spawn a server against a port the shell EXPLICITLY targeted (--port /
+    // --name / HALTIJA_PORT / …), and never under --no-launch.
+    //
+    // Spawning a server is a machine-topology mutation, and doing it from a read-only-ish
+    // command (`hj eval`, `hj tree`) against a targeted port is the sharpest edge in the CLI:
+    // the target is a server the USER manages — very often their dev server, embedded on a
+    // port they chose. If it's momentarily not answering (mid-restart, or HTTPS-only so the
+    // HTTP /status probe fails), spawning a generic server that BINDS that port collides with
+    // their setup and knocks it offline. That's a bug report, and it was: `hj --no-launch
+    // --port 8700 eval` bound its own listener on 8700 and took the dev channel down.
+    //
+    // So auto-spawn is only for the bare, unconfigured 8700 default — the zero-config "I just
+    // want it to work" path. This mirrors the Electron auto-launch rule (hj.mjs), which the
+    // server spawn had drifted out of sync with. An explicit target that isn't answering is an
+    // actionable error, not license to spawn.
+    if (noLaunch || explicitTarget) {
+      console.error(`Error: nothing is answering on the haltija server you targeted (port ${port}).`)
+      console.error(explicitTarget
+        ? 'That port is yours to manage — haltija will not spawn a server against a target you named.'
+        : 'Start it yourself: `haltija --server`  (or drop --no-launch to let hj start one on the default port).')
+      console.error('`hj where` shows what a shell is targeting and why.')
+      process.exit(1)
+    }
+
     // Respect "user manually quit Haltija" before we try to spawn anything.
     // The marker is dropped by the desktop app on will-quit and cleared on
     // its next launch — agent calls in between should not bring it back.
     try {
       const quitMarker = join(homedir(), '.haltija', 'last-quit')
-      if (!noLaunch && existsSync(quitMarker)) {
+      if (existsSync(quitMarker)) {
         console.error('Haltija was quit by user; not auto-launching.')
         console.error('Open Haltija manually to resume — or run `hj --no-launch` to bypass this check.')
         process.exit(1)
@@ -875,6 +932,7 @@ async function doRequest(url, method, body, context = {}) {
     }
 
     const resp = await fetch(url, opts)
+    warnOnVersionSkew(resp)
     const contentType = resp.headers.get('content-type') || ''
 
     if (contentType.includes('application/json')) {
@@ -925,7 +983,18 @@ async function doRequest(url, method, body, context = {}) {
           console.log(JSON.stringify(result, null, 2))
         }
       } else {
+        // The fall-through for BOTH `--json` and plain action commands with no special
+        // formatter (hj click / navigate / key / type / scroll …): print the envelope,
+        // then EXIT NON-ZERO IF IT SAYS FAILURE.
+        //
+        // This used to print `{"success": false, "error": "No browser connected…"}` (or an
+        // element-not-found) and exit 0. An agent that checks the exit code — which is how a
+        // harness decides whether a step worked — saw success while the payload said failure.
+        // That is the instrument lying, and for a debugging tool a lying instrument is worse
+        // than none: you can't tell "the page is broken" from "my probe is broken". A click
+        // that didn't click, or a probe with no browser, is a failure and now exits 1.
         console.log(JSON.stringify(json, null, 2))
+        if (json && json.success === false) process.exit(1)
       }
     } else {
       const text = await resp.text()