haltija 1.12.0 → 1.12.2

package/CHANGELOG.md

@@ -1,5 +1,182 @@
 # Changelog
 
+## 1.12.2
+
+Two fixes, both from an agent driving real apps. Each is a case where haltija reported success — or
+green health — while quietly producing something you couldn't trust, which is the same thread the
+1.12.x line has been pulling on throughout.
+
+**[#26](https://github.com/tonioloewald/haltija/issues/26) remains open and is NOT a 1.12.0
+regression.** The reporter's own control run settled it: the known-bad version survived the original
+failing surface through seven hard navigations plus an HMR rebuild. A tab becoming permanently
+undrivable was really observed, so the issue stays open as a standing record — but neither of us can
+currently reproduce it on any version, and nothing here claims to fix it.
+
+
+### `--private` instances get their own Electron profile — [#31](https://github.com/tonioloewald/haltija/issues/31)
+
+Private mode isolated ports, the registry, retirement and teardown — but **not the Electron
+profile**, so every instance ran with the same `--user-data-dir`. Chromium's single-instance locking
+means the second one to launch can't take the profile lock and falls back to caches it cannot
+persist, losing the HTTP cache and the V8 code cache. A large app bundle is then fully re-parsed on
+every navigation: **roughly 10x slower page boots**.
+
+The damage isn't the slowness, it's that it **lies in the one workflow private mode exists for**.
+Comparing two versions side by side, the failure followed **launch order, not version** — 22.1s vs
+2.04s, the same version passing or failing depending only on which started first, and each fine
+alone. The reporter nearly wrote up a version regression that did not exist. Every health signal
+read green throughout, including `hj doctor` and a measured 120fps rAF cadence, because nothing was
+broken — it was just slow.
+
+Each private instance now gets `<tmpdir>/haltija-private-<pid>` as its `userData` and `sessionData`,
+set before `app.whenReady()` and before anything reads `preferences.json`.
+
+Two related leaks closed at the same time, both cases of "private" having meant *private ports*
+rather than *touches nothing of yours*:
+
+- **A private run no longer writes `~/.haltija/last-quit`.** That marker tells `hj`'s auto-launch the
+  user deliberately quit, so an automated run ending was suppressing auto-launch for the interactive
+  app a developer was using.
+- **Stale private scratch is swept** at the start of the next private run — profiles and the
+  port-files the launcher writes (175 had accumulated on one machine). Swept at startup rather than
+  on exit because Chromium flushes its caches *after* `will-quit`, so deleting the profile there
+  just gets it recreated. The sweep keys on whether the owning pid is still alive and **never
+  touches a live peer** — `EPERM` from `kill(pid, 0)` counts as alive, since the process exists and
+  merely belongs to someone else. That decision is a tested function (`src/private-state.ts`), not a
+  loop in the launcher, because deleting a running instance's profile would be far worse than the
+  litter it tidies.
+
+### The test-suite runner gains `drag`, and a `wait` can no longer pass without waiting — [#30](https://github.com/tonioloewald/haltija/issues/30)
+
+**`drag` is now a step action.** `hj drag` and `POST /drag` had shipped for releases; the runner's
+dispatcher simply had no case, so a perfectly reasonable suite failed with `Unsupported step action:
+drag`. Sliders, resize handles and drag-reorder lists are exactly the interactions you cannot cover
+another way — a synthetic keydown on a slider thumb is not a faithful substitute.
+
+The routine now lives in `src/drag.ts` and both `/drag` and the runner call it. Dragging is not one
+message to the widget (scroll into view → measure → mouseenter/over/move → mousedown → N
+interpolated mousemoves → mouseup), and a second copy in the runner's switch would have been the
+fifth instance this cycle of one idea with two implementations.
+
+**A `wait` step with nothing to wait for was reported as PASSING.** `{"action": "wait",
+"forElement": "tbody tr", "timeout": 10000}` fell out of the runner's chain to `break`, and since a
+step passes by default it looked green — so a guard that had never waited for anything let every
+assertion after it race the page. Two fixes: `forElement` is now accepted as an alias of `selector`
+(the name `/wait` uses, and the name **our own SKILL.md example used**, which means the documented
+example never waited), and a `wait` carrying none of `duration`/`ms`/`selector`/`forElement`/
+`forWindow`/`url` is now an **error**.
+
+This is the same defect as the CLI's `hj wait --hidden`, fixed in 1.12.0 — that fix landed in the
+CLI and never reached the runner.
+
+**`hj test validate` now rejects illegal steps before the suite runs**, with a "did you mean":
+
+```
+step 0: unknown step action "drg" — did you mean "drag"?. Legal actions: navigate, click, …
+step 1: wait step has nothing to wait for — give it `duration` (ms), `selector` (or `forElement`) …
+```
+
+Validation previously checked only that selectors resolved, so `{"action": "drag"}` validated clean
+and then died in CI.
+
+**And the list is published and enforced.** There was nowhere to look up the legal actions: `hj api`
+documents the HTTP endpoints, which reads as though the same verbs work as steps. The canonical list
+is now `TEST_STEP_ACTIONS` in `src/test-actions.ts`, printed in `SKILL.md`, `CLAUDE.md` and
+`docs/CI-INTEGRATION.md` — and a test asserts it matches the runner's `switch (step.action)` in
+**both** directions. Writing that guard immediately found `screenshot` documented in `SKILL.md` as a
+step action when the runner has never had one.
+
+## 1.12.1
+
+A patch of fixes reported by an agent driving a real React + web-components admin app against
+1.12.0 — the kind of surface no fixture reproduces. Four of the five below are cases where haltija
+answered confidently and wrongly, which is the same thread 1.12.0 was pulling on.
+
+**Still open: [#26](https://github.com/tonioloewald/haltija/issues/26)** — tabs reportedly
+disconnect permanently on webpack-dev-server (CRA) origins in 1.12.0, and rc.5 is unaffected. It is
+**not fixed here**, because I could not reproduce it: a real webpack-dev-server (v5 client, `hot` +
+`liveReload`) survived on both 1.12.0 and the rc.5 widget, the opposite of the reporter's A/B. The
+re-injection fix below may cover it and may not. If you drive a CRA dev server, test before you rely
+on this release, and please add to that issue.
+
+
+### Text selectors pick the element you could actually click — [#27](https://github.com/tonioloewald/haltija/issues/27)
+
+Two ways the same selector chose the wrong element, both found driving a real admin app:
+
+- **A hidden duplicate that came first won.** `click` took the first match in DOM order and left the
+  visibility gate to complain afterwards, so a `display:none` copy made `hj click ':text(Save
+  Changes)'` fail with "zero-size bounding rect" while the visible copy sat right there — and
+  `hj find`, which filters before choosing, returned the right one. One selector, two answers.
+- **An off-canvas element was clicked silently.** The `position:absolute; left:-9999px` skip-link
+  idiom has a perfectly normal box (measured: 99x35 at x=-9999), so every size and style check
+  passed it. `click` actuated an element no human can see and reported **success** — a script then
+  asserts against a state it never produced. This is the worse of the two: it fails confidently.
+
+Resolution now filters *before* choosing, and `find` and `click` share one predicate so they cannot
+disagree. An off-canvas element that is the ONLY match fails loudly (`positioned off-canvas`) rather
+than being clicked invisibly.
+
+Off-canvas is measured in **page** coordinates, so content merely **below the fold** is unaffected —
+visible still means *rendered*, not *on screen*. That is also why `elementFromPoint` isn't used
+here despite catching this case: it rejects everything scrolled out of view, which would fail
+legitimate content in a small headless viewport.
+
+### `hj doctor` probes requestAnimationFrame — [#28](https://github.com/tonioloewald/haltija/issues/28)
+
+**A tab can report `visibilityState: "visible"` and still not be compositing.** Occluded windows,
+offscreen windows and a sleeping display all do it. Nothing rAF-driven then renders — React's
+scheduler, tosijs `queueRender`, animations, virtual scrollers — while geometry probes keep
+returning real numbers, so the absence of an element stops being evidence of anything.
+
+That doesn't merely hide information, it manufactures a plausible wrong answer. The reporter found
+four routes "not mounting" on hard navigation, had a coherent mechanism (the router gates its first
+mount on rAF), reproduced it four times, and nearly filed it as an application bug. Opening a second
+tab fixed all four.
+
+`hj doctor` now measures it directly and fails with `requestAnimationFrame DID NOT FIRE within 2s`.
+If the probe itself can't run, that is reported as **unchecked** — never as a pass — and the probe
+is bounded at 3s so a pre-flight can't hang on a socket that never answers.
+
+### `hj tabs` — the array is `windows`, and a `tabs` alias now exists ([#29](https://github.com/tonioloewald/haltija/issues/29))
+
+`d['tabs']` KeyError'd because the payload key is `windows` — accurate, since the list holds popups
+and iframes too, but the command is `hj tabs`, so the obvious guess failed and it looked like the
+caller's bug. `tabs` is now sent as an alias of the same array. The hint no longer mixes the two
+vocabularies in one sentence ("Multiple **tabs** connected. Use `?window=<id>`"), which is where the
+wrong idea came from.
+
+Popups being indistinguishable from user-opened tabs, the other half of that report, is fixed by the
+popup work below: they carry `windowType: "popup"` and never take focus.
+
+### Popups are popups again (desktop app) — [#25](https://github.com/tonioloewald/haltija/issues/25)
+
+A page calling `window.open(url, name, 'width=...')` now gets a genuine popup: `window.open()`
+returns a real `WindowProxy`, the child has `window.opener`, and `opener.postMessage(...)` reaches
+the parent.
+
+Previously the desktop app decided by **guessing from the URL** — allow if it contained `oauth`,
+`signin`, `login`, `accounts.google.com` or `/__/auth/`; deny everything else and re-open it as a
+tab, which severs the opener in both directions. `window.open()` returned `null` and the child had
+no `opener`. That is the shape of every OAuth popup flow: the SDK keeps the returned window to poll
+`.closed` and to `.close()`, and the callback page delivers its credential via `opener.postMessage`.
+With neither, a user can complete a sign-in in a window that cannot report back and the app just
+waits — arguably worse than a clean block.
+
+The heuristic failed both ways: an innocent `/login-help` page became a popup, while the common SDK
+pattern of opening `about:blank` and *then* navigating matched nothing and was denied — the very
+case the list existed to catch. The decision now keys on Electron's `disposition`, which is what the
+page actually asked for, so there is nothing to guess.
+
+Two things come free, because the window model already handled popups correctly: the popup registers
+as `windowType: "popup"` (tellable from a user-opened tab) and it **does not steal focus**, so
+untargeted commands keep going to the tab you were driving.
+
+Ordinary `<a target="_blank">` links still open as tabs in the app's tab strip — that behaviour is
+deliberate and unchanged. **Known residual:** a featureless `window.open(url, '_blank')` is
+indistinguishable from a `target="_blank"` link at this layer (both report `foreground-tab`), so it
+still becomes a tab and still returns `null`.
+
 ## 1.12.0 — trustworthy by default
 
 **Trustworthy by default.** A minor, gated on the nine-lens pre-release review: every finding it

package/apps/desktop/main.js

@@ -44,6 +44,44 @@ const IS_PRIVATE = process.env.HALTIJA_PRIVATE === '1'
 // consumer (e.g. a dev-server test lane) can drive this instance.
 const CALLER_PORT_FILE = IS_PRIVATE ? (process.env.HALTIJA_PORT_FILE || null) : null
 
+// A PRIVATE INSTANCE GETS ITS OWN ELECTRON PROFILE.
+//
+// Private mode isolated the ports, the registry, retirement and teardown — but not the profile, so
+// every instance ran with the same `--user-data-dir`. Chromium single-instance locking means the
+// second one to launch cannot take the profile lock and falls back to caches it cannot persist,
+// losing the HTTP cache and the V8 code cache. A large app bundle is then fully re-parsed on every
+// navigation: measured at roughly 10x slower page boots (issue #31).
+//
+// The damage is not just slowness, it is a LIE in the one workflow private mode exists for. Running
+// two versions side by side, the failure followed LAUNCH ORDER rather than version — 22.1s vs 2.04s,
+// and the same version passed or failed depending only on which started first. The reporter nearly
+// wrote up a version regression that did not exist. Every health signal read green throughout,
+// including `hj doctor` and a 120fps rAF cadence, because nothing was broken; it was just slow.
+//
+// Keyed on pid, not port: the private ports are ephemeral and not known yet at this point, and pid
+// is unique across concurrent runs by construction. Set BEFORE `app.whenReady()` and before
+// anything reads `app.getPath('userData')` (preferences.json does), or the isolation is partial —
+// which is how this bug existed at all.
+let PRIVATE_USER_DATA = null
+if (IS_PRIVATE) {
+  PRIVATE_USER_DATA = path.join(os.tmpdir(), `haltija-private-${process.pid}`)
+  try {
+    fs.mkdirSync(PRIVATE_USER_DATA, { recursive: true })
+    app.setPath('userData', PRIVATE_USER_DATA)
+    // Also keep the disk cache with it, so nothing is left in the shared profile.
+    app.setPath('sessionData', PRIVATE_USER_DATA)
+  } catch (err) {
+    // Falling back to the shared profile is slow and pollutes it, but it still WORKS — so say so
+    // loudly rather than refusing to start a run over a temp-directory failure.
+    console.error(
+      `[Haltija Desktop] Could not create a private profile at ${PRIVATE_USER_DATA}: ${err.message}. ` +
+        `Falling back to the shared profile — concurrent private instances will be slow and are ` +
+        `NOT safe to compare against each other (see issue #31).`,
+    )
+    PRIVATE_USER_DATA = null
+  }
+}
+
 // Haltija server config
 let HALTIJA_PORT = IS_PRIVATE ? 0 : parseInt(process.env.HALTIJA_PORT || '8700')
 let HALTIJA_SERVER = `http://localhost:${HALTIJA_PORT}`
@@ -690,28 +728,47 @@ function setupWebContentsInjection(wc) {
 
   console.log('[Haltija Desktop] Monitoring webContents:', wc.id, wc.getType())
 
-  // Intercept window.open() calls - redirect to tabs instead of new windows
-  // Exception: allow auth popups which need to close and callback
-  wc.setWindowOpenHandler(({ url, frameName, features }) => {
-    console.log('[Haltija Desktop] Intercepted window.open:', url)
-
-    // Allow OAuth/auth popups - they need popup behavior to work
-    const isAuthPopup =
-      url.includes('accounts.google.com') ||
-      url.includes('/__/auth/') ||
-      url.includes('/emulator/auth') ||
-      url.includes('firebaseapp.com/__/auth') ||
-      url.includes('oauth') ||
-      url.includes('signin') ||
-      url.includes('login') ||
-      frameName === 'firebaseAuth'
-
-    if (isAuthPopup) {
-      console.log('[Haltija Desktop] Allowing auth popup:', url)
+  // Intercept window.open(): a genuine POPUP stays a popup; an ordinary new-window link becomes a
+  // tab in our own tab strip.
+  //
+  // This used to decide by GUESSING FROM THE URL — allow if it contained `oauth`, `signin`,
+  // `login`, `accounts.google.com`, `/__/auth/`. Everything else was denied and re-opened as a tab,
+  // which severs the opener relationship in both directions: `window.open()` returns **null** and
+  // the child has no `window.opener`. That is the shape of every OAuth popup flow (issue #25):
+  // an SDK keeps the returned WindowProxy to poll `.closed` and to `.close()`, and the callback
+  // page delivers its credential via `opener.postMessage(...)`. With neither, the user can complete
+  // a sign-in in a window that cannot report back — worse than a clean block, because the app just
+  // waits.
+  //
+  // The heuristic failed in both directions: an innocent `/login-help` page became a popup, while
+  // the common SDK pattern of opening `about:blank` and *then* navigating matched nothing and was
+  // denied — the case the list was written to catch.
+  //
+  // `disposition` is what the page actually asked for, so there is nothing to guess (verified
+  // against Electron):
+  //   window.open(url, name, 'width=420,height=320')  -> 'new-window'     features: "width=..."
+  //   window.open(url, '_blank')                      -> 'foreground-tab' features: ""
+  //   <a target="_blank">                             -> 'foreground-tab' features: ""
+  //
+  // Allowing a real popup also fixes two things for free, because the window model already handles
+  // popups correctly: it registers as `windowType: "popup"` (so scripts can tell it from a
+  // user-opened tab) and it does NOT steal focus, since only real tabs become the untargeted
+  // command target.
+  //
+  // KNOWN RESIDUAL: a featureless `window.open(url, '_blank')` is indistinguishable from a
+  // `target="_blank"` link at this layer — both report 'foreground-tab' — so it still becomes a tab
+  // and still returns null. Preserving the tab UX for ordinary links is worth that; if an SDK turns
+  // up that opens featureless popups and needs the opener, this is the line to revisit.
+  wc.setWindowOpenHandler((details) => {
+    const { url, disposition } = details
+    console.log('[Haltija Desktop] Intercepted window.open:', url, `(disposition: ${disposition})`)
+
+    if (disposition === 'new-window') {
+      console.log('[Haltija Desktop] Genuine popup — preserving the opener relationship:', url)
       return { action: 'allow' }
     }
 
-    // Regular links: open as new tab instead of window
+    // Ordinary new-window link: open as a tab instead.
     if (mainWindow && mainWindow.webContents) {
       mainWindow.webContents.send('open-url-in-tab', url)
     }
@@ -1675,11 +1732,24 @@ if (!gotTheLock) {
     }
     // Drop a marker so hj's auto-launch knows the user explicitly quit.
     // Cleared next time the user manually starts Haltija.
-    try {
-      const dir = path.join(os.homedir(), '.haltija')
-      fs.mkdirSync(dir, { recursive: true })
-      fs.writeFileSync(path.join(dir, 'last-quit'), String(Date.now()))
-    } catch {}
+    //
+    // NOT in private mode: `~/.haltija/last-quit` is SHARED state, and an automated run ending is
+    // not the user quitting anything. Writing it suppressed auto-launch for the interactive app the
+    // developer is actually using — the same class as the profile sharing above (#31), where
+    // "private" turned out to mean "private ports" rather than "touches nothing of yours".
+    if (!IS_PRIVATE) {
+      try {
+        const dir = path.join(os.homedir(), '.haltija')
+        fs.mkdirSync(dir, { recursive: true })
+        fs.writeFileSync(path.join(dir, 'last-quit'), String(Date.now()))
+      } catch {}
+    }
+
+    // NOTE: the private profile is deliberately NOT deleted here. Chromium flushes its caches
+    // AFTER 'will-quit', so removing the directory at this point just gets it recreated — measured:
+    // both dirs survived a clean shutdown. Stale profiles are swept at the START of the next
+    // private run instead (see sweepStalePrivateState in bin/tosijs-dev.mjs), keyed on whether the
+    // owning pid is still alive, which is immune to shutdown ordering.
   })
 
   // Handle certificate errors (for self-signed certs in dev)

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.12.0",
+  "version": "1.12.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.12.0";
+  var VERSION = "1.12.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;
@@ -624,6 +624,19 @@
     const candidates = queryAllDeep(parsed.baseSelector).filter((el) => !NON_RENDERED_TEXT.has(el.tagName) && elementTextMatches(el, parsed));
     return candidates.filter((el) => !candidates.some((other) => other !== el && containsDeep(el, other)));
   }
+  function isOffCanvas(el) {
+    const r = el.getBoundingClientRect();
+    return r.right + window.scrollX <= 0 || r.bottom + window.scrollY <= 0;
+  }
+  function isActionable(el) {
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0")
+      return false;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0)
+      return false;
+    return !isOffCanvas(el);
+  }
   function resolveSelector(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
       return document.querySelector(selector) || queryAllDeep(selector)[0] || null;
@@ -631,7 +644,8 @@
     const parsed = parseTextSelector(selector);
     if (!parsed)
       return document.querySelector(selector);
-    return textMatchesInDocument(parsed)[0] || null;
+    const matches = textMatchesInDocument(parsed);
+    return matches.find(isActionable) || matches[0] || null;
   }
   function resolveSelectorAll(selector) {
     if (!TEXT_PSEUDO_RE.test(selector)) {
@@ -5027,6 +5041,9 @@ ${elementSummary}${moreText}`;
       }
       this.render();
     }
+    get isDefunct() {
+      return this.killed;
+    }
     kill() {
       this.killed = true;
       hideHighlight();
@@ -7555,6 +7572,9 @@ ${elementSummary}${moreText}`;
       };
     }
     getHiddenReason(el) {
+      if (isOffCanvas(el)) {
+        return "positioned off-canvas (e.g. left:-9999px) — rendered but not reachable by a user";
+      }
       const rect = el.getBoundingClientRect();
       if (rect.width === 0 && rect.height === 0) {
         return "zero-size bounding rect (element not rendered or in hidden container)";
@@ -8711,6 +8731,7 @@ ${elementSummary}${moreText}`;
     currentTagName = TAG_NAME;
     window.__haltija_resolveSelector = resolveSelector;
     window.__haltija_resolveSelectorAll = resolveSelectorAll;
+    window.__haltija_isActionable = isActionable;
     window.__haltija_refRegistry = refRegistry;
   }
   registerDevChannel();
@@ -8723,6 +8744,9 @@ ${elementSummary}${moreText}`;
       if (existingVersion !== VERSION2) {
         console.log(`${LOG_PREFIX} Version mismatch (${existingVersion} -> ${VERSION2}), replacing`);
         existing.remove();
+      } else if (existing.isDefunct) {
+        console.log(`${LOG_PREFIX} Existing widget is defunct (killed), replacing`);
+        existing.remove();
       } else {
         return existing;
       }

package/bin/hj.mjs

@@ -357,6 +357,58 @@ async function runDoctor(port, portSource, portSourceKind, jsonOutput) {
     if (status.serverVersion && differsBeyondPatch(HJ_VERSION, status.serverVersion)) {
       notes.push(`hj ${HJ_VERSION} is driving server ${status.serverVersion} (version skew)`)
     }
+
+    // Does this tab actually PAINT? `visibilityState` answers "is this tab selected", not "is this
+    // tab being composited", and the two diverge for occluded windows, offscreen windows and a
+    // sleeping display. A starved tab renders nothing while reporting `visible`, geometry probes
+    // still return real numbers, and the absence of an element stops being evidence of anything.
+    //
+    // That is worse than a missing feature: it invites a plausible code-level explanation. An agent
+    // driving a React app found four routes "not mounting" on hard navigation, had a coherent
+    // mechanism (the router gates its first mount on rAF), reproduced it four times, and nearly
+    // filed it as an application bug. Opening a second tab fixed all four (#28). This check is here
+    // to convert that silent, confidently-wrong outcome into a visible one.
+    if (ready && tabs.length) {
+      const probe =
+        `new Promise(r => { const s = Date.now();` +
+        ` const t = setTimeout(() => r({ fired: false, ms: Date.now() - s }), 2000);` +
+        ` requestAnimationFrame(() => { clearTimeout(t); r({ fired: true, ms: Date.now() - s }) }) })`
+      let raf = null
+      try {
+        // BOUND IT. The probe resolves in ~2s at the latest when a browser is there to answer, so a
+        // longer wait means nothing is coming — and doctor is a pre-flight: a lane runs it to find
+        // out quickly, not to sit through another component's timeout. Without this, a connected
+        // 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`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', ...(token ? { 'X-Haltija-Token': token } : {}) },
+          body: JSON.stringify({ code: probe }),
+          signal: cancel,
+        })
+        if (r.ok) {
+          const j = await r.json()
+          if (j && j.success && j.data && typeof j.data.fired === 'boolean') raf = j.data
+        }
+      } catch {
+        // Fall through to the unchecked branch — never a pass.
+      }
+      if (raf === null) {
+        unchecked.push(
+          `could not run the requestAnimationFrame probe — whether this tab actually paints is ` +
+            `UNKNOWN. If elements seem missing, suspect a non-compositing tab before the page.`,
+        )
+      } else if (!raf.fired) {
+        problems.push(
+          `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 ` +
+            `display, and re-run.`,
+        )
+      }
+    }
     // Declared origins decide WHICH tab answers. A broken declaration silently disables the
     // routing it configures, and doctor is where a CI lane finds out.
     const origins = describeOrigins(tabs)

package/bin/private-state.mjs

@@ -0,0 +1,29 @@
+/** ⚠️  AUTO-GENERATED FROM src/private-state.ts — DO NOT EDIT. Run: bun run build */
+// src/private-state.ts
+function stalePrivateEntries(names, deps) {
+  const out = [];
+  for (const name of names) {
+    const m = /^haltija-private-(\d+)(\.json)?$/.exec(name);
+    if (!m)
+      continue;
+    const pid = parseInt(m[1], 10);
+    if (!pid || pid === deps.selfPid)
+      continue;
+    if (deps.isAlive(pid))
+      continue;
+    out.push(name);
+  }
+  return out;
+}
+function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+export {
+  stalePrivateEntries,
+  pidIsAlive
+};

package/bin/tosijs-dev.mjs

@@ -13,10 +13,11 @@
  */
 
 import { spawn, execSync as execSyncImported } from 'child_process'
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync } from 'fs'
 import { homedir, platform, tmpdir } from 'os'
 import { fileURLToPath } from 'url'
 import { dirname, join } from 'path'
+import { stalePrivateEntries, pidIsAlive } from './private-state.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const serverPath = join(__dirname, '../dist/server.js')
@@ -452,8 +453,45 @@ if (privateMode) {
     ? args[portFileIdx + 1]
     : join(tmpdir(), `haltija-private-${process.pid}.json`)
   env.HALTIJA_PORT_FILE = privatePortFile
+  sweepStalePrivateState()
 }
 
+/**
+ * Remove the scratch left by private runs that are no longer alive.
+ *
+ * Two kinds accumulate in tmpdir, both named `haltija-private-<pid>`:
+ *   - the port-file (`<pid>.json`) this launcher writes
+ *   - the Electron profile directory (issue #31), several MB of cache per run
+ *
+ * Swept at STARTUP rather than on exit because Chromium flushes its caches AFTER Electron's
+ * 'will-quit' fires — deleting the profile there simply gets it recreated, which is what happened
+ * when this was first written that way. Liveness of the owning pid is the test, so a sweep can
+ * never touch a concurrent run: the whole point of private mode is that instances don't interfere,
+ * and a cleanup that deletes a live peer's profile would be a far worse bug than the litter.
+ *
+ * Runs for `--private --headless` too, since the launcher is common to both.
+ */
+function sweepStalePrivateState() {
+  const dir = tmpdir()
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  // The decision lives in src/private-state.ts and is unit-tested: never sweep a live peer, never
+  // sweep ourselves, and treat EPERM from kill(pid,0) as ALIVE (the process exists, it is just not
+  // ours to signal). Getting that backwards would delete another user's running instance.
+  for (const name of stalePrivateEntries(entries, { selfPid: process.pid, isAlive: pidIsAlive })) {
+    try {
+      rmSync(join(dir, name), { recursive: true, force: true })
+    } catch {
+      // Best effort — the OS reaps tmpdir eventually, and failing to tidy must never stop a run.
+    }
+  }
+}
+
+
 /** Poll the private instance's port-file until it reports its ephemeral port. */
 /**
  * Wait for a private instance to report its ephemeral port. 30s because this may be waiting on a

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.0'
+export const HJ_VERSION = '1.12.2'