haltija 1.13.0-beta.2 → 1.13.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # Changelog
 
+## 1.13.0-beta.4 (2026-10-17)
+
+### Added
+
+- **Dialogs can be let through to a person: `hj dialog-configure --alert show`** (virta #3274).
+  `show` is a new policy value for `alert`, `confirm` and `prompt` (also `POST /dialog/configure
+  {"alert":"show"}`). The dialog reaches the person at the page, and it is still recorded and
+  reported with their answer (`shown: true` in `/dialog/history`). It is opt-in: interception stays
+  the default, because a native modal blocks the page and an agent driving it cannot see or answer
+  one. The policy lives in the tab and resets on reload.
+  - `hj dialog-configure` and `hj dialog-history` are now real commands. Both endpoints declared
+    those CLI names, but neither was ever invokable.
+  - An unknown policy value is refused with the valid ones named. It used to answer success and
+    change nothing; for `prompt`, every prompt then returned `undefined`.
+  - The documented response shapes of both endpoints are corrected to `{ success, data: … }`.
+
+### Fixed
+
+- **An intercepted `alert`, `confirm` or `prompt` now says so on the page's console** (virta #3274).
+  The dev channel answers native dialogs so an agent driving the page is never blocked, but a person
+  using the same page saw `alert()` do nothing, with no hint why. Each intercepted dialog now logs
+  one `[haltija] intercepted …` line naming what it answered and how to show dialogs instead. The line
+  goes to the real console only; it is not captured as page output in `/console`. Interception
+  itself is unchanged.
+
+- **`press` in `haltija/test` (and `DevChannelClient.press`) is a real key sequence at the focused
+  element** (virta #3121). It goes through `/key`, like `hj key`: the modifier keys go down, then
+  keydown → … → keyup for the key, then the modifiers come up. It used to be one `keydown` dispatched
+  at `body`, so a handler on a focused input, or one listening for `keyup`, never fired. A test that
+  relied on the event's target being `body` will now see the focused element instead.
+
+- **With nothing focused, `hj doctor` judges the tab commands actually reach** (virta #3123). It
+  picked the first visible tab, where the server picks the most recently seen active one, so its
+  `observability:` line could describe a tab no command goes to. `/status` now reports
+  `targetWindowId` (the server's own answer) and doctor reads it; against an older server it falls
+  back as before.
+
+- **`clickAt` and `dragFrom` refuse the shared default 8700 like `click` does** (virta #3120). They
+  act through `eval`, which `haltija/test` leaves open on the shared port so reads keep working, so
+  with no `HALTIJA_PORT` / `HALTIJA_URL` they dispatched pointer events into whatever tab was focused
+  there, possibly another project's. `read` and `hj.eval` are unchanged; `HALTIJA_TEST_ALLOW_SHARED=1`
+  still opts in.
+
+- **`hj test validate <file>` works** (GitHub #55). It returned HTTP 500 ("undefined is not an
+  object (evaluating 'test.steps.length')") for every file, because the CLI sends `{ test }` as the
+  schema documents and the server read only a bare test. Both shapes are accepted now; a body with
+  no `steps` array is a 400 that says so. The documented response shape is corrected to what the
+  endpoint returns: `{ valid, issues, stepCount }`.
+
+- **The MCP server works from npm** (GitHub #46, #47). `haltija --setup-mcp` (Claude Desktop) and
+  `haltija-mcp-setup` (Claude Code) both exited 1 for every npm user: they looked for
+  `apps/mcp/build/index.js`, which the package never contained. Even if it had been shipped, that
+  file imported an SDK npm never installs for a nested package. The server now ships as
+  `dist/mcp.js` (bin `haltija-mcp`), one bundle with its dependencies inlined, about 170 KB gzipped,
+  and adds no dependencies to an install.
+  - Both setup commands write a command that starts it. When the package runs from an npx/bunx
+    cache, they write a version-pinned `npx -p haltija@<version> haltija-mcp` instead of a path the
+    cache will delete.
+  - The server sends `HALTIJA_TOKEN`, so it works against a server started with `--token`, and it
+    reports haltija's version instead of `0.1.0`.
+  - It compiles again: `tsc` failed with TS2589 on handler types inferred from a runtime-built shape.
+    In-range updates cleared ten advisories (1 critical, 3 high).
+  - Tested the way a user gets it: a new test packs the tarball, extracts it with no `node_modules`
+    above it, runs each setup command, and calls a tool through the written config against a live,
+    token-protected server.
+
+- **The test runner's `wait` with `forWindow: true` no longer stops at an iframe, and returns as
+  soon as the window appears** (virta #2468). It accepted any new window, including a frame
+  injecting its own widget, and then slept a fixed 300 ms. A window registers on its `connected`
+  message, so it already takes commands at that point. The step now waits for a new tab or popup.
+
+- **The desktop app says when it ignores your `DEV_CHANNEL_MODE`** (virta #1078). Its public
+  server always serves both transports, because it serves other projects' pages too. That is
+  unchanged, but an explicit `http` or `https` used to be dropped without a word. It now prints one
+  line naming what was ignored and why.
+
+## 1.13.0-beta.3 (2026-10-08)
+
+### Added
+
+- **`hj doctor` prints an `observability:` line whenever a tab is connected** (#821, GitHub #50). It
+  says whether the tab that commands go to is visible and painting and, for widgets 1.12.6 or
+  newer, how long ago it last drew a frame. When
+  it isn't, the line says what that invalidates: geometry, screenshots and anything rAF-driven. A
+  backgrounded tab still answers, just wrongly, so this matters even when nothing fails. Also in
+  `--json` as `observability`.
+
+- **`hj map` reads tosijs's shipped agent-surface contract** (#787, GitHub #16). It reads
+  `describe().version`, `exposure` and `writable` instead of inferring them, and was verified
+  against real tosijs 1.10.6.
+  - A read-only surface (a manifest without `write: true`) is reported as read-only. The map used
+    to tell agents to call `write()`, which the surface refuses.
+  - The callable actions are listed.
+  - An empty `'closed'` surface, the tosijs default, comes with a hint on how the app's author
+    enables it.
+  - A surface version haltija doesn't read produces a warning.
+  - The tier is no longer marked experimental, in the skill or in the `/map` API description.
+
+- **`playwrightBridge(page)`** in `haltija/test`: runs `testInBrowser` probes in Firefox and WebKit
+  through a Playwright page you launch (virta #3088). Tested in all three engines. New
+  `docs/TEST-IN-BROWSER.md` covers it, the bridge contract, and which engine each route reaches.
+
+### Fixed
+
+- **A bridge that wraps its `eval` reply is now named as the problem** (virta #2415).
+  `BrowserBridge.eval` was typed `Promise<any>` with no stated contract, and a bridge returning
+  `{ success: true, value }` made every `read()` fail with a bare "probe threw" although the probe
+  had run. The return shape is now typed and documented, and the error says the bridge returned no
+  `{ ok }` envelope and lists the keys it did return.
+
+  - Type change: `BrowserBridge.eval` now resolves to `unknown` rather than `any`. Bridges you
+    wrote still compile. Code that calls `.eval()` on a `BrowserBridge`-typed value and reads a
+    property off the result needs a cast.
+
+- **`haltija --server` no longer leaves its server running when the launcher is stopped.** The
+  server is a child process, and nothing passed a signal on, so a process manager (or a closed
+  terminal) that stopped the launcher left the server alive and holding its ports. SIGTERM, SIGINT
+  and SIGHUP now stop both.
+
+- **The docs no longer say `--headless` gives Firefox/WebKit coverage.** It launches Chromium and
+  has no engine flag. `--help`, the CI guide, the skill and `/llms.txt` all said to pick it for
+  multi-engine coverage.
+
+- **`hj doctor` checks visibility on the tab commands actually go to**, not across all tabs. A
+  hidden target used to pass with a note as long as some other tab was visible, while every
+  command went to the hidden one. For a project with declared origins that is the tab its
+  commands are pinned to, whichever tab has focus.
+
+- **Freeing a busy HTTPS port is now deliberate.** It used to probe the HTTPS port with plain HTTP,
+  which always failed, so the holder was refused as "a server we could not identify". That was the
+  right outcome only by accident, and the message misled (#1079).
+  - The HTTPS port is freed only when it was itself explicitly requested (`--https-port` /
+    `DEV_CHANNEL_HTTPS_PORT`). Being strict about the HTTP port says nothing about the HTTPS one,
+    and stopping a server's HTTPS listener stops its whole process, HTTP included.
+  - The holder is identified over TLS and asked to stop, under the same rules as the HTTP port.
+
 ## 1.13.0-beta.2 (2026-09-29)
 
 ### Changed

package/README.md

@@ -31,7 +31,9 @@ Paste this into your agent conversation:
 
 > I have the `hj` browser tool. Run `hj tree` to see the page, `hj click <id>` to interact, and `hj docs` for help.
 
-Or for Claude Code with MCP: `bunx haltija --setup-mcp`
+Or as MCP tools: `npx -p haltija haltija-mcp-setup` in a project (Claude Code, writes `.mcp.json`), or
+`bunx haltija --setup-mcp` (Claude Desktop). Claude Code can load the haltija skill instead:
+`/plugin marketplace add tonioloewald/haltija`, then `/plugin install haltija-skill@haltija`.
 
 ---
 

package/apps/desktop/main.js

@@ -24,7 +24,7 @@ const os = require('os')
 const { spawn } = require('child_process')
 const http = require('http')
 const { attachNetwork, detachNetwork, getNetworkLog, getNetworkStats, clearNetwork, isMonitoring } = require('./cdp-network.js')
-const { buildServerEnv } = require('./server-env.js')
+const { buildServerEnv, overriddenModeNotice } = require('./server-env.js')
 const { DEFAULT_HTTP_PORT, DEFAULT_INTERNAL_PORT, internalPortConflict } = require('./ports.js')
 // The wire protocol, generated from src/machine-channel.ts — NOT re-declared here. main.js used to
 // hand-roll the prefixes, the line split and the parse; that copy is where the __NEED_WINDOW__
@@ -1384,6 +1384,8 @@ ipcMain.handle('machine-request', async (_evt, path, init) => {
   function spawnHaltijaServer({ port, role, serverPath, useCompiledBinary, componentDir, portFile }) {
   // Built by src/desktop-server-env.ts, whose contract is unit-tested without launching Electron —
   // getting this wrong is silent (a child that ignores its port, binds the parent's, and dies).
+  const modeNotice = overriddenModeNotice(process.env, role === 'public' ? 'public' : 'internal')
+  if (modeNotice) console.warn(modeNotice)
 const env = buildServerEnv(process.env, {
     port,
     role: role === 'public' ? 'public' : 'internal',

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.13.0-beta.2",
+  "version": "1.13.0-beta.4",
   "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.13.0-beta.2";
+  var VERSION = "1.13.0-beta.4";
 
   // src/ws-url.ts
   function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
@@ -228,6 +228,29 @@
     return { width: W, height: H };
   }
 
+  // src/dialog-policy.ts
+  var DIALOG_POLICY_VALUES = {
+    alert: ["dismiss", "show"],
+    confirm: ["accept", "dismiss", "show"],
+    prompt: ["dismiss", "show", '{ "response": "text" }'],
+    beforeunload: ["allow", "block"]
+  };
+  function dialogPolicyError(payload2) {
+    if (!payload2)
+      return null;
+    for (const key of ["alert", "confirm", "beforeunload"]) {
+      const v = payload2[key];
+      if (v !== undefined && !DIALOG_POLICY_VALUES[key].includes(v)) {
+        return `dialog ${key} must be one of ${DIALOG_POLICY_VALUES[key].map((x) => `"${x}"`).join(", ")}; got ${JSON.stringify(v)}`;
+      }
+    }
+    const p = payload2.prompt;
+    if (p !== undefined && p !== "dismiss" && p !== "show" && !(p && typeof p === "object" && typeof p.response === "string")) {
+      return `dialog prompt must be "dismiss", "show" or { "response": "text" }; got ${JSON.stringify(p)}`;
+    }
+    return null;
+  }
+
   // src/component.ts
   var VERSION2 = VERSION;
   var PRODUCT_NAME = "Haltija";
@@ -1374,16 +1397,26 @@
         const description = agent.describe();
         const wiring = description?.wiring;
         const shapeWarning = wiring === undefined ? `${globalName}.describe() returned no 'wiring' — this haltija understands the agent ` + `surface as { wiring: [{ tag, id, label, on }] }. The map below is passed through ` + `unchanged and may be missing structure; the schematic will be empty. Check the ` + `tosijs version, or use hj map with the DOM fallback (a page without tosiAgent).` : !Array.isArray(wiring) ? `${globalName}.describe().wiring is ${typeof wiring}, expected an array — passing it ` + `through unchanged, but the schematic cannot render it.` : undefined;
+        const d = description;
+        const surfaceVersion = d?.version ?? agent.version;
+        const surfaceMajor = surfaceVersion && typeof surfaceVersion === "object" && typeof surfaceVersion.surface === "string" ? surfaceVersion.surface.split(".")[0] : null;
+        const versionWarning = surfaceMajor !== null && surfaceMajor !== "1" ? `${globalName} reports agent surface ${surfaceVersion.surface}; this haltija reads surface ` + `1.x, so fields may be missing or misread. Update haltija.` : undefined;
+        const warning = [shapeWarning, versionWarning].filter(Boolean).join(" ") || undefined;
+        const closedHint = d?.exposure === "closed" && Array.isArray(wiring) && wiring.length === 0 ? `The app exposes no wiring: exposure is 'closed', the tosijs default. Its author enables ` + `it with expose: { roots } (add write: true to allow write()). Until then, find controls ` + `with hj tree and drive them with hj click / hj type.` : undefined;
+        const actions = Array.isArray(d?.actions) ? d.actions : undefined;
+        const writeAdvice = d?.writable === false ? `This surface is READ-ONLY (describe().writable is false): ${globalName}.write() will be ` + `refused, so act through actions or realistic input instead.` : d?.writable === true ? `${globalName}.write(path, value) for a ⟷ two-way binding.` : `${globalName}.write(path, value) for a ⟷ two-way binding (writability not reported ` + `by this surface; it may refuse).`;
+        const callAdvice = actions && actions.length === 0 ? `It exposes no actions.` : `${globalName}.call(actionPath) for an action${actions ? ` (one of: ${actions.slice(0, 8).join(", ")}${actions.length > 8 ? ", …" : ""})` : ""}.`;
         return {
           url: location.href,
           title: document.title,
           source: "tosi-agent",
           global: globalName,
-          agentSurfaceVersion: agent.version ?? description?.version,
-          ...shapeWarning ? { warning: shapeWarning } : {},
+          agentSurfaceVersion: surfaceVersion,
+          ...warning ? { warning } : {},
+          ...closedHint ? { hint: closedHint } : {},
           ...description,
           act: {
-            note: `Act through the paths, not synthesized input: ${globalName}.write(path, value) for a ` + `⟷ two-way binding, ${globalName}.call(actionPath) for an action. ` + `Run them with: hj eval "${globalName}.write('some.path', 'value')"`,
+            note: `Act through the paths, not synthesized input. ${writeAdvice} ${callAdvice}` + (actions && actions.length === 0 ? "" : ` Run one with: hj eval "${globalName}.call('some.action')"`),
             legend: {
               "⟷": "two-way binding — user-writable; writing the path updates the UI and app state",
               "⟵": "bound to DOM — display only; it reflects the path, writing the DOM will not stick",
@@ -6455,6 +6488,11 @@ ${elementSummary}${moreText}`;
     handleDialogMessage(msg2) {
       const { action: action2, payload: payload2 } = msg2;
       if (action2 === "configure") {
+        const bad = dialogPolicyError(payload2);
+        if (bad) {
+          this.respond(msg2.id, false, undefined, bad);
+          return;
+        }
         if (payload2.alert !== undefined)
           this.dialogPolicy.alert = payload2.alert;
         if (payload2.confirm !== undefined)
@@ -8669,22 +8707,32 @@ ${elementSummary}${moreText}`;
       this.originalDialogs.confirm = window.confirm.bind(window);
       this.originalDialogs.prompt = window.prompt.bind(window);
       const self = this;
+      const announce = (type, msg2, outcome) => {
+        const info = self.originalConsole.info ?? console.info;
+        const shown = msg2.length > 80 ? msg2.slice(0, 77) + "..." : msg2;
+        info.call(console, `[haltija] intercepted ${type}(${JSON.stringify(shown)}) and ${outcome}: the dev channel answers native dialogs so an agent driving the page is never blocked by one. To show dialogs instead: hj dialog-configure --alert show (or --confirm / --prompt show).`);
+      };
       window.alert = function(message) {
         if (self._inHaltijaUI)
           return self.originalDialogs.alert(message);
         const msg2 = String(message ?? "");
-        const entry = { type: "alert", message: msg2, response: undefined, timestamp: Date.now() };
+        const shown = self.dialogPolicy.alert === "show";
+        const entry = { type: "alert", message: msg2, response: undefined, shown, timestamp: Date.now() };
         self.dialogHistory.push(entry);
         if (self.dialogHistory.length > 50)
           self.dialogHistory = self.dialogHistory.slice(-25);
-        self.send("dialog", "opened", { type: "alert", message: msg2, windowId: self.windowId });
+        self.send("dialog", "opened", { type: "alert", message: msg2, shown, windowId: self.windowId });
+        if (shown)
+          return self.originalDialogs.alert(message);
+        announce("alert", msg2, "did not show it");
       };
       window.confirm = function(message) {
         if (self._inHaltijaUI)
           return self.originalDialogs.confirm(message);
         const msg2 = String(message ?? "");
-        const accept = self.dialogPolicy.confirm === "accept";
-        const entry = { type: "confirm", message: msg2, response: accept, timestamp: Date.now() };
+        const shown = self.dialogPolicy.confirm === "show";
+        const accept = shown ? self.originalDialogs.confirm(message) : self.dialogPolicy.confirm === "accept";
+        const entry = { type: "confirm", message: msg2, response: accept, shown, timestamp: Date.now() };
         self.dialogHistory.push(entry);
         if (self.dialogHistory.length > 50)
           self.dialogHistory = self.dialogHistory.slice(-25);
@@ -8692,8 +8740,12 @@ ${elementSummary}${moreText}`;
           type: "confirm",
           message: msg2,
           response: accept,
+          shown,
           windowId: self.windowId
         });
+        if (shown)
+          return accept;
+        announce("confirm", msg2, `answered ${accept ? "OK" : "Cancel"} without showing it`);
         return accept;
       };
       window.prompt = function(message, defaultValue) {
@@ -8701,8 +8753,9 @@ ${elementSummary}${moreText}`;
           return self.originalDialogs.prompt(message, defaultValue);
         const msg2 = String(message ?? "");
         const policy = self.dialogPolicy.prompt;
-        const response = policy === "dismiss" ? null : policy.response;
-        const entry = { type: "prompt", message: msg2, defaultValue, response, timestamp: Date.now() };
+        const shown = policy === "show";
+        const response = shown ? self.originalDialogs.prompt(message, defaultValue) : policy === "dismiss" ? null : policy.response;
+        const entry = { type: "prompt", message: msg2, defaultValue, response, shown, timestamp: Date.now() };
         self.dialogHistory.push(entry);
         if (self.dialogHistory.length > 50)
           self.dialogHistory = self.dialogHistory.slice(-25);
@@ -8711,8 +8764,12 @@ ${elementSummary}${moreText}`;
           message: msg2,
           defaultValue,
           response,
+          shown,
           windowId: self.windowId
         });
+        if (shown)
+          return response;
+        announce("prompt", msg2, `answered ${response === null ? "Cancel" : JSON.stringify(response)} without showing it`);
         return response;
       };
     }

package/apps/desktop/server-env.js

@@ -40,9 +40,16 @@ var __export = (target, all) => {
 // src/desktop-server-env.ts
 var exports_desktop_server_env = {};
 __export(exports_desktop_server_env, {
-  buildServerEnv: () => buildServerEnv
+  buildServerEnv: () => buildServerEnv,
+  overriddenModeNotice: () => overriddenModeNotice
 });
 module.exports = __toCommonJS(exports_desktop_server_env);
+function overriddenModeNotice(base, role) {
+  const asked = base.DEV_CHANNEL_MODE?.trim();
+  if (role !== "public" || !asked || asked.toLowerCase() === "both")
+    return null;
+  return `[haltija] ignoring DEV_CHANNEL_MODE=${asked} for the desktop app's public server: it serves ` + `HTTP and HTTPS ('both'), because it serves other projects' pages too and one project's ` + `transport choice would decide for all of them whether https:// pages can connect (#32). For a ` + `single-transport server of your own, run \`haltija --server\` with that mode instead.`;
+}
 function buildServerEnv(base, opts) {
   const port = String(opts.port);
   const env = {};

package/bin/cli-commands.mjs

@@ -47,6 +47,8 @@ var ROUTED_COMMANDS = [
   "network-watch",
   "network-unwatch",
   "network-stats",
+  "dialog-configure",
+  "dialog-history",
   "recording",
   "recording-start",
   "recording-stop",

package/bin/cli-subcommand.mjs

@@ -112,12 +112,14 @@ export const COMPOUND_PATHS = {
   'network-watch': '/network/watch',
   'network-unwatch': '/network/unwatch',
   'network-stats': '/network/stats',
+  'dialog-configure': '/dialog/configure',
+  'dialog-history': '/dialog/history',
 }
 
 // GET compound endpoints
 export const GET_COMPOUND = new Set([
   'mutations-status', 'events-stats', 'select-status', 'select-result', 'video-status',
-  'network-stats'
+  'network-stats', 'dialog-history'
 ])
 
 // How to map positional args to body fields for each endpoint
@@ -344,6 +346,14 @@ export const ARG_MAPS = {
     return body
   },
   'video-stop': () => ({}),
+  // `--prompt` takes "dismiss", "show", or the text to answer with — any other word is the answer.
+  'dialog-configure': (args) => {
+    const { flags } = takeFlags(args, { '--alert': 'str', '--confirm': 'str', '--prompt': 'str', '--beforeunload': 'str' })
+    if (typeof flags.prompt === 'string' && flags.prompt !== 'dismiss' && flags.prompt !== 'show') {
+      flags.prompt = { response: flags.prompt }
+    }
+    return flags
+  },
   'events-watch': (args) => ({ preset: presetArg(args, 'interactive') }),
   // These two had the ORIGINAL args[0] bug still in them, one line below the comment describing the
   // fix — `hj mutations-watch --preset smart` sent preset:'--preset', `FILTER_PRESETS[preset]` came
@@ -952,6 +962,7 @@ export const KNOWN_FLAGS = {
   refresh: ['--soft', '--no-wait', '--timeout'],
   navigate: ['--no-wait', '--timeout'],
   'test-run': ['--vars', '--seed', '--timeoutMs', '--allow-failures', '--allow-failures-streak', '--step-delay'],
+  'dialog-configure': ['--alert', '--confirm', '--prompt', '--beforeunload'],
   'test-validate': ['--vars', '--seed', '--timeoutMs', '--allow-failures', '--allow-failures-streak', '--step-delay'],
   'test-suite': ['--vars', '--seed', '--timeoutMs', '--allow-failures', '--allow-failures-streak', '--step-delay'],
   // Added after an invariant test derived them from the parsers themselves. Missing entries are
@@ -1623,6 +1634,8 @@ export function listSubcommands() {
     refresh [--soft] [--no-wait]      Reload page; waits for it to come back
     tabs ${dim('open|close|focus')}            Tab management (default: list)
     eval <code>                       Run JS in browser
+    dialog-configure --alert show     Let alert/confirm/prompt reach a person (default: answered)
+    dialog-history                    Dialogs the page opened, and how each was answered
 
   ${bold('Test')}
     test ${dim('run|suite|validate')} <file>   Run tests (default: run)

package/bin/hj.mjs

@@ -79,7 +79,7 @@ function describeOrigins(windows) {
     return { line: yellow(msg), problem: msg }
   }
   const list = declared.origins.join(', ')
-  const routing = routeByDeclaredOrigin(declared.origins, windows || [], null)
+  const routing = routeByDeclaredOrigin(declared.origins, windows || [], (windows || []).find((w) => w.focused)?.id ?? null)
   if (routing.kind === 'matched') {
     return { line: `${list} ${dim(`(${declared.source}) → window ${routing.windowId}`)}`, problem: null }
   }
@@ -331,6 +331,11 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
   // this command exists to remove.
   const unchecked = []
   let status = null
+  // First-class answer to "can I believe what this tab tells me?" (#821, GitHub #50). Everything
+  // else doctor checks is about reaching a tab; this is about whether its answers are trustworthy.
+  // A hidden or non-compositing tab still answers — geometry, screenshots and anything rAF-driven
+  // just come back wrong — so it is printed on every run, not only when something fails.
+  let observability = null
 
   try {
     const resp = await fetch(`http://localhost:${port}/status`, {
@@ -365,6 +370,25 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
     // Reads `active` via the shared predicate: /status and /windows disagreed on polarity, and
     // keying on one endpoint's field name is what made this diverge from the origin router.
     const hidden = tabs.filter((w) => !isVisible(w))
+    // The tab commands go to, resolved the way a command resolves it. Judging visibility over ALL
+    // tabs passed a lane whose target was hidden as long as some OTHER tab was visible — every
+    // command still went to the hidden one.
+    //
+    // A project with declared origins has its commands PINNED to the matching tab, wherever focus
+    // is. The first version of this looked only at focus, so for exactly the projects that
+    // declared their tabs it described another project's tab: a false pass when ours was hidden
+    // behind their visible one, a false failure the other way round (1.13.0-beta.3 review).
+    const focusedTab = tabs.find((w) => w.focused) ?? null
+    const declaredOrigins = findProjectOrigins(process.cwd(), process.env)
+    const routed = declaredOrigins?.origins.length
+      ? routeByDeclaredOrigin(declaredOrigins.origins, tabs, focusedTab?.id ?? null)
+      : null
+    const pinned = routed?.kind === 'matched' ? tabs.find((w) => w.id === routed.windowId) ?? null : null
+    // Unpinned, it is whatever the server says it would target (#3123); the local fallback is only
+    // for servers older than 1.13.0-beta.4, which don't report it.
+    const serverTarget = status.targetWindowId ? tabs.find((w) => w.id === status.targetWindowId) ?? null : null
+    const target = pinned ?? serverTarget ?? focusedTab ?? tabs.find((w) => isVisible(w)) ?? tabs[0] ?? null
+    const targetLabel = target ? `${target.title && target.title !== '(untitled)' ? `"${target.title}" ` : ''}${target.url || target.id}` : ''
     // A tab that reported NEITHER field hasn't told us anything; `isVisible` had to assume. Say so
     // rather than counting the assumption as a passed check.
     const silent = tabs.filter((w) => !visibilityKnown(w))
@@ -378,14 +402,16 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
           `Upgrade the server to make this checkable.`,
       )
     }
-    if (ready && hidden.length === tabs.length) {
+    if (ready && target && !isVisible(target)) {
       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.`,
+        `the tab commands go to (${targetLabel}) reports HIDDEN — it still answers, but geometry, ` +
+          `screenshots and anything rAF-driven WILL be wrong (timers and rendering are throttled). ` +
+          `Bring it to the front, or target a visible tab with --window <id>.`,
       )
     } else if (hidden.length) {
       notes.push(`${hidden.length} of ${tabs.length} tab(s) are hidden; commands targeting them may return stale results`)
     }
+    if (ready && target) observability = { target: target.id, label: targetLabel, visible: isVisible(target), painting: null, paintAgeMs: null }
     if (status.serverVersion && differsBeyondPatch(HJ_VERSION, status.serverVersion)) {
       notes.push(`hj ${HJ_VERSION} is driving server ${status.serverVersion} (version skew)`)
     }
@@ -413,7 +439,8 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
         // socket that never answers `/eval` (a widget mid-teardown, or a test harness holding an
         // open WebSocket) made `hj doctor` block for the server's full browser timeout.
         const cancel = AbortSignal.timeout(3000)
-        const r = await fetch(`http://localhost:${port}/eval`, {
+        // Asked of the TARGET tab. Untargeted, it measured whichever tab had focus.
+        const r = await fetch(`http://localhost:${port}/eval${target ? `?window=${encodeURIComponent(target.id)}` : ''}`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json', ...(token ? { 'X-Haltija-Token': token } : {}) },
           body: JSON.stringify({ code: probe }),
@@ -435,6 +462,10 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
       } catch {
         // Fall through to the unchecked branch — never a pass.
       }
+      if (observability && raf !== null) {
+        observability.painting = !!raf.fired
+        observability.paintAgeMs = raf.measured ? raf.ms : null
+      }
       if (raf === null) {
         unchecked.push(
           `could not run the requestAnimationFrame probe — whether this tab actually paints is ` +
@@ -484,6 +515,7 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
       ready: status ? (typeof status.ready === 'boolean' ? status.ready : (status.windows?.length ?? 0) > 0) : false,
       tabs: status?.windows?.length ?? 0,
       problems, notes,
+      observability,
       origins: (() => {
         const d = findProjectOrigins(process.cwd(), process.env)
         return d ? { declared: d.origins, source: d.source } : null
@@ -501,6 +533,7 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
     console.log(`${bold('server:')} haltija ${status.serverVersion || '?'}${status.desktopApp ? dim(' (desktop app)') : ''}, ${tabCount} tab${tabCount === 1 ? '' : 's'}`)
   }
   if (status) console.log(`${bold('origins:')} ${describeOrigins(status.windows || []).line}`)
+  if (observability) console.log(`${bold('observability:')} ${describeObservability(observability)}`)
   for (const n of notes) console.log(`${yellow('!')} ${n}`)
   // `?` — its own glyph, because the whole point is that this is neither a pass nor a failure.
   for (const u of unchecked) console.log(`${dim('?')} ${u}`)
@@ -517,6 +550,20 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
   return ok
 }
 
+/**
+ * The `observability:` line: whether the tab commands go to will tell the truth (#821). Says what a
+ * bad state invalidates rather than only naming the state — the recorded failures were agents who
+ * knew a tab was "hidden" and still trusted its geometry.
+ */
+function describeObservability(o) {
+  const where = dim(`(${o.label})`)
+  if (!o.visible) return `${red('✗ hidden')} — geometry, screenshots and rAF-driven rendering will be wrong ${where}`
+  if (o.painting === false) return `${red('✗ not painting')} — visible but not compositing; missing elements prove nothing ${where}`
+  if (o.painting === null) return `${dim('? visible, painting unknown')} ${where}`
+  const age = o.paintAgeMs === null ? '' : dim(` (last frame ${(o.paintAgeMs / 1000).toFixed(1)}s ago)`)
+  return `${green('✓ visible and painting')}${age} ${where}`
+}
+
 /**
  * Resolve a named haltija instance to its port by reading
  * ~/.haltija/servers/<name>.json. Returns null if the file is missing,

package/bin/mcp-locate.mjs

@@ -0,0 +1,33 @@
+/**
+ * Where the MCP server is, and the command an MCP client should run to start it. ONE copy, used by
+ * both setup paths (`haltija --setup-mcp` for Claude Desktop, `haltija-mcp-setup` for Claude Code).
+ * They had a finder each, both looking for `apps/mcp/build/index.js`, which the npm package never
+ * contained — so setup failed for every npm user (GitHub #47).
+ *
+ * The server is `dist/mcp.js`, a single bundle with its dependencies inlined: npm never installs a
+ * nested package's dependencies, so an unbundled server could not have imported its SDK.
+ */
+import { existsSync, readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** Absolute path of the bundled MCP server in this package, or null (a checkout that never built). */
+export function mcpServerPath(root = PACKAGE_ROOT) {
+  const p = join(root, 'dist', 'mcp.js')
+  return existsSync(p) ? p : null
+}
+
+/**
+ * The `{ command, args }` an MCP client config should hold. A package run through `npx` / `bunx`
+ * lives in a cache that gets cleaned, so an absolute path there works today and breaks later with
+ * nothing to say why; those get the version-pinned `npx` form instead.
+ */
+export function mcpServerCommand(serverPath, root = PACKAGE_ROOT) {
+  if (/[\\/](_npx|bunx-[^\\/]*|\.bun[\\/]install[\\/]cache)[\\/]/.test(serverPath)) {
+    const { version } = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+    return { command: 'npx', args: ['-y', '-p', `haltija@${version}`, 'haltija-mcp'] }
+  }
+  return { command: 'node', args: [serverPath] }
+}