haltija 1.12.5 → 1.12.6

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 1.12.6
+
+Security updates, three silent-failure fixes in the path from "server tells page how to reach me",
+a new way to watch — and talk to — the agent driving your browser, and both halves of the
+shared-browser trade: instances that never died, and tabs that answer while asleep.
+
+### Security
+
+- **Electron 40.6.1 → 43.4.1.** 40.6.1 sat inside the range for **two context-isolation bypasses**,
+  and context isolation is haltija's security boundary — the desktop app strips CSP and injects into
+  arbitrary pages. One bump clears eight advisories.
+- **`apps/mcp` re-locked** off a cross-client data leak in `@modelcontextprotocol/sdk` 1.25.2
+  (→ 1.30.0), plus `hono`, `@hono/node-server` and `fast-uri`.
+- **`electron-builder` is no longer a dependency.** It was pulling **271 transitive packages** into
+  `apps/desktop` — 285 before, 14 after — and supplied five advisories including a critical `tar`
+  one, all for DMG packaging nothing exercises. The `build:*` scripts invoke it on demand instead.
+
+### Three ways the page could not reach the server, all silent
+
+Each of these ended with no widget, `hj where` reporting `0 tabs`, and the reasonable conclusion
+that your own setup was wrong.
+
+- **Access over LAN or Bonjour never worked.** `/inject.js` and `/dev.js` handed the browser URLs
+  built as `localhost:<port>` — and `localhost` in a served script means the *browser's* machine. A
+  page opened from another device was told to connect to itself. Both now derive the host from the
+  request, which is exactly "how the client reached us", so LAN hostnames, `.local` names, fixed IPs
+  and tunnels all work. The generated embed snippet had the same bug and now uses
+  `location.hostname`.
+- **Server-side recording was broken for every `wss://` configuration**, including ordinary HTTPS
+  localhost. `"wss://host/…".replace("ws:", "http:")` is a no-op — the substring is `wss:` — so the
+  derived URL stayed `wss://`, which `fetch` cannot use. Three places derived an HTTP base from a WS
+  URL and two were wrong; there is one function now.
+- **The widget never sent its token.** Eight `fetch` call sites, zero `X-Haltija-Token`, so on a
+  `--token` server every page-side feature returned 401. That made "require a token" and "the page
+  can talk to the server" mutually exclusive — which matters most over a tunnel, exactly where a
+  token matters most.
+
+### Two halves of the shared-browser trade (#39, #41)
+
+Moving to shared tabs and servers stopped per-run Electron instances proliferating and stopped a
+launch killing a peer's channel. It also swapped in two problems, reported together.
+
+- **A `--private` instance now has a lifetime bound.** It exits after 8h with no client activity,
+  saying why on the way out — an instance that vanishes silently is indistinguishable from a crash.
+  The only previous bound was spawner-pid polling, which cannot help when teardown never *runs*: a
+  SIGKILLed session, a sleeping laptop, a crashed harness. #39 found one twelve days old at 5.7 GB
+  and ~150% CPU on a machine at load average 212, with the slowdown blamed on unrelated code.
+  Shared servers stay unbounded — their stickiness is the feature. `HALTIJA_IDLE_TIMEOUT_HOURS`
+  overrides in both directions; `0` disables.
+
+  Polling does **not** count as activity. The desktop app's own renderer hits `/status` every five
+  seconds forever, so under the obvious implementation a `--private --app` instance would have
+  refreshed its idle clock from its own UI and never expired — leaving exactly the configuration
+  #39 reported as the one case still immune.
+
+- **A tab can report `visible` and not be painting, and now says so.** `visibilityState` means "is
+  this tab selected", not "is it being composited"; they diverge for occluded windows, offscreen
+  windows and a sleeping display. In that gap the tab answers confidently about content that never
+  rendered, and a screenshot shows a stale frame the compositor is holding. Every result now carries
+  `paintAgeMs`, and a stale one attaches a warning naming the cause. `hj doctor` reads the same
+  number rather than keeping its own opinion.
+
+  Not fixed: getting a foreground window cheaply, which is what #41 actually asks for. That needs a
+  shape decision and is tracked in `TODO.md`.
+
+### `hj session` — watch the agent, and talk back
+
+```bash
+hj session attach <tmux-session>   # opt in (read-only)
+hj session read --follow           # watch it work
+hj session write "this is wrong"   # needs --allow-input at attach
+```
+
+Mirrors an agent running in tmux into the browser channel, so a **page** — including one on a VR
+headset over a tunnel — can watch the agent work and say something to it. `capture-pane` returns
+already-rendered text, so the page view is a `<pre>` rather than a terminal emulator, and tmux can
+attach to a session that is **already running**.
+
+Writing uses `send-keys`, so your sentence arrives on the agent's stdin as a normal turn — no queue,
+no message API, no polling primitive.
+
+**Reading and writing are separate grants**, because they are different risks: reading leaks what the
+agent *prints*, writing decides what the agent *does* — including answering a permission prompt,
+where this is indistinguishable from the operator typing. A mirror attached for watching refuses
+writes; detaching revokes the grant. Attaching an **unauthenticated** server warns, because a mirror
+turns "can reach this port" into "can read everything the agent prints".
+
 ## 1.12.5
 
 **Installing this delivers 1.12.3 and 1.12.4 as well** — both were tagged but never published, so

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.12.5",
+  "version": "1.12.6",
   "private": true,
   "description": "Haltija Desktop - God Mode Browser for AI Agents",
   "homepage": "https://github.com/tonioloewald/haltija",
@@ -18,15 +18,14 @@
     "compile:server": "cd ../.. && bun run build && bun build --compile --target=bun-darwin-arm64 src/server.ts --outfile apps/desktop/resources/haltija-server-arm64 && bun build --compile --target=bun-darwin-x64 src/server.ts --outfile apps/desktop/resources/haltija-server-x64 && cp dist/component.js apps/desktop/resources/component.js && cp haltija-icon.svg apps/desktop/resources/icon.svg",
     "compile:server:win": "cd ../.. && bun build --compile --target=bun-windows-x64 src/server.ts --outfile apps/desktop/resources/haltija-server-x64.exe",
     "compile:server:linux": "cd ../.. && bun build --compile --target=bun-linux-x64 src/server.ts --outfile apps/desktop/resources/haltija-server-x64 && bun build --compile --target=bun-linux-arm64 src/server.ts --outfile apps/desktop/resources/haltija-server-arm64",
-    "build": "electron-builder",
-    "build:mac": "npm run sync-version && npm run icons && npm run compile:server && electron-builder --mac",
-    "build:win": "npm run sync-version && npm run compile:server:win && electron-builder --win",
-    "build:linux": "npm run sync-version && npm run compile:server:linux && electron-builder --linux"
+    "build": "npx --yes electron-builder@26",
+    "build:mac": "npm run sync-version && npm run icons && npm run compile:server && npx --yes electron-builder@26 --mac",
+    "build:win": "npm run sync-version && npm run compile:server:win && npx --yes electron-builder@26 --win",
+    "build:linux": "npm run sync-version && npm run compile:server:linux && npx --yes electron-builder@26 --linux"
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "electron": "^40.6.1",
-    "electron-builder": "^24.9.1"
+    "electron": "^43.4.1"
   },
   "build": {
     "appId": "com.haltija.desktop",

package/apps/desktop/resources/component.js

@@ -46,7 +46,14 @@
   });
 
   // src/version.ts
-  var VERSION = "1.12.5";
+  var VERSION = "1.12.6";
+
+  // src/ws-url.ts
+  function httpBaseFromWsUrl(wsUrl2, fallback = "http://localhost:8700") {
+    if (!wsUrl2)
+      return fallback;
+    return wsUrl2.replace(/^wss:/, "https:").replace(/^ws:/, "http:").replace("/ws/browser", "");
+  }
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -1358,6 +1365,10 @@
       ...buildDomAffordances(opts.maxNodes)
     };
   }
+  function serverHeaders(extra = {}) {
+    const token = window.__haltija_config__?.token;
+    return token ? { ...extra, "X-Haltija-Token": String(token) } : { ...extra };
+  }
   function isOwnWidget(el) {
     if (el.tagName === TAG_NAME.toUpperCase())
       return true;
@@ -3000,6 +3011,7 @@
         };
         document.addEventListener("visibilitychange", this.visibilityHandler);
       }
+      this.startPaintHeartbeat();
       this.connect();
     }
     disconnectedCallback() {
@@ -3015,6 +3027,7 @@
         document.removeEventListener("visibilitychange", this.visibilityHandler);
         this.visibilityHandler = null;
       }
+      this.stopPaintHeartbeat();
     }
     attributeChangedCallback(name, _old, value) {
       if (name === "server") {
@@ -3594,7 +3607,7 @@
           </div>
         </div>
         <div class="body"${this.isElectron ? ' style="display:none"' : ""}>
-            <a href="javascript:(function(){fetch('${this.serverUrl.replace("ws:", "http:").replace("wss:", "https:").replace("/ws/browser", "")}/inject.js').then(r=>r.text()).then(eval).catch(e=>alert('${PRODUCT_NAME}: Cannot reach server'))})();"
+            <a href="javascript:(function(){fetch('${httpBaseFromWsUrl(this.serverUrl)}/inject.js').then(r=>r.text()).then(eval).catch(e=>alert('${PRODUCT_NAME}: Cannot reach server'))})();"
                style="color: #6366f1; text-decoration: none;"
                title="Drag to bookmarks bar"
                class="bookmark-link">\uD83E\uDDDD bookmark</a>
@@ -3902,10 +3915,10 @@
     async startRecordingViaServer() {
       try {
         const config = window.__haltija_config__;
-        const serverUrl2 = config?.serverUrl?.replace("ws:", "http:").replace("/ws/browser", "") || "http://localhost:8700";
+        const serverUrl2 = httpBaseFromWsUrl(config?.serverUrl);
         const response = await fetch(`${serverUrl2}/recording`, {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          headers: serverHeaders({ "Content-Type": "application/json" }),
           body: JSON.stringify({ action: "start", window: this.windowId })
         });
         const result = await response.json();
@@ -3930,10 +3943,10 @@
     async stopRecordingViaServer() {
       try {
         const config = window.__haltija_config__;
-        const serverUrl2 = config?.serverUrl?.replace("ws:", "http:").replace("/ws/browser", "") || "http://localhost:8700";
+        const serverUrl2 = httpBaseFromWsUrl(config?.serverUrl);
         const response = await fetch(`${serverUrl2}/recording`, {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          headers: serverHeaders({ "Content-Type": "application/json" }),
           body: JSON.stringify({ action: "stop", window: this.windowId })
         });
         const result = await response.json();
@@ -4245,7 +4258,7 @@
         const serverUrl2 = this.serverUrl.replace("ws://", "http://").replace("wss://", "https://").replace("/ws/browser", "");
         const response = await fetch(`${serverUrl2}/recording/${this.lastRecordingId}/send`, {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          headers: serverHeaders({ "Content-Type": "application/json" }),
           body: JSON.stringify({ description, agentId })
         });
         const result = await response.json();
@@ -4685,7 +4698,7 @@
       const serverUrl2 = this.serverUrl.replace("ws://", "http://").replace("wss://", "https://").replace("/ws/browser", "");
       let agents = [];
       try {
-        const response = await fetch(`${serverUrl2}/terminal/agents`);
+        const response = await fetch(`${serverUrl2}/terminal/agents`, { headers: serverHeaders() });
         const data = await response.json();
         agents = data.agents || [];
       } catch (err) {
@@ -4855,7 +4868,7 @@ ${elementSummary}${moreText}`;
       try {
         const response = await fetch(`${serverUrl2}/selection/send`, {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          headers: serverHeaders({ "Content-Type": "application/json" }),
           body: JSON.stringify({
             agentId,
             message: messageText,
@@ -6244,6 +6257,29 @@ ${elementSummary}${moreText}`;
       });
       this.render();
     }
+    lastPaintAt = Date.now();
+    paintTimer = null;
+    paintAgeOnArrival = new Map;
+    startPaintHeartbeat() {
+      if (typeof requestAnimationFrame !== "function" || typeof setTimeout !== "function")
+        return;
+      const tick = () => {
+        requestAnimationFrame(() => {
+          this.lastPaintAt = Date.now();
+        });
+        this.paintTimer = setTimeout(tick, 1000);
+      };
+      tick();
+    }
+    stopPaintHeartbeat() {
+      if (this.paintTimer !== null) {
+        clearTimeout(this.paintTimer);
+        this.paintTimer = null;
+      }
+    }
+    paintAgeMs() {
+      return Date.now() - this.lastPaintAt;
+    }
     send(channel, action2, payload2, id) {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
         return;
@@ -6258,6 +6294,8 @@ ${elementSummary}${moreText}`;
       this.ws.send(JSON.stringify(msg2));
     }
     respond(requestId, success, data, error) {
+      const arrivalPaintAge = this.paintAgeOnArrival.get(requestId);
+      this.paintAgeOnArrival.delete(requestId);
       const local = this.localPending.get(requestId);
       if (local) {
         this.localPending.delete(requestId);
@@ -6273,7 +6311,8 @@ ${elementSummary}${moreText}`;
         success,
         data,
         error,
-        timestamp: Date.now()
+        timestamp: Date.now(),
+        paintAgeMs: arrivalPaintAge ?? this.paintAgeMs()
       };
       this.ws?.send(JSON.stringify(response));
     }
@@ -6292,6 +6331,14 @@ ${elementSummary}${moreText}`;
       });
     }
     handleMessage(msg2) {
+      if (msg2.id) {
+        if (this.paintAgeOnArrival.size > 200) {
+          const oldest = this.paintAgeOnArrival.keys().next().value;
+          if (oldest !== undefined)
+            this.paintAgeOnArrival.delete(oldest);
+        }
+        this.paintAgeOnArrival.set(msg2.id, this.paintAgeMs());
+      }
       if (msg2.source === "agent" || msg2.source === "server") {
         this.show();
       }

package/bin/cli-commands.mjs

@@ -55,6 +55,10 @@ var ROUTED_COMMANDS = [
   "test-run",
   "test-validate",
   "test-suite",
+  "session-attach",
+  "session-read",
+  "session-write",
+  "session-detach",
   "send",
   "send-message",
   "send-selection",

package/bin/cli-subcommand.mjs

@@ -102,6 +102,10 @@ export const COMPOUND_PATHS = {
   'test-run': '/test/run',
   'test-suite': '/test/suite',
   'test-validate': '/test/validate',
+  'session-attach': '/session/attach',
+  'session-read': '/session/read',
+  'session-write': '/session/write',
+  'session-detach': '/session/detach',
   'send-message': '/send/message',
   'send-selection': '/send/selection',
   'send-recording': '/send/recording',
@@ -192,6 +196,27 @@ export function takeFlags(args, spec) {
 }
 
 export const ARG_MAPS = {
+  // `hj session attach <name>` / `hj session read --lines N`. Compound form handled in hj.mjs.
+  'session-attach': (args) => ({
+    target: args.find((a) => !a.startsWith('-')),
+    allowInput: args.includes('--allow-input') || undefined,
+  }),
+  'session-write': (args) => {
+    const keyIdx = args.indexOf('--key')
+    const key = keyIdx !== -1 ? args[keyIdx + 1] : process.env.HALTIJA_SESSION_KEY
+    const text = args
+      .filter((a, i) => !a.startsWith('-') && i !== keyIdx + 1)
+      .join(' ')
+    return { text, submit: args.includes('--no-submit') ? false : undefined, writeKey: key }
+  },
+  'session-read': (args) => {
+    const body = {}
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--lines') { body.lines = Number(args[++i]); continue }
+    }
+    return body
+  },
+  'session-detach': () => ({}),
   click: (args) => parseClickArgs(args),
   type: (args) => {
     // Flags first, so an advertised `--clear` stops being typed as literal text.
@@ -925,6 +950,9 @@ export const KNOWN_FLAGS = {
   // not cosmetic: BOTH `normalizeEqualsFlags` and `warnUnknownFlags` are gated on an entry
   // existing, so `hj map --scale=3` parsed to `{}` and warned about nothing.
   map: ['--global', '--max-nodes', '--image', '--png', '--data-url', '--scale', '--maxWidth', '--max-width', '--maxHeight', '--max-height', '--format', '--quality', '--full-page', '--layout'],
+  'session-read': ['--lines', '--follow'],
+  'session-attach': ['--allow-input'],
+  'session-write': ['--no-submit', '--key'],
   'events-watch': ['--preset'],
   'mutations-watch': ['--preset'],
   'network-watch': ['--preset'],
@@ -974,6 +1002,7 @@ export function normalizeEqualsFlags(args, known) {
 export const FREE_TEXT_COMMANDS = new Set([
   'type', 'highlight', 'call', 'eval', 'find', 'snapshot',
   'send', 'send-message', 'send-selection', 'send-recording',
+  'session-write',
 ])
 
 

package/bin/hints.json

@@ -1,4 +1,8 @@
 {
+  "session-attach": "--allow-input | see: session-read, session-write, session-detach",
+  "session-read": "--lines N, --follow | see: session-attach",
+  "session-write": "--no-submit | see: session-attach",
+  "session-detach": "see: session-attach",
   "tree": "-d 3 (shallow), -i (interactive only), --visible, --compact | see: inspect, query, click",
   "query": "@ref or \"selector\", --all | see: tree, inspect",
   "inspect": "@ref or \"selector\", --styles, --rules | see: tree (for ancestors), query",

package/bin/hints.mjs

@@ -1,5 +1,9 @@
 /** ⚠️  AUTO-GENERATED FROM src/api-schema.ts — DO NOT EDIT. Run: bun run build */
 export const COMMAND_HINTS = {
+  "session-attach": "--allow-input | see: session-read, session-write, session-detach",
+  "session-read": "--lines N, --follow | see: session-attach",
+  "session-write": "--no-submit | see: session-attach",
+  "session-detach": "see: session-attach",
   "tree": "-d 3 (shallow), -i (interactive only), --visible, --compact | see: inspect, query, click",
   "query": "@ref or \"selector\", --all | see: tree, inspect",
   "inspect": "@ref or \"selector\", --styles, --rules | see: tree (for ancestors), query",
@@ -27,6 +31,10 @@ export const COMMAND_HINTS = {
 }
 
 export const COMMAND_SUMMARIES = {
+  "session-attach": "Mirror a tmux session into the channel (opt-in, read-only)",
+  "session-read": "Read the mirrored terminal session",
+  "session-write": "Type into the mirrored session (requires the input grant)",
+  "session-detach": "Stop mirroring the terminal session",
   "tree": "Get DOM tree structure",
   "query": "Query DOM elements by selector",
   "inspect": "Deep inspection of an element",

package/bin/hj.mjs

@@ -15,6 +15,7 @@ import { extractWindowTarget } from './arg-utils.mjs'
 import { findProjectOrigins, routeByDeclaredOrigin, ORIGINS_FILE } from './project-origins.mjs'
 import { collectCandidates, describeServer, sortRows, labelFor, isAmbiguousTarget } from './server-list.mjs'
 import { isDrivable, isVisible, visibilityKnown } from './window-state.mjs'
+import { PAINT_STALE_MS } from './tab-liveness.mjs'
 import { LOCAL_COMMANDS, LOCAL_COMMAND_HELP } from './cli-commands.mjs'
 import { HJ_VERSION } from './version.mjs'
 import { differsBeyondPatch } from './semver.mjs'
@@ -416,7 +417,16 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
         })
         if (r.ok) {
           const j = await r.json()
-          if (j && j.success && j.data && typeof j.data.fired === 'boolean') raf = j.data
+          // Prefer the widget's OWN measurement when it sends one. It answers the same question
+          // this probe does — is the tab compositing — but it is the signal the server already
+          // attaches to every result, so doctor and the result warnings cannot disagree about a
+          // borderline tab. The probe stays as the fallback for a widget older than 1.12.6, which
+          // reports no paintAgeMs at all; without it, an old widget would silently go unchecked.
+          if (typeof j?.paintAgeMs === 'number' && Number.isFinite(j.paintAgeMs)) {
+            raf = { fired: j.paintAgeMs < PAINT_STALE_MS, ms: j.paintAgeMs, measured: true }
+          } else if (j && j.success && j.data && typeof j.data.fired === 'boolean') {
+            raf = j.data
+          }
         }
       } catch {
         // Fall through to the unchecked branch — never a pass.
@@ -428,7 +438,9 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
         )
       } else if (!raf.fired) {
         problems.push(
-          `requestAnimationFrame DID NOT FIRE within 2s — this tab is not compositing, even though ` +
+          (raf.measured
+            ? `this tab HAS NOT PAINTED A FRAME IN ${(raf.ms / 1000).toFixed(1)}s — it is not compositing, even though `
+            : `requestAnimationFrame DID NOT FIRE within 2s — this tab is not compositing, even though `) +
             `it reports visibilityState "visible". Anything rAF-driven (React's scheduler, tosijs ` +
             `queueRender, animations, virtual scrollers) will never render, so a missing element ` +
             `is NOT evidence of an application bug. Bring a window to the front, or wake the ` +
@@ -776,11 +788,52 @@ const NOUN_DEFAULTS = {
   'tabs': 'windows',        // show tab list
   'video': 'video-status',
   'send': 'send',           // already a command
+  'session': 'session-read',// bare `hj session` shows the mirror
 }
 if (args.length === 1 && !isSubcommand(args[0]) && Object.hasOwn(NOUN_DEFAULTS, args[0])) {
   args[0] = NOUN_DEFAULTS[args[0]]
 }
 
+// `hj session read --follow` — poll the mirror and print only what is new.
+//
+// Client-side rather than a streaming endpoint: the page in the headset polls the same endpoint, so
+// a second transport would be a second thing to keep working. newTailOnly() is shared with the
+// server module and unit-tested, including the case where the pane has scrolled past what we saw.
+if ((args[0] === 'session-read' || (args[0] === 'session' && args[1] === 'read')) && args.includes('--follow')) {
+  const { newTailOnly } = await import('./tmux-session.mjs')
+  const linesIdx = args.indexOf('--lines')
+  const lines = linesIdx !== -1 ? Number(args[linesIdx + 1]) : 200
+  let seen = ''
+  let firstPass = true
+  process.stderr.write(`[hj] following the mirrored session — Ctrl-C to stop\n`)
+  for (;;) {
+    let json
+    try {
+      const resp = await fetch(`http://localhost:${port}/session/read`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...(process.env.HALTIJA_TOKEN ? { 'X-Haltija-Token': process.env.HALTIJA_TOKEN } : {}) },
+        body: JSON.stringify({ lines }),
+      })
+      json = await resp.json()
+    } catch (err) {
+      console.error(`hj: ${err.message}`)
+      process.exit(1)
+    }
+    if (!json.success) {
+      // Do not spin silently on a session that has gone away — say it once and stop, so a dead
+      // mirror cannot look like an idle agent.
+      console.error(`hj: ${json.error}`)
+      process.exit(1)
+    }
+    const text = json.text || ''
+    const fresh = firstPass ? text : newTailOnly(seen, text)
+    if (fresh) process.stdout.write(fresh.endsWith('\n') ? fresh : fresh + '\n')
+    seen = text
+    firstPass = false
+    await new Promise((r) => setTimeout(r, 1000))
+  }
+}
+
 const subcommand = args[0]
 let subArgs = args.slice(1)
 // Re-attach a leading --window so cli-subcommand's existing handling sees it (both positions work).

package/bin/tab-liveness.mjs

@@ -0,0 +1,27 @@
+/** ⚠️  AUTO-GENERATED FROM src/tab-liveness.ts — DO NOT EDIT. Run: bun run build */
+// src/tab-liveness.ts
+function hiddenTabWarning(win) {
+  if (!win)
+    return null;
+  if (win.active !== false)
+    return null;
+  const which = win.title ? `"${win.title}"` : win.id;
+  return `The tab that answered (${which}) reports it is HIDDEN — backgrounded, minimized, ` + `behind another window, or the display is asleep. Browsers stop requestAnimationFrame and ` + `throttle timers in a hidden tab, so anything mounted by rAF/IntersectionObserver may never ` + `have run: THIS RESULT CAN BE PLAUSIBLE BUT WRONG (an empty selector here means "not mounted ` + `yet", not "broken"). Bring the tab to the front, or target a visible one with --window <id>.`;
+}
+var PAINT_STALE_MS = 3000;
+function stalePaintWarning(win, paintAgeMs) {
+  if (typeof paintAgeMs !== "number" || !Number.isFinite(paintAgeMs))
+    return null;
+  if (paintAgeMs < PAINT_STALE_MS)
+    return null;
+  if (win?.active === false)
+    return null;
+  const which = win?.title ? `"${win.title}"` : win?.id ?? "the answering tab";
+  const seconds = (paintAgeMs / 1000).toFixed(1);
+  return `The tab that answered (${which}) says it is VISIBLE but HAS NOT PAINTED A FRAME IN ` + `${seconds}s — it is not being composited. That happens when a window is occluded by another, ` + `is offscreen, or the display is asleep, and it is not something visibilityState reports. ` + `Anything driven by requestAnimationFrame (React's scheduler, tosijs queueRender, animations, ` + `virtual scrollers) is NOT RUNNING, so a missing element is not evidence of an application ` + `bug and a screenshot may show a stale frame the compositor is still holding. Raise the ` + `window (or wake the display) and re-run before believing this result.`;
+}
+export {
+  PAINT_STALE_MS,
+  hiddenTabWarning,
+  stalePaintWarning
+};

package/bin/tmux-session.mjs

@@ -0,0 +1,131 @@
+/** ⚠️  AUTO-GENERATED FROM src/tmux-session.ts — DO NOT EDIT. Run: bun run build */
+// src/tmux-session.ts
+var state = { target: null, attachedAt: null, allowInput: false, writeKey: null };
+function sessionState() {
+  return { ...state };
+}
+async function listSessions(run) {
+  const res = await run(["list-sessions", "-F", "#{session_name}"]);
+  if (!res.ok)
+    return [];
+  return res.stdout.split(`
+`).map((l) => l.trim()).filter(Boolean);
+}
+function tokenAdvisory(hasToken) {
+  if (hasToken)
+    return;
+  return "this server has no token, so anything that can reach its port can now read the agent's " + "terminal — not just drive the browser. Fine on a laptop; NOT fine over a tunnel. Start the " + "server with `--token <secret>` (and set HALTIJA_TOKEN for clients) if the port is reachable " + "from anywhere else.";
+}
+async function attachSession(run, target, hasToken = false, allowInput = false) {
+  const available = await listSessions(run);
+  if (!available.length) {
+    return {
+      ok: false,
+      error: "no tmux sessions are running. Start your agent inside one — `tmux new -s agent` then run " + "it there — or attach to an existing session by name.",
+      available: []
+    };
+  }
+  if (!available.includes(target)) {
+    return {
+      ok: false,
+      error: `no tmux session named "${target}"`,
+      available
+    };
+  }
+  state.target = target;
+  state.attachedAt = Date.now();
+  state.allowInput = allowInput;
+  state.writeKey = allowInput ? mintKey() : null;
+  return { ok: true, target, available, allowInput, writeKey: state.writeKey ?? undefined, warning: tokenAdvisory(hasToken) };
+}
+function detachSession() {
+  state.target = null;
+  state.attachedAt = null;
+  state.allowInput = false;
+  state.writeKey = null;
+}
+async function readSession(run, lines = 200) {
+  if (!state.target) {
+    return {
+      ok: false,
+      error: "no session attached. `hj session attach <tmux-session>` first — mirroring is opt-in because " + "it exposes everything the agent prints."
+    };
+  }
+  const safeLines = Math.max(1, Math.min(1e4, Math.floor(lines) || 200));
+  const res = await run(["capture-pane", "-t", state.target, "-p", "-S", `-${safeLines}`]);
+  if (!res.ok) {
+    return {
+      ok: false,
+      target: state.target,
+      error: `could not read tmux session "${state.target}": ${res.stderr.trim() || "unknown error"}`
+    };
+  }
+  return { ok: true, target: state.target, text: res.stdout.replace(/\s+$/, "") };
+}
+function newTailOnly(previous, current) {
+  if (!previous)
+    return current;
+  if (current.startsWith(previous))
+    return current.slice(previous.length);
+  const lastLine = previous.trimEnd().split(`
+`).pop() || "";
+  if (lastLine) {
+    const idx = current.lastIndexOf(lastLine);
+    if (idx !== -1)
+      return current.slice(idx + lastLine.length);
+  }
+  return current;
+}
+function mintKey() {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function keyMatches(provided, expected) {
+  if (provided.length !== expected.length)
+    return false;
+  let diff = 0;
+  for (let i = 0;i < provided.length; i++)
+    diff |= provided.charCodeAt(i) ^ expected.charCodeAt(i);
+  return diff === 0;
+}
+async function writeSession(run, text, submit = true, writeKey = "") {
+  if (!state.target) {
+    return { ok: false, error: "no session attached. `hj session attach <tmux-session>` first." };
+  }
+  if (!state.allowInput || !state.writeKey) {
+    return {
+      ok: false,
+      target: state.target,
+      error: "this session was attached for reading only; writing is a separate grant made at attach time."
+    };
+  }
+  if (!keyMatches(writeKey, state.writeKey)) {
+    return {
+      ok: false,
+      target: state.target,
+      error: "missing or invalid write key. The handle is returned once, to the caller that attached " + "with input permitted; pass it as `writeKey`."
+    };
+  }
+  if (!text)
+    return { ok: false, target: state.target, error: "nothing to send" };
+  const args = ["send-keys", "-t", state.target, "-l", "--", text];
+  const res = await run(args);
+  if (res.ok && submit) {
+    const nl = await run(["send-keys", "-t", state.target, "Enter"]);
+    if (!nl.ok) {
+      return { ok: false, target: state.target, error: nl.stderr.trim() || "send-keys Enter failed" };
+    }
+  }
+  return res.ok ? { ok: true, target: state.target } : { ok: false, target: state.target, error: res.stderr.trim() || "send-keys failed" };
+}
+export {
+  attachSession,
+  detachSession,
+  listSessions,
+  newTailOnly,
+  readSession,
+  sessionState,
+  tokenAdvisory,
+  writeSession
+};

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.12.5'
+export const HJ_VERSION = '1.12.6'