haltija 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## 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)).
+
+Outside the desktop app, `hj tabs open <url>` has no tab API, so it falls back to `window.open()` —
+and that new tab has **no haltija widget** unless its page injects one. So the server never hears
+from it, it doesn't appear in `hj tabs`, and commands can't reach it (they go to the focused widget
+tab). It presents as "the tab opened fine but every command goes somewhere else" — indistinguishable
+from a routing bug.
+
+- The fallback response now carries a `reason`, promoted to a top-level `warning` that `hj` prints
+  on stderr — at the one moment the client-less tab is created.
+- The `/tabs/open` schema and `SKILL.md` now state plainly that only widget-injected tabs are
+  controllable and appear in `hj tabs`, so a non-responding tab is the first thing to check.
+
+## 1.5.3
+
+Discoverability fix for the two CI browser engines ([#6](https://github.com/tonioloewald/haltija/issues/6)).
+
+Both `--headless` and `--ci` said "for CI" with no hint that they drive **different** engines:
+`--headless` is Playwright Chromium (and needs the `playwright` package), while `--ci` / `--app` /
+`--private --app` drive Electron and need no Playwright. An agent picked `--headless`, hit
+"Playwright not installed", and wrongly concluded haltija's CI mode is just a Playwright wrapper.
+
+- `hj --help` now names the engine per mode and adds a "Choosing a CI engine" block; `--private` is
+  clarified as an *isolation* modifier that pairs with either engine (not "pair with `--headless`").
+- The "Playwright not installed" error points at the Electron path (`--ci` / `--private --app`) as
+  the no-Playwright alternative.
+- `llms.txt`, `docs/CI-INTEGRATION.md`, and `SKILL.md` get an honest "which engine?" framing:
+  it's Electron vs Playwright (neither is bundled), and the real reason to choose Playwright is
+  multi-engine coverage (Firefox/WebKit), not the words "for CI".
+
 ## 1.5.2
 
 Two follow-ups from the 1.5.0 review, both about the multi-tab experience on a shared server.

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.2",
+  "version": "1.6.0",
   "private": true,
   "description": "Haltija Desktop - God Mode Browser for AI Agents",
   "homepage": "https://github.com/tonioloewald/haltija",

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.5.2";
+  var VERSION = "1.6.0";
 
   // 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();
@@ -5637,7 +5639,11 @@ ${elementSummary}${moreText}`;
           });
         } else {
           window.open(payload2.url, "_blank");
-          this.respond(msg2.id, true, { opened: true, fallback: true });
+          this.respond(msg2.id, true, {
+            opened: true,
+            fallback: true,
+            reason: "Opened a plain browser tab via window.open() (this is not the Haltija desktop app). " + "That tab has NO Haltija widget unless its page injects one, so it will NOT appear in " + "`hj tabs` and hj commands cannot reach it — untargeted commands go to the focused " + "widget tab instead. To control the new tab: inject the widget on that page (e.g. " + "HALTIJA_DEV=1 / haltijaDev:true in that project), or use the Haltija desktop app, " + "which auto-injects into every tab."
+          });
         }
       } else if (action2 === "close") {
         if (haltija?.closeTab) {
@@ -7422,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",
@@ -7437,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

@@ -1073,7 +1073,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,71 @@ 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>`)
+}
+
 /**
  * Resolve a named haltija instance to its port by reading
  * ~/.haltija/servers/<name>.json. Returns null if the file is missing,
@@ -211,6 +276,11 @@ ${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 shutdown')}                    # stop the targeted server (a private --app: Electron + all)
 ${listSubcommands()}
 Run ${dim('hj --help')} for this help.
 Run ${dim('haltija --help')} for server/app options.
@@ -367,6 +437,43 @@ 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 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

@@ -37,12 +37,12 @@ ${bold('haltija')} - Browser control for AI agents
 Usage:
   haltija [options]
 
-Modes:
+Modes: ${dim('(the browser ENGINE differs — see "Choosing a CI engine" below)')}
   ${dim('(default)')}       Launch desktop app if electron available, otherwise server
-  --app           Explicitly launch desktop app (Electron)
-  --server        Server only (for CI, headless, or bookmarklet usage)
-  --headless      Start with headless Chromium browser (for CI)
-  --ci            CI mode: Electron app + wait for ready + sandbox disabled
+  --app           Explicitly launch desktop app (Electron — Chromium)
+  --server        Server only; bring your own browser (inject the widget). For bookmarklets/CI-lite
+  --headless      Headless Chromium via ${bold('Playwright')} (needs the 'playwright' package) — for CI
+  --ci            CI mode: ${bold('Electron')} app + wait-ready + sandbox off. No Playwright. Recommended for CI
 
 Options:
   --http          HTTP only on port 8700 (default protocol)
@@ -62,7 +62,9 @@ Options:
   --private       Isolated automation instance: own server on an EPHEMERAL port (never
                   8700), own browser, torn down with the run. Never sees/adopts/navigates
                   the shared interactive browser. Reports its address on stdout
-                  (HALTIJA_PRIVATE_READY {json}) and to --port-file. Pair with --headless.
+                  (HALTIJA_PRIVATE_READY {json}) and to --port-file. This is an ISOLATION
+                  modifier, not an engine: pair with --app (Electron, no Playwright) or
+                  --headless (Playwright Chromium).
   --port-file <p> Write the (private) server's bound address as JSON to <p> when ready.
   --setup-mcp     Configure Claude Desktop MCP integration
   --setup-mcp-check  Check MCP configuration status
@@ -106,13 +108,23 @@ Subcommands:
 
   Use 'hj' as a short alias: hj tree, hj click @42, etc.
 
+Choosing a CI engine ${dim('(both need one external browser, but a DIFFERENT one):')}
+  ${bold('Electron')} (Chromium, same engine the desktop app uses) — no Playwright:
+    haltija --ci                   # recommended: Electron + wait-ready + sandbox off
+    haltija --private --app        # + isolation (own ephemeral port, adopts nothing)
+    ${dim('Electron is fetched via npx if not already installed.')}
+  ${bold('Playwright')} Chromium — needs the 'playwright' package:
+    npm i playwright && npx playwright install chromium
+    haltija --headless             # single-engine; or --private --headless for isolation
+    ${dim("Pick this for MULTI-ENGINE coverage (Firefox/WebKit) — not just because it says \"CI\".")}
+
 Examples:
   haltija                          # Desktop app (or server fallback)
   haltija --app                    # Desktop app explicitly
-  haltija --server                 # Server only
+  haltija --server                 # Server only (bring your own browser)
   haltija --server --https         # HTTPS server only
-  haltija --headless               # Headless browser for CI
-  haltija --ci                     # CI mode (headless + wait + sandbox disabled)
+  haltija --ci                     # CI: Electron (no Playwright) + wait + sandbox off
+  haltija --headless               # CI: Playwright Chromium (needs playwright)
   haltija --setup-mcp              # Configure Claude Desktop integration
 `)
   process.exit(0)
@@ -568,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' })
@@ -583,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) {
@@ -729,8 +752,12 @@ const startHeadlessBrowser = async (port) => {
     
   } catch (err) {
     if (err.code === 'ERR_MODULE_NOT_FOUND') {
-      console.error('[tosijs-dev] Playwright not installed. Run: npm install playwright')
-      console.error('[tosijs-dev] Then: npx playwright install chromium')
+      console.error('[tosijs-dev] --headless uses Playwright Chromium, which is not installed.')
+      console.error('[tosijs-dev]   To use Playwright: npm install playwright && npx playwright install chromium')
+      console.error('[tosijs-dev]   Or skip Playwright entirely and use the ELECTRON engine instead:')
+      console.error('[tosijs-dev]     haltija --ci                 (Electron, waits for ready, sandbox off)')
+      console.error('[tosijs-dev]     haltija --private --app      (Electron + isolated ephemeral instance)')
+      console.error('[tosijs-dev]   Reach for --headless (Playwright) when you need Firefox/WebKit coverage.')
     } else {
       console.error('[tosijs-dev] Failed to start headless browser:', err.message)
     }

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.2'
+export const HJ_VERSION = '1.6.0'

package/dist/component.d.ts

@@ -20,13 +20,14 @@
  * - Option+Tab toggles visibility (but active state always shows briefly)
  * - Localhost only by default
  */
-export declare const VERSION = "1.5.2";
+export declare const VERSION = "1.6.0";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;
     private ws;
     private state;
     private consoleBuffer;
+    private errorCaptureInstalled;
     private eventWatchers;
     private mutationObserver;
     private shadowObservers;
@@ -396,7 +397,27 @@ export declare class DevChannel extends HTMLElement {
     private replaySession;
     private interceptDialogs;
     private restoreDialogs;
+    /**
+     * Serialize a console argument for capture. `JSON.stringify(new Error(...))` returns `"{}"` —
+     * message and stack are non-enumerable — so a plain round-trip silently drops the single most
+     * useful thing an agent wants. Convert Errors (at any depth, via the replacer) to a structured
+     * `{name, message, stack}` instead.
+     */
+    private serializeConsoleArg;
+    /** Record one console/error entry: buffer it, cap the buffer, and (for errors) push to the
+     * server and flag the UI. Shared by console interception AND the uncaught-error listeners. */
+    private recordConsoleEntry;
     private interceptConsole;
+    /**
+     * Capture what `console.error` interception alone misses: uncaught exceptions and unhandled
+     * promise rejections — i.e. the errors that are actual bugs, which never route through
+     * `console.error`. Without these, `hj console` shows a page as clean while it's throwing.
+     */
+    private onWindowError;
+    private onUnhandledRejection;
+    private installErrorCapture;
+    /** Remove the uncaught-error/rejection listeners so they don't accumulate across re-injection. */
+    private uninstallErrorCapture;
     private restoreConsole;
 }
 /**