haltija 1.12.2 → 1.12.6

package/CHANGELOG.md

@@ -1,5 +1,227 @@
 # 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
+npm went straight from 1.12.2 to here. Their entries below still describe what they contained.
+
+### Embedding on an HTTPS dev server no longer fails silently ([#33](https://github.com/tonioloewald/haltija/issues/33))
+
+An `https://` page cannot load an `http://` script: the browser blocks it as **mixed content** and
+reports nothing that names the cause. You get no widget, `hj where` says `0 tabs`, and the natural
+conclusion is that your own setup is wrong. The reporter worked it out from `--help` and source.
+
+This is not an edge case — the tosijs-ui doc-system dev server is HTTPS by default (`bun run tls`),
+so the default project setup hits it on the first attempt.
+
+A static `src` cannot branch on the page's scheme, so the canonical embed snippet is now a
+three-line loader that picks the matching transport, with the plain tag kept below as the equivalent
+for HTTP pages. Serving an HTTPS page also needs `bunx haltija --server --both` and accepting the
+self-signed cert once at `https://localhost:8701`.
+
+Same root cause as [#32](https://github.com/tonioloewald/haltija/issues/32) from the other end:
+there, a shared HTTP-only server silently denied another project's HTTPS pages; here, an HTTPS page
+silently cannot reach an HTTP server. **Opening both transports by default would remove the class
+rather than documenting it**, which is why that remains the top of the queue rather than something
+more prose can fix.
+
+## 1.12.4
+
+Backlog work done while releases were paused. **Includes everything in 1.12.3**, which was tagged
+but never published — installing 1.12.4 gets both.
+
+### Three bugs found by closing a coverage hole
+
+**Ten of seventeen step actions had no executable coverage in any lane** — including the
+deprecated-alias branch and the `select-text` dispatch that shipped in 1.12.3. Nothing was red; the
+lanes simply never ran those paths, and the failure mode there is a *silent success*. There is now a
+blocking suite that asserts an **observable effect** per action (a checkbox actually checked, a
+keydown that actually arrived), and it found:
+
+- **`hj drag` does nothing to a native `<input type=range>` and reported success.** Measured: a 60px
+  drag leaves a native range at 0 while moving a custom div thumb 0 → 60px. Browsers drive native
+  controls from *trusted* input only; a custom implementation listens for `mousemove` on `document`,
+  which is why MUI sliders, resize handles and reorder lists are unaffected. `/drag` now returns a
+  warning naming the cause and the way round it.
+- **`hj test validate` accepted an `assert` step with no `assertion` object** — the shape our own
+  `CLAUDE.md` documented. Such a step never checks anything: a guard that cannot fail.
+- **`tests/haltija.test.ts` reported 11 passes for work it never did.** With no server it early-returned
+  from each test body, and bun records that as PASSED. Now 0 pass / 11 skip.
+
+### The MCP server has been shipping 43 of 63 endpoints since January
+
+`apps/mcp/build/endpoints.json` — what the committed MCP server imports at runtime — had drifted
+seven months behind. Anyone on the MCP path had no `/map`, `/find`, `/wait`, `/key`, `/call`,
+`/form`, `/fetch`, `/select`, `/recording`, `/test/suite`, or the `/network`, `/video` and `/dialog`
+families. Twenty endpoints.
+
+`docs-drift` could not catch it, and that is the lesson: the gate asserts a build leaves the tree
+clean, and **nothing in the build wrote that file**. A drift gate only covers what the build
+produces. Now it writes it, with a test asserting the runtime copy matches the generated one.
+
+Also fixed: `hj --setup-mcp` pointed at `node_modules/tosijs-dev/…` in two of three lookups, a
+package name that changed long ago. (`apps/mcp` is still not in the npm `files` list — that is a
+packaging decision, deliberately left rather than guessed at.)
+
+### `hj where` says which transports are open — and why one is not ([#32](https://github.com/tonioloewald/haltija/issues/32))
+
+```
+transports: http 8700 ✓   https 8701 ✗ (no certs in <path>)
+```
+
+The channel is shared across projects, so **one project's transport choice is paid for by another**:
+an instance that came up HTTP-only leaves every `https` page with nothing to import, because mixed
+content blocks the fallback. The reporter's doc site had no haltija at all while `hj where` said
+"haltija 1.12.2, 1 tab" and everything looked healthy. A half-open channel and a full one were
+indistinguishable from outside; now the reason is named (`not requested`, `no certs at <path>`, or
+`port N is held`). A `--private` instance reports transports but not the cross-project warning — it
+is isolated by construction and denies nobody.
+
+Opening both transports by default (the other half of that issue) needs a release to exercise and is
+queued rather than rushed.
+
+### Also
+
+- Four stale copies folded in, including a **fourth** hand-maintained step list in `api-schema.ts`
+  that had drifted to 8 of 17 and propagated to `API.md` and the MCP definitions.
+- `CLAUDE.md`'s test-JSON example used the flat `assert` shape the runner ignores.
+
+## 1.12.3
+
+Documentation-drift machinery, a measured rename, and the six blockers a nine-lens review raised
+against all of it. **Known open:** [#26](https://github.com/tonioloewald/haltija/issues/26) (a tab
+becoming permanently undrivable — observed, not reproducible on any version) and
+[#16](https://github.com/tonioloewald/haltija/issues/16) (native tosiAgent bridge, on hold).
+
+**Recorded suites now use `select-text`, which servers before 1.12.3 reject.** If you record on an
+updated machine and run against a pinned older haltija, that step fails with `unknown step action`.
+The paved CI path (`bunx haltija@latest`) is unaffected.
+
+
+### `select` is now `select-text` — and `select` is being freed
+
+Measured, not argued. Shown the bare step vocabulary with no descriptions, **3/3 agents reached for
+`select` to choose an option from a dropdown, and 3/3 read it cold as "choose an `<option>`".
+Nobody read it as text selection** — which is what it does. A name that unanimously means something
+else to competent readers is not a documentation problem.
+
+`select-text` says what it does. **`select` still works** as a deprecated alias, so existing suites
+keep running; steps using it now carry a `warning` naming the replacement, rendered in the test
+report rather than only present in `--json`.
+
+The recorder also stopped emitting two illegal steps it had emitted since long before this release:
+`set` (not a step action at all — recorded suites died with "Unsupported step action: set") and
+`select` for **dropdowns**, which resolved to `select-text` and dispatched a text-selection event at
+the `<select>`, passing while choosing nothing. Both now record an explicit `eval` that works, and a
+test asserts every action the recorder can emit is legal and non-deprecated.
+
+The point of the deprecation is the reuse: once the alias can be dropped, `select` is free to mean
+what everyone already expects — pick an option from a `<select>` — which haltija cannot do at all
+today. A test enforces that the two meanings can never overlap (`no alias may shadow a live
+action`), because a word meaning two things depending on vintage is exactly the silent-wrong-action
+trap the rename exists to remove.
+
+**Correction, and it matters more than the rename.** An earlier draft of these notes acquitted
+`check`, `verify` and `tabs-focus` as "measured and fine". That was wrong: the harness spawned each
+agent **in this repo**, so every "first impression" had our own `CLAUDE.md` — which documents the
+vocabulary under test — in context. Re-run from a neutral directory, `check` is cold-read as
+*"asserts that some condition is true"* by **3/3** (the exact confusion it was cleared of), and
+`verify` slips to 2/3. What survives is narrower and honest: with the full vocabulary in view agents
+still pick `assert` for assertions and `check` for checkboxes, so `check` is safe **in context** and
+misleading **in isolation**. `tabs-focus` holds at 3/3.
+
+The `select` verdict is unaffected — contamination ran in its favour and it still lost 3/3, and the
+clean re-run agrees. The probe now runs each sample in an empty temp directory, and its vocabularies
+are derived from the registries rather than hand-copied (the old copy still listed `select`, stale
+as of the commit it motivated). Harness: `tools/naming-probe.mjs`, run with bun.
+
 ## 1.12.2
 
 Two fixes, both from an agent driving real apps. Each is a case where haltija reported success — or

package/apps/desktop/artifacts.js

@@ -40,12 +40,12 @@ var __export = (target, all) => {
 // src/artifacts.ts
 var exports_artifacts = {};
 __export(exports_artifacts, {
-  saveDataUrl: () => saveDataUrl,
-  pruneKind: () => pruneKind,
-  pruneArtifacts: () => pruneArtifacts,
-  parseDataUrl: () => parseDataUrl,
+  RETENTION: () => RETENTION,
   artifactDir: () => artifactDir,
-  RETENTION: () => RETENTION
+  parseDataUrl: () => parseDataUrl,
+  pruneArtifacts: () => pruneArtifacts,
+  pruneKind: () => pruneKind,
+  saveDataUrl: () => saveDataUrl
 });
 module.exports = __toCommonJS(exports_artifacts);
 var import_promises = require("fs/promises");

package/apps/desktop/isolation.js

@@ -40,12 +40,12 @@ var __export = (target, all) => {
 // src/desktop-isolation.ts
 var exports_desktop_isolation = {};
 __export(exports_desktop_isolation, {
-  resolveServerUrl: () => resolveServerUrl,
-  resolvePublicUrl: () => resolvePublicUrl,
-  resolveInternalPort: () => resolveInternalPort,
-  isPrivateInstance: () => isPrivateInstance,
+  SHARED_INTERNAL_PORT: () => SHARED_INTERNAL_PORT,
   SHARED_PUBLIC_URL: () => SHARED_PUBLIC_URL,
-  SHARED_INTERNAL_PORT: () => SHARED_INTERNAL_PORT
+  isPrivateInstance: () => isPrivateInstance,
+  resolveInternalPort: () => resolveInternalPort,
+  resolvePublicUrl: () => resolvePublicUrl,
+  resolveServerUrl: () => resolveServerUrl
 });
 module.exports = __toCommonJS(exports_desktop_isolation);
 var SHARED_PUBLIC_URL = "http://localhost:8700";

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.12.2",
+  "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/renderer/isolation.js

@@ -26,10 +26,10 @@ function resolveServerUrl(inputs) {
   return injected || persisted || SHARED_PUBLIC_URL;
 }
 export {
-  resolveServerUrl,
-  resolvePublicUrl,
-  resolveInternalPort,
-  isPrivateInstance,
+  SHARED_INTERNAL_PORT,
   SHARED_PUBLIC_URL,
-  SHARED_INTERNAL_PORT
+  isPrivateInstance,
+  resolveInternalPort,
+  resolvePublicUrl,
+  resolveServerUrl
 };

package/apps/desktop/resources/component.js

@@ -40,13 +40,20 @@
   // src/component.ts
   var exports_component = {};
   __export(exports_component, {
-    inject: () => inject,
+    DevChannel: () => DevChannel,
     VERSION: () => VERSION2,
-    DevChannel: () => DevChannel
+    inject: () => inject
   });
 
   // src/version.ts
-  var VERSION = "1.12.2";
+  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();
@@ -4095,25 +4108,21 @@
             let inputDesc = "";
             if (isCleared) {
               inputDesc = `Clear ${inputLabel}`;
-            } else if (inputType === "range") {
-              inputAction = "set";
-              inputDesc = `Set ${inputLabel} to ${inputValue}`;
-            } else if (inputType === "select-one" || inputType === "select-multiple") {
-              inputAction = "select";
-              inputDesc = `Select "${inputValue}" in ${inputLabel}`;
+            } else if (inputType === "range" || inputType === "select-one" || inputType === "select-multiple" || inputType === "date" || inputType === "time" || inputType === "color") {
+              inputAction = "eval";
+              inputDesc = `Set ${inputLabel} to "${inputValue}"`;
             } else if (inputType === "checkbox" || inputType === "radio") {
               inputAction = "check";
               inputDesc = `Check ${inputLabel}`;
-            } else if (inputType === "date" || inputType === "time" || inputType === "color") {
-              inputAction = "set";
-              inputDesc = `Set ${inputLabel} to ${inputValue}`;
             } else {
               inputDesc = `Type "${inputValue}" in ${inputLabel}`;
             }
             steps.push(withFallback({
               action: inputAction,
               selector,
-              ...inputAction === "type" || inputAction === "set" ? { text: inputValue } : { value: inputValue },
+              ...inputAction === "eval" ? {
+                code: `const el = document.querySelector(${JSON.stringify(selector)});` + ` el.value = ${JSON.stringify(inputValue)};` + ` el.dispatchEvent(new Event('input', { bubbles: true }));` + ` el.dispatchEvent(new Event('change', { bubbles: true }));`
+              } : inputAction === "type" ? { text: inputValue } : { value: inputValue },
               description: inputDesc,
               ...delay && delay > 50 ? { delay } : {}
             }, event.target));
@@ -4146,7 +4155,7 @@
           case "interaction:select":
             const selectedText = this.cleanDescription(event.payload?.text || "", 50);
             steps.push({
-              action: "select",
+              action: "select-text",
               selector,
               text: event.payload?.text || "",
               description: `Select text "${selectedText}"`,
@@ -4249,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();
@@ -4689,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) {
@@ -4859,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,
@@ -6248,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;
@@ -6262,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);
@@ -6277,7 +6311,8 @@ ${elementSummary}${moreText}`;
         success,
         data,
         error,
-        timestamp: Date.now()
+        timestamp: Date.now(),
+        paintAgeMs: arrivalPaintAge ?? this.paintAgeMs()
       };
       this.ws?.send(JSON.stringify(response));
     }
@@ -6296,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",
@@ -120,9 +124,9 @@ function cliNameForEndpoint(path) {
   return isKnownCommand(name) ? name : null;
 }
 export {
-  isKnownCommand,
-  cliNameForEndpoint,
-  ROUTED_COMMANDS,
+  LOCAL_COMMANDS,
   LOCAL_COMMAND_HELP,
-  LOCAL_COMMANDS
+  ROUTED_COMMANDS,
+  cliNameForEndpoint,
+  isKnownCommand
 };