haltija 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+## 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

@@ -1292,39 +1292,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
 }
 

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "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.0";
 
   // 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()

package/bin/hj.mjs

@@ -11,12 +11,22 @@
  */
 
 import { runSubcommand, isSubcommand, getSuggestion, listSubcommands, COMMAND_HINTS } from './cli-subcommand.mjs'
+import { HJ_VERSION } from './version.mjs'
+import { differsBeyondPatch } from './semver.mjs'
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
 const args = process.argv.slice(2)
 
+/** Where instance entries live. Mirrors DEFAULT_REGISTRY_DIR in src/sessions.ts. */
+const REGISTRY_DIR = process.env.HALTIJA_REGISTRY_DIR || join(homedir(), '.haltija', 'servers')
+
+if (args[0] === '--version' || args[0] === '-v') {
+  console.log(HJ_VERSION)
+  process.exit(0)
+}
+
 /**
  * Print what server this shell is currently targeting and what's alive
  * there. Reports the resolved port, the source of the resolution (flag,
@@ -45,7 +55,7 @@ async function runWhere(port, portSource, jsonOutput) {
   // an entry pointing at this port.
   let instanceName = null
   try {
-    const dir = join(homedir(), '.haltija', 'servers')
+    const dir = REGISTRY_DIR
     if (existsSync(dir)) {
       for (const file of readdirSync(dir)) {
         if (!file.endsWith('.json')) continue
@@ -68,6 +78,9 @@ async function runWhere(port, portSource, jsonOutput) {
       portSource,
       reachable: !!serverInfo,
       error: serverError,
+      client: HJ_VERSION,
+      // Same policy as the human output: patch drift is not "skew", it's normal.
+      versionSkew: serverInfo ? differsBeyondPatch(serverInfo.serverVersion || '', HJ_VERSION) : null,
       server: serverInfo ? {
         version: serverInfo.serverVersion,
         instanceName,
@@ -95,11 +108,21 @@ async function runWhere(port, portSource, jsonOutput) {
     serverInfo.agents > 0 ? `${serverInfo.agents} agent${serverInfo.agents === 1 ? '' : 's'}` : null,
   ].filter(Boolean).join(', ')
   console.log(`${bold('server:')} ${desc}`)
+  console.log(`${bold('client:')} hj ${HJ_VERSION}`)
   if (focused) {
     console.log(`${bold('focused:')} ${focused.title || dim('(no title)')} ${dim(`— ${focused.url}`)}`)
   } else if (tabs === 0) {
     console.log(`${bold('focused:')} ${dim('no tabs connected')}`)
   }
+  // `hj where` is the diagnostic command, so it always SHOWS both versions above.
+  // It only escalates to a warning when the gap is wide enough to matter — patch
+  // skew between one global hj and many pinned per-project servers is normal and
+  // unfixable, and a warning that always fires is one nobody reads.
+  if (serverInfo.serverVersion && differsBeyondPatch(serverInfo.serverVersion, HJ_VERSION)) {
+    console.log(`\n${bold('warning:')} hj ${HJ_VERSION} is driving server ${serverInfo.serverVersion}.`)
+    console.log(dim(`  That gap is wide enough to route or format wrongly.`))
+    console.log(dim(`  This hj is ${process.argv[1]}`))
+  }
 }
 
 /**
@@ -108,7 +131,7 @@ async function runWhere(port, portSource, jsonOutput) {
  * malformed, or the recorded pid is no longer alive.
  */
 function lookupNamedInstance(name) {
-  const path = join(homedir(), '.haltija', 'servers', `${name}.json`)
+  const path = join(REGISTRY_DIR, `${name}.json`)
   if (!existsSync(path)) return null
   let entry
   try {
@@ -122,6 +145,47 @@ function lookupNamedInstance(name) {
   return entry
 }
 
+/**
+ * Every live entry in ~/.haltija/servers/. Mirrors `list()` in src/sessions.ts —
+ * duplicated rather than imported because this file is plain .mjs bundled
+ * standalone into dist/hj.js, with no access to the compiled TS.
+ */
+function listLiveInstances() {
+  const dir = REGISTRY_DIR
+  if (!existsSync(dir)) return []
+  const out = []
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.json')) continue
+    const entry = lookupNamedInstance(file.slice(0, -'.json'.length))
+    if (entry) out.push(entry)
+  }
+  return out
+}
+
+/** True if `dir` is `p` or one of its ancestors (segment-wise, not raw prefix). */
+function isAncestorOf(dir, p) {
+  if (!dir || !p) return false
+  if (dir === p) return true
+  return p.startsWith(dir.endsWith('/') ? dir : dir + '/')
+}
+
+/**
+ * Find the live server that owns `cwd` — the one whose recorded directory is
+ * the nearest ancestor of it. This is what makes plain `hj` inside a project
+ * reach *that project's* server instead of the global default port.
+ *
+ * `/` and the home directory are ancestors of everything, so servers started
+ * there can't win a match; otherwise they'd capture every project on the box.
+ */
+function resolveByCwd(cwd, instances) {
+  const candidates = instances.filter(
+    (e) => e.cwd && e.cwd !== '/' && e.cwd !== homedir() && isAncestorOf(e.cwd, cwd),
+  )
+  if (!candidates.length) return null
+  candidates.sort((a, b) => b.cwd.length - a.cwd.length || (b.startedAt || 0) - (a.startedAt || 0))
+  return candidates[0]
+}
+
 if (!args.length || args.includes('--help') || args.includes('-h')) {
   const bold = (s) => `\x1b[1m${s}\x1b[0m`
   const dim = (s) => `\x1b[2m${s}\x1b[0m`
@@ -130,7 +194,14 @@ ${bold('hj')} - Haltija command-line interface
 
 Usage: hj <command> [args...]
 
-${dim('Targeting a specific haltija server (per-shell):')}
+${dim('Which server does hj talk to?')}
+  ${dim('By default, the one that owns the directory you are in: a haltija server')}
+  ${dim('records where it was started, and hj picks the one whose directory is the')}
+  ${dim('nearest ancestor of your cwd. So inside a project with its own server,')}
+  ${dim('plain `hj tree` just works. Otherwise it falls back to port 8700.')}
+  ${dim('Run `hj where` to see the port, WHY it was chosen, and what is alive there.')}
+
+${dim('Overriding that (per-shell):')}
   ${dim('haltija --name api --server')}   # in another shell: register as "api"
   ${dim('export HALTIJA_NAME=api')}       # all hj calls in this shell talk to "api"
   ${dim('hj --name api tree')}            # one-off name override
@@ -138,6 +209,7 @@ ${dim('Targeting a specific haltija server (per-shell):')}
   ${dim('hj --port 9123 tree')}           # one-off port override
   ${dim('export HALTIJA_TOKEN=secret')}   # required when server was started with HALTIJA_TOKEN
   ${dim('hj --token secret tree')}        # one-off token override
+  ${dim('hj --version')}                  # which hj is this?
 ${listSubcommands()}
 Run ${dim('hj --help')} for this help.
 Run ${dim('haltija --help')} for server/app options.
@@ -156,29 +228,69 @@ if (nameIdx !== -1 && args[nameIdx + 1]) {
   args.splice(nameIdx, 2)
 }
 
+// Parse --port up front. It must be consumed BEFORE resolution runs: the
+// fallback branch below warns about landing on the default port, and if --port
+// were still unparsed at that moment, `hj --port 9999` would warn "you're on
+// 8700, use --port" and then correctly use 9999 — a single run contradicting
+// itself, telling the user to reach for the flag they just used.
+let portFlag = ''
+const portIdx = args.indexOf('--port')
+if (portIdx !== -1 && args[portIdx + 1]) {
+  portFlag = args[portIdx + 1]
+  args.splice(portIdx, 2)
+}
+
 // Port resolution priority:
 //   --port flag > --name/HALTIJA_NAME registry lookup > HALTIJA_PORT env
-//   > DEV_CHANNEL_PORT env > 8700 default
+//   > DEV_CHANNEL_PORT env > cwd match against the registry > 8700 default
+//
+// The cwd step is what keeps projects from stepping on each other: a server
+// started inside a project records its directory, so plain `hj` run anywhere
+// under that directory routes to it. Without it, every `hj` in every project
+// lands on 8700 and drives whatever browser is focused there — silently.
+//
+// Resolved highest-precedence-first and short-circuited, so each source is
+// consulted only when nothing above it decided. Only the final, losing branch
+// warns.
 let port, portSource
-if (process.env.DEV_CHANNEL_PORT) { port = process.env.DEV_CHANNEL_PORT; portSource = 'DEV_CHANNEL_PORT env (legacy)' }
-if (process.env.HALTIJA_PORT)     { port = process.env.HALTIJA_PORT;     portSource = 'HALTIJA_PORT env' }
-if (!port) { port = '8700'; portSource = '8700 (default)' }
-if (resolvedName) {
+if (portFlag) {
+  port = portFlag
+  portSource = '--port flag'
+} else if (resolvedName) {
   const entry = lookupNamedInstance(resolvedName)
-  if (entry) {
-    port = String(entry.port)
-    portSource = `name "${resolvedName}" via ${nameSource}`
-  } else {
+  if (!entry) {
     console.error(`hj: no live haltija instance named "${resolvedName}".`)
     console.error(`Start one with:  haltija --name ${resolvedName} --server`)
     process.exit(1)
   }
-}
-const portIdx = args.indexOf('--port')
-if (portIdx !== -1 && args[portIdx + 1]) {
-  port = args[portIdx + 1]
-  portSource = '--port flag'
-  args.splice(portIdx, 2)
+  port = String(entry.port)
+  portSource = `name "${resolvedName}" via ${nameSource}`
+} else if (process.env.HALTIJA_PORT) {
+  port = process.env.HALTIJA_PORT
+  portSource = 'HALTIJA_PORT env'
+} else if (process.env.DEV_CHANNEL_PORT) {
+  port = process.env.DEV_CHANNEL_PORT
+  portSource = 'DEV_CHANNEL_PORT env (legacy)'
+} else {
+  const live = listLiveInstances()
+  const cwdMatch = resolveByCwd(process.cwd(), live)
+  if (cwdMatch) {
+    port = String(cwdMatch.port)
+    portSource = `cwd match: ${cwdMatch.name}`
+  } else {
+    port = '8700'
+    portSource = '8700 (default)'
+    // Falling back to the shared default while project servers are running is
+    // the classic misroute — you think you're driving this project's browser
+    // and you're driving someone else's. Say so rather than doing it quietly.
+    // Reached only when nothing else selected a port, so it can't contradict an
+    // explicit choice.
+    if (live.length) {
+      const names = live.map((e) => `${e.name} (${e.cwd})`).join(', ')
+      console.error(`hj: warning — targeting the default port 8700, but these haltija servers are running: ${names}`)
+      console.error(`hj: if you meant one of them, cd into its directory, or use --name/--port. See \`hj where\`.`)
+    }
+  }
 }
 
 // Parse --token option (sets HALTIJA_TOKEN env so cli-subcommand.mjs picks it up).