Package moshi-hook and run its daemon from home-manager on macOS and Linux

[cameronraysmith]

Replaces the ad-hoc Homebrew install of the Moshi companion daemon with a
declarative module that works the same on every host where agent sessions run.

What moshi-hook is

It installs hook configuration into supported coding agents, serves the local
Unix socket those hooks post events to, exposes a localhost gateway the iOS app
forwards to for the diff and browser-preview views, and holds a WebSocket to
Moshi for approval round-trips and status.

Packaging

pkgs/by-name/moshi-hook pins the vendor's four release tarballs. There is no
source build to do: the vendor publishes no source repository, and both
documented install paths — the rjyo/moshi Homebrew tap and
getmoshi.app/install.sh — resolve to exactly these assets under
cdn.getmoshi.app. The tap's formula is generated by the vendor's own release
script from the same URLs and digests, so pinning them directly reproduces what
Homebrew would have installed while keeping the daemon inside the nix closure
and off the Homebrew upgrade path. update.sh reads the vendor's per-release
checksums.txt rather than re-hashing downloads, so the pinned digests stay
equal to the published ones.

Two platform details are load-bearing. The Linux assets are statically linked
Go, so nothing needs patchelf. The darwin assets carry a Developer ID signature
with the hardened runtime; stripping rewrites the Mach-O and macOS then refuses
to exec the binary, so stripping is suppressed there.

One option surface, two backends

services.moshi-hook is a home-manager module in the ai aggregate, because
the daemon is per-user rather than per-machine: it owns a socket that this
user's agent processes post to and a WebSocket carrying this user's pairing.
Options cover only what the daemon needs — enable, package,
pairingTokenFile, stateDir, socketPath. macOS realizes it as a launchd
user agent, Linux as a moshi-hook.service user unit named to match what the
vendor's own documentation tells you to restart. Both run the same launcher
script, so the pairing gate, state layout, and failure behaviour are identical
and only the supervisor differs.

The macOS secret store defaults to Keychain, which is unreachable from an SSH
session against a locked login keychain — unusable for a daemon whose whole
point is being driven from a phone. Setting MOSHI_STATE_DIR switches the store
to <state>/secrets.json on macOS as well as Linux; verified against
moshi-hook 0.2.86, where status --json then reports "secretStore":"file".
That single override is what lets one launcher serve both platforms.

The environment is bound to the package via a wrapper rather than to the
service, because the service is not the only caller: the hook entries are
executed by the agent processes, moshi-hook status is run by hand, and the iOS
app probes the host over SSH. A caller that missed the override would look for a
different socket and, on macOS, a different secret store.

Pairing token

The token arrives as a sops-nix secret at mode 0400 and is handed to the daemon
as a path. The launcher reads it only when the daemon reports itself unpaired —
pair rotates the host secret, so calling it every start would invalidate the
credential the app already holds — and passes it through MOSHI_PAIRING_TOKEN
so it never appears in the host's process listing. Nothing writes it into a nix
store path and Keychain is never involved.

sops-nix validates every declared key when the generation is built, so the key
has to exist before the token does. It is seeded blank; a blank value is the
not-yet-paired state, and the daemon starts and serves its local socket
regardless.

Agent-config reconciliation

moshi-hook install writes hook entries into agent config files this repository
also generates — ~/.claude/settings.json and ~/.codex/config.toml are
reinstalled wholesale on every activation, so anything moshi added is gone by
the time the daemon next starts.

The choice here is to let moshi-hook remain the sole writer of its own entries
and to order the two writers rather than merge them: nix installs its declared
configuration first, then an activation entry sequenced after every generator
runs moshi-hook install, which re-adds moshi's entries on top. Every
activation converges to the same state.

The alternative — teaching our generators to emit moshi's entries — was
rejected because it pins two things we do not own. The entries embed
moshi-hook's own binary path and a per-agent event schema the vendor versions
independently, so every upstream bump would silently desynchronize them. And
install writes more than settings keys: TypeScript extension modules for
pi, omp, and opencode, and a plugin directory plus a config entry for hermes.
Reproducing that in nix would be reimplementing the vendor's installer.

Ordering composes because install is additive and idempotent, which was
checked rather than assumed against moshi-hook 0.2.86: it appended its hooks
beside nix-declared PreToolUse and SessionStart entries without touching
them, a second run left the file byte-identical, and uninstall removed exactly
its own entries and restored the file to its pre-install content. The
reconciliation step reports failure without aborting activation, so a malformed
config file belonging to an agent this repository does not manage cannot fail an
otherwise valid generation switch.

Verification

Built green:

• .#packages.aarch64-darwin.moshi-hook and .#packages.x86_64-linux.moshi-hook
  — versionCheckHook execs the installed binary on each, which is also what
  proves the darwin signature survived packaging.
• .#checks.aarch64-darwin.home-manager-crs58, .#checks.aarch64-darwin.home-manager-cameron,
  and .#checks.x86_64-linux.home-manager-cameron.
• .#checks.aarch64-darwin.darwin-blackphos and .#checks.x86_64-linux.nixos-cinnabar
  — one host configuration per platform.

That selection is the narrowest thing that would fail if this change were
wrong. The module is consumed by exactly one home-manager aggregate, and the
activationPackage checks are enumerated per user automatically, so no new check
file is needed; the two host builds add the platform-specific service
realization on top of the same home closure.

Inspected in the built outputs rather than inferred:

• The launchd plist and the systemd unit each render only on their own
  platform, and are absent from the other.
• The activation script orders moshiHookReconcile after linkGeneration,
  claudeCodeMutableSettings, codexMutableSettings, ompMergeConfig, and
  piCodingAgentMutableSettings, and before setupLaunchAgents.
• The wrapper sets MOSHI_STATE_DIR and MOSHI_SOCKET_PATH as overridable
  defaults, and the moshi alias resolves to the wrapper rather than past it.
• The secret renders at mode 0400.

Ran the generated launcher directly: it reports the blank token, starts the
daemon, and the socket appears at 0600 with the gateway listening. Also
confirmed against 0.2.86 that a full install skips absent agents and exits
zero, so the activation step is quiet in the normal case.

Not run: the full nix flake check, which is dominated by work unrelated to
this change, and .#packages.aarch64-linux.moshi-hook, because no builder for
that platform was reachable and no machine here targets it. The platform is
still declared, since the vendor publishes the asset.

Pairing itself is not covered here — it needs the token from the app.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request