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
fix(windows): point the Start-Menu entry at our own exe, not at pythonw
Haraldaea5a652aeed
diff --git a/jarvis/ui/icon_utils.py b/jarvis/ui/icon_utils.pyindex cf7567b59e..21972221cb 100644--- a/jarvis/ui/icon_utils.py+++ b/jarvis/ui/icon_utils.py@@ -142,6 +142,32 @@ def _pythonw_executable() -> Path | None:return exe if exe.exists() else None+def _shortcut_launch_target() -> Path | None:+ """What the Start-Menu shortcut should launch — our own exe when we have one.++ Windows does not list a shortcut whose target is a GENERIC HOST as an app.+ That is not a quirk: the same rule hides the shell's own+ ``Command Prompt`` (cmd.exe), ``Run`` (rundll32.exe) and ``File Explorer``+ entries from the app list, because one host executable cannot stand for the+ many different things launched through it. A shortcut aimed at+ ``pythonw.exe`` falls in that bucket, so the entry exists on disk, opens the+ app on a double-click, and is still absent from Windows Search — the exact+ report from 2026-08-16, next to an Obsidian and a Discord entry that work+ because each points at its own ``.exe``.++ ``PersonalJarvis.exe`` built inside the venv IS our own executable and needs+ no environment handed to it, so it is a valid shortcut target and makes the+ entry a real app. The other branded homes need ``__PYVENV_LAUNCHER__``,+ which a shortcut cannot supply — those keep the historical ``pythonw``+ target, where the branded copy is reached through the re-exec in ``main()``+ instead. Falls back to ``pythonw`` whenever no branded copy can be built.+ """+ branded = ensure_branded_launcher_exe()+ if branded is not None and _is_self_contained_branded_exe(branded):+ return branded+ return _pythonw_executable()++def _interpreter_can_open_a_window() -> bool:"""Does the RUNNING interpreter have the toolkit the desktop window needs?@@ -276,28 +302,75 @@ def _user_launcher_dir() -> Path | None:return Path(local) / WINDOWS_BRANDED_LAUNCHER_DIR_NAME / "bin"-def _branded_launcher_candidates() -> list[Path]:- """Target paths for the branded copy, best first.-- 1. NEXT TO the base interpreter — it finds ``pythonXX.dll`` without any- extra file, but needs a writable base dir (admin-only under- ``Program Files``).- 2. The per-user dir — always writable, but the interpreter runtime DLLs- must be copied beside the exe (see ``_interpreter_runtime_dlls``).+def _venv_pythonw_executable() -> Path | None:+ """The venv's OWN ``pythonw.exe``, when this process runs inside a venv.- In both homes the venv/base is re-attached at launch via+ Unlike the base interpreter this is a real ~250 KB launcher binary even when+ the base Python came from the Microsoft Store, and it locates its+ environment from ``pyvenv.cfg`` one directory up — by its LOCATION, not its+ file name. A renamed copy beside it therefore boots the same venv with no+ ``__PYVENV_LAUNCHER__`` and no copied runtime DLLs, which is what makes it+ the only branding source that survives a Store install (see+ ``_branded_launcher_candidates``).+ """+ exe = Path(sys.executable)+ cand = exe.with_name("pythonw.exe")+ if not cand.is_file():+ return None+ if not (cand.parent.parent / "pyvenv.cfg").is_file():+ return None # not a venv layout — the copy would not find an environment+ try:+ if cand.stat().st_size == 0:+ return None # an alias, not a launcher+ except OSError:+ return None+ return cand+++def _branded_launcher_candidates() -> list[tuple[Path, Path]]:+ """``(source, target)`` pairs for the branded copy, best first.++ 1. INSIDE THE VENV, copied from the venv's own launcher. Self-contained: the+ copy finds its environment from ``pyvenv.cfg`` by location, so it needs+ no ``__PYVENV_LAUNCHER__`` and is therefore a valid *shortcut target* —+ the others are not. This is also the only home that works on a **Microsoft+ Store** Python, where the base "interpreter" is a 0-byte app-execution+ alias and its real binary sits in an unwritable ``WindowsApps`` folder+ whose copies refuse to run outside their app container (forensic+ 2026-08-16: that is why branding silently failed on such a machine and+ the app never appeared in Windows Search — see+ ``_shortcut_launch_target``).+ 2. NEXT TO the base interpreter — finds ``pythonXX.dll`` without any extra+ file, but needs a writable base dir (admin-only under ``Program Files``).+ 3. The per-user dir — always writable, but the interpreter runtime DLLs must+ be copied beside the exe (see ``_interpreter_runtime_dlls``).++ In homes 2 and 3 the venv/base is re-attached at launch via``__PYVENV_LAUNCHER__``, so path resolution inside the child is identical."""+ candidates: list[tuple[Path, Path]] = []+ venv = _venv_pythonw_executable()+ if venv is not None:+ candidates.append((venv, venv.with_name(BRANDED_LAUNCHER_EXE_NAME)))base = _base_pythonw_executable()- if base is None:- return []- candidates = [base.with_name(BRANDED_LAUNCHER_EXE_NAME)]- user_dir = _user_launcher_dir()- if user_dir is not None:- candidates.append(user_dir / BRANDED_LAUNCHER_EXE_NAME)+ if base is not None:+ candidates.append((base, base.with_name(BRANDED_LAUNCHER_EXE_NAME)))+ user_dir = _user_launcher_dir()+ if user_dir is not None:+ candidates.append((base, user_dir / BRANDED_LAUNCHER_EXE_NAME))return candidates+def _is_self_contained_branded_exe(exe: Path) -> bool:+ """Does this branded copy run the app without ``__PYVENV_LAUNCHER__``?++ True only for the in-venv copy (home 1): it resolves its environment from+ its own location. That is exactly the property a Start-Menu shortcut needs,+ since a shortcut carries no environment of its own.+ """+ return (exe.parent.parent / "pyvenv.cfg").is_file()++def _interpreter_runtime_dlls(src_dir: Path) -> list[Path]:"""The DLLs a *relocated* ``pythonw`` copy needs beside it to start.@@ -312,13 +385,18 @@ def _interpreter_runtime_dlls(src_dir: Path) -> list[Path]:def _branded_copy_boots(exe: Path) -> bool:- """One out-of-process start of a freshly built *relocated* branded copy.-- A relocated copy that cannot load its runtime DLLs dies before any window- exists — and the re-exec parent has already exited, so a broken copy would- mean NO app at all (observed during development). Verified once at build- time with the same ``__PYVENV_LAUNCHER__`` re-attach as the real launch;- on failure the caller deletes the copy and falls back to bare ``pythonw``.+ """One out-of-process start of a freshly built branded copy.++ A copy that cannot load its runtime DLLs dies before any window exists — and+ the re-exec parent has already exited, so a broken copy would mean NO app at+ all (observed during development). Since the in-venv copy is also the+ Start-Menu shortcut's target, a broken one there would leave the user with a+ Start-Menu entry that does nothing, so every fresh copy is verified.++ The start mirrors how that copy is really launched: a self-contained in-venv+ copy gets NO ``__PYVENV_LAUNCHER__``, because a shortcut hands it no+ environment either; the other homes get the same re-attach ``main()`` uses.+ On failure the caller deletes the copy and falls back to bare ``pythonw``."""try:import subprocess@@ -327,7 +405,9 @@ def _branded_copy_boots(exe: Path) -> bool:env = dict(os.environ)venv_pythonw = Path(sys.executable).with_name("pythonw.exe")- if venv_pythonw.is_file():+ if _is_self_contained_branded_exe(exe):+ env.pop("__PYVENV_LAUNCHER__", None)+ elif venv_pythonw.is_file():env["__PYVENV_LAUNCHER__"] = str(venv_pythonw)proc = subprocess.run( # noqa: S603 — our own freshly built exe[str(exe), "-c", "import sys; sys.exit(0)"],@@ -372,21 +452,18 @@ def ensure_branded_launcher_exe() -> Path | None:"""if sys.platform != "win32":return None- src = _base_pythonw_executable()- if src is None:- return Noneico = project_icon_path()if not ico.is_file():return None- try:- # MS Store base exe is a 0-byte alias → unbrandable.- if src.stat().st_size == 0:- logger.debug("base pythonw is a 0-byte alias (MS Store); cannot brand")- return None- except OSError as exc:- logger.debug("base pythonw not statable; cannot brand: {}", exc)- return None- for target in _branded_launcher_candidates():+ for src, target in _branded_launcher_candidates():+ try:+ # A 0-byte app-execution alias (MS Store) copies to an empty husk.+ if src.stat().st_size == 0:+ logger.debug("{} is a 0-byte alias (MS Store); skipping", src)+ continue+ except OSError as exc:+ logger.debug("{} not statable; skipping: {}", src, exc)+ continuebuilt = _ensure_branded_copy_at(src, target, ico)if built is not None:return built@@ -425,8 +502,12 @@ def _ensure_branded_copy_at(src: Path, target: Path, ico: Path) -> Path | None:# remove it so the caller falls through to the next home / bare pythonw._unlink_quietly(target)return None- if relocated and not _branded_copy_boots(target):- logger.debug("relocated branded copy does not boot, discarding: {}", target)+ # Smoke-start EVERY fresh copy, not just a relocated one. The in-venv+ # copy is the Start-Menu shortcut's target, so a broken one would leave+ # a Start-Menu entry that does nothing at all — worse than the generic+ # pythonw target it replaces. Runs once per rebuild, never per launch.+ if not _branded_copy_boots(target):+ logger.debug("branded copy does not boot, discarding: {}", target)_unlink_quietly(target)return Nonelogger.debug("Branded launcher exe ready: {}", target)@@ -474,8 +555,17 @@ def maybe_reexec_through_branded_launcher(argv: list[str]) -> int | None:# real running image is ``sys._base_executable`` (our branded copy).if os.environ.get(_BRANDED_LAUNCH_ENV) == "1":return None+ branded_name = BRANDED_LAUNCHER_EXE_NAME.lower()base_exe = getattr(sys, "_base_executable", "") or ""- if Path(base_exe).name.lower() == BRANDED_LAUNCHER_EXE_NAME.lower():+ if Path(base_exe).name.lower() == branded_name:+ return None+ # The in-venv branded copy IS the running image, yet `_base_executable`+ # still names the interpreter behind it (a Store alias, say) — so the check+ # above cannot see it and the app re-exec'd through the very exe that had+ # just started it. Harmless (the child sets the env marker and stops) but a+ # wasted process and boot delay on every Start-Menu launch, which is the+ # normal way in once the shortcut targets this exe.+ if Path(sys.executable).name.lower() == branded_name:return None# A visible-console/debug run wants python.exe's console; re-exec'ing through# a windowless pythonw copy would swallow it. Leave those alone.@@ -620,7 +710,7 @@ def ensure_start_menu_shortcut(logger.debug("pywin32 unavailable; Start-Menu shortcut not ensured: {}", exc)return False- pythonw = _pythonw_executable()+ pythonw = _shortcut_launch_target()if pythonw is None:return Falseico = icon_path or project_icon_path()diff --git a/tests/unit/ui/test_branded_launcher.py b/tests/unit/ui/test_branded_launcher.pyindex 478d3e1e88..fbe4d01a39 100644--- a/tests/unit/ui/test_branded_launcher.py+++ b/tests/unit/ui/test_branded_launcher.py@@ -65,33 +65,65 @@ def test_reexec_skips_a_debug_console_run(monkeypatch: pytest.MonkeyPatch) -> No@pytest.mark.skipif(sys.platform != "win32", reason="Windows-only branding")-def test_branded_candidates_prefer_base_then_user_dir(+def test_branded_candidates_prefer_the_venv_then_base_then_user_dir(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:- """Candidate 1 sits beside the BASE pythonw (zero-copy DLL adjacency);- candidate 2 is the always-writable per-user dir — the fix for machines- where the base dir is read-only (Program Files installs)."""+ """Candidate 1 sits INSIDE the venv, copied from the venv's own launcher —+ self-contained (finds its environment from pyvenv.cfg), so it is the only+ one usable as a Start-Menu shortcut target, and the only one that survives a+ Microsoft Store Python. Candidate 2 sits beside the BASE pythonw (zero-copy+ DLL adjacency); candidate 3 is the always-writable per-user dir — the fix+ for machines where the base dir is read-only (Program Files installs)."""monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))candidates = icon_utils._branded_launcher_candidates()if not candidates:- pytest.skip("no base pythonw resolvable in this environment")- assert candidates[0].parent == Path(sys.base_prefix)- assert candidates[1] == tmp_path / "PersonalJarvis" / "bin" / (- icon_utils.BRANDED_LAUNCHER_EXE_NAME- )- assert all(c.name == icon_utils.BRANDED_LAUNCHER_EXE_NAME for c in candidates)+ pytest.skip("no interpreter resolvable in this environment")+ venv = icon_utils._venv_pythonw_executable()+ targets = [t for _src, t in candidates]+ if venv is not None:+ assert candidates[0] == (venv, venv.with_name(icon_utils.BRANDED_LAUNCHER_EXE_NAME))+ targets = targets[1:]+ if icon_utils._base_pythonw_executable() is not None:+ assert targets[0].parent == Path(sys.base_prefix)+ assert targets[1] == tmp_path / "PersonalJarvis" / "bin" / (+ icon_utils.BRANDED_LAUNCHER_EXE_NAME+ )+ assert all(t.name == icon_utils.BRANDED_LAUNCHER_EXE_NAME for _s, t in candidates)@pytest.mark.skipif(sys.platform != "win32", reason="Windows-only branding")-def test_no_localappdata_means_base_candidate_only(+def test_no_localappdata_drops_only_the_per_user_home(monkeypatch: pytest.MonkeyPatch,) -> None:monkeypatch.delenv("LOCALAPPDATA", raising=False)candidates = icon_utils._branded_launcher_candidates()if not candidates:- pytest.skip("no base pythonw resolvable in this environment")- assert len(candidates) == 1- assert candidates[0].parent == Path(sys.base_prefix)+ pytest.skip("no interpreter resolvable in this environment")+ targets = [t for _s, t in candidates]+ # Nothing may point into the (now unknown) per-user dir.+ assert all("PersonalJarvis\\bin" not in str(t) for t in targets)+ if icon_utils._base_pythonw_executable() is not None:+ assert any(t.parent == Path(sys.base_prefix) for t in targets)++[email protected](sys.platform != "win32", reason="Windows-only branding")+def test_venv_copy_is_recognised_as_self_contained() -> None:+ """Only a copy inside the venv resolves its environment by location, which+ is what lets a shortcut (which carries no environment) launch it."""+ venv = icon_utils._venv_pythonw_executable()+ if venv is None:+ pytest.skip("not running inside a venv")+ branded = venv.with_name(icon_utils.BRANDED_LAUNCHER_EXE_NAME)+ assert icon_utils._is_self_contained_branded_exe(branded) is True+ # A per-user home has no pyvenv.cfg above it, so it is NOT self-contained.+ user_dir = icon_utils._user_launcher_dir()+ if user_dir is not None:+ assert (+ icon_utils._is_self_contained_branded_exe(+ user_dir / icon_utils.BRANDED_LAUNCHER_EXE_NAME+ )+ is False+ )def _fake_interpreter_dir(tmp_path: Path) -> Path:@@ -187,7 +219,9 @@ def test_unwritable_first_home_falls_through_to_the_user_dir(bad = blocker / icon_utils.BRANDED_LAUNCHER_EXE_NAMEgood = tmp_path / "user" / "bin" / icon_utils.BRANDED_LAUNCHER_EXE_NAMEmonkeypatch.setattr(icon_utils, "_base_pythonw_executable", lambda: src)- monkeypatch.setattr(icon_utils, "_branded_launcher_candidates", lambda: [bad, good])+ monkeypatch.setattr(+ icon_utils, "_branded_launcher_candidates", lambda: [(src, bad), (src, good)]+ )monkeypatch.setattr(icon_utils, "project_icon_path", lambda: ico)assert icon_utils.ensure_branded_launcher_exe() == good@@ -196,11 +230,22 @@ def test_unwritable_first_home_falls_through_to_the_user_dir(@pytest.mark.skipif(sys.platform != "win32", reason="Windows-only branding")-def test_ms_store_alias_base_is_not_branded(monkeypatch: pytest.MonkeyPatch) -> None:- """A 0-byte base exe (the MS Store app-execution alias) must bail gracefully."""+def test_ms_store_alias_base_is_skipped_not_copied(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A 0-byte base exe (the MS Store app-execution alias) copies to an empty+ husk, so that source must be skipped rather than branded.++ Not the same as "no branding at all" any more: on a Store install the venv's+ own launcher is a real binary and takes over (see the venv candidate). This+ pins the SOURCE rule — never copy an alias — while leaving that fallback+ free to succeed, which is what put the app back in Windows Search.+ """fake_base = icon_utils._base_pythonw_executable()if fake_base is None:pytest.skip("no base pythonw resolvable")+ # Isolate the base-source rule: drop the venv candidate for this test.+ monkeypatch.setattr(icon_utils, "_venv_pythonw_executable", lambda: None)real_stat = os.statdiff --git a/tests/unit/ui/test_start_menu_shortcut_target.py b/tests/unit/ui/test_start_menu_shortcut_target.pyindex 35c4ea395b..558afe4692 100644--- a/tests/unit/ui/test_start_menu_shortcut_target.py+++ b/tests/unit/ui/test_start_menu_shortcut_target.py@@ -128,6 +128,100 @@ class TestShortcutWriterRefusesADeadTarget:assert sc.Arguments.strip() == f"-m {icon_utils._LAUNCHER_MODULE}"+class TestShortcutTargetsOurOwnExe:+ """Windows will not list a shortcut aimed at a GENERIC HOST as an app.++ Forensic 2026-08-16, second half: the .lnk existed, opened the app on a+ double-click, and was still absent from Windows Search. Its target was+ `pythonw.exe`. The shell applies the same rule to its own entries — that is+ why `Command Prompt` (cmd.exe), `Run` (rundll32.exe) and `File Explorer` are+ likewise missing from the app list, while Obsidian and Discord, each aimed+ at its own .exe, are present.++ So the shortcut has to point at OUR exe. The in-venv `PersonalJarvis.exe`+ is the one branded copy that needs no environment handed to it, which is+ exactly what a shortcut can't supply.+ """++ def test_prefers_a_self_contained_branded_exe(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ branded = tmp_path / "Scripts" / "PersonalJarvis.exe"+ monkeypatch.setattr(icon_utils, "ensure_branded_launcher_exe", lambda: branded)+ monkeypatch.setattr(+ icon_utils, "_is_self_contained_branded_exe", lambda p: True+ )+ assert icon_utils._shortcut_launch_target() == branded++ def test_falls_back_to_pythonw_when_the_copy_needs_an_environment(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """A per-user-dir copy needs __PYVENV_LAUNCHER__, which a shortcut has+ no way to set — pointing at it would produce an entry that does nothing."""+ branded = tmp_path / "bin" / "PersonalJarvis.exe"+ monkeypatch.setattr(icon_utils, "ensure_branded_launcher_exe", lambda: branded)+ monkeypatch.setattr(+ icon_utils, "_is_self_contained_branded_exe", lambda p: False+ )+ assert icon_utils._shortcut_launch_target() == icon_utils._pythonw_executable()++ def test_falls_back_when_nothing_can_be_branded(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ monkeypatch.setattr(icon_utils, "ensure_branded_launcher_exe", lambda: None)+ assert icon_utils._shortcut_launch_target() == icon_utils._pythonw_executable()++ @windows_only+ def test_self_contained_test_keys_off_pyvenv_cfg(self, tmp_path: Path) -> None:+ scripts = tmp_path / "venv" / "Scripts"+ scripts.mkdir(parents=True)+ exe = scripts / "PersonalJarvis.exe"+ assert icon_utils._is_self_contained_branded_exe(exe) is False+ (tmp_path / "venv" / "pyvenv.cfg").write_text("home = x", encoding="utf-8")+ assert icon_utils._is_self_contained_branded_exe(exe) is True++ @windows_only+ def test_written_shortcut_points_at_a_real_launchable_file(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """End to end: whatever target is chosen, it must exist on disk."""+ programs = tmp_path / "Programs"+ programs.mkdir()+ monkeypatch.setattr(icon_utils, "_interpreter_can_open_a_window", lambda: True)+ assert icon_utils.ensure_start_menu_shortcut(+ aumid=_TEST_AUMID, programs_dir=programs+ )+ from win32com.client import Dispatch++ sc = Dispatch("WScript.Shell").CreateShortcut(+ str(programs / icon_utils.START_MENU_SHORTCUT_NAME)+ )+ assert Path(sc.TargetPath).is_file(), "shortcut points at a missing exe"+++class TestReexecLoopGuard:+ """Launching THROUGH the branded exe must not re-exec through it again."""++ @windows_only+ def test_running_as_the_branded_exe_short_circuits(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """`sys._base_executable` still names the interpreter behind the branded+ copy (a Store alias, say), so the older guard could not see this and the+ app spawned a second process on every Start-Menu launch."""+ monkeypatch.delenv(icon_utils._BRANDED_LAUNCH_ENV, raising=False)+ monkeypatch.delenv("JARVIS_DEBUG", raising=False)+ monkeypatch.setattr(+ icon_utils.sys,+ "executable",+ r"C:\proj\.venv\Scripts\PersonalJarvis.exe",+ )+ monkeypatch.setattr(+ icon_utils.sys, "_base_executable", r"C:\store\pythonw.exe", raising=False+ )+ assert icon_utils.maybe_reexec_through_branded_launcher([]) is None++class TestShellIsToldAboutTheEntry:"""Writing the file is half the job — the app index needs the notification.