haltija 1.5.4 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## 1.6.1
+
+Makes haltija's detection reachable by automation ([#8](https://github.com/tonioloewald/haltija/issues/8),
+[#11](https://github.com/tonioloewald/haltija/issues/11)).
+
+haltija already *detects* the situations that wreck a test lane — the wrong project's browser, a
+hidden tab returning stale results, a server with nothing to drive. It only ever **warned on
+stderr**, so scripts consumed plausible-but-wrong results and failed much later, pointing at the
+caller's own code.
+
+### New: `ready` — "server is up" is not "server is drivable"
+
+`/status` and `/windows` now return **`ready`**: true when at least one top-level tab is connected.
+A server running with *zero* windows answers `/status` 200, so an adopter's reuse probe skipped
+starting its own browser and then had nothing to navigate. Gate a lane on `ready`, not on the 200.
+
+### New: `hj doctor`
+
+One-command preflight that **exits non-zero**: server reachable → a tab is connected → the target
+isn't ambiguous → tabs aren't all hidden → versions aligned. `--json` for machine-readable output.
+Use it as the wait-loop condition in CI.
+
+### New: `hj --strict` / `HALTIJA_STRICT=1`
+
+Turns the advisory warnings into **non-zero exits**, and refuses to print a suspect result to
+stdout at all — a script must not consume a value that may be wrong. A warning is the right default
+for a human at a prompt and the wrong one for a lane.
+
+### Fixed
+
+- **Warning de-duplication silently defeated strict mode.** The server withheld a repeated warning
+  entirely, so the first command in a lane failed and every later one within the cooldown passed.
+  The server now always reports the condition and marks repeats (`warningRepeated`); de-dup is a
+  presentation concern, so `hj` stays quiet on a repeat while `--strict` fails on any warning.
+
+## 1.6.0
+
+Consolidating release: rolls up everything from 1.5.2–1.5.7 (the last npm-published version was
+1.5.4) and adds the fixes from a full nine-lens pre-release review of the whole span.
+
+**Highlights since 1.5.4** (see the per-version entries below for detail):
+
+- **`--private --app` teardown** (1.5.5, #7) — private Electron no longer orphans: skips the
+  single-instance lock, self-terminates when its spawner dies, `hj shutdown` tears it all down.
+- **Console capture** (1.5.6) — uncaught exceptions, unhandled rejections, and `console.error(Error)`
+  messages/stacks are now captured (all were previously dropped).
+- **Server picker** (1.5.7) — `hj servers` lists every live server; the desktop app is reachable as
+  `hj --name desktop`.
+
+**Review-driven fixes in this release:**
+
+- **`hj shutdown` no longer orphans a running desktop app.** It refuses (with a clear message —
+  quit the app from its window) instead of killing just the embedded server and leaving the window
+  on screen with dead tabs. `--private` instances still tear down fully.
+- **`--name desktop` is reserved** — a normal server can no longer claim it and clobber the desktop
+  app's registry entry.
+- The uncaught-error listeners are removed on widget disconnect (no leak across re-injection).
+- `hj ls` is now an alias for `hj servers` (was `hj tree`); the old alias is gone.
+- Added tabs-focus regression tests and `hj servers` / `hj --name desktop` / `hj shutdown` to the
+  generated docs and the agent skill.
+
+## 1.5.7
+
+Pick between coexisting servers.
+
+When a normal haltija server and the Electron desktop app both ran, there was no way to see them or
+target the app — it was unregistered, invisible to `hj where` and the registry.
+
+- **`hj servers`** (alias `hj ls`) lists every live server: registry entries, the probed defaults
+  8700/8701, and this shell's target — with port, name, version, tab count, whether it's the
+  desktop app, and a `▸` on the one `hj` would drive.
+- **The desktop app is now reachable as `hj --name desktop`.** Its public server registers under
+  the reserved name `desktop`, but *cwd-less* — so it's nameable without ever hijacking cwd routing.
+  (The internal chrome server stays unregistered; a `--private` app registers nothing.)
+
+## 1.5.6
+
+`hj console` now captures the errors that actually matter.
+
+It intercepted `console.*` calls, but the most important errors slipped through: an **uncaught
+exception** (`throw`) and an **unhandled promise rejection** were never captured (no `window`
+error / `unhandledrejection` listener), and `console.error(new Error(...))` recorded `{}` because
+`JSON.stringify` drops an Error's message and stack. A page could be throwing on every action while
+`hj console` showed it clean.
+
+- Uncaught exceptions and unhandled rejections are now captured as `error` entries, with the real
+  stack. The `error` listener uses the capture phase, so failed resource loads (img/script/…) are
+  seen too.
+- Error objects serialize to `{name, message, stack}` (at any depth), so the message survives.
+- Note: capture begins when the widget is injected, so errors thrown *before* injection are only
+  caught by the desktop app (which injects at document-start).
+
+## 1.5.5
+
+`--private` now really is "torn down with the run" ([#7](https://github.com/tonioloewald/haltija/issues/7)).
+
+The private Electron instance used to survive teardown — holding Electron's single-instance lock (so
+the **next** `--private` run failed with "Another instance is already running") and leaking a process
+per run. Fixed three ways, all verified with real Electron:
+
+- **A private run never takes the single-instance lock.** Private instances are isolated on ephemeral
+  ports and meant to run concurrently / back-to-back, so an orphan can no longer block the next run,
+  and two private runs coexist.
+- **The private Electron self-terminates** when its spawner dies (even via SIGKILL) or on
+  SIGTERM/SIGINT. It reparents to launchd, so it watches the launcher's pid (`HALTIJA_SPAWNER_PID`)
+  and calls `app.quit()` — which reaps its own helper processes, unlike an external tree-kill.
+- **`hj shutdown` / `hj quit`** (and `POST /shutdown`) on a private-desktop instance tears down the
+  whole thing — Electron and its servers — for a deterministic end-of-run teardown.
+
 ## 1.5.4
 
 The `hj tabs open` client-less-tab trap now explains itself ([#5](https://github.com/tonioloewald/haltija/issues/5)).

package/apps/desktop/main.js

@@ -1212,6 +1212,10 @@ function spawnHaltijaServer({ port, role, serverPath, useCompiledBinary, compone
     HALTIJA_PORT: port.toString(),    // what src/server.ts actually reads
     DEV_CHANNEL_PORT: port.toString(),
     HALTIJA_DESKTOP: '1',
+    // Only the PUBLIC server (the one agents drive) registers under the reserved 'desktop' name so
+    // `hj --name desktop` / `hj servers` can find it; the internal chrome server stays unregistered.
+    // See src/server.ts REGISTRY_NAME. (Ignored for a private run — those never register.)
+    HALTIJA_DESKTOP_PUBLIC: role === 'public' ? '1' : '0',
   }
   if (IS_PRIVATE) {
     // Isolated instance: this child binds an EPHEMERAL port (HALTIJA_PRIVATE forces PORT=0) and
@@ -1532,8 +1536,12 @@ async function ensureServer() {
   }
 }
 
-// Single-instance lock — prevent multiple Electron windows from launching
-const gotTheLock = app.requestSingleInstanceLock()
+// Single-instance lock — prevent multiple Electron windows from launching.
+// A PRIVATE run must NOT contend for it (issue #7): private instances are isolated on ephemeral
+// ports and are meant to run many at once / back-to-back. Taking the shared lock means an orphaned
+// private Electron blocks the NEXT private run ("Another instance is already running"), and two
+// concurrent private runs collide. So a private run never requests and never holds the lock.
+const gotTheLock = IS_PRIVATE ? true : app.requestSingleInstanceLock()
 
 if (!gotTheLock) {
   console.log('[Haltija Desktop] Another instance is already running. Focusing existing window.')
@@ -1548,6 +1556,29 @@ if (!gotTheLock) {
     }
   })
 
+  // "Torn down with the run": a PRIVATE Electron must not outlive its spawner (issue #7). An
+  // orphaned private Electron holds nothing shared anymore (we skip the lock above), but it still
+  // leaks a process + its servers. Electron reparents to launchd shortly after startup, so
+  // process.ppid is useless — the launcher passes its own pid as HALTIJA_SPAWNER_PID and we poll
+  // it. On the spawner's death, or a SIGTERM/SIGINT, quit via app.quit() → 'will-quit' kills the
+  // child servers AND Electron reaps its own helper processes (which an EXTERNAL kill notoriously
+  // fails to do — the reason we self-terminate instead of asking the consumer to hunt the tree).
+  if (IS_PRIVATE) {
+    let quitting = false
+    const quitOnce = () => { if (quitting) return; quitting = true; try { app.quit() } catch {} }
+    process.on('SIGTERM', quitOnce)
+    process.on('SIGINT', quitOnce)
+    const spawnerPid = parseInt(process.env.HALTIJA_SPAWNER_PID || '', 10)
+    if (Number.isFinite(spawnerPid)) {
+      const iv = setInterval(() => {
+        let alive = true
+        try { process.kill(spawnerPid, 0) } catch { alive = false } // signal 0 = existence check
+        if (!alive) { clearInterval(iv); console.log('[Haltija Desktop] spawner gone — tearing down private instance'); quitOnce() }
+      }, 1000)
+      if (iv.unref) iv.unref()
+    }
+  }
+
   // App lifecycle
   app.whenReady().then(async () => {
     console.log('[Haltija Desktop] App ready, starting initialization...')

package/apps/desktop/package.json

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

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.5.4";
+  var VERSION = "1.6.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -1738,6 +1738,7 @@
     ws = null;
     state = "disconnected";
     consoleBuffer = [];
+    errorCaptureInstalled = false;
     eventWatchers = new Map;
     mutationObserver = null;
     shadowObservers = new Map;
@@ -1969,6 +1970,7 @@
       this.killed = true;
       this.disconnect();
       this.restoreConsole();
+      this.uninstallErrorCapture();
       this.restoreDialogs();
       this.clearEventWatchers();
       this.stopMutationWatch();
@@ -7426,6 +7428,26 @@ ${elementSummary}${moreText}`;
         window.prompt = this.originalDialogs.prompt;
       this.originalDialogs = {};
     }
+    serializeConsoleArg(arg) {
+      try {
+        return JSON.parse(JSON.stringify(arg, (_k, v) => v instanceof Error ? { name: v.name, message: v.message, stack: v.stack } : v));
+      } catch {
+        return String(arg);
+      }
+    }
+    recordConsoleEntry(entry) {
+      try {
+        this.consoleBuffer.push(entry);
+        if (this.consoleBuffer.length > 1000) {
+          this.consoleBuffer = this.consoleBuffer.slice(-500);
+        }
+        if (entry.level === "error") {
+          if (this.state === "connected")
+            this.send("console", "error", entry);
+          this.updateUI();
+        }
+      } catch {}
+    }
     interceptConsole() {
       const levels = [
         "log",
@@ -7441,31 +7463,73 @@ ${elementSummary}${moreText}`;
           try {
             const entry = {
               level,
-              args: args.map((arg) => {
-                try {
-                  return JSON.parse(JSON.stringify(arg));
-                } catch {
-                  return String(arg);
-                }
-              }),
+              args: args.map((arg) => this.serializeConsoleArg(arg)),
               timestamp: Date.now()
             };
             if (level === "error") {
-              entry.stack = new Error().stack;
-            }
-            this.consoleBuffer.push(entry);
-            if (this.consoleBuffer.length > 1000) {
-              this.consoleBuffer = this.consoleBuffer.slice(-500);
-            }
-            if (level === "error") {
-              if (this.state === "connected") {
-                this.send("console", level, entry);
-              }
-              this.updateUI();
+              const errArg = args.find((a) => a instanceof Error);
+              entry.stack = errArg?.stack || new Error().stack;
             }
+            this.recordConsoleEntry(entry);
           } catch {}
         };
       }
+      this.installErrorCapture();
+    }
+    onWindowError = null;
+    onUnhandledRejection = null;
+    installErrorCapture() {
+      if (typeof window === "undefined" || this.errorCaptureInstalled)
+        return;
+      this.errorCaptureInstalled = true;
+      this.onWindowError = (event) => {
+        try {
+          const err = event.error;
+          let message;
+          let stack;
+          if (err instanceof Error) {
+            message = `Uncaught ${err.name}: ${err.message}`;
+            stack = err.stack;
+          } else if (event.target?.tagName) {
+            const el = event.target;
+            message = `Resource failed to load: <${String(el.tagName).toLowerCase()}> ${el.src || el.href || ""}`.trim();
+          } else {
+            message = `Uncaught error: ${event.message || "unknown"}`;
+          }
+          const where = event.filename ? ` (${event.filename}:${event.lineno}:${event.colno})` : "";
+          this.recordConsoleEntry({
+            level: "error",
+            args: [message + where],
+            timestamp: Date.now(),
+            stack
+          });
+        } catch {}
+      };
+      window.addEventListener("error", this.onWindowError, true);
+      this.onUnhandledRejection = (event) => {
+        try {
+          const reason = event.reason;
+          const args = reason instanceof Error ? [`Unhandled promise rejection: ${reason.name}: ${reason.message}`] : ["Unhandled promise rejection:", this.serializeConsoleArg(reason)];
+          this.recordConsoleEntry({
+            level: "error",
+            args,
+            timestamp: Date.now(),
+            stack: reason instanceof Error ? reason.stack : undefined
+          });
+        } catch {}
+      };
+      window.addEventListener("unhandledrejection", this.onUnhandledRejection);
+    }
+    uninstallErrorCapture() {
+      if (typeof window !== "undefined") {
+        if (this.onWindowError)
+          window.removeEventListener("error", this.onWindowError, true);
+        if (this.onUnhandledRejection)
+          window.removeEventListener("unhandledrejection", this.onUnhandledRejection);
+      }
+      this.onWindowError = null;
+      this.onUnhandledRejection = null;
+      this.errorCaptureInstalled = false;
     }
     restoreConsole() {
       for (const [level, fn] of Object.entries(this.originalConsole)) {

package/bin/cli-subcommand.mjs

@@ -942,7 +942,19 @@ async function doRequest(url, method, body, context = {}) {
       // 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}`)
+        if (process.env.HALTIJA_STRICT === '1') {
+          // Strict mode (issue #8): if the result may be wrong, a script must not consume it. Fail
+          // fast with the real reason instead of emitting a plausible-but-wrong value that makes the
+          // lane fail later, pointing at the caller's own code. stdout stays empty on purpose.
+          // NB: fails on `warningRepeated` too — the condition still holds, and suppressing repeats
+          // here would let every command after the first silently pass.
+          console.error(`hj: ERROR (strict) — ${json.warning}`)
+          console.error(`hj: refusing to return a result that may be wrong. Fix the condition above, or drop --strict/HALTIJA_STRICT to proceed anyway.`)
+          process.exit(1)
+        }
+        // Non-strict: stay quiet on a repeat within the cooldown, so a burst of commands doesn't
+        // re-print the same block and train the reader to ignore it.
+        if (!json.warningRepeated) console.error(`hj: warning — ${json.warning}`)
       }
 
       // Text format for supported subcommands (unless --json)
@@ -1073,7 +1085,7 @@ const COMMAND_ALIASES = {
   'execute': 'eval',
   'shot': 'screenshot',
   'capture': 'screenshot',
-  'ls': 'tree',
+  // NB: `ls` is NOT an alias for `tree` — it's intercepted in hj.mjs as `hj servers` (list servers).
   'list': 'tree',
   'show': 'tree',
   'help': '--help',

package/bin/hj.mjs

@@ -126,6 +126,169 @@ async function runWhere(port, portSource, jsonOutput) {
   }
 }
 
+/**
+ * `hj servers` — enumerate every live haltija server so you can pick one when several coexist
+ * (e.g. a project server + the Electron desktop app). Sources: the registry, the well-known
+ * defaults 8700/8701 (to catch anything unregistered), and this shell's resolved target. Marks the
+ * one `hj` would drive. Pure probes + registry read; no side effects, never auto-launches.
+ */
+async function runServers(resolvedPort) {
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`
+  const green = (s) => `\x1b[32m${s}\x1b[0m`
+  const token = process.env.HALTIJA_TOKEN
+
+  const byPort = new Map()
+  for (const e of listLiveInstances()) {
+    byPort.set(String(e.port), { port: String(e.port), name: e.name, cwd: e.cwd })
+  }
+  for (const p of ['8700', '8701', String(resolvedPort)]) {
+    if (!byPort.has(p)) byPort.set(p, { port: p, name: null, cwd: null })
+  }
+
+  const rows = await Promise.all(
+    [...byPort.values()].map(async (c) => {
+      try {
+        const resp = await fetch(`http://localhost:${c.port}/status`, {
+          headers: token ? { 'X-Haltija-Token': token } : {},
+          signal: AbortSignal.timeout(2000),
+        })
+        if (!resp.ok) return { ...c, up: false }
+        const s = await resp.json()
+        return {
+          ...c,
+          up: true,
+          version: s.serverVersion || '?',
+          desktopApp: !!s.desktopApp,
+          tabs: Array.isArray(s.windows) ? s.windows.length : s.browsers ?? 0,
+        }
+      } catch {
+        return { ...c, up: false }
+      }
+    }),
+  )
+
+  const up = rows.filter((r) => r.up).sort((a, b) => Number(a.port) - Number(b.port))
+  if (!up.length) {
+    console.log('No haltija servers are running.')
+    console.log(dim('Start one:  bunx haltija --server   (or the desktop app:  bunx haltija)'))
+    return
+  }
+
+  console.log(bold('Live haltija servers') + dim('  (▸ = what this shell targets)'))
+  for (const r of up) {
+    const here = String(r.port) === String(resolvedPort) ? green('▸') : ' '
+    const name = r.desktopApp ? 'desktop' : r.name || '(unnamed)'
+    const tabs = `${r.tabs} tab${r.tabs === 1 ? '' : 's'}`
+    const kind = r.desktopApp ? 'desktop app' : r.cwd || ''
+    console.log(
+      `  ${here} ${String(r.port).padEnd(6)} ${name.padEnd(14)} v${String(r.version).padEnd(8)} ${tabs.padEnd(9)} ${dim(kind)}`,
+    )
+  }
+  if (!up.some((r) => String(r.port) === String(resolvedPort))) {
+    console.log(dim(`\nThis shell targets :${resolvedPort}, but nothing is listening there.`))
+  }
+  console.log(dim('\nPick one:  ') + `hj --port <n> <cmd>` + dim('  or  ') + `hj --name <name> <cmd>`)
+}
+
+/**
+ * `hj doctor` — one-command preflight for a test lane: "is the thing I'm about to drive the thing
+ * I mean, and can it actually be driven?" (issues #8, #11). Exits NON-ZERO when it isn't, which is
+ * the whole point: "is a server up?" is a cheap probe that does NOT predict success, so adopters
+ * who used it skipped spawning their own browser and failed much later on a timeout.
+ *
+ * Checks, in the order they bite: server reachable → drivable (a tab is connected) → targeting is
+ * unambiguous (cwd matches, or the choice was explicit) → tabs visible → versions aligned.
+ */
+async function runDoctor(port, portSource, jsonOutput) {
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`
+  const green = (s) => `\x1b[32m${s}\x1b[0m`
+  const red = (s) => `\x1b[31m${s}\x1b[0m`
+  const yellow = (s) => `\x1b[33m${s}\x1b[0m`
+  const token = process.env.HALTIJA_TOKEN
+
+  const problems = [] // fatal → exit 1
+  const notes = [] // advisory
+  let status = null
+
+  try {
+    const resp = await fetch(`http://localhost:${port}/status`, {
+      headers: token ? { 'X-Haltija-Token': token } : {},
+      signal: AbortSignal.timeout(3000),
+    })
+    if (resp.ok) status = await resp.json()
+    else problems.push(`server on port ${port} returned HTTP ${resp.status}`)
+  } catch (err) {
+    const refused = err.code === 'ConnectionRefused' || err.cause?.code === 'ECONNREFUSED'
+    problems.push(
+      refused
+        ? `no haltija server is listening on port ${port} — start one (bunx haltija) or check the target`
+        : `could not reach the server on port ${port}: ${err.message}`,
+    )
+  }
+
+  if (status) {
+    // The signal that actually predicts success. Older servers (<1.6.1) don't send `ready`; fall
+    // back to counting tabs rather than inventing a pass.
+    const tabs = Array.isArray(status.windows) ? status.windows : []
+    const ready = typeof status.ready === 'boolean' ? status.ready : tabs.length > 0
+    if (!ready) {
+      problems.push(
+        `the server on port ${port} is up but has NO connected browser tab — nothing to drive. ` +
+          `Open a tab in the desktop app, or inject the widget into a page. ` +
+          `("server is up" is not "server is drivable" — that's what this check exists for.)`,
+      )
+    }
+    const hidden = tabs.filter((w) => w.hidden)
+    if (ready && hidden.length === tabs.length) {
+      problems.push(
+        `every connected tab reports HIDDEN — results from a backgrounded tab can be ` +
+          `plausible-but-wrong (rAF/timers throttled). Bring one to the front.`,
+      )
+    } else if (hidden.length) {
+      notes.push(`${hidden.length} of ${tabs.length} tab(s) are hidden; commands targeting them may return stale results`)
+    }
+    if (status.serverVersion && differsBeyondPatch(HJ_VERSION, status.serverVersion)) {
+      notes.push(`hj ${HJ_VERSION} is driving server ${status.serverVersion} (version skew)`)
+    }
+  }
+
+  // Ambiguous targeting: we fell back to the shared default while other projects' servers are live.
+  const live = listLiveInstances()
+  const ambiguous = portSource === '8700 (default)' && live.length > 0
+  if (ambiguous) {
+    problems.push(
+      `targeting the shared default port 8700, but ${live.length} other haltija server(s) are ` +
+        `running and none matches this directory (${process.cwd()}) — the target is ambiguous. ` +
+        `Pick one with --name/--port, or run from the project's directory.`,
+    )
+  }
+
+  const ok = problems.length === 0
+
+  if (jsonOutput) {
+    console.log(JSON.stringify({
+      ok, port, portSource,
+      serverVersion: status?.serverVersion ?? null,
+      ready: status ? (typeof status.ready === 'boolean' ? status.ready : (status.windows?.length ?? 0) > 0) : false,
+      tabs: status?.windows?.length ?? 0,
+      problems, notes,
+    }, null, 2))
+    return ok
+  }
+
+  console.log(`${bold('target:')} port ${port} ${dim(`(${portSource})`)}`)
+  if (status) {
+    const tabCount = status.windows?.length ?? 0
+    console.log(`${bold('server:')} haltija ${status.serverVersion || '?'}${status.desktopApp ? dim(' (desktop app)') : ''}, ${tabCount} tab${tabCount === 1 ? '' : 's'}`)
+  }
+  for (const n of notes) console.log(`${yellow('!')} ${n}`)
+  for (const p of problems) console.log(`${red('✗')} ${p}`)
+  if (ok) console.log(`${green('✓')} ready to drive`)
+  return ok
+}
+
 /**
  * Resolve a named haltija instance to its port by reading
  * ~/.haltija/servers/<name>.json. Returns null if the file is missing,
@@ -211,6 +374,17 @@ ${dim('Overriding that (per-shell):')}
   ${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?
+
+${dim('Lifecycle:')}
+  ${dim('hj where')}                       # which server this shell targets + what is alive there
+  ${dim('hj servers')}                     # list ALL live servers (pick one with --port/--name)
+  ${dim('hj doctor')}                      # preflight: drivable + unambiguous? EXITS 1 if not
+  ${dim('hj shutdown')}                    # stop the targeted server (a private --app: Electron + all)
+
+${dim('For scripts / CI:')}
+  ${dim('hj --strict <cmd>')}              # turn advisory warnings (wrong project, hidden tab)
+  ${dim('HALTIJA_STRICT=1')}               # into non-zero exits, so a lane fails fast on the
+                                  ${dim('# real cause instead of a later timeout')}
 ${listSubcommands()}
 Run ${dim('hj --help')} for this help.
 Run ${dim('haltija --help')} for server/app options.
@@ -218,6 +392,23 @@ Run ${dim('haltija --help')} for server/app options.
   process.exit(0)
 }
 
+// Parse --strict FIRST — before port resolution, which is itself one of the things strict mode
+// turns from a warning into an error. (A check placed before the input it depends on is a
+// recurring bug shape: parse the flag, then run the code that reads it.) Sets HALTIJA_STRICT so
+// cli-subcommand.mjs sees it too.
+//
+// In strict mode the advisory warnings — cross-project targeting, hidden tab, focus ambiguity —
+// become non-zero exits (issue #8). haltija already DETECTS these precisely; the gap was that
+// detection never reached the exit code, so a lane consumed a plausible-but-wrong result and failed
+// much later pointing at the caller's own code. A warning is right for a human at a prompt and
+// wrong for a script.
+const strictIdx = args.indexOf('--strict')
+if (strictIdx !== -1) {
+  process.env.HALTIJA_STRICT = '1'
+  args.splice(strictIdx, 1)
+}
+const STRICT = process.env.HALTIJA_STRICT === '1'
+
 // Parse --name option (or HALTIJA_NAME env): resolve to a port via
 // ~/.haltija/servers/<name>.json, written by `haltija --name <foo>`.
 let resolvedName = process.env.HALTIJA_NAME || ''
@@ -288,6 +479,13 @@ if (portFlag) {
     // explicit choice.
     if (live.length) {
       const names = live.map((e) => `${e.name} (${e.cwd})`).join(', ')
+      if (STRICT) {
+        // A lane must not silently drive another project's browser (issue #8, case 1).
+        console.error(`hj: ERROR (strict) — refusing to fall back to the default port 8700 while other haltija servers are running: ${names}`)
+        console.error(`hj: this shell's cwd (${process.cwd()}) matches none of them, so the target is ambiguous.`)
+        console.error(`hj: pick one explicitly with --name/--port (or cd into its directory), or drop --strict to proceed anyway.`)
+        process.exit(1)
+      }
       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\`.`)
     }
@@ -367,6 +565,50 @@ if (subcommand === 'where') {
   process.exit(0)
 }
 
+// `hj servers` / `hj ls` — list every live haltija server (registry + defaults + this shell's
+// target), so you can pick one when several coexist. Diagnostic; never auto-launches.
+if (subcommand === 'servers' || subcommand === 'ls') {
+  await runServers(port)
+  process.exit(0)
+}
+
+// `hj doctor` — preflight for a test lane. EXITS NON-ZERO when the target isn't drivable or is
+// ambiguous, so a lane can fail fast with the real reason (issues #8, #11). Never auto-launches.
+if (subcommand === 'doctor') {
+  const ok = await runDoctor(port, portSource, subArgs.includes('--json'))
+  process.exit(ok ? 0 : 1)
+}
+
+// `hj shutdown` / `hj quit` — cleanly stop the targeted server. For a private `--app` instance this
+// tears down the WHOLE thing (Electron + its child servers); for a plain server it stops that
+// server. Never auto-launches (it's a stop command), so it's handled here before the routing table.
+if (subcommand === 'shutdown' || subcommand === 'quit') {
+  const token = process.env.HALTIJA_TOKEN
+  try {
+    const resp = await fetch(`http://localhost:${port}/shutdown`, {
+      method: 'POST',
+      headers: token ? { 'X-Haltija-Token': token } : {},
+      signal: AbortSignal.timeout(3000),
+    })
+    const j = await resp.json().catch(() => ({}))
+    if (resp.ok) {
+      console.log(j.message || `Shutdown requested on port ${port}.`)
+      process.exit(0)
+    }
+    // Surface the server's explanation (e.g. the desktop-app refusal), not a bare status code.
+    console.error(`hj ${subcommand}: ${j.error || `server on port ${port} returned HTTP ${resp.status}`}`)
+    process.exit(1)
+  } catch (err) {
+    // Nothing listening = already stopped; that's success for a stop command.
+    if (err.code === 'ConnectionRefused' || err.cause?.code === 'ECONNREFUSED') {
+      console.log(`No server listening on port ${port} (already stopped).`)
+      process.exit(0)
+    }
+    console.error(`hj ${subcommand}: ${err.message}`)
+    process.exit(1)
+  }
+}
+
 if (!isSubcommand(subcommand)) {
   const suggestion = getSuggestion(subcommand)
   if (suggestion === '--help') {

package/bin/tosijs-dev.mjs

@@ -580,7 +580,12 @@ function launchApp(desktopDir, port) {
   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) }
+  // For a private run we also hand the app OUR pid (HALTIJA_SPAWNER_PID): the Electron process
+  // reparents to launchd shortly after startup, so it can't watch us via process.ppid — it polls
+  // this pid instead and quits when we're gone (issue #7, "torn down with the run").
+  const appEnv = privateMode
+    ? { ...env, HALTIJA_SPAWNER_PID: String(process.pid) }
+    : { ...env, DEV_CHANNEL_PORT: String(port) }
   const child = electronBinary
     ? spawn(electronBinary, [desktopDir], { env: appEnv, stdio: 'inherit' })
     : spawn('npx', ['--yes', 'electron', desktopDir], { env: appEnv, stdio: 'inherit' })
@@ -595,6 +600,12 @@ function launchApp(desktopDir, port) {
   child.on('exit', code => {
     process.exit(code || 0)
   })
+
+  // Belt-and-suspenders to the app's own spawner-pid poll: if WE get a signal, ask the app to quit
+  // before we exit. (If we're SIGKILLed we can't do this — that's exactly what the poll covers.)
+  const signalChild = () => { try { child.kill('SIGTERM') } catch {} ; process.exit(0) }
+  process.on('SIGTERM', signalChild)
+  process.on('SIGINT', signalChild)
   
   // In CI/wait-ready mode, wait for server + browser to be ready
   if (waitReady) {

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.5.4'
+export const HJ_VERSION = '1.6.1'

package/dist/api-handlers.d.ts

@@ -18,6 +18,8 @@ export interface DevResponse {
     timestamp: number;
     /** Hidden-tab / focus-ambiguity caveat attached by the server (see requestFromBrowser). */
     warning?: string;
+    /** True when this exact warning was already reported within the cooldown (see types.ts). */
+    warningRepeated?: boolean;
 }
 /** Function to send request to browser widget */
 export type RequestFromBrowserFn = (channel: string, action: string, payload: any, timeoutMs?: number, windowId?: string) => Promise<DevResponse>;