feat: macOS menu bar tray app for github-scan daemon

[serenakeyitan]

Summary

Implements the macOS menu bar tray proposed in #408. Native SwiftUI app, distributed via the existing first-tree github scan install command, integrated as a thin client of the daemon's /inbox HTTP surface.

The install command is now idempotent — re-running it on a host with a live daemon gracefully restarts that daemon instead of erroring out.

User-visible changes

• macOS users: first-tree github scan install prompts to install the menu bar app (default yes). Two prompts: install yes/no, and silent first-launch yes/no.
• Linux / Windows users: no behavior change. The darwin platform check guards every tray code path.
• Re-install: previously errored with "daemon already running". Now detects the running daemon (via lock file + pid liveness check) and gracefully restarts it.

Risk

The change touches the install command's daemon-start path, which all macOS users hit. Mitigations:

• Daemon-only flow (--no-tray) is unchanged on macOS and unaffected on other platforms.
• Self-healing detection is fail-safe: if lock.env is unreadable or the pid isn't found, the code falls through to the existing "start fresh" path. No new error paths.
• The CLI flags (--tray, --no-tray, --keep-quarantine[=yes|no]) are additive; no existing flags change meaning.

Rollback

If a regression surfaces post-merge, reverting this PR restores the prior install behavior verbatim. The tray app it leaves on disk at ~/.first-tree/tray/ becomes inert (not started by install after revert) — users who want it removed run apps/tray-mac/scripts/uninstall-tray.sh --purge from a checkout.

Verification

• Lint / typecheck / unit tests: pass via pnpm ci:check. The smoke tests for runInstall were updated to await the now-async function.
• Build: pnpm build and swift build pass on a clean tree.
• E2E (manual, isolated environment): clean install, re-install with a running daemon, stale-lock recovery, and --no-tray flow all produce the expected outcomes; the production daemon was untouched throughout.

Out of scope (tracked separately)

• Pre-build menu bar tray .app into the npm tarball #393 — pre-build .app in npm tarball (kills the ~90s inline Swift compile).
• fix(github-scan): launchd label collides across different GITHUB_SCAN_DIR values #394 — launchd label collision across distinct GITHUB_SCAN_DIR values.
• Apple Developer signing + notarization (no issue yet; tracked in [Design] macOS menu bar tray for github-scan #408).

---

Design proposal: #408
Tracks: #393, #394

[bingran-you]

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

Two blocking issues stood out in review:

1. apps/tray-mac/Sources/FirstTreeTray/App.swift:983
Pause Instead only calls inbox.markPaused(true) and closes the window. It never invokes pauseDaemon() / startPauseInBackground, so the daemon keeps running while the tray flips to paused. Thirty seconds later InboxModel.refresh() will even fire the "Daemon is still running" drift notification (App.swift:177-197), and a later Resume click fails because start sees the daemon is already alive. This needs to actually stop the daemon or the button text/behavior needs to change.

2. apps/tray-mac/Sources/FirstTreeTray/App.swift:381
   The fallback CLI resolution is broken. When the binary is not in one of the three hardcoded paths, firstTreeBinaryURL returns /usr/bin/env, but runCLI() still passes ["github", "scan", ...] as the argv (App.swift:350-356). That executes env github ..., not env first-tree github ..., so pause/resume/stop fails for any install that lives elsewhere on PATH (for example nonstandard npm/pnpm global bins). The fallback needs to resolve first-tree explicitly or prepend it to the args.

I also ran swift build in apps/tray-mac; it completed successfully.

[bingran-you]

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

Both blocking issues from my prior review are addressed in bef87db. LGTM.

1. Pause Instead (App.swift:993): Now calls daemon.startPauseInBackground(inbox: inbox), which awaits pauseDaemon() before flipping markPaused(true) — same path as the menu bar Pause button. The drift notification + "already running" Resume failure are no longer reachable from this button.

2. CLI fallback (App.swift:386-395): firstTreeInvocation(args:) now returns ("/usr/bin/env", ["first-tree"] + args) in the fallback branch, so the spawned process is env first-tree github scan … instead of env github scan …. Combined with runtimePath being injected into the child env, env will resolve first-tree against the configured PATH (nvm/Homebrew/~/.local/bin/system bins).

[serenakeyitan]

Thanks for the re-review @bingran-you — confirming both fixes landed in bef87db (Pause Instead now routes through startPauseInBackground; CLI fallback prepends first-tree so env resolves it on PATH). Branch is behind main, so I'll rebase and land. This reply was drafted by github-scan, an autonomous agent running on behalf of the account owner.

[bingran-you]

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

Re-reviewing after @liuchao-001's pass — both of their findings reproduce against the current head (583b1d0), and both are genuine regressions/gaps that I missed in my earlier approval. Switching back to changes-requested.

1. Tray install only works from a source checkout (packages/github-scan/src/github-scan/engine/commands/install.ts:262-272, apps/cli/scripts/copy-github-scan-assets.mjs:23-50)

Confirmed. findRepoRoot() walks up looking for apps/tray-mac/scripts/install-tray.sh. The published first-tree package only ships dist/ (apps/cli/package.json:26-28), and the prepack copy step copies assets/dashboard.html, README.md, VERSION, and skills/ — nothing under apps/tray-mac/. So on a real npm i -g first-tree (or pnpm global), the loop walks up from dist/, never finds the marker, returns null, and installTrayInteractive exits at line 271 without prompting or warning. The headline tray feature is invisible to anyone who isn't in a repo checkout.

Two viable fixes:

• Bundle apps/tray-mac/{Sources,scripts,Package.swift,…} (or at minimum the install script + a prebuilt .app) into dist/ via the prepack script and have findRepoRoot() accept the bundled location too. This pairs naturally with #393.
• Until #393 lands, gate the prompt on findRepoRoot() succeeding and print a one-line "tray not bundled with this build — see " hint when it doesn't, so users at least know the feature exists.

Either way the silent skip is the wrong default for the shipped CLI.

2. Offline Start button errors when the daemon was stopped externally (apps/tray-mac/Sources/FirstTreeTray/App.swift:851-854, App.swift:501-506)

Confirmed. StatusRow.actionButton shows Start for inbox.state == .offline and routes through daemon.startResumeInBackground → resumeDaemon(), which only reads ~/.first-tree/tray-state.json. That file is written exclusively by pauseDaemon() (App.swift:418-435). So the failure modes liuchao called out are real:

• Daemon stopped via first-tree github scan stop (or crashed, or never paused via tray) → tray-state.json missing or empty → Start throws "No saved repo scope".
• Worth noting the plist does survive stop: stopLaunchdJob only does launchctl bootout and skips deletion (packages/github-scan/src/github-scan/engine/daemon/launchd.ts:366-379). So readDaemonPlistConfig() would succeed in exactly the case where Start currently fails — the recovery data is on disk, the tray just isn't reading it.

Cleanest fix: have resumeDaemon() fall back to readDaemonPlistConfig() when loadState() returns nil/empty (mirror what pauseDaemon() already does), persist the recovered state, then proceed. As a safety net, hide the Start button (or surface a "Run first-tree github scan start --allow-repo … once" hint inline) when neither source has a usable scope, so the button never produces an error toast.

---

Other than these two, the rest of the diff still looks good. --no-tray / Linux / Windows paths are untouched, the self-healing daemon-restart logic in runInstall is sound, and the Pause Instead + CLI fallback fixes from bef87db hold up.

Happy to re-approve once (1) and (2) are addressed.

[bingran-you]

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

One blocking issue remains in the current head:

1. apps/tray-mac/Sources/FirstTreeTray/App.swift:508-523
resumeDaemon() still prefers tray-state.json over the launchd plist, so this only fixes the "no saved repo scope" case. If a user ever pauses from the tray (saving scope A), then later changes the daemon scope outside the tray as the Preferences flow explicitly tells them to do, the updated launchd plist is left on disk when they stop the daemon (packages/github-scan/src/github-scan/engine/daemon/launchd.ts:366-379), but resumeDaemon() will ignore that newer config and restart with the stale saved scope A. In practice the tray's offline Start button can silently roll back a repo-scope/tree-repo change after an external stop or crash. The launchd plist is the authoritative record of the last successful start; resumeDaemon() should read that first when it exists, and only fall back to tray-state.json if the plist is missing or unreadable.

[liuchao-001]

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

Re-reviewed at 39e0736. Both blockers from my prior review are addressed; LGTM.

1. Tray payload bundled with the published CLI (apps/cli/scripts/copy-github-scan-assets.mjs:53-72, packages/github-scan/src/github-scan/engine/commands/install.ts:344-365)

copy-github-scan-assets.mjs now copies apps/tray-mac/{Sources,Package.swift,scripts,…} into dist/tray-mac/ (excluding .build, .swiftpm, DerivedData), and findInstallTrayScript() accepts both apps/tray-mac/scripts/install-tray.sh (source checkout) and tray-mac/scripts/install-tray.sh (npm install) when walking up. I verified locally by running node scripts/copy-github-scan-assets.mjs — apps/cli/dist/tray-mac/scripts/install-tray.sh is now present, so pnpm pack will include it. The added "tray payload not bundled — see #393" hint when --tray=yes falls through is a nice touch.

2. Offline Start recovers from launchd plist (apps/tray-mac/Sources/FirstTreeTray/App.swift:501-527)

resumeDaemon() now tries loadState() → falls back to readDaemonPlistConfig() → persists the recovered scope before proceeding. This is exactly the symmetric path I suggested (and matches what pauseDaemon() already did at L419-424). The CLI-stop / crash / never-paused-via-tray cases all recover cleanly now since stopLaunchdJob leaves the plist on disk.

Bonus: dynamic version string (apps/tray-mac/Sources/FirstTreeTray/App.swift:1226-1235, apps/tray-mac/scripts/build-tray-app.sh:51-79)

Reading CFBundleShortVersionString from Bundle.main.infoDictionary with a "dev" fallback is the right shape, and the build script's heredoc-based version injection (walking up to the nearest package.json) gets the right value in both the source-checkout (first-tree-monorepo root) and npm-install (first-tree cli) layouts. Both currently resolve to 0.4.0-alpha.1 so the "fresh install always claims update" regression is gone.

Verification on this end

• pnpm typecheck clean.
• pnpm test — 591 passed (493 github-scan + 98 cli, no failures).
• swift build in apps/tray-mac — Build complete! (only pre-existing Sendable warnings).
• node scripts/copy-github-scan-assets.mjs — produces dist/tray-mac/scripts/install-tray.sh as expected.

Non-blocking observations (fine to defer / address separately)

• build-tray-app.sh:60 interpolates $CANDIDATE directly into a node -e JS string; paths with single quotes would break the eval. Build-time only and the fallback degrades to 0.0.0-dev, so non-issue in practice — but a JSON.stringify(process.argv[1]) with the path passed as an arg would be more robust.
• The source-checkout build picks up the monorepo root package.json (first-tree-monorepo) for the version, not apps/cli/package.json (first-tree). They match today; if they ever diverge a future swift build from a checkout would advertise the wrong version. Worth a comment in build-tray-app.sh noting the source-of-truth or preferring apps/cli/package.json explicitly.

Approving.

[serenakeyitan]

Thanks @liuchao-001 — both points look correct on inspection and I want to flag the scope question before pushing fixes.

1. Tray ships only from source checkout. Confirmed: apps/cli/package.json only ships dist/, and copy-github-scan-assets.mjs doesn't include apps/tray-mac/. So findRepoRoot() returns null on a real npm install and tray onboarding silently no-ops. This is exactly what #393 (pre-build .app in npm tarball) tracks. Two options:

• (a) Fold Pre-build menu bar tray .app into the npm tarball #393 into this PR: bundle a pre-built FirstTreeTray.app (or the Swift sources + build script) into dist/ and update findRepoRoot() / installScript resolution to find it. Keeps the headline feature working from npm. Adds binary/source weight to the tarball.
• (b) Land as-is, gate the install prompt: explicitly skip the tray prompt when the bundle isn't present (current behavior) and document that the tray is dev-checkout-only until Pre-build menu bar tray .app into the npm tarball #393 lands. Honest, but the PR title oversells what ships.

2. Offline Start button can throw "No saved repo scope". Confirmed: StatusRow shows Start whenever offline (App.swift:851-857), but resumeDaemon() requires tray-state.json from a prior tray-initiated pause (App.swift:501-518). Fix is local — fall back to readDaemonPlistConfig() (already exists at App.swift:450) when loadState() returns nil, and only hide/disable Start if neither source has a usable allow-list.

I'd lean toward (a) + fix #2 so the PR ships a working feature end-to-end, but that's a real scope expansion past the original "design proposal #408" boundary. Holding for serenakeyitan's call on scope before pushing changes.

This reply was drafted by github-scan, an autonomous agent running on behalf of the account owner.

[bingran-you]

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

Re-reviewed at fa20749. The blocker from my prior review is addressed; LGTM.

resumeDaemon() now treats launchd plist as the source of truth (apps/tray-mac/Sources/FirstTreeTray/App.swift:501-533)

The order is exactly what the failure mode required: readDaemonPlistConfig() first (and persist what it returns so the tray's local state catches up), then loadState() only as a fallback for the first-ever-run case where no plist exists yet. The "Pause via tray (scope A) → change scope outside tray (scope B in plist) → external stop → tray Start" path now restarts with scope B, not scope A. This matches what pauseDaemon() already did at App.swift:418-435, so the two paths agree on the source of truth.

The new comment block at App.swift:502-513 is a clear record of why the order matters — useful for whoever next refactors this.

Verification on this end

• swift build in apps/tray-mac — Build complete! (only pre-existing warnings).
• Visually traced the new branch order against pauseDaemon() and stopLaunchdJob (packages/github-scan/src/github-scan/engine/daemon/launchd.ts:366-379); the plist-survives-stop assumption still holds, so the recovery path is sound.

Non-blocking nit

• App.swift:497 doc comment still says "Start the daemon using the allow-list + bound dir + tree-repo captured at the last pause." With the new ordering, the primary source is the last successful start (via the plist), not the last pause. Worth updating to reflect that the plist is now the primary source. Pure docstring, fine to land separately.

Approving.