haltija 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 1.5.2
+
+Two follow-ups from the 1.5.0 review, both about the multi-tab experience on a shared server.
+
+### Fixed
+
+- **`hj tabs focus <id>` no longer times out** ([#4](https://github.com/tonioloewald/haltija/issues/4)).
+  It was dispatching a `focus` command to the browser, routed to the *focused* tab rather than the
+  target, so nobody answered — and even routed correctly, a backgrounded tab can't raise itself.
+  Focus is now a **server-side** routing change: it validates the tab and points untargeted commands
+  at it, returning instantly (unknown tab → a clean error, never a timeout). It does not physically
+  raise the tab; to pin a single command use `--window <id>`. "Focus follows the visible tab" still
+  applies when you physically switch tabs — that's genuine intent that should win over a stale pin.
+
+### Changed
+
+- **The hidden-tab / focus-ambiguity warnings are de-duplicated within a short (15s) cooldown**, so
+  a burst of commands from one agent doesn't repeat the same block every time. A *changed* condition
+  (different tab, newly-hidden tab, a new origin on the server) always re-warns; the cooldown
+  re-arms rather than suppressing forever. Set `HALTIJA_NO_TAB_WARN=1` to silence them entirely.
+
+## 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

package/apps/desktop/main.js

@@ -1350,7 +1350,12 @@ async function startEmbeddedServer() {
     }
     const pubPort = await readPort(pubFile)
     const intPort = await readPort(intFile)
-    if (!pubPort) { console.error('[Haltija Desktop] Private public server did not report its port'); return false }
+    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}`

package/apps/desktop/package.json

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

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.5.0";
+  var VERSION = "1.5.2";
 
   // 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/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'
@@ -313,12 +314,11 @@ if (noLaunchIdx !== -1) {
 // 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.
-let windowTarget = null
-const windowIdx = args.indexOf('--window')
-if (windowIdx !== -1 && args[windowIdx + 1]) {
-  windowTarget = args[windowIdx + 1]
-  args.splice(windowIdx, 2)
-}
+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

package/bin/tosijs-dev.mjs

@@ -88,6 +88,7 @@ Environment Variables:
   HALTIJA_NO_RETIRE        Set to 1: do not stop pre-1.4.0 haltija servers
   HALTIJA_NO_INSTALL       Set to 1: do not install hj into ~/.local/bin
   HALTIJA_NO_SKEW_WARN     Set to 1: silence hj's version-skew warning
+  HALTIJA_NO_TAB_WARN      Set to 1: silence hidden-tab / focus-ambiguity result warnings
   HALTIJA_REGISTRY_DIR     Instance registry location (default: ~/.haltija/servers)
   DEV_CHANNEL_PORT         Legacy alias for HALTIJA_PORT
   DEV_CHANNEL_HTTPS_PORT   HTTPS port (default: 8701)

package/bin/version.mjs

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

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>;
@@ -50,6 +52,18 @@ export interface HandlerContext {
     headers: Record<string, string>;
     url: URL;
     getWindowInfo: (windowId?: string) => WindowInfo | undefined;
+    /**
+     * Set the server-side focused window — the tab that receives untargeted commands. This is pure
+     * server state, NOT a browser roundtrip: it validates the tab exists and returns immediately, so
+     * it can never time out the way dispatching a command *to* the (possibly hidden) tab does (#4).
+     */
+    focusWindow: (windowId: string) => {
+        ok: boolean;
+        error?: string;
+        active?: boolean;
+        windowType?: string;
+        title?: string;
+    };
     startRecordingSession: (windowId: string, url: string, name?: string) => void;
     stopRecordingSession: (windowId: string) => RecordingSessionInfo | undefined;
     getRecordingSession: (windowId: string) => RecordingSessionInfo | undefined;

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.5.0";
+export declare const VERSION = "1.5.2";
 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.5.0";
+var VERSION = "1.5.2";
 
 // 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.5.0";
+  var VERSION = "1.5.2";
 
   // 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.5.0
+// haltija-cli:do-not-edit v1.5.2
 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.5.0";
+var HJ_VERSION = "1.5.2";
 
 // bin/semver.mjs
 function parseVersion(v) {
@@ -1906,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";
@@ -2137,12 +2148,9 @@ if (noLaunchIdx !== -1) {
   noLaunch = true;
   args.splice(noLaunchIdx, 1);
 }
-var windowTarget = null;
-var windowIdx = args.indexOf("--window");
-if (windowIdx !== -1 && args[windowIdx + 1]) {
-  windowTarget = args[windowIdx + 1];
-  args.splice(windowIdx, 2);
-}
+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]}`);

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.5.0";
+var VERSION = "1.5.2";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2224,11 +2224,15 @@ Get window IDs from /windows endpoint.
 
 ### \`POST /tabs/focus\`
 
-**Focus a tab**
+**Focus a tab (route untargeted commands to it)**
 
-Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.
+Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.
 
 **Parameters:**
 
@@ -2238,7 +2242,7 @@ Useful when working with multiple tabs to ensure the right one is visible.
 
 **Examples:**
 
-- **focus**: Bring tab to front
+- **focus**: Route untargeted commands to this tab
   \`\`\`json
   {"window":"window-abc123"}
   \`\`\`
@@ -2802,7 +2806,7 @@ hj --help              # All commands
 - \`hj windows\` - List connected windows
 - \`hj tabs-open [url]\` - Open a new tab
 - \`hj tabs-close [window]\` - Close a tab
-- \`hj tabs-focus [window]\` - Focus a tab
+- \`hj tabs-focus [window]\` - Focus a tab (route untargeted commands to it)
 
 ### Record & Replay
 
@@ -3097,7 +3101,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.0";
+  var VERSION = "1.5.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -12857,10 +12861,14 @@ Get window IDs from /windows endpoint.`,
 var tabsFocus = endpoint({
   path: "/tabs/focus",
   method: "POST",
-  summary: "Focus a tab",
-  description: `Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.`,
+  summary: "Focus a tab (route untargeted commands to it)",
+  description: `Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.`,
   category: "windows",
   input: L.object({
     window: L.string.describe("Window ID to focus")
@@ -12869,7 +12877,7 @@ Useful when working with multiple tabs to ensure the right one is visible.`,
     {
       name: "focus",
       input: { window: "window-abc123" },
-      description: "Bring tab to front"
+      description: "Route untargeted commands to this tab"
     }
   ],
   hints: "<window-id> | see: windows, tabs-close, tabs-open"
@@ -13727,6 +13735,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);
@@ -14249,10 +14260,19 @@ registerHandler(tabsClose, async (body, ctx) => {
 registerHandler(tabsFocus, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   if (!windowId) {
-    return Response.json({ success: false, error: "window id is required" }, { status: 400, headers: ctx.headers });
+    return Response.json({ success: false, error: "window id is required (run `hj tabs` to list connected tabs)" }, { status: 400, headers: ctx.headers });
   }
-  const response = await ctx.requestFromBrowser("tabs", "focus", { windowId });
-  return Response.json(response, { headers: ctx.headers });
+  const r = ctx.focusWindow(windowId);
+  if (!r.ok) {
+    return Response.json({ success: false, error: r.error }, { status: 404, headers: ctx.headers });
+  }
+  const result = { success: true, focused: windowId, active: r.active !== false };
+  if (r.title)
+    result.title = r.title;
+  if (r.active === false) {
+    result.warning = "Untargeted commands now route to this tab, but it reports HIDDEN \u2014 browsers freeze " + "requestAnimationFrame and throttle timers in a backgrounded tab, so results can be stale " + '("not mounted yet", not "broken"). Bring it to the front in your browser to wake it.';
+  }
+  return Response.json(result, { headers: ctx.headers });
 });
 registerHandler(mutationsWatch, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("mutations", "watch", {
@@ -14557,7 +14577,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 +14683,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 });
 });
@@ -15272,6 +15292,22 @@ function ambiguousFocusWarning(opts) {
 ${pins}${more}`;
 }
 
+// src/warning-dedupe.ts
+function shouldEmitWarning(warning, cache, now, cooldownMs) {
+  const last = cache.get(warning);
+  if (last !== undefined && now - last < cooldownMs) {
+    return false;
+  }
+  cache.set(warning, now);
+  if (cache.size > 64) {
+    for (const [key2, ts] of cache) {
+      if (now - ts >= cooldownMs)
+        cache.delete(key2);
+    }
+  }
+  return true;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16126,6 +16162,9 @@ function getComponentJs() {
 }
 var browsers = new Map;
 var windows2 = new Map;
+var recentTabWarnings = new Map;
+var TAB_WARN_COOLDOWN_MS = 15000;
+var TAB_WARN_DISABLED = process.env.HALTIJA_NO_TAB_WARN === "1";
 var agents = new Set;
 var focusedWindowId = null;
 var isDesktopApp = process.env.HALTIJA_DESKTOP === "1";
@@ -16438,12 +16477,10 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
     source: "agent"
   };
   return new Promise((resolve) => {
-    const timeout = setTimeout(() => {
-      pendingResponses.delete(id);
-      resolve({ id, success: false, error: "Timeout", timestamp: Date.now() });
-    }, timeoutMs);
     let sentTo = null;
-    const resolveWithLiveness = (res) => {
+    const attachWarning = (res) => {
+      if (TAB_WARN_DISABLED)
+        return res;
       const hidden = hiddenTabWarning(sentTo);
       const ambiguous = ambiguousFocusWarning({
         windows: Array.from(windows2.values()),
@@ -16453,8 +16490,18 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       const warning = [hidden, ambiguous].filter(Boolean).join(`
 
 `);
-      resolve(warning ? { ...res, warning } : res);
+      if (!warning)
+        return res;
+      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
+        return res;
+      }
+      return { ...res, warning };
     };
+    const timeout = setTimeout(() => {
+      pendingResponses.delete(id);
+      resolve(attachWarning({ id, success: false, error: "Timeout", timestamp: Date.now() }));
+    }, timeoutMs);
+    const resolveWithLiveness = (res) => resolve(attachWarning(res));
     pendingResponses.set(id, { resolve: resolveWithLiveness, timeout });
     if (windowId) {
       const win = windows2.get(windowId);
@@ -16619,6 +16666,15 @@ var createHandlerContext = (req, url) => {
     headers,
     url,
     getWindowInfo,
+    focusWindow: (windowId) => {
+      const win = windows2.get(windowId);
+      if (!win) {
+        return { ok: false, error: `Tab ${windowId} not found (run \`hj tabs\` to list connected tabs)` };
+      }
+      focusedWindowId = windowId;
+      updateHjStatus();
+      return { ok: true, active: win.active, windowType: win.windowType, title: win.title };
+    },
     startRecordingSession,
     stopRecordingSession,
     getRecordingSession,
@@ -18296,12 +18352,10 @@ Type 'help <topic>' for details.`);
             break;
           }
           case "tabs-focus": {
-            const resp = await requestFromBrowser("tabs", "focus", { windowId: step.window }, stepTimeout);
-            if (!resp.success) {
+            if (!step.window || !windows2.has(step.window)) {
               stepPassed = false;
-              error = resp.error || "Failed to focus tab";
-            }
-            if (step.window && windows2.has(step.window)) {
+              error = `Tab ${step.window ?? "(none)"} not found`;
+            } else {
               focusedWindowId = step.window;
             }
             break;

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.5.0";
+var VERSION = "1.5.2";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2224,11 +2224,15 @@ Get window IDs from /windows endpoint.
 
 ### \`POST /tabs/focus\`
 
-**Focus a tab**
+**Focus a tab (route untargeted commands to it)**
 
-Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.
+Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.
 
 **Parameters:**
 
@@ -2238,7 +2242,7 @@ Useful when working with multiple tabs to ensure the right one is visible.
 
 **Examples:**
 
-- **focus**: Bring tab to front
+- **focus**: Route untargeted commands to this tab
   \`\`\`json
   {"window":"window-abc123"}
   \`\`\`
@@ -2802,7 +2806,7 @@ hj --help              # All commands
 - \`hj windows\` - List connected windows
 - \`hj tabs-open [url]\` - Open a new tab
 - \`hj tabs-close [window]\` - Close a tab
-- \`hj tabs-focus [window]\` - Focus a tab
+- \`hj tabs-focus [window]\` - Focus a tab (route untargeted commands to it)
 
 ### Record & Replay
 
@@ -3097,7 +3101,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.0";
+  var VERSION = "1.5.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -12857,10 +12861,14 @@ Get window IDs from /windows endpoint.`,
 var tabsFocus = endpoint({
   path: "/tabs/focus",
   method: "POST",
-  summary: "Focus a tab",
-  description: `Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.`,
+  summary: "Focus a tab (route untargeted commands to it)",
+  description: `Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.`,
   category: "windows",
   input: L.object({
     window: L.string.describe("Window ID to focus")
@@ -12869,7 +12877,7 @@ Useful when working with multiple tabs to ensure the right one is visible.`,
     {
       name: "focus",
       input: { window: "window-abc123" },
-      description: "Bring tab to front"
+      description: "Route untargeted commands to this tab"
     }
   ],
   hints: "<window-id> | see: windows, tabs-close, tabs-open"
@@ -13727,6 +13735,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);
@@ -14249,10 +14260,19 @@ registerHandler(tabsClose, async (body, ctx) => {
 registerHandler(tabsFocus, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   if (!windowId) {
-    return Response.json({ success: false, error: "window id is required" }, { status: 400, headers: ctx.headers });
+    return Response.json({ success: false, error: "window id is required (run `hj tabs` to list connected tabs)" }, { status: 400, headers: ctx.headers });
   }
-  const response = await ctx.requestFromBrowser("tabs", "focus", { windowId });
-  return Response.json(response, { headers: ctx.headers });
+  const r = ctx.focusWindow(windowId);
+  if (!r.ok) {
+    return Response.json({ success: false, error: r.error }, { status: 404, headers: ctx.headers });
+  }
+  const result = { success: true, focused: windowId, active: r.active !== false };
+  if (r.title)
+    result.title = r.title;
+  if (r.active === false) {
+    result.warning = "Untargeted commands now route to this tab, but it reports HIDDEN \u2014 browsers freeze " + "requestAnimationFrame and throttle timers in a backgrounded tab, so results can be stale " + '("not mounted yet", not "broken"). Bring it to the front in your browser to wake it.';
+  }
+  return Response.json(result, { headers: ctx.headers });
 });
 registerHandler(mutationsWatch, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("mutations", "watch", {
@@ -14557,7 +14577,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 +14683,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 });
 });
@@ -15272,6 +15292,22 @@ function ambiguousFocusWarning(opts) {
 ${pins}${more}`;
 }
 
+// src/warning-dedupe.ts
+function shouldEmitWarning(warning, cache, now, cooldownMs) {
+  const last = cache.get(warning);
+  if (last !== undefined && now - last < cooldownMs) {
+    return false;
+  }
+  cache.set(warning, now);
+  if (cache.size > 64) {
+    for (const [key2, ts] of cache) {
+      if (now - ts >= cooldownMs)
+        cache.delete(key2);
+    }
+  }
+  return true;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16126,6 +16162,9 @@ function getComponentJs() {
 }
 var browsers = new Map;
 var windows2 = new Map;
+var recentTabWarnings = new Map;
+var TAB_WARN_COOLDOWN_MS = 15000;
+var TAB_WARN_DISABLED = process.env.HALTIJA_NO_TAB_WARN === "1";
 var agents = new Set;
 var focusedWindowId = null;
 var isDesktopApp = process.env.HALTIJA_DESKTOP === "1";
@@ -16438,12 +16477,10 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
     source: "agent"
   };
   return new Promise((resolve) => {
-    const timeout = setTimeout(() => {
-      pendingResponses.delete(id);
-      resolve({ id, success: false, error: "Timeout", timestamp: Date.now() });
-    }, timeoutMs);
     let sentTo = null;
-    const resolveWithLiveness = (res) => {
+    const attachWarning = (res) => {
+      if (TAB_WARN_DISABLED)
+        return res;
       const hidden = hiddenTabWarning(sentTo);
       const ambiguous = ambiguousFocusWarning({
         windows: Array.from(windows2.values()),
@@ -16453,8 +16490,18 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       const warning = [hidden, ambiguous].filter(Boolean).join(`
 
 `);
-      resolve(warning ? { ...res, warning } : res);
+      if (!warning)
+        return res;
+      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
+        return res;
+      }
+      return { ...res, warning };
     };
+    const timeout = setTimeout(() => {
+      pendingResponses.delete(id);
+      resolve(attachWarning({ id, success: false, error: "Timeout", timestamp: Date.now() }));
+    }, timeoutMs);
+    const resolveWithLiveness = (res) => resolve(attachWarning(res));
     pendingResponses.set(id, { resolve: resolveWithLiveness, timeout });
     if (windowId) {
       const win = windows2.get(windowId);
@@ -16619,6 +16666,15 @@ var createHandlerContext = (req, url) => {
     headers,
     url,
     getWindowInfo,
+    focusWindow: (windowId) => {
+      const win = windows2.get(windowId);
+      if (!win) {
+        return { ok: false, error: `Tab ${windowId} not found (run \`hj tabs\` to list connected tabs)` };
+      }
+      focusedWindowId = windowId;
+      updateHjStatus();
+      return { ok: true, active: win.active, windowType: win.windowType, title: win.title };
+    },
     startRecordingSession,
     stopRecordingSession,
     getRecordingSession,
@@ -18296,12 +18352,10 @@ Type 'help <topic>' for details.`);
             break;
           }
           case "tabs-focus": {
-            const resp = await requestFromBrowser("tabs", "focus", { windowId: step.window }, stepTimeout);
-            if (!resp.success) {
+            if (!step.window || !windows2.has(step.window)) {
               stepPassed = false;
-              error = resp.error || "Failed to focus tab";
-            }
-            if (step.window && windows2.has(step.window)) {
+              error = `Tab ${step.window ?? "(none)"} not found`;
+            } else {
               focusedWindowId = step.window;
             }
             break;

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.5.0";
+export declare const VERSION = "1.5.2";

package/dist/warning-dedupe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * De-duplicate the tab warnings (hidden-tab #3, focus-ambiguity #2) so a burst of untargeted
+ * commands from one agent doesn't repeat the same multi-line block on every single one. That
+ * repetition is the alarm-fatigue the repo's own skew-warning rationale warns about: a caveat that
+ * fires on every command trains agents to ignore it, including the time it matters.
+ *
+ * **Why a short cooldown and not "once, forever":** the server has many clients and can't tell them
+ * apart, so a permanent global suppression would hide the warning from a *second* agent that never
+ * saw it — the exact "plausible-but-wrong answer with no caveat" failure these warnings exist to
+ * prevent. A short cooldown collapses the one-agent burst (the real fatigue source) while keeping
+ * the window in which another client could miss it tiny; the condition persists, so their next
+ * command past the cooldown re-warns.
+ *
+ * **Why key on the whole warning string:** the text already encodes the full condition — which tab
+ * answered, whether it's hidden, the exact set of other origins. So a *changed* situation (a
+ * different tab, a newly-hidden tab, a new origin on the server) produces different text and is
+ * never suppressed. Identical text means identical situation.
+ */
+export declare function shouldEmitWarning(warning: string, cache: Map<string, number>, now: number, cooldownMs: number): boolean;

package/package.json

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