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(macos): put the installed app in the Dock once and name a stalled Spotlight index
Harald Herzdf7c0bd1fa92
diff --git a/docs/BUGS.md b/docs/BUGS.mdindex 5ee1fa1729..6f0a863220 100644--- a/docs/BUGS.md+++ b/docs/BUGS.md@@ -15429,3 +15429,19 @@ for every suite.Mac this was verified on, 71 of 72 apps in `/Applications` were missing fromit — a stalled system index that only `sudo mdutil -E /` repairs; `jarvisdoctor` names it. No app can fix that without an administrator password.++**Follow-up 2026-09-17 (installed, and still nowhere to be seen).** The user+reported the app missing from the Dock and from Spotlight. Two separate causes.+*Dock:* no installer path ever added a tile, so a finished install was only+startable by someone who already knew where it lived. `jarvis/setup/macos_dock.py`+adds the tile once per install (`--pin-to-dock`, passed by the installer only);+a marker remembers it, so a user who drags the app out keeps it out, a+same-named DMG build's tile is never touched, and uninstall removes ours so no+"?" tile stays behind. *Spotlight:* the Mac's index had stopped absorbing+anything new days earlier — a fresh probe file was not indexed either, and no+app installed after that date was findable. `mdimport` is accepted and changes+nothing; only `sudo mdutil -E /` repairs it. The installer now proves the stall+(`wait_until_indexed` returns `False`) and prints that command instead of+finishing silently on an app search cannot find. Launchpad listed the app all+along. Guards: `tests/unit/setup/test_macos_dock.py`,+`tests/unit/install/test_installer_flow.py`.diff --git a/docs/os-parity.md b/docs/os-parity.mdindex fbcb93a8ef..7490626245 100644--- a/docs/os-parity.md+++ b/docs/os-parity.md@@ -326,7 +326,10 @@ falling back to `~/Applications` for standard accounts; an existing per-userinstall is moved over by rename, keeping its signature and TCC grants, and theLaunchAgent is pointed at the new path in the same step (BUG-218). A same-namedapp with another bundle id (the DMG build) is never replaced or removed, and a-certificate-signed bundle's `Info.plist` version follows source updates. Windows+certificate-signed bundle's `Info.plist` version follows source updates. The+installer adds the app to the Dock once per install (the macOS counterpart of+the Windows Desktop/Start-menu launcher) and names a stalled Spotlight index+with its admin repair command. Windowsand Linux areunchanged — their index announcements already feed the search the user typesinto.diff --git a/install/installer.py b/install/installer.pyindex 5dd2fb692f..ce08ac8e88 100644--- a/install/installer.py+++ b/install/installer.py@@ -556,6 +556,41 @@ def _write_desktop_integration_log(result: object) -> Path | None:return log_path+_SPOTLIGHT_PROBE = (+ "from jarvis.setup.macos_app_bundle import macos_app_bundle_path\n"+ "from jarvis.setup.macos_search_index import wait_until_indexed\n"+ "print(wait_until_indexed(macos_app_bundle_path()))\n"+)+++def _note_stalled_spotlight() -> None:+ """Say so when this Mac's Spotlight will not find the app just installed.++ Spotlight answers from an index macOS owns. When that index has stalled —+ it accepts the import and never lists the app — the app is in Finder and+ Launchpad but typing its name finds nothing, which reads as a failed+ install. Only an administrator can rebuild the index, so the installer+ names the one command instead of leaving the user to guess.+ """+ try:+ result = subprocess.run(+ [str(venv_python()), "-c", _SPOTLIGHT_PROBE],+ cwd=repo_root(),+ capture_output=True,+ text=True,+ timeout=90,+ check=False,+ )+ except (OSError, subprocess.TimeoutExpired):+ # The probe is a courtesy; an install never fails over it.+ return+ if (result.stdout or "").strip().splitlines()[-1:] != ["False"]:+ return+ note("Spotlight on this Mac is not indexing new apps, so search will not find")+ note(f"{PRODUCT_NAME} yet (Finder › Applications, Launchpad and the Dock do).")+ note("To repair the macOS search index, run: sudo mdutil -E /")++def step_desktop_integration(*, enabled: bool, dry_run: bool) -> bool:"""Register the managed install with the current desktop shell."""if not enabled:@@ -578,6 +613,8 @@ def step_desktop_integration(*, enabled: bool, dry_run: bool) -> bool:# across every future update. Trusting it is the one step macOS# guards with a password dialog — say so before it appears.argv.append("--create-signing-identity")+ # Once per install; a user who removes the tile keeps it removed.+ argv.append("--pin-to-dock")console.print("[muted]│ macOS may ask for your login password once: it trusts the "f"local signing certificate that keeps {PRODUCT_NAME}'s permissions "@@ -606,6 +643,8 @@ def step_desktop_integration(*, enabled: bool, dry_run: bool) -> bool:and report.get("attempted")):ok("desktop app registered with the operating system")+ if sys.platform == "darwin":+ _note_stalled_spotlight()return Trueconsole.print("[bad]│ ✗ desktop app registration failed — installation stopped. "diff --git a/jarvis/setup/desktop_integration.py b/jarvis/setup/desktop_integration.pyindex 2bc5c8f262..8ed30a0501 100644--- a/jarvis/setup/desktop_integration.py+++ b/jarvis/setup/desktop_integration.py@@ -319,6 +319,7 @@ def ensure_desktop_integration(macos_applications_dir: Path | None = None,linux_applications_dir: Path | None = None,macos_create_signing_identity: bool = False,+ macos_pin_to_dock: bool = False,) -> DesktopIntegrationReport:"""Install or repair the current platform's desktop-shell artifacts.@@ -326,7 +327,8 @@ def ensure_desktop_integration(installer already registered the app and nothing here may touch it.``macos_create_signing_identity`` permits the one-time trust dialog forthe per-user signing certificate — the installer's call only, never the- app's background repair.+ app's background repair. ``macos_pin_to_dock`` is the installer's too: it+ adds the app to the Dock once per install (``macos_dock``)."""plat = _platform(platform)@@ -418,6 +420,11 @@ def ensure_desktop_integration()if bundle is not None:artifacts.append("applications_bundle")+ if macos_pin_to_dock:+ from jarvis.setup.macos_dock import pin_to_dock_once++ if pin_to_dock_once(bundle):+ artifacts.append("dock_tile")else:reason = macos_app_bundle.last_error() or "unknown error"warnings.append(@@ -521,6 +528,11 @@ def remove_desktop_integration(try:from jarvis.setup.macos_app_bundle import remove_macos_app_bundle+ if macos_applications_dir is None:+ from jarvis.setup.macos_dock import remove_from_dock++ if remove_from_dock():+ artifacts.append("dock_tile")if remove_macos_app_bundle(applications_dir=macos_applications_dir):artifacts.append("applications_bundle")else:@@ -566,6 +578,11 @@ def main(argv: list[str] | None = None) -> int:action="store_true",help="macOS: create and trust the per-user signing certificate (one password dialog)",)+ parser.add_argument(+ "--pin-to-dock",+ action="store_true",+ help="macOS: add the app to the Dock, once per install",+ )args = parser.parse_args(argv)report = (@@ -575,6 +592,7 @@ def main(argv: list[str] | None = None) -> int:install_dir=args.install_dir,require_managed=not args.allow_unmanaged,macos_create_signing_identity=args.create_signing_identity,+ macos_pin_to_dock=args.pin_to_dock,))if args.json:diff --git a/jarvis/setup/macos_dock.py b/jarvis/setup/macos_dock.pynew file mode 100644index 0000000000..041f8d5d98--- /dev/null+++ b/jarvis/setup/macos_dock.py@@ -0,0 +1,177 @@+"""Keep the managed macOS app in the Dock — once, and only once.++A Mac user looks for an app in three places: the Applications folder,+Spotlight, and the Dock. The first is a file, the second an index macOS owns;+the Dock is a preference list, and an installer that never touches it leaves a+freshly installed app reachable only by someone who already knows where it is.++The tile is added exactly once per install, recorded by a marker: a user who+drags the app out of the Dock has made a decision, and no update or repair may+undo it. Uninstall takes the tile back out, so no "?" tile is left pointing at+a deleted app. Everything here is best-effort, macOS-only and never raises.+"""++from __future__ import annotations++import logging+import plistlib+import subprocess+import sys+from pathlib import Path+from urllib.parse import unquote, urlparse++from jarvis.core.branding import MACOS_APP_DIR_NAME, MACOS_BUNDLE_ID+from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS++log = logging.getLogger(__name__)++_DEFAULTS = "/usr/bin/defaults"+_KILLALL = "/usr/bin/killall"+_DOCK_DOMAIN = "com.apple.dock"+_MARKER_FILENAME = "macos-dock-pinned"+_TIMEOUT_S = 30+++def _marker_path() -> Path:+ from jarvis.core.paths import user_data_dir++ return user_data_dir() / _MARKER_FILENAME+++def _run(argv: list[str]) -> subprocess.CompletedProcess[bytes] | None:+ if sys.platform != "darwin" or not Path(argv[0]).is_file():+ return None+ try:+ return subprocess.run( # noqa: S603 - fixed system path, no shell+ argv,+ timeout=_TIMEOUT_S,+ stdin=subprocess.DEVNULL,+ capture_output=True,+ check=False,+ creationflags=NO_WINDOW_CREATIONFLAGS,+ )+ except (OSError, subprocess.SubprocessError) as exc:+ log.debug("%s did not run: %s", Path(argv[0]).name, exc)+ return None+++def _persistent_apps() -> list[dict] | None:+ """The Dock's app tiles, or ``None`` when the preferences are unreadable."""+ result = _run([_DEFAULTS, "export", _DOCK_DOMAIN, "-"])+ if result is None or result.returncode != 0:+ return None+ try:+ tiles = plistlib.loads(result.stdout).get("persistent-apps", [])+ except (ValueError, plistlib.InvalidFileException) as exc:+ log.debug("Dock preferences are unreadable: %s", exc)+ return None+ return [tile for tile in tiles if isinstance(tile, dict)]+++def is_our_tile(tile: dict) -> bool:+ """Whether a Dock tile is the managed app, wherever it points.++ Matches the bundle id the Dock recorded, or — for a tile written before+ the Dock resolved it — the bundle directory name at the end of its URL.+ """+ data = tile.get("tile-data")+ if not isinstance(data, dict):+ return False+ if data.get("bundle-identifier") == MACOS_BUNDLE_ID:+ return True+ file_data = data.get("file-data")+ url = file_data.get("_CFURLString") if isinstance(file_data, dict) else None+ if not isinstance(url, str):+ return False+ path = unquote(urlparse(url).path if "://" in url else url).rstrip("/")+ return Path(path).name == MACOS_APP_DIR_NAME and "bundle-identifier" not in data+++def _tile_for(bundle: Path) -> dict:+ return {+ "tile-type": "file-tile",+ "tile-data": {+ "bundle-identifier": MACOS_BUNDLE_ID,+ "file-label": bundle.stem,+ "file-type": 41,+ "file-data": {+ "_CFURLString": bundle.as_uri() + "/",+ "_CFURLStringType": 15,+ },+ },+ }+++def _xml_fragment(value: dict) -> str:+ """``defaults write -array`` takes one XML plist fragment per element."""+ document = plistlib.dumps(value, fmt=plistlib.FMT_XML).decode("utf-8")+ start = document.index("<dict>")+ return document[start : document.rindex("</dict>") + len("</dict>")]+++def _restart_dock() -> None:+ # The Dock only reads its preferences at launch; launchd restarts it at once.+ _run([_KILLALL, "Dock"])+++def pin_to_dock_once(bundle: Path) -> bool:+ """Add ``bundle`` to the Dock unless this install already did so once.++ Returns ``True`` only when a tile was added now.+ """+ marker = _marker_path()+ if marker.exists():+ return False+ tiles = _persistent_apps()+ if tiles is None:+ return False+ added = False+ if not any(is_our_tile(tile) for tile in tiles):+ result = _run(+ [+ _DEFAULTS,+ "write",+ _DOCK_DOMAIN,+ "persistent-apps",+ "-array-add",+ _xml_fragment(_tile_for(bundle)),+ ]+ )+ if result is None or result.returncode != 0:+ log.debug("The Dock tile could not be written.")+ return False+ _restart_dock()+ added = True+ log.info("Added %s to the Dock.", bundle.name)+ try:+ marker.parent.mkdir(parents=True, exist_ok=True)+ marker.write_text("1\n", encoding="utf-8")+ except OSError as exc:+ # Without the marker the next installer run looks again; it finds the+ # tile and adds nothing, so the cost is one more look.+ log.debug("Could not record the Dock pin: %s", exc)+ return added+++def remove_from_dock() -> bool:+ """Take the managed app's tile out of the Dock; ``True`` when one was removed."""+ _marker_path().unlink(missing_ok=True)+ tiles = _persistent_apps()+ if tiles is None:+ return False+ kept = [tile for tile in tiles if not is_our_tile(tile)]+ if len(kept) == len(tiles):+ return False+ result = _run(+ [_DEFAULTS, "write", _DOCK_DOMAIN, "persistent-apps", "-array"]+ + [_xml_fragment(tile) for tile in kept]+ )+ if result is None or result.returncode != 0:+ log.debug("The Dock tile could not be removed.")+ return False+ _restart_dock()+ log.info("Removed the app from the Dock.")+ return True+++__all__ = ["is_our_tile", "pin_to_dock_once", "remove_from_dock"]diff --git a/tests/conftest.py b/tests/conftest.pyindex ad0193117b..99427218f1 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -140,6 +140,12 @@ def _macos_shell_registration_in_tmp(tmp_path_factory, monkeypatch): # noqa: ANmonkeypatch.setattr(autostart_macos, "_launchctl", lambda *_argv: True)monkeypatch.setattr(mab, "_LSREGISTER", str(agents / "no-lsregister"))monkeypatch.setattr(search_index, "_MDIMPORT", str(agents / "no-mdimport"))+ # ``defaults write com.apple.dock`` + ``killall Dock`` on a developer's Mac.+ import jarvis.setup.macos_dock as macos_dock++ monkeypatch.setattr(macos_dock, "_DEFAULTS", str(agents / "no-defaults"))+ monkeypatch.setattr(macos_dock, "_KILLALL", str(agents / "no-killall"))+ monkeypatch.setattr(macos_dock, "_marker_path", lambda: agents / "macos-dock-pinned")yield agentsdiff --git a/tests/unit/install/test_installer_flow.py b/tests/unit/install/test_installer_flow.pyindex 0ca3f07bfa..027537703d 100644--- a/tests/unit/install/test_installer_flow.py+++ b/tests/unit/install/test_installer_flow.py@@ -213,3 +213,40 @@ def test_update_summary_promises_no_reonboarding(monkeypatch, capsys, tmp_path)out = capsys.readouterr().outassert rc == 0assert "no re-onboarding" in out+++class _ProbeResult:+ def __init__(self, stdout: str) -> None:+ self.stdout = stdout+++ ("probe_output", "expect_note"),+ [("False\n", True), ("True\n", False), ("None\n", False), ("", False)],+)+def test_a_stalled_spotlight_index_is_named_with_its_repair_command(+ monkeypatch: pytest.MonkeyPatch, probe_output: str, expect_note: bool+) -> None:+ """Reported 2026-09-17: installed, in Launchpad, and Spotlight found nothing+ — the Mac's index had stopped absorbing new apps. Only a proven stall+ (import accepted, app never listed) may speak; "unknown" stays silent."""+ notes: list[str] = []+ monkeypatch.setattr(installer, "note", notes.append)+ monkeypatch.setattr(+ installer.subprocess, "run", lambda *_a, **_kw: _ProbeResult(probe_output)+ )++ installer._note_stalled_spotlight()++ assert any("sudo mdutil -E /" in line for line in notes) is expect_note+++def test_a_spotlight_probe_that_cannot_run_never_fails_the_install(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def _boom(*_a, **_kw):+ raise OSError("no interpreter")++ monkeypatch.setattr(installer.subprocess, "run", _boom)++ installer._note_stalled_spotlight()diff --git a/tests/unit/setup/test_macos_dock.py b/tests/unit/setup/test_macos_dock.pynew file mode 100644index 0000000000..a053b20465--- /dev/null+++ b/tests/unit/setup/test_macos_dock.py@@ -0,0 +1,136 @@+"""The installed app is in the Dock — once, and the user's choice after that.++Reported 2026-09-17: a finished install left the app out of the Dock, so the+only way to start it was to already know where it lived. These tests pin that+the installer adds one tile, never a second, never again after the user+removed it, never confuses the same-named DMG build with itself, and that+uninstall leaves no dead tile behind.+"""++from __future__ import annotations++import plistlib+import sys+from pathlib import Path++import pytest++import jarvis.setup.macos_dock as dock++_BUNDLE = Path("/Applications/Personal Jarvis.app")+++def _tile(url: str, bundle_id: str | None) -> dict:+ data: dict = {"file-data": {"_CFURLString": url, "_CFURLStringType": 15}}+ if bundle_id is not None:+ data["bundle-identifier"] = bundle_id+ return {"tile-type": "file-tile", "tile-data": data}+++_SAFARI = _tile("file:///Applications/Safari.app/", "com.apple.Safari")+_OURS = _tile("file:///Applications/Personal%20Jarvis.app/", "com.personal-jarvis.desktop")+_DMG = _tile("file:///Applications/Personal%20Jarvis.app/", "ai.personaljarvis.desktop")+++class _Result:+ def __init__(self, stdout: bytes = b"") -> None:+ self.returncode = 0+ self.stdout = stdout+++def fake_dock(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):+ """A Dock whose preferences live in a list; records every command."""+ state = {"tiles": [_SAFARI]}+ calls: list[list[str]] = []++ def _run(argv: list[str]):+ calls.append(argv)+ if argv[1] == "export":+ return _Result(plistlib.dumps({"persistent-apps": state["tiles"]}))+ return _Result()++ monkeypatch.setattr(sys, "platform", "darwin")+ monkeypatch.setattr(dock, "_run", _run)+ monkeypatch.setattr(dock, "_marker_path", lambda: tmp_path / "macos-dock-pinned")+ return state, calls+++def _writes(calls: list[list[str]]) -> list[list[str]]:+ return [argv for argv in calls if argv[1] == "write"]+++def test_a_fresh_install_lands_in_the_dock(fake_dock) -> None:+ _state, calls = fake_dock++ assert dock.pin_to_dock_once(_BUNDLE) is True++ (write,) = _writes(calls)+ assert write[2:5] == ["com.apple.dock", "persistent-apps", "-array-add"]+ tile = plistlib.loads(b'<plist version="1.0">' + write[5].encode("utf-8") + b"</plist>")+ assert tile["tile-data"]["file-data"]["_CFURLString"] == (+ "file:///Applications/Personal%20Jarvis.app/"+ )+ assert dock.is_our_tile(tile)+ assert calls[-1] == [dock._KILLALL, "Dock"]+++def test_a_tile_the_user_removed_stays_removed(fake_dock) -> None:+ """The marker, not the Dock, remembers that the pin already happened."""+ _state, calls = fake_dock+ dock.pin_to_dock_once(_BUNDLE)+ calls.clear()++ assert dock.pin_to_dock_once(_BUNDLE) is False+ assert calls == []+++def test_an_app_already_in_the_dock_gets_no_second_tile(fake_dock) -> None:+ state, calls = fake_dock+ state["tiles"] = [_SAFARI, _OURS]++ assert dock.pin_to_dock_once(_BUNDLE) is False+ assert _writes(calls) == []+++def test_the_dmg_build_is_not_mistaken_for_the_managed_app() -> None:+ assert dock.is_our_tile(_OURS)+ assert not dock.is_our_tile(_DMG)+ assert not dock.is_our_tile(_SAFARI)+ # Written by us, not yet resolved by the Dock: recognised by its name.+ assert dock.is_our_tile(_tile("file:///Users/u/Applications/Personal%20Jarvis.app/", None))+++def test_uninstall_takes_only_our_tile_out(fake_dock) -> None:+ state, calls = fake_dock+ state["tiles"] = [_SAFARI, _OURS, _DMG]++ assert dock.remove_from_dock() is True++ (write,) = _writes(calls)+ assert write[2:5] == ["com.apple.dock", "persistent-apps", "-array"]+ kept = [+ plistlib.loads(b'<plist version="1.0">' + raw.encode("utf-8") + b"</plist>")+ for raw in write[5:]+ ]+ assert kept == [_SAFARI, _DMG]+++def test_uninstall_without_a_tile_leaves_the_dock_alone(fake_dock) -> None:+ _state, calls = fake_dock++ assert dock.remove_from_dock() is False+ assert _writes(calls) == []+ assert [dock._KILLALL, "Dock"] not in calls+++def test_unreadable_dock_preferences_change_nothing(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ monkeypatch.setattr(dock, "_run", lambda _argv: None)+ marker = tmp_path / "macos-dock-pinned"+ monkeypatch.setattr(dock, "_marker_path", lambda: marker)++ assert dock.pin_to_dock_once(_BUNDLE) is False+ # Nothing was decided, so the next installer run looks again.+ assert not marker.exists()