Skip to content

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.

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.md
index 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 from
it — a stalled system index that only `sudo mdutil -E /` repairs; `jarvis
doctor` 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.md
index 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-user
install is moved over by rename, keeping its signature and TCC grants, and the
LaunchAgent is pointed at the new path in the same step (BUG-218). A same-named
app 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. Windows
and Linux are
unchanged — their index announcements already feed the search the user types
into.
diff --git a/install/installer.py b/install/installer.py
index 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 True
console.print(
"[bad]│ ✗ desktop app registration failed — installation stopped. "
diff --git a/jarvis/setup/desktop_integration.py b/jarvis/setup/desktop_integration.py
index 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 for
the 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.py
new file mode 100644
index 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.py
index 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: AN
monkeypatch.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 agents
diff --git a/tests/unit/install/test_installer_flow.py b/tests/unit/install/test_installer_flow.py
index 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().out
assert rc == 0
assert "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.py
new file mode 100644
index 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()