Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(ci): a WebGL scene that never gives its context back fails the build
Harald06ebee83ec3e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 8891d5f0f6..eddd7fd850 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -393,6 +393,13 @@ jobs:# fails only when a file GAINS one. Mirrors pre-push.run: python scripts/ci/check_silent_exception_handlers.py+ - name: WebGL-context gate (every 3D surface gives its context back)+ # Static + stdlib-only: a browser allows ~16 live WebGL contexts and+ # kills the OLDEST to make room, and three.js `dispose()` never returns+ # one — so a scene that mounts without releasing eventually kills a+ # different, innocent scene on the page (AP-32).+ run: python scripts/ci/check_webgl_contexts_released.py+- name: CLI reference drift gate (docs in sync with command tree)# Fails if a curated command was added/changed without regenerating# docs/jarvis-cli-reference.md. Mirrors the pre-push docgen gate.diff --git a/AGENTS.md b/AGENTS.mdindex f998ce47ac..fbb602a9ba 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -85,7 +85,7 @@ kill-on-crash + tool broker (ADR-0025/26); UTF-8 + `NO_WINDOW_CREATIONFLAGS`on every subprocess. Safety tiers safe/monitor/ask/block, blacklist >whitelist > default; only `ToolExecutor.execute()`; skills stay `draft`.-## 7. Anti-patterns AP-1..31 (BINDING)+## 7. Anti-patterns AP-1..32 (BINDING)Full register: `docs/agent-contract.md` §7; §8 there reads it backward(symptom → cause) when you are debugging. Essence: no keys via voice/chat;enum strings in ALL five layers; no spawn tools in worker sets; atomic TOML@@ -94,7 +94,8 @@ the boot critical path; no LLM in the voice scrubber; native inference = lock+ fresh-model recover; GPU wake gates ONLY on the inference probe; wakeverification word-agnostic, never transcript content; no `isinstance` gateson unpinned libs; signing private keys ONLY in GH Actions secrets; no silent-`except`; no unread config switch.+`except`; no unread config switch; a WebGL scene releases its context and+survives losing it.## 9. Operational reality & gitWorking tree is SHARED: stage only YOUR files (`git add -p`/pathspec, neverdiff --git a/CLAUDE.md b/CLAUDE.mdindex f998ce47ac..fbb602a9ba 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -85,7 +85,7 @@ kill-on-crash + tool broker (ADR-0025/26); UTF-8 + `NO_WINDOW_CREATIONFLAGS`on every subprocess. Safety tiers safe/monitor/ask/block, blacklist >whitelist > default; only `ToolExecutor.execute()`; skills stay `draft`.-## 7. Anti-patterns AP-1..31 (BINDING)+## 7. Anti-patterns AP-1..32 (BINDING)Full register: `docs/agent-contract.md` §7; §8 there reads it backward(symptom → cause) when you are debugging. Essence: no keys via voice/chat;enum strings in ALL five layers; no spawn tools in worker sets; atomic TOML@@ -94,7 +94,8 @@ the boot critical path; no LLM in the voice scrubber; native inference = lock+ fresh-model recover; GPU wake gates ONLY on the inference probe; wakeverification word-agnostic, never transcript content; no `isinstance` gateson unpinned libs; signing private keys ONLY in GH Actions secrets; no silent-`except`; no unread config switch.+`except`; no unread config switch; a WebGL scene releases its context and+survives losing it.## 9. Operational reality & gitWorking tree is SHARED: stage only YOUR files (`git add -p`/pathspec, neverdiff --git a/docs/agent-contract.md b/docs/agent-contract.mdindex b557dbbabe..e0e4b2462d 100644--- a/docs/agent-contract.md+++ b/docs/agent-contract.md@@ -492,6 +492,33 @@ downgrades to `safe` (anti-confirmation-fatigue contract). Direct| AP-23 | Build or test only against the maintainer's config/keys/OS and claim done | Whole surface bricked for every other downloader; verify §3's paths || AP-30 | Catch an exception and neither log, re-raise, nor say why silence is right | The feature just does nothing and nobody can tell it failed — the single largest source of "it only half works" (gate: `check_silent_exception_handlers.py`) || AP-31 | Add a config field nothing reads, or leave a switch whose value is ignored | `jarvis.toml` and the settings screen promise behaviour that does not exist (gate: `check_config_switches_wired.py`) |+| AP-32 | Mount a WebGL renderer without giving the context back | A browser allows ~16 live contexts and kills the OLDEST to make room, so the leak kills a DIFFERENT, innocent scene — and the browser paints its broken-canvas placeholder there (gate: `check_webgl_contexts_released.py`) |++### AP-32 — Never mount a WebGL renderer without a release path++A browser gives a page a small, fixed number of live WebGL contexts (Chromium:+16) and enforces the cap by silently taking the OLDEST one away. `dispose()`+does not return a context — only `WEBGL_lose_context` / `forceContextLoss()`+does. So the component that leaks is never the one that breaks: the scene that+dies is whichever has been running longest, and the browser paints its own+broken-canvas placeholder there — a white rectangle with a small sad face —+while the app carries on believing everything is fine. Measured 2026-08-21:+fourteen trips into the Wiki section and back left fifteen live contexts behind+ONE canvas, and the deck's memory map (mounted since boot) went white.++Two obligations, and the second is as binding as the first, because a GPU reset+takes every context no matter how clean the release path is:++1. **Give it back.** On unmount, hand the context to the browser.+2. **Survive losing it.** `webglcontextlost` must call `preventDefault()` —+ without it the browser never fires `webglcontextrestored` — and the scene+ must be rebuilt on a fresh canvas. When rebuilding fails repeatedly, degrade+ honestly (the flat map) with the REAL reason, never a dead canvas.++Both live in `jarvis/ui/web/frontend/src/hooks/useWebglSurface.ts`; use it+rather than re-deriving them. Note the trap it documents: React commits the+rebuilt child BEFORE running the old effect's cleanup, so touching the graph+ref in that cleanup reaches the NEW scene and pauses it.### AP-24 — Never share a native inference engine between concurrent callers@@ -594,6 +621,7 @@ adds no rules of its own. Detail in [`docs/BUGS.md`](BUGS.md).| Wake fires on silence, or goes deaf on its own word | Wake transcript trap (BUG-037) | One root, not two: word-agnostic verification only (AP-27) || A feature "half works" and nothing is logged | Silent handler | Log, re-raise, or say why silence is right (AP-30) || A settings switch changes nothing | Unwired config | Read the value or delete the field (AP-31) |+| A white rectangle with a small sad face where a 3D view was | Lost WebGL context | Release the context on unmount and rebuild on loss — `useWebglSurface` (AP-32) |---diff --git a/scripts/ci/check_webgl_contexts_released.py b/scripts/ci/check_webgl_contexts_released.pynew file mode 100644index 0000000000..d633efaa21--- /dev/null+++ b/scripts/ci/check_webgl_contexts_released.py@@ -0,0 +1,115 @@+"""WebGL-context gate.++A browser hands a page a small, fixed number of live WebGL contexts —+Chromium's cap is 16 — and it enforces the cap by silently taking the OLDEST+context away when a new one is asked for. Nothing in three.js gives one back:+``WebGLRenderer.dispose()`` frees buffers and textures, not the context. Only+``WEBGL_lose_context.loseContext()`` (three's ``forceContextLoss()``) does.++So a component that mounts a WebGL renderer and never releases it spends one+of those sixteen slots per mount, for the lifetime of the page. On 2026-08-21+fourteen trips into the Wiki section and back left FIFTEEN live contexts behind+one canvas, and the browser killed the longest-running scene on the page — the+deck's memory map — leaving Chromium's own broken-canvas placeholder there: a+white rectangle with a small sad face. Nothing in the app noticed, because+without a ``webglcontextlost`` handler that calls ``preventDefault()`` the+browser never offers the context back either.++This gate enforces the invariant: **every frontend module that mounts a WebGL+renderer must also give the context back and survive losing it.** In practice+that means using ``hooks/useWebglSurface.ts``, which does both; a module that+calls ``WEBGL_lose_context`` itself (the capability probe in+``lib/graphDimension.ts``) also satisfies it.++Static analysis only — it never runs a bundler, so it is cheap and+dependency-free. Run from CI and covered by+``tests/unit/ui/test_webgl_contexts_released.py``.+"""+from __future__ import annotations++import argparse+import re+import sys+from pathlib import Path++_REPO = Path(__file__).resolve().parents[2]+_FRONTEND = _REPO / "jarvis" / "ui" / "web" / "frontend" / "src"++#: An import of the 3D graph renderer, a hand-rolled three.js renderer, or a+#: raw WebGL context. Type-only imports are excluded at the call site: a module+#: that merely names `NodeObject` never owns a context.+_MOUNTS: tuple[tuple[str, re.Pattern[str]], ...] = (+ ("react-force-graph-3d", re.compile(r"^\s*import\s+(?!type\b)[^\n]*react-force-graph-3d", re.M)),+ ("new WebGLRenderer", re.compile(r"\bnew\s+(?:THREE\.)?WebGLRenderer\b")),+ ("@react-three/fiber", re.compile(r"^\s*import\s+(?!type\b)[^\n]*@react-three/fiber", re.M)),+ ("getContext(\"webgl\")", re.compile(r"""getContext\(\s*['"]webgl2?['"]""")),+)++#: Proof that the module hands the context back. `useWebglSurface` is the+#: shared way; the other three are what it (or an equivalent) calls.+_RELEASES: tuple[str, ...] = (+ "useWebglSurface",+ "releaseWebglContext",+ "WEBGL_lose_context",+ "forceContextLoss",+)++#: Files whose WebGL use is a test double or a fixture, never a live scene.+_TEST_SUFFIXES = (".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx")+++def _is_test(path: Path) -> bool:+ return path.name.endswith(_TEST_SUFFIXES) or "__tests__" in path.parts+++def offenders(root: Path | None = None) -> list[tuple[str, str]]:+ """Return (repo-relative path, what it mounts) for every unreleased scene."""+ base = root or _FRONTEND+ found: list[tuple[str, str]] = []+ for path in sorted(base.rglob("*.ts*")):+ if _is_test(path):+ continue+ try:+ text = path.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ continue+ mounted = next((label for label, rx in _MOUNTS if rx.search(text)), None)+ if not mounted:+ continue+ if any(token in text for token in _RELEASES):+ continue+ found.append((_label(path), mounted))+ return found+++def _label(path: Path) -> str:+ """Repo-relative where possible; the tests scan a tmp tree of their own."""+ try:+ return path.relative_to(_REPO).as_posix()+ except ValueError:+ return path.as_posix()+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.parse_args(argv)+ bad = offenders()+ if not bad:+ print("WebGL-context gate: every 3D surface releases its context.")+ return 0+ print("WebGL contexts that are taken and never given back:\n", file=sys.stderr)+ for path, mounted in bad:+ print(f" {path} (mounts: {mounted})", file=sys.stderr)+ print(+ "\nUse `useWebglSurface(hostRef)` from @/hooks/useWebglSurface and put its\n"+ "`generation` on the renderer as a `key`. It releases the context on\n"+ "unmount and rebuilds the scene when the browser takes one away — without\n"+ "it the sixteenth mount kills the oldest scene on the page and the browser\n"+ "paints a white canvas with a sad face over it (AP-32).",+ file=sys.stderr,+ )+ return 1+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/tests/unit/ui/test_webgl_contexts_released.py b/tests/unit/ui/test_webgl_contexts_released.pynew file mode 100644index 0000000000..ac35585bb5--- /dev/null+++ b/tests/unit/ui/test_webgl_contexts_released.py@@ -0,0 +1,76 @@+"""The WebGL-context gate must hold: no 3D surface keeps a context forever.++A browser gives a page ~16 live WebGL contexts and takes the OLDEST away to+make room for a seventeenth. Since `WebGLRenderer.dispose()` does not return+one, a scene that mounts without releasing spends a slot per mount — and the+scene that dies is not the greedy one, it is the longest-running one on the+page. That is how the deck's memory map turned into the browser's own+broken-canvas placeholder on 2026-08-21 (AP-32).++These tests protect the mechanism, not one component: the gate has to stay+green on the shipped tree AND still catch a fresh offender.+"""+from __future__ import annotations++import importlib.util+from pathlib import Path++_REPO = Path(__file__).resolve().parents[3]+_GATE = _REPO / "scripts" / "ci" / "check_webgl_contexts_released.py"+++def _load_gate():+ spec = importlib.util.spec_from_file_location("check_webgl_contexts_released", _GATE)+ mod = importlib.util.module_from_spec(spec)+ assert spec and spec.loader+ spec.loader.exec_module(mod)+ return mod+++def test_every_shipped_3d_surface_releases_its_context():+ gate = _load_gate()+ bad = gate.offenders()+ assert bad == [], (+ "these modules mount a WebGL renderer and never hand the context back: "+ f"{bad}. Use useWebglSurface(hostRef) and key the renderer on its generation."+ )+++def test_the_gate_catches_a_scene_that_never_releases(tmp_path: Path):+ """A new 3D view added without the hook must fail, or the gate is decoration."""+ gate = _load_gate()+ offender = tmp_path / "NewSpaceView.tsx"+ offender.write_text(+ 'import ForceGraph3D from "react-force-graph-3d";\n'+ "export const NewSpaceView = () => <ForceGraph3D graphData={{nodes: [], links: []}} />;\n",+ encoding="utf-8",+ )++ found = gate.offenders(tmp_path)++ assert [name for name, _ in found], "the gate did not notice an unreleased context"+ assert found[0][1] == "react-force-graph-3d"+++def test_a_type_only_import_is_not_a_mounted_scene(tmp_path: Path):+ """The deck card names the library's types without ever owning a context."""+ gate = _load_gate()+ (tmp_path / "TypesOnly.tsx").write_text(+ 'import type { NodeObject } from "react-force-graph-3d";\n'+ "export type N = NodeObject;\n",+ encoding="utf-8",+ )++ assert gate.offenders(tmp_path) == []+++def test_releasing_by_hand_also_passes(tmp_path: Path):+ """The capability probe returns its context directly; that counts."""+ gate = _load_gate()+ (tmp_path / "probe.ts").write_text(+ 'const gl = canvas.getContext("webgl2");\n'+ 'gl?.getExtension("WEBGL_lose_context")?.loseContext();\n',+ encoding="utf-8",+ )++ assert gate.offenders(tmp_path) == []