haltija 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 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

package/apps/desktop/package.json

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

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)

package/bin/hj.mjs

@@ -191,6 +191,104 @@ async function runServers(resolvedPort) {
   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,
@@ -280,7 +378,13 @@ ${dim('Overriding that (per-shell):')}
 ${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.
@@ -288,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 || ''
@@ -358,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\`.`)
     }
@@ -444,6 +572,13 @@ if (subcommand === 'servers' || subcommand === 'ls') {
   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.

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.6.0'
+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>;

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.6.0";
+export declare const VERSION = "1.6.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.6.0";
+var VERSION = "1.6.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.6.0";
+  var VERSION = "1.6.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/hj.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// haltija-cli:do-not-edit v1.6.0
+// haltija-cli:do-not-edit v1.6.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.6.0";
+var HJ_VERSION = "1.6.1";
 
 // bin/semver.mjs
 function parseVersion(v) {
@@ -1629,7 +1629,13 @@ async function doRequest(url, method, body, context = {}) {
     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 (process.env.HALTIJA_STRICT === "1") {
+          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);
+        }
+        if (!json.warningRepeated)
+          console.error(`hj: warning — ${json.warning}`);
       }
       if (!jsonOutput && subcommand === "tree" && json.success && json.data) {
         console.log(formatTree(json.data, 0, { depth: body?.depth }));
@@ -2063,6 +2069,77 @@ This shell targets :${resolvedPort}, but nothing is listening there.`));
   console.log(dim3(`
 Pick one:  `) + `hj --port <n> <cmd>` + dim3("  or  ") + `hj --name <name> <cmd>`);
 }
+async function runDoctor(port, portSource, jsonOutput) {
+  const bold2 = (s) => `\x1B[1m${s}\x1B[0m`;
+  const dim3 = (s) => `\x1B[2m${s}\x1B[0m`;
+  const green2 = (s) => `\x1B[32m${s}\x1B[0m`;
+  const red2 = (s) => `\x1B[31m${s}\x1B[0m`;
+  const yellow2 = (s) => `\x1B[33m${s}\x1B[0m`;
+  const token = process.env.HALTIJA_TOKEN;
+  const problems = [];
+  const notes = [];
+  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) {
+    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)`);
+    }
+  }
+  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(`${bold2("target:")} port ${port} ${dim3(`(${portSource})`)}`);
+  if (status) {
+    const tabCount = status.windows?.length ?? 0;
+    console.log(`${bold2("server:")} haltija ${status.serverVersion || "?"}${status.desktopApp ? dim3(" (desktop app)") : ""}, ${tabCount} tab${tabCount === 1 ? "" : "s"}`);
+  }
+  for (const n of notes)
+    console.log(`${yellow2("!")} ${n}`);
+  for (const p of problems)
+    console.log(`${red2("✗")} ${p}`);
+  if (ok)
+    console.log(`${green2("✓")} ready to drive`);
+  return ok;
+}
 function lookupNamedInstance(name) {
   const path = join2(REGISTRY_DIR, `${name}.json`);
   if (!existsSync2(path))
@@ -2138,13 +2215,25 @@ ${dim3("Overriding that (per-shell):")}
 ${dim3("Lifecycle:")}
   ${dim3("hj where")}                       # which server this shell targets + what is alive there
   ${dim3("hj servers")}                     # list ALL live servers (pick one with --port/--name)
+  ${dim3("hj doctor")}                      # preflight: drivable + unambiguous? EXITS 1 if not
   ${dim3("hj shutdown")}                    # stop the targeted server (a private --app: Electron + all)
+
+${dim3("For scripts / CI:")}
+  ${dim3("hj --strict <cmd>")}              # turn advisory warnings (wrong project, hidden tab)
+  ${dim3("HALTIJA_STRICT=1")}               # into non-zero exits, so a lane fails fast on the
+                                  ${dim3("# real cause instead of a later timeout")}
 ${listSubcommands()}
 Run ${dim3("hj --help")} for this help.
 Run ${dim3("haltija --help")} for server/app options.
 `);
   process.exit(0);
 }
+var strictIdx = args.indexOf("--strict");
+if (strictIdx !== -1) {
+  process.env.HALTIJA_STRICT = "1";
+  args.splice(strictIdx, 1);
+}
+var STRICT = process.env.HALTIJA_STRICT === "1";
 var resolvedName = process.env.HALTIJA_NAME || "";
 var nameSource = resolvedName ? "HALTIJA_NAME env" : "";
 var nameIdx = args.indexOf("--name");
@@ -2190,6 +2279,12 @@ if (portFlag) {
     portSource = "8700 (default)";
     if (live.length) {
       const names = live.map((e) => `${e.name} (${e.cwd})`).join(", ");
+      if (STRICT) {
+        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\`.`);
     }
@@ -2238,6 +2333,10 @@ if (subcommand === "servers" || subcommand === "ls") {
   await runServers(port);
   process.exit(0);
 }
+if (subcommand === "doctor") {
+  const ok = await runDoctor(port, portSource, subArgs.includes("--json"));
+  process.exit(ok ? 0 : 1);
+}
 if (subcommand === "shutdown" || subcommand === "quit") {
   const token = process.env.HALTIJA_TOKEN;
   try {

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.6.0";
+var VERSION = "1.6.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -1008,9 +1008,13 @@ curl -X POST localhost:8700/click -d '{"selector":"#submit"}'
 
 Returns server info and connected browser count.
 
-Response: { version, uptime, browsers: n, focused?: windowId }
+Response: { serverVersion, ready, windows: [...], browsers: n, desktopApp, pid, ... }
 
-Use to verify server is running and browsers are connected before testing.
+Use to verify the server is running \u2014 but gate a test lane on **\`ready\`**, not on the 200. A
+server can be up with zero connected tabs: /status answers fine and there is still nothing to
+drive, so a lane that adopts it fails later on a timeout that points at the caller's own code.
+\`ready\` is true when at least one top-level tab is connected. \`hj doctor\` checks this (plus
+ambiguous targeting) and exits non-zero, which is the one-command preflight for a lane.
 
 ---
 
@@ -2166,10 +2170,16 @@ Deprecated: Use POST /select {"action":"clear"} instead.
 
 Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused }] }
+Response: { windows: [{ id, url, title, focused }], count, ready, hint }
 
 Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.
 
+**\`ready\` is the signal to gate a test lane on, not "is the server up".** A server can be running
+with zero connected tabs \u2014 it answers /status 200 but there is nothing to drive, and a lane that
+adopts it fails later on a confusing timeout. \`ready\` is true when at least one top-level tab is
+connected. (Hidden tabs count as ready \u2014 they're reachable, just possibly stale; see the hidden-tab
+warning.) \`hj doctor\` checks this and exits non-zero, so a lane can fail fast on the real cause.
+
 ---
 
 ### \`POST /tabs/open\`
@@ -2867,8 +2877,16 @@ hj tree                                    # ...and plain hj reaches it
 
 hj where                                   # which port, WHY, and what is alive there
 hj servers                                 # list ALL live servers; pick with --port/--name
+hj doctor                                  # preflight for a script: EXITS 1 if not drivable
+hj --strict <cmd>                          # warnings (wrong project / hidden tab) become errors
 \`\`\`
 
+**In a script or CI lane, gate on \`hj doctor\` (or the \`ready\` field), not on "the server
+answered".** A server can be up with zero connected tabs \u2014 \`/status\` returns 200 and there
+is still nothing to drive, so a lane that adopts it fails later on a timeout that points at
+your own code. \`hj doctor\` exits non-zero on exactly that, and \`--strict\` turns the advisory
+warnings into failures so a suspect result is never consumed.
+
 When several haltijas run at once (e.g. a project server AND the desktop app),
 \`hj servers\` (alias \`hj ls\`) lists them all \u2014 the desktop app is reachable as
 \`hj --name desktop\`. If no server owns your directory, \`hj\` falls back to the shared default port
@@ -3040,6 +3058,11 @@ Two first-party ways to run (plus embedding, below):
   port a shell targets and WHY; override with \`--port\` or \`--name\`. When several servers
   run at once (e.g. a project server AND the desktop app), \`hj servers\` lists them all \u2014
   the desktop app is reachable as \`hj --name desktop\`.
+- **Scripts/CI:** gate on \`hj doctor\` (exits non-zero when the target is not drivable or is
+  ambiguous) or on the \`ready\` field of \`/status\`/\`/windows\` \u2014 NOT on "the server answered".
+  A server can be up with zero connected tabs, so a lane that adopts it fails later on a
+  confusing timeout. \`hj --strict\` (or HALTIJA_STRICT=1) turns the hidden-tab and
+  cross-project warnings into non-zero exits so a suspect result is never consumed.
 - **CI:** two engines, and the choice matters \u2014 both need one external browser, but
   a *different* one:
   - \`haltija --ci\` (or \`--private --app\` for an isolated instance) drives **Electron**
@@ -3126,7 +3149,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.6.0";
+  var VERSION = "1.6.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -12906,9 +12929,15 @@ var windows = endpoint({
   summary: "List connected windows",
   description: `Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused }] }
+Response: { windows: [{ id, url, title, focused }], count, ready, hint }
+
+Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.
 
-Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.`,
+**\`ready\` is the signal to gate a test lane on, not "is the server up".** A server can be running
+with zero connected tabs \u2014 it answers /status 200 but there is nothing to drive, and a lane that
+adopts it fails later on a confusing timeout. \`ready\` is true when at least one top-level tab is
+connected. (Hidden tabs count as ready \u2014 they're reachable, just possibly stale; see the hidden-tab
+warning.) \`hj doctor\` checks this and exits non-zero, so a lane can fail fast on the real cause.`,
   category: "windows",
   hints: "--json | see: tabs-open, tabs-close, tabs-focus, status"
 });
@@ -13379,9 +13408,13 @@ var status = endpoint({
   summary: "Server status",
   description: `Returns server info and connected browser count.
 
-Response: { version, uptime, browsers: n, focused?: windowId }
+Response: { serverVersion, ready, windows: [...], browsers: n, desktopApp, pid, ... }
 
-Use to verify server is running and browsers are connected before testing.`,
+Use to verify the server is running \u2014 but gate a test lane on **\`ready\`**, not on the 200. A
+server can be up with zero connected tabs: /status answers fine and there is still nothing to
+drive, so a lane that adopts it fails later on a timeout that points at the caller's own code.
+\`ready\` is true when at least one top-level tab is connected. \`hj doctor\` checks this (plus
+ambiguous targeting) and exits non-zero, which is the one-command preflight for a lane.`,
   category: "meta",
   hints: "--json | see: windows, stats, console"
 });
@@ -13840,7 +13873,9 @@ function inferSuggestion(step, pageContext) {
 
 // src/api-handlers.ts
 function withWarning(body, response) {
-  return response.warning ? { ...body, warning: response.warning } : body;
+  if (!response.warning)
+    return body;
+  return response.warningRepeated ? { ...body, warning: response.warning, warningRepeated: true } : { ...body, warning: response.warning };
 }
 var handlers = new Map;
 function registerHandler(endpoint2, handler) {
@@ -16611,10 +16646,8 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
 `);
       if (!warning)
         return res;
-      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
-        return res;
-      }
-      return { ...res, warning };
+      const repeated = !shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS);
+      return repeated ? { ...res, warning, warningRepeated: true } : { ...res, warning };
     };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
@@ -17041,6 +17074,7 @@ async function handleRest(req) {
     return Response.json({
       ok: allWindows.length > 0,
       windows: windowList,
+      ready: allWindows.filter((w) => (w.windowType || "tab") === "tab").length > 0,
       serverVersion: SERVER_VERSION,
       pid: process.pid,
       recording: activeRecordings > 0,
@@ -18988,11 +19022,14 @@ ${messageText}`;
       label: w.label,
       windowType: w.windowType || "tab"
     }));
+    const drivableTabs = windowList.filter((w) => (w.windowType || "tab") === "tab");
+    const ready = drivableTabs.length > 0;
     const hint = windowList.length > 1 ? "Multiple tabs connected. Use ?window=<id> to target specific tab (e.g., /tree?window=abc123)" : windowList.length === 1 ? "One tab connected. Commands automatically target it." : "No tabs connected. Inject the widget into a browser tab.";
     return Response.json({
       windows: windowList,
       focused: focusedWindowId,
       count: windowList.length,
+      ready,
       hint
     }, { headers });
   }

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.6.0";
+var VERSION = "1.6.1";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -1008,9 +1008,13 @@ curl -X POST localhost:8700/click -d '{"selector":"#submit"}'
 
 Returns server info and connected browser count.
 
-Response: { version, uptime, browsers: n, focused?: windowId }
+Response: { serverVersion, ready, windows: [...], browsers: n, desktopApp, pid, ... }
 
-Use to verify server is running and browsers are connected before testing.
+Use to verify the server is running \u2014 but gate a test lane on **\`ready\`**, not on the 200. A
+server can be up with zero connected tabs: /status answers fine and there is still nothing to
+drive, so a lane that adopts it fails later on a timeout that points at the caller's own code.
+\`ready\` is true when at least one top-level tab is connected. \`hj doctor\` checks this (plus
+ambiguous targeting) and exits non-zero, which is the one-command preflight for a lane.
 
 ---
 
@@ -2166,10 +2170,16 @@ Deprecated: Use POST /select {"action":"clear"} instead.
 
 Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused }] }
+Response: { windows: [{ id, url, title, focused }], count, ready, hint }
 
 Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.
 
+**\`ready\` is the signal to gate a test lane on, not "is the server up".** A server can be running
+with zero connected tabs \u2014 it answers /status 200 but there is nothing to drive, and a lane that
+adopts it fails later on a confusing timeout. \`ready\` is true when at least one top-level tab is
+connected. (Hidden tabs count as ready \u2014 they're reachable, just possibly stale; see the hidden-tab
+warning.) \`hj doctor\` checks this and exits non-zero, so a lane can fail fast on the real cause.
+
 ---
 
 ### \`POST /tabs/open\`
@@ -2867,8 +2877,16 @@ hj tree                                    # ...and plain hj reaches it
 
 hj where                                   # which port, WHY, and what is alive there
 hj servers                                 # list ALL live servers; pick with --port/--name
+hj doctor                                  # preflight for a script: EXITS 1 if not drivable
+hj --strict <cmd>                          # warnings (wrong project / hidden tab) become errors
 \`\`\`
 
+**In a script or CI lane, gate on \`hj doctor\` (or the \`ready\` field), not on "the server
+answered".** A server can be up with zero connected tabs \u2014 \`/status\` returns 200 and there
+is still nothing to drive, so a lane that adopts it fails later on a timeout that points at
+your own code. \`hj doctor\` exits non-zero on exactly that, and \`--strict\` turns the advisory
+warnings into failures so a suspect result is never consumed.
+
 When several haltijas run at once (e.g. a project server AND the desktop app),
 \`hj servers\` (alias \`hj ls\`) lists them all \u2014 the desktop app is reachable as
 \`hj --name desktop\`. If no server owns your directory, \`hj\` falls back to the shared default port
@@ -3040,6 +3058,11 @@ Two first-party ways to run (plus embedding, below):
   port a shell targets and WHY; override with \`--port\` or \`--name\`. When several servers
   run at once (e.g. a project server AND the desktop app), \`hj servers\` lists them all \u2014
   the desktop app is reachable as \`hj --name desktop\`.
+- **Scripts/CI:** gate on \`hj doctor\` (exits non-zero when the target is not drivable or is
+  ambiguous) or on the \`ready\` field of \`/status\`/\`/windows\` \u2014 NOT on "the server answered".
+  A server can be up with zero connected tabs, so a lane that adopts it fails later on a
+  confusing timeout. \`hj --strict\` (or HALTIJA_STRICT=1) turns the hidden-tab and
+  cross-project warnings into non-zero exits so a suspect result is never consumed.
 - **CI:** two engines, and the choice matters \u2014 both need one external browser, but
   a *different* one:
   - \`haltija --ci\` (or \`--private --app\` for an isolated instance) drives **Electron**
@@ -3126,7 +3149,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.6.0";
+  var VERSION = "1.6.1";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -12906,9 +12929,15 @@ var windows = endpoint({
   summary: "List connected windows",
   description: `Returns all connected browser windows/tabs with IDs, URLs, and titles.
 
-Response: { windows: [{ id, url, title, focused }] }
+Response: { windows: [{ id, url, title, focused }], count, ready, hint }
+
+Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.
 
-Use window IDs in other endpoints (e.g., /click, /tree) to target specific tabs.`,
+**\`ready\` is the signal to gate a test lane on, not "is the server up".** A server can be running
+with zero connected tabs \u2014 it answers /status 200 but there is nothing to drive, and a lane that
+adopts it fails later on a confusing timeout. \`ready\` is true when at least one top-level tab is
+connected. (Hidden tabs count as ready \u2014 they're reachable, just possibly stale; see the hidden-tab
+warning.) \`hj doctor\` checks this and exits non-zero, so a lane can fail fast on the real cause.`,
   category: "windows",
   hints: "--json | see: tabs-open, tabs-close, tabs-focus, status"
 });
@@ -13379,9 +13408,13 @@ var status = endpoint({
   summary: "Server status",
   description: `Returns server info and connected browser count.
 
-Response: { version, uptime, browsers: n, focused?: windowId }
+Response: { serverVersion, ready, windows: [...], browsers: n, desktopApp, pid, ... }
 
-Use to verify server is running and browsers are connected before testing.`,
+Use to verify the server is running \u2014 but gate a test lane on **\`ready\`**, not on the 200. A
+server can be up with zero connected tabs: /status answers fine and there is still nothing to
+drive, so a lane that adopts it fails later on a timeout that points at the caller's own code.
+\`ready\` is true when at least one top-level tab is connected. \`hj doctor\` checks this (plus
+ambiguous targeting) and exits non-zero, which is the one-command preflight for a lane.`,
   category: "meta",
   hints: "--json | see: windows, stats, console"
 });
@@ -13840,7 +13873,9 @@ function inferSuggestion(step, pageContext) {
 
 // src/api-handlers.ts
 function withWarning(body, response) {
-  return response.warning ? { ...body, warning: response.warning } : body;
+  if (!response.warning)
+    return body;
+  return response.warningRepeated ? { ...body, warning: response.warning, warningRepeated: true } : { ...body, warning: response.warning };
 }
 var handlers = new Map;
 function registerHandler(endpoint2, handler) {
@@ -16611,10 +16646,8 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
 `);
       if (!warning)
         return res;
-      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
-        return res;
-      }
-      return { ...res, warning };
+      const repeated = !shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS);
+      return repeated ? { ...res, warning, warningRepeated: true } : { ...res, warning };
     };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
@@ -17041,6 +17074,7 @@ async function handleRest(req) {
     return Response.json({
       ok: allWindows.length > 0,
       windows: windowList,
+      ready: allWindows.filter((w) => (w.windowType || "tab") === "tab").length > 0,
       serverVersion: SERVER_VERSION,
       pid: process.pid,
       recording: activeRecordings > 0,
@@ -18988,11 +19022,14 @@ ${messageText}`;
       label: w.label,
       windowType: w.windowType || "tab"
     }));
+    const drivableTabs = windowList.filter((w) => (w.windowType || "tab") === "tab");
+    const ready = drivableTabs.length > 0;
     const hint = windowList.length > 1 ? "Multiple tabs connected. Use ?window=<id> to target specific tab (e.g., /tree?window=abc123)" : windowList.length === 1 ? "One tab connected. Commands automatically target it." : "No tabs connected. Inject the widget into a browser tab.";
     return Response.json({
       windows: windowList,
       focused: focusedWindowId,
       count: windowList.length,
+      ready,
       hint
     }, { headers });
   }

package/dist/types.d.ts

@@ -32,6 +32,12 @@ export interface DevResponse {
      * mounted. The command succeeded; the number may still be wrong. See src/tab-liveness.ts.
      */
     warning?: string;
+    /**
+     * True when `warning` describes a condition already reported within the recent cooldown. The
+     * condition still holds — this only says "you've been told". Clients suppress the repeat for
+     * humans; strict/CI consumers must fail on `warning` regardless of this flag.
+     */
+    warningRepeated?: boolean;
 }
 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.6.0";
+export declare const VERSION = "1.6.1";

package/docs/CI-INTEGRATION.md

@@ -168,29 +168,46 @@ xvfb-run --auto-servernum npx electron . &
 
 ## Waiting for Ready State
 
-Don't use `sleep` — use a proper wait loop:
+Don't use `sleep`, and **don't gate on "the server answered"** — that is the single most common
+way a lane fails confusingly. A haltija server can be up with **zero connected tabs**: `/status`
+returns 200, your lane decides haltija is available and skips starting its own browser, and then
+`navigate` fails with "no browser reachable" — or worse, times out somewhere that looks like your
+code's fault. *Server up ≠ drivable.*
+
+Use the built-in preflight, which exits non-zero on exactly that case:
 
 ```bash
-# Wait for server
+# Wait until the target is actually drivable (not merely alive)
 for i in $(seq 1 30); do
-  if curl -sf http://localhost:8700/status | jq -e '.serverVersion' > /dev/null 2>&1; then
-    echo "Haltija server ready after ${i}s"
-    break
-  fi
+  if hj doctor >/dev/null 2>&1; then break; fi
   sleep 1
 done
 
-# Wait for browser connection (if using Electron app)
-for i in $(seq 1 30); do
-  WINDOWS=$(curl -sf http://localhost:8700/windows 2>/dev/null | jq '.windows | length' 2>/dev/null || echo 0)
-  if [ "$WINDOWS" -gt 0 ]; then
-    echo "Browser connected after ${i}s"
-    break
-  fi
-  sleep 1
-done
+hj doctor   # print the verdict; exits 1 if it's not drivable or the target is ambiguous
+```
+
+`hj doctor` checks, in the order they bite: server reachable → a tab is actually connected → the
+target isn't ambiguous (your cwd matches, or you chose explicitly) → tabs aren't all hidden →
+versions aligned. Add `--json` for machine-readable output.
+
+Checking by hand instead? Gate on the **`ready`** field, not on the HTTP status:
+
+```bash
+curl -sf http://localhost:8700/status | jq -e '.ready'   # true only when a tab is connected
+```
+
+And for a lane, add **`--strict`** (or `HALTIJA_STRICT=1`) to your `hj` calls so advisory warnings —
+cross-project targeting, a hidden tab returning stale results — become non-zero exits instead of
+stderr noise your script ignores:
+
+```bash
+hj --strict navigate "$URL"
 ```
 
+Best of all, don't share state at all: `haltija --private --app` (or `--private --headless`) gives
+the lane its own isolated server and browser on an ephemeral port, which nothing else can adopt and
+which tears down with the run.
+
 ## The hj CLI
 
 The `hj` command is installed to `~/.local/bin` when Haltija starts. Add it to PATH:

package/llms.txt

@@ -42,6 +42,11 @@ Two first-party ways to run (plus embedding, below):
   port a shell targets and WHY; override with `--port` or `--name`. When several servers
   run at once (e.g. a project server AND the desktop app), `hj servers` lists them all —
   the desktop app is reachable as `hj --name desktop`.
+- **Scripts/CI:** gate on `hj doctor` (exits non-zero when the target is not drivable or is
+  ambiguous) or on the `ready` field of `/status`/`/windows` — NOT on "the server answered".
+  A server can be up with zero connected tabs, so a lane that adopts it fails later on a
+  confusing timeout. `hj --strict` (or HALTIJA_STRICT=1) turns the hidden-tab and
+  cross-project warnings into non-zero exits so a suspect result is never consumed.
 - **CI:** two engines, and the choice matters — both need one external browser, but
   a *different* one:
   - `haltija --ci` (or `--private --app` for an isolated instance) drives **Electron**

package/package.json

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