[vishr]

What changed

Fixes the macOS Driga service lifecycle and corrects the MCP and service docs. The findings came from an independent code review; each was checked against main before changing it.

1. HIGH: repairing a stale launch agent that is loaded but not running. internal/service/launchd_darwin.go now runs launchctl itself instead of going through kardianos. Install always runs launchctl bootout gui/$UID/<label> (and ignores "not loaded") before it writes a changed plist. Start runs bootstrap gui/$UID <plist> on an unloaded job and kickstart on a loaded job whose process has exited. Restart uses kickstart -k. Status comes from launchctl print. Nothing calls load or unload any more. The fake launchctl models a launchd domain. In the new loaded-but-not-running test, a stale plist's executable no longer exists. docs/release.md describes the new sequence.
2. HIGH: orphaned launch agent after uninstall. The cask adds uninstall launchctl: "run.driga.service", signal: [["TERM", "run.driga"]] and a zap trash: list covering data, logs, config, caches, prefs, WebKit, saved state and the legacy collector plist. Homebrew skips signal on upgrade, where the app restarts itself. I left out quit because it can stall Homebrew for 10 seconds with an Automation prompt. An upgrade runs the old version's uninstall, launchctl included, so uninstall_preflight first saves the plist to ~/Library/Caches/run.driga. The postflight reinstalls from the live plist or that copy (see Review follow-ups, item 5, for how the copy is now tied to the upgrading brew process).
   For an app deleted without brew, KeepAlive is now PathState {<drigad path>: true}, so launchd stops respawning a missing helper and restarts the job when the path comes back. The service also checks its executable once a minute and exits cleanly when it is gone. The docs, the README and the cask caveats say to run driga service uninstall before deleting the app by hand.
3. MEDIUM: dev and release services collide. Release builds now carry the link-time marker -X github.com/labstack/driga/internal/variant.release=true (moved from internal/service in the follow-ups; empty in snapshots), which .goreleaser.yaml sets on all three builds. Every other build is a development build: just build, just install, go build and go run. It installs run.driga.service.dev, driga-dev on Linux or Driga service (dev) on Windows, and logs under driga-dev. An executable named driga-<name> still uses <name>. docs/usage.md, the README source-build section and CONTRIBUTING are updated.
4. MEDIUM: docs and MCP truthfulness. The README no longer calls the MCP tools read-only; it says driga mcp serves read views plus Driga dashboard edits. The README's paragraph saying the app "removes the service and runs it itself" now describes the current design and how to uninstall. The site's MCP guide and index are corrected too.
   All Chat action tools now have annotations, following Canon mcp.md:
   • run_command: destructive, open world
   • answer_prompt, kill, cleanup: destructive
   • ack_inbox: idempotent, not destructive
   • jump, approve: not destructive
   • summarize: open world (it goes through the Claude CLI)
     The generated MCP reference now shows Destructive and Idempotent columns. A test requires every served tool to carry annotations, and every state-changing tool to set the destructive and open-world hints explicitly.
5. LOW: plist and polling. The plist now sets ProcessType Background and ThrottleInterval 30. The app still checks the lock and process every 2 seconds, which needs no subprocess. Lifecycle reuses the service manager's answer (from launchctl, systemd or Task Scheduler) for 30 seconds while those stay the same, and asks again as soon as the service starts or stops.
6. Environment refresh. On macOS, install compares the complete rendered plist, environment included, with the installed one, so a changed login-shell PATH reaches the service at the next app launch. If the app cannot read the login shell, it reuses the environment the service already records (service.RecordedEnvironment), so a bare Finder PATH never replaces it. On Linux and Windows an existing service keeps its environment, which the docs now state.

Why

kardianos/service's darwin backend uses launchctl load/unload and checks status with list. It cannot tell a loaded-but-not-running job from a stopped one, and load refuses a job launchd already has. The domain commands handle both cases. A link-time marker is the only build-independent way to tell a release from a checkout build, since nothing produced the driga-dev executable name.

Risk and rollout

• No store migration. Nothing changes in agent settings or captured text, and nothing new signals or kills processes. The cask's signal only TERMs the Driga app when it is uninstalled.
• After upgrading, every existing macOS plist is rewritten once, because the KeepAlive, ProcessType and ThrottleInterval keys changed. That causes one service restart.
• Anyone running a checkout build as run.driga.service gets a second service under the .dev label the next time they install. Run driga service uninstall with the old build first (documented in usage.md).
• ProcessType Background applies launchd's background resource policy (lower CPU and I/O priority) to the collector, which also serves Chat and actions. Watch whether the app feels slower; Adaptive is the fallback.
• Not verified against real launchd or a real Homebrew install. Both are tested only through fakes: a fake launchctl domain, and the cask's Ruby block run under a fake DSL with a temporary HOME.

Contract changes

• MCP: Chat action tools gain annotations. Names, arguments and results are unchanged.
• Service labels: non-release builds install the .dev / -dev label.
• CLI: driga service install --refresh-env (see Review follow-ups). No config keys or schema changes.

Verified

Run on macOS (darwin/arm64) on the host:

• gofmt -l . is clean, go mod tidy -diff, go vet ./... (native, GOOS=windows, GOOS=linux)
• go run ./cmd/driga-docgen --check, go generate ./internal/config with no .env.example diff
• scripts/isolated.sh go test -count=1 ./...: all packages pass
• scripts/isolated.sh go test -race on internal/service, internal/mcp, internal/desktop, scripts: pass (I did not run the full just race)
• Cask Ruby block tested with Ruby 4.0 in four scenarios: fresh install, existing service, upgrade through the kept copy, and a stale copy
• Not run: just ui-check / design-check (UI untouched), goreleaser check / just snapshot (goreleaser is not installed locally; CI's snapshot job covers it), actionlint, govulncheck

Follow-ups

• SMAppService migration (SMAppService.agent(plistName:) with the plist inside the bundle) is deliberately left out of this PR. It would replace the launch agent registration and give users the Login Items UI.
• An event-driven service status in the app (for example a lock-file watch) instead of the 2-second lock poll.
• Environment refresh for existing Linux and Windows services.
• Check ProcessType Background against real Chat and actions latency.

Review follow-ups

Findings from the Opus and Codex reviews of this PR, a full Codex review of main (breaking changes accepted), and automated security review of the follow-ups. Each was checked against the code first.

1. bootout/bootstrap race. bootout now polls launchctl print until launchd has let the job go (100 ms steps, at most 10 s) and treats 36 as in progress. bootstrap retries 5/36/37 with backoff (6 attempts) and counts a job another client loaded only when it runs. Start no longer kicks a job it just bootstrapped, and watches a loaded-but-not-running job for 1 s before kicking it, so a definition being torn down is bootstrapped instead. The fake launchctl gained a mode where a job stays loaded for N prints after bootout (kickstart during teardown fails the test). Tests: teardown wait, Stop then Start, Start on a job being torn down, bootstrap backoff, bounded wait.
2. No GUI session. Exit 112 / "Could not find domain" maps to ErrNoGUISession ("log in to the desktop session to start the Driga service"). Uninstall treats it as not loaded and still deletes the plist. Stop is a no-op. Start, Restart and Status return the message. Install writes the plist for launchd to load at the next login. Covered by a domain-absent fake.
3. Environment churn. The app's login-shell environment is now the only source. The app runs driga service install --refresh-env. A plain driga service install keeps the environment the plist records. A restart caused by a changed environment logs the variable names only (service_env_changed). Doctor's stale-plist hint names --refresh-env.
4. Lifecycle cache. Control clears the registration cache, so the tray asks launchctl again right after any action.
5. Cask plist heuristic. The 10-minute rule is gone. uninstall_preflight names its copy run.driga.service.<brew pid>.plist and deletes it from at_exit. Only the same brew process's postflight restores it, however long the upgrade takes. Copies from other processes are deleted and never restored. The restored plist keeps its recorded environment, so the postflight runs a plain service install with no /usr/bin/env pass-through. scripts/macos_app_test.go covers fresh, existing, a slow upgrade (day-old copy, must restore), an ordinary uninstall (no copy left after brew exits, and a later install must not restore) and another process's copy. Deviation: a brew reinstall also restores the service, because it runs uninstall launchctl too.
6. Snapshots marked as releases. The marker is {{ if not .IsSnapshot }}true{{ end }} on all three builds. A test renders the ldflags for both cases. CONTRIBUTING, usage and the release guide are updated.
7. Dev-build advice. usage.md drops the "uninstall with the old build first" advice: installing a release replaces whatever holds the release's label.
8. Dev data directory. The marker moved to the new internal/variant package, which config and service both read. Development builds default to driga-dev for data and spool (~/Library/Application Support/driga-dev, ~/.local/share/driga-dev, ~/.local/state/driga-dev/events, %LOCALAPPDATA%\driga-dev). The config file is still shared. The settings reference and .env.example are regenerated.
9. Source install builds only driga. The README, the site install guide and the release guide now build driga and link drigad (or just build). driga service install checks that the drigad it would run exists and is executable, and errors clearly if not.
10. Renamed Driga.app. BundlePath accepts any <name>.app with driga/drigad in Contents/MacOS whose Info.plist says CFBundleIdentifier is run.driga. self.CLI maps the nested Driga Service.app back to the outer bundle whatever its name. Tests cover a renamed bundle, another app with the same layout, and a bundle without an Info.plist.
11. Repair without rollback. Install renders and checks the new plist (label and program) and writes it beside the old one with an fsync. Only then does it boot the job out (waiting as in item 1), rename the new plist into place and bootstrap it. If launchd refuses it, the previous plist is restored and bootstrapped again, and the error says so. The Control comment now describes this. Tests cover a refused definition (the old one runs again) and a bounded teardown wait (old plist untouched, no temp file left behind).
12. Spool permissions. Append fchmods the day file it writes to 0600 and the directory to 0700. spool.Protect tightens the directory and every file, and the service runs it at start and at each hourly prune (private DACL on Windows). Tested with a 0755 dir and 0644 files.
13. README "read-only MCP". Verified: driga mcp registers action tools only for Chat's MCP child (o.Chat), so "read views plus dashboard edits" is accurate.

Security review of the follow-ups (internal/command, run_command sandbox policy):

14. Denylist missed other variants' state. The new config.StateDirs lists the config file and default config dir, this process's data/spool overrides, and the data and state directories of release, -dev and any driga-<name> variant found. The policy denies all of them, plus driga, driga-dev and driga-* under each HOME default root regardless of XDG variables. Tested with defaults, overrides, a symlink and a relative path.
15. Symlink canonicalization differential. canonical now resolves like the kernel. It walks from the root, splices each symlink target relative to the already-resolved prefix, never cleans .. lexically, bounds hops at 40, and follows dangling links. Existing paths go to EvalSymlinks first. Tests: a relative link inside a symlinked parent, an absolute link, a dangling tail, .. after links, and a loop.
16. Windows rooted targets. Volume-less rooted targets (\x) resolve at the link's drive. Tests are platform-independent table tests.
17. Windows device/volume targets. Fail closed: only relative, rooted and drive-absolute (C:\x) targets resolve. UNC, \\?\ (including Volume{GUID} and GLOBALROOT), \\.\, drive-relative C:x and other colon forms return errUnresolvableLink, and the classifier refuses a path through one (Never).

Breaking changes

• Development builds (just build, go build, go run, GoReleaser snapshots) use their own driga-dev data and spool directories, so they no longer see the release's database. The link-time marker is now -X github.com/labstack/driga/internal/variant.release=true.
• On macOS, driga service install keeps the service's recorded environment. Pass --refresh-env to record the calling shell's.
• Driga.app is found by bundle identifier and layout, so renamed bundles work. A bundle whose Info.plist does not say run.driga is no longer treated as Driga.app.
• run_command refuses a path through a Windows symlink whose target is UNC, \\?\, \\.\ or drive-relative.

Follow-up verification

Run on macOS (darwin/arm64) on the host:

• gofmt -l . clean, go mod tidy -diff, go vet ./... native, GOOS=windows and GOOS=linux
• go run ./cmd/driga-docgen --check; go generate ./internal/config leaves no .env.example diff
• scripts/isolated.sh go test -count=1 ./...: all packages pass
• -race on internal/service, variant, config, spool, self, command, cli, desktop, collector and scripts: pass
• Cask Ruby block under the fake DSL: fresh, existing, slow upgrade, ordinary uninstall followed by a later install, another process's copy
• Still not verified against real launchd, a real Homebrew upgrade, or Windows hosts. The exit codes 112, 5, 36 and 37 come from launchctl documentation and the reviews, not from observation. The Windows path tests are host-independent tables, not runs on Windows. just ui-check, goreleaser check and just snapshot were not run.

https://claude.ai/code/session_01XkoYQXnzjsCqogTYDHrxNJ