haltija 1.4.1 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 1.5.1
+
+Low-risk follow-ups from the 1.5.0 pre-release review — the two new "instrument must not lie"
+warnings now reach more of the surfaces where they matter.
+
+### Fixed
+
+- **The hidden-tab / focus-ambiguity warning is no longer dropped on the paths where it's most
+  useful.** It's now attached on the **timeout** path — a hidden tab whose rAF-driven `eval` never
+  resolves now returns a `Timeout` that *explains* it may be asleep, instead of a bare timeout —
+  and preserved by the `hj find` / `hj form` handlers, which previously reshaped the response and
+  lost it. (`hj screenshot` already carried it; `hj call` intentionally still returns the raw value
+  with no envelope.)
+
+### Internal
+
+- Extracted the `hj --window <id>` argument handling into a pure, unit-tested helper
+  (`bin/arg-utils.mjs`), covering both the leading and trailing positions — the leading form was
+  the escape hatch that broke in 1.4.0, and it now has a regression test.
+- A private-app startup that fails to learn its ephemeral port no longer leaves its temp port-files
+  behind.
+
+## 1.5.0
+
+Completes the **private-automation** feature (`--private`) begun in 1.4.1 — now for the Electron
+app as well as headless — and adds two **"the instrument must not lie"** guards so a command that
+lands on the wrong or sleeping tab says so instead of returning a plausible-but-wrong answer.
+
+### New: `--private --app` — isolated Electron automation ([#1](https://github.com/tonioloewald/haltija/issues/1))
+
+`--private` gave headless runs an isolated server + browser on an ephemeral port. `--private --app`
+extends that to the desktop app: it spawns its **own** public and internal servers on ephemeral
+ports (never 8700/8701), drives its **own** browser, writes the public address to `--port-file`,
+and never sees, adopts, registers, or touches the shared interactive channel. The app's port
+constants are now resolved *after* the private servers report their ephemeral ports, so every
+downstream use — widget injection, `/status`, content tabs — follows the ephemeral instance.
+
+### New: hidden-tab warning ([#3](https://github.com/tonioloewald/haltija/issues/3))
+
+A backgrounded tab **answers** — `hj eval 'document.querySelectorAll("x").length'` returns `0`, not
+a timeout — because browsers stop `requestAnimationFrame` and throttle timers in a hidden tab, so
+anything mounted by rAF/IntersectionObserver never ran. The page looks broken when it's merely
+asleep. When a command is routed to a tab that reported itself hidden, the result now carries a
+warning that the number can be plausible-but-wrong, with how to target a visible tab.
+
+### New: focus-ambiguity warning ([#2](https://github.com/tonioloewald/haltija/issues/2))
+
+cwd routing gets an untargeted `hj` command to the right shared *server* and then stops — which
+*tab* answers falls back to focus. So two agents each staying in their own project can drive each
+other's pages once both have a tab on the shared server. When a command isn't pinned to a window
+and the server spans more than one origin, the result now warns that *focus*, not your directory,
+chose the tab — and lists the other tabs as `--window` pins. It deliberately does **not** guess
+which tab is "yours" (there's no reliable origin→directory map); ranking waits for one that can
+justify itself.
+
+### Fixed
+
+- **`hj --window <id> <cmd>`** — the documented leading form printed the usage banner instead of
+  targeting the window (`--window` wasn't pre-parsed like `--port`/`--name`). Both positions work now.
+- **Desktop-spawned servers get their port** via the env the server actually reads
+  (`HALTIJA_PORT`/`DEV_CHANNEL_PORT`, not `PORT`) — the app couldn't control its servers' ports before.
+
 ## 1.4.1
 
 Five cross-project bugs, all of the same shape: **haltija reaching out and disrupting a healthy

package/apps/desktop/main.js

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

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.4.1",
+  "version": "1.5.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.4.1";
+  var VERSION = "1.5.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/bin/arg-utils.mjs

@@ -0,0 +1,21 @@
+/**
+ * Pure arg helpers for the `hj` CLI, extracted so they can be unit-tested (see
+ * src/hj-args.test.ts) — the leading-`--window` form was fully broken and shipped without a test.
+ */
+
+/**
+ * Pull a `--window <id>` flag out of `args` from ANY position, returning the id and the remaining
+ * args (input is not mutated). Mirrors how `--port`/`--name`/`--token` are pre-parsed, so both
+ * `hj --window <id> <cmd>` (leading) and `hj <cmd> --window <id>` (trailing) resolve the same tab.
+ * A `--window` with no following value is left in place (treated as not-a-target) so it surfaces as
+ * a normal unknown-flag rather than silently swallowing the next real arg.
+ */
+export function extractWindowTarget(args) {
+  const i = args.indexOf('--window')
+  if (i === -1 || args[i + 1] === undefined) {
+    return { windowTarget: null, args: [...args] }
+  }
+  const rest = [...args]
+  rest.splice(i, 2)
+  return { windowTarget: args[i + 1], args: rest }
+}

package/bin/cli-subcommand.mjs

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

package/bin/hj.mjs

@@ -11,6 +11,7 @@
  */
 
 import { runSubcommand, isSubcommand, getSuggestion, listSubcommands, COMMAND_HINTS } from './cli-subcommand.mjs'
+import { extractWindowTarget } from './arg-utils.mjs'
 import { HJ_VERSION } from './version.mjs'
 import { differsBeyondPatch } from './semver.mjs'
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
@@ -308,6 +309,17 @@ if (noLaunchIdx !== -1) {
   args.splice(noLaunchIdx, 1)
 }
 
+// Parse --window <id> HERE so it works BEFORE the subcommand, like --port/--name/--token do.
+// It was only handled after the subcommand, so the documented form `hj --window <id> eval …`
+// died with "Unknown command: '--window'" — i.e. the escape hatch we tell people to use for a
+// hidden/wrong tab didn't work in the shape the docs gave. Pulled out here and re-appended to
+// the subcommand args below, so BOTH positions work.
+const { windowTarget, args: argsWithoutWindow } = extractWindowTarget(args)
+// Preserve the `const args` reference (downstream code mutates it in place) while dropping the
+// consumed --window <id> pair.
+args.length = 0
+args.push(...argsWithoutWindow)
+
 // Did the shell explicitly target a private instance (--port / --name /
 // HALTIJA_PORT / HALTIJA_NAME / DEV_CHANNEL_PORT)? If so, this is a
 // project-owned server with a bring-your-own browser — auto-launching the
@@ -343,7 +355,9 @@ if (args.length === 1 && !isSubcommand(args[0]) && NOUN_DEFAULTS[args[0]]) {
 }
 
 const subcommand = args[0]
-const subArgs = args.slice(1).filter(a => a !== '--window' || true) // keep all args
+let subArgs = args.slice(1)
+// Re-attach a leading --window so cli-subcommand's existing handling sees it (both positions work).
+if (windowTarget) subArgs = [...subArgs, '--window', windowTarget]
 
 // `hj where` — show which haltija server this shell is targeting and what
 // (if anything) is alive there. Pure client-side resolution plus a single

package/bin/tosijs-dev.mjs

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

package/bin/version.mjs

@@ -3,4 +3,4 @@
  * ⚠️  To change the version, update package.json and run: bun run build
  */
 
-export const HJ_VERSION = '1.4.1'
+export const HJ_VERSION = '1.5.1'

package/dist/api-handlers.d.ts

@@ -16,6 +16,8 @@ export interface DevResponse {
     data?: any;
     error?: string;
     timestamp: number;
+    /** Hidden-tab / focus-ambiguity caveat attached by the server (see requestFromBrowser). */
+    warning?: string;
 }
 /** Function to send request to browser widget */
 export type RequestFromBrowserFn = (channel: string, action: string, payload: any, timeoutMs?: number, windowId?: string) => Promise<DevResponse>;

package/dist/component.d.ts

@@ -20,7 +20,7 @@
  * - Option+Tab toggles visibility (but active state always shows briefly)
  * - Localhost only by default
  */
-export declare const VERSION = "1.4.1";
+export declare const VERSION = "1.5.1";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;

package/dist/component.esm.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "1.4.1";
+var VERSION = "1.5.1";
 
 // src/text-selector.ts
 var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/component.js

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

package/dist/focus-ambiguity.d.ts

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

package/dist/hj.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// haltija-cli:do-not-edit v1.4.1
+// haltija-cli:do-not-edit v1.5.1
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -756,7 +756,7 @@ function substituteGeneratedVars(text, seed) {
 }
 
 // bin/version.mjs
-var HJ_VERSION = "1.4.1";
+var HJ_VERSION = "1.5.1";
 
 // bin/semver.mjs
 function parseVersion(v) {
@@ -1628,6 +1628,9 @@ async function doRequest(url, method, body, context = {}) {
     const contentType = resp.headers.get("content-type") || "";
     if (contentType.includes("application/json")) {
       const json = await resp.json();
+      if (json && typeof json.warning === "string" && json.warning) {
+        console.error(`hj: warning — ${json.warning}`);
+      }
       if (!jsonOutput && subcommand === "tree" && json.success && json.data) {
         console.log(formatTree(json.data, 0, { depth: body?.depth }));
       } else if (!jsonOutput && subcommand === "events" && (json.events || Array.isArray(json))) {
@@ -1903,6 +1906,17 @@ function dim2(s) {
   return `\x1B[2m${s}\x1B[0m`;
 }
 
+// bin/arg-utils.mjs
+function extractWindowTarget(args) {
+  const i = args.indexOf("--window");
+  if (i === -1 || args[i + 1] === undefined) {
+    return { windowTarget: null, args: [...args] };
+  }
+  const rest = [...args];
+  rest.splice(i, 2);
+  return { windowTarget: args[i + 1], args: rest };
+}
+
 // bin/hj.mjs
 import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
@@ -2134,6 +2148,9 @@ if (noLaunchIdx !== -1) {
   noLaunch = true;
   args.splice(noLaunchIdx, 1);
 }
+var { windowTarget, args: argsWithoutWindow } = extractWindowTarget(args);
+args.length = 0;
+args.push(...argsWithoutWindow);
 var explicitTarget = portSource !== "8700 (default)";
 if (args.length >= 2 && isSubcommand(`${args[0]}-${args[1]}`)) {
   args.splice(0, 2, `${args[0]}-${args[1]}`);
@@ -2152,7 +2169,9 @@ if (args.length === 1 && !isSubcommand(args[0]) && NOUN_DEFAULTS[args[0]]) {
   args[0] = NOUN_DEFAULTS[args[0]];
 }
 var subcommand = args[0];
-var subArgs = args.slice(1).filter((a) => a !== "--window" || true);
+var subArgs = args.slice(1);
+if (windowTarget)
+  subArgs = [...subArgs, "--window", windowTarget];
 if (subcommand === "where") {
   await runWhere(port, portSource, subArgs.includes("--json"));
   process.exit(0);

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.4.1";
+var VERSION = "1.5.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -3097,7 +3097,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.4.1";
+  var VERSION = "1.5.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -13727,6 +13727,9 @@ function inferSuggestion(step, pageContext) {
 }
 
 // src/api-handlers.ts
+function withWarning(body, response) {
+  return response.warning ? { ...body, warning: response.warning } : body;
+}
 var handlers = new Map;
 function registerHandler(endpoint2, handler) {
   handlers.set(endpoint2.path, handler);
@@ -14557,7 +14560,7 @@ registerHandler(find, async (body, ctx) => {
   })()`;
   const response = await ctx.requestFromBrowser("eval", "exec", { code: findCode }, 5000, windowId);
   if (response.success && response.data) {
-    return Response.json({ success: true, ...response.data }, { headers: ctx.headers });
+    return Response.json(withWarning({ success: true, ...response.data }, response), { headers: ctx.headers });
   }
   return Response.json(response, { headers: ctx.headers });
 });
@@ -14663,7 +14666,7 @@ registerHandler(formData, async (body, ctx) => {
   })()`;
   const response = await ctx.requestFromBrowser("eval", "exec", { code: formCode }, 5000, windowId);
   if (response.success && response.data) {
-    return Response.json(response.data, { headers: ctx.headers });
+    return Response.json(withWarning(response.data, response), { headers: ctx.headers });
   }
   return Response.json(response, { headers: ctx.headers });
 });
@@ -15226,6 +15229,52 @@ function isHaltijaProcess(pid) {
   }
 }
 
+// src/tab-liveness.ts
+function hiddenTabWarning(win) {
+  if (!win)
+    return null;
+  if (win.active !== false)
+    return null;
+  const which = win.title ? `"${win.title}"` : win.id;
+  return `The tab that answered (${which}) reports it is HIDDEN \u2014 backgrounded, minimized, ` + `behind another window, or the display is asleep. Browsers stop requestAnimationFrame and ` + `throttle timers in a hidden tab, so anything mounted by rAF/IntersectionObserver may never ` + `have run: THIS RESULT CAN BE PLAUSIBLE BUT WRONG (an empty selector here means "not mounted ` + `yet", not "broken"). Bring the tab to the front, or target a visible one with --window <id>.`;
+}
+
+// src/focus-ambiguity.ts
+function isTopLevelTab(w) {
+  return w.windowType !== "iframe" && w.windowType !== "popup";
+}
+function originOf(url) {
+  if (!url)
+    return null;
+  try {
+    const origin = new URL(url).origin;
+    return origin === "null" ? url : origin;
+  } catch {
+    return url;
+  }
+}
+function ambiguousFocusWarning(opts) {
+  const { windows: windows2, sentToId, wasTargeted } = opts;
+  if (wasTargeted)
+    return null;
+  if (!sentToId)
+    return null;
+  const withOrigin = windows2.filter(isTopLevelTab).map((w) => ({ ...w, origin: originOf(w.url) })).filter((w) => w.origin !== null);
+  const distinctOrigins = new Set(withOrigin.map((w) => w.origin));
+  if (distinctOrigins.size < 2)
+    return null;
+  const chosen = withOrigin.find((w) => w.id === sentToId);
+  const chosenWhere = chosen ? `${chosen.origin}${chosen.title ? ` \u2014 "${chosen.title}"` : ""}` : sentToId;
+  const others = withOrigin.filter((w) => !chosen || w.origin !== chosen.origin);
+  const MAX = 4;
+  const pins = others.slice(0, MAX).map((w) => `  --window ${w.id}  \u2192 ${w.origin}${w.title ? ` ("${w.title}")` : ""}`).join(`
+`);
+  const more = others.length > MAX ? `
+  \u2026and ${others.length - MAX} more` : "";
+  return `This command was NOT pinned to a window and this server has tabs from ` + `${distinctOrigins.size} different origins, so *focus* \u2014 not your working directory \u2014 chose ` + `which tab answered (${chosenWhere}). A tab you didn't mean (another project's page on this ` + `shared server, or one a human just clicked into) can silently receive the command. If you ` + `meant a different page, pin it:
+${pins}${more}`;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16392,14 +16441,29 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
     source: "agent"
   };
   return new Promise((resolve) => {
+    let sentTo = null;
+    const attachWarning = (res) => {
+      const hidden = hiddenTabWarning(sentTo);
+      const ambiguous = ambiguousFocusWarning({
+        windows: Array.from(windows2.values()),
+        sentToId: sentTo?.id,
+        wasTargeted: !!windowId
+      });
+      const warning = [hidden, ambiguous].filter(Boolean).join(`
+
+`);
+      return warning ? { ...res, warning } : res;
+    };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
-      resolve({ id, success: false, error: "Timeout", timestamp: Date.now() });
+      resolve(attachWarning({ id, success: false, error: "Timeout", timestamp: Date.now() }));
     }, timeoutMs);
-    pendingResponses.set(id, { resolve, timeout });
+    const resolveWithLiveness = (res) => resolve(attachWarning(res));
+    pendingResponses.set(id, { resolve: resolveWithLiveness, timeout });
     if (windowId) {
       const win = windows2.get(windowId);
       if (win) {
+        sentTo = win;
         win.ws.send(JSON.stringify(msg));
       } else {
         clearTimeout(timeout);
@@ -16408,13 +16472,16 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       }
     } else if (focusedWindowId && windows2.has(focusedWindowId)) {
       const focusedWin = windows2.get(focusedWindowId);
+      sentTo = focusedWin;
       focusedWin.ws.send(JSON.stringify(msg));
     } else {
       const activeWindows = Array.from(windows2.values()).filter((w) => w.active).sort((a, b) => b.lastSeen - a.lastSeen);
       if (activeWindows.length > 0) {
+        sentTo = activeWindows[0];
         activeWindows[0].ws.send(JSON.stringify(msg));
       } else if (windows2.size > 0) {
         const mostRecent = Array.from(windows2.values()).sort((a, b) => b.lastSeen - a.lastSeen)[0];
+        sentTo = mostRecent;
         mostRecent.ws.send(JSON.stringify(msg));
       } else {
         clearTimeout(timeout);
@@ -16798,6 +16865,7 @@ async function handleRest(req) {
       title: w.title?.slice(0, 50) || "(untitled)",
       url: w.url,
       focused: w.id === focusedWindowId,
+      hidden: w.active === false,
       recording: activeRecordingSessions.has(w.id)
     }));
     const activeRecordings = activeRecordingSessions.size;

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.4.1";
+var VERSION = "1.5.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -3097,7 +3097,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.4.1";
+  var VERSION = "1.5.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -13727,6 +13727,9 @@ function inferSuggestion(step, pageContext) {
 }
 
 // src/api-handlers.ts
+function withWarning(body, response) {
+  return response.warning ? { ...body, warning: response.warning } : body;
+}
 var handlers = new Map;
 function registerHandler(endpoint2, handler) {
   handlers.set(endpoint2.path, handler);
@@ -14557,7 +14560,7 @@ registerHandler(find, async (body, ctx) => {
   })()`;
   const response = await ctx.requestFromBrowser("eval", "exec", { code: findCode }, 5000, windowId);
   if (response.success && response.data) {
-    return Response.json({ success: true, ...response.data }, { headers: ctx.headers });
+    return Response.json(withWarning({ success: true, ...response.data }, response), { headers: ctx.headers });
   }
   return Response.json(response, { headers: ctx.headers });
 });
@@ -14663,7 +14666,7 @@ registerHandler(formData, async (body, ctx) => {
   })()`;
   const response = await ctx.requestFromBrowser("eval", "exec", { code: formCode }, 5000, windowId);
   if (response.success && response.data) {
-    return Response.json(response.data, { headers: ctx.headers });
+    return Response.json(withWarning(response.data, response), { headers: ctx.headers });
   }
   return Response.json(response, { headers: ctx.headers });
 });
@@ -15226,6 +15229,52 @@ function isHaltijaProcess(pid) {
   }
 }
 
+// src/tab-liveness.ts
+function hiddenTabWarning(win) {
+  if (!win)
+    return null;
+  if (win.active !== false)
+    return null;
+  const which = win.title ? `"${win.title}"` : win.id;
+  return `The tab that answered (${which}) reports it is HIDDEN \u2014 backgrounded, minimized, ` + `behind another window, or the display is asleep. Browsers stop requestAnimationFrame and ` + `throttle timers in a hidden tab, so anything mounted by rAF/IntersectionObserver may never ` + `have run: THIS RESULT CAN BE PLAUSIBLE BUT WRONG (an empty selector here means "not mounted ` + `yet", not "broken"). Bring the tab to the front, or target a visible one with --window <id>.`;
+}
+
+// src/focus-ambiguity.ts
+function isTopLevelTab(w) {
+  return w.windowType !== "iframe" && w.windowType !== "popup";
+}
+function originOf(url) {
+  if (!url)
+    return null;
+  try {
+    const origin = new URL(url).origin;
+    return origin === "null" ? url : origin;
+  } catch {
+    return url;
+  }
+}
+function ambiguousFocusWarning(opts) {
+  const { windows: windows2, sentToId, wasTargeted } = opts;
+  if (wasTargeted)
+    return null;
+  if (!sentToId)
+    return null;
+  const withOrigin = windows2.filter(isTopLevelTab).map((w) => ({ ...w, origin: originOf(w.url) })).filter((w) => w.origin !== null);
+  const distinctOrigins = new Set(withOrigin.map((w) => w.origin));
+  if (distinctOrigins.size < 2)
+    return null;
+  const chosen = withOrigin.find((w) => w.id === sentToId);
+  const chosenWhere = chosen ? `${chosen.origin}${chosen.title ? ` \u2014 "${chosen.title}"` : ""}` : sentToId;
+  const others = withOrigin.filter((w) => !chosen || w.origin !== chosen.origin);
+  const MAX = 4;
+  const pins = others.slice(0, MAX).map((w) => `  --window ${w.id}  \u2192 ${w.origin}${w.title ? ` ("${w.title}")` : ""}`).join(`
+`);
+  const more = others.length > MAX ? `
+  \u2026and ${others.length - MAX} more` : "";
+  return `This command was NOT pinned to a window and this server has tabs from ` + `${distinctOrigins.size} different origins, so *focus* \u2014 not your working directory \u2014 chose ` + `which tab answered (${chosenWhere}). A tab you didn't mean (another project's page on this ` + `shared server, or one a human just clicked into) can silently receive the command. If you ` + `meant a different page, pin it:
+${pins}${more}`;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16392,14 +16441,29 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
     source: "agent"
   };
   return new Promise((resolve) => {
+    let sentTo = null;
+    const attachWarning = (res) => {
+      const hidden = hiddenTabWarning(sentTo);
+      const ambiguous = ambiguousFocusWarning({
+        windows: Array.from(windows2.values()),
+        sentToId: sentTo?.id,
+        wasTargeted: !!windowId
+      });
+      const warning = [hidden, ambiguous].filter(Boolean).join(`
+
+`);
+      return warning ? { ...res, warning } : res;
+    };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
-      resolve({ id, success: false, error: "Timeout", timestamp: Date.now() });
+      resolve(attachWarning({ id, success: false, error: "Timeout", timestamp: Date.now() }));
     }, timeoutMs);
-    pendingResponses.set(id, { resolve, timeout });
+    const resolveWithLiveness = (res) => resolve(attachWarning(res));
+    pendingResponses.set(id, { resolve: resolveWithLiveness, timeout });
     if (windowId) {
       const win = windows2.get(windowId);
       if (win) {
+        sentTo = win;
         win.ws.send(JSON.stringify(msg));
       } else {
         clearTimeout(timeout);
@@ -16408,13 +16472,16 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       }
     } else if (focusedWindowId && windows2.has(focusedWindowId)) {
       const focusedWin = windows2.get(focusedWindowId);
+      sentTo = focusedWin;
       focusedWin.ws.send(JSON.stringify(msg));
     } else {
       const activeWindows = Array.from(windows2.values()).filter((w) => w.active).sort((a, b) => b.lastSeen - a.lastSeen);
       if (activeWindows.length > 0) {
+        sentTo = activeWindows[0];
         activeWindows[0].ws.send(JSON.stringify(msg));
       } else if (windows2.size > 0) {
         const mostRecent = Array.from(windows2.values()).sort((a, b) => b.lastSeen - a.lastSeen)[0];
+        sentTo = mostRecent;
         mostRecent.ws.send(JSON.stringify(msg));
       } else {
         clearTimeout(timeout);
@@ -16798,6 +16865,7 @@ async function handleRest(req) {
       title: w.title?.slice(0, 50) || "(untitled)",
       url: w.url,
       focused: w.id === focusedWindowId,
+      hidden: w.active === false,
       recording: activeRecordingSessions.has(w.id)
     }));
     const activeRecordings = activeRecordingSessions.size;

package/dist/tab-liveness.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Is the tab we just talked to actually awake?
+ *
+ * From issue #3, and it is the sharpest failure this tool has: a hidden tab **answers**. Run
+ * `hj eval 'document.querySelectorAll("tosi-b3d").length'` against a backgrounded tab and you get
+ * `0` — not a timeout, not an error. A confident, wrong number. The custom elements are
+ * registered and the static markup rendered, but browsers stop `requestAnimationFrame` and
+ * throttle timers in a hidden tab, so anything mounted by rAF / IntersectionObserver never runs.
+ * The page looks **broken** when it is merely **asleep**, and the reporter burned several rounds
+ * diagnosing a component bug that didn't exist.
+ *
+ * This is the instrument lying in its most dangerous form: not silence, but a plausible answer.
+ * So when we route a command to a tab that has told us it is hidden, we say so alongside the
+ * result rather than letting the number speak for itself.
+ *
+ * **Why not `lastSeen` staleness?** The reporter suggested it, and the data does go stale — but
+ * there is no periodic heartbeat: `lastSeen` only advances on navigation/visibility events. So an
+ * idle-but-perfectly-healthy tab looks exactly as stale as a sleeping one, and labelling on it
+ * would add a NEW false signal to fix a lying one. `active` is the honest signal: the widget sets
+ * it from `document.visibilityState` on `visibilitychange`, so `active === false` means the tab
+ * itself reported being hidden.
+ */
+/** The bits of a tracked window this decision needs. */
+export interface TabLivenessInfo {
+    id: string;
+    title?: string;
+    /** False when the tab reported itself hidden (visibilitychange → hidden). */
+    active?: boolean;
+}
+/**
+ * A warning to attach to a result that came from a hidden tab, or null when the tab is awake
+ * (or we have no basis to claim otherwise — `active` undefined means the tab never reported,
+ * and we do not invent a warning we can't support).
+ */
+export declare function hiddenTabWarning(win: TabLivenessInfo | null | undefined): string | null;

package/dist/types.d.ts

@@ -26,6 +26,12 @@ export interface DevResponse {
     data?: any;
     error?: string;
     timestamp: number;
+    /**
+     * Set when the result is real but may be MISLEADING — currently: it came from a tab that
+     * reported itself hidden, where rAF/timers are throttled so rAF-driven content may never have
+     * mounted. The command succeeded; the number may still be wrong. See src/tab-liveness.ts.
+     */
+    warning?: string;
 }
 export interface DomQueryRequest {
     selector?: string;

package/dist/version.d.ts

@@ -8,4 +8,4 @@
  * ⚠️  AUTO-GENERATED FROM package.json - DO NOT EDIT THIS FILE
  * ⚠️  To change the version, update package.json and run: bun run build
  */
-export declare const VERSION = "1.4.1";
+export declare const VERSION = "1.5.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Browser control for AI agents - query DOM, click, type, run JS, watch mutations",
   "type": "module",
   "main": "dist/index.js",