Epic: fold secrets-agent broker into a hardened, always-on daemon

[muqsitnawaz]

Tracking issue for the architecture decision recorded in docs/08-secrets-agent-process-model.md (added in #413).

Decision

The secrets-agent broker should not be a standalone launchd service. It belongs inside a hardened, always-on routines daemon — the daemon is meant to be the most reliable, supervised, bounce-back backbone, so a critical service (every secret read depends on it) should be hosted there, not routed around it.

Make the host (the daemon) reliable enough to carry the critical service — don't route the critical service around the host.

This supersedes the standalone com.phnx-labs.agents-secrets-agent service shipped in 1.20.20. PR #413 (persistent service + self-heal + the ADR) is the interim foundation; this epic is the consolidation.

Work

• daemon: enforce single-instance (fix PID-null / duplicate daemon processes) #414 — daemon: enforce single-instance (fix PID-null / duplicate processes)
• daemon: become always-on (start for any background need, not only 'routines add') #415 — daemon: become always-on (start for any background need, not only routines add)
• secrets: host the broker inside the daemon (socket-first), retire the standalone service #416 — secrets: host the broker inside the daemon (socket-first), retire the standalone service
• daemon: spawn heavy services (browser IPC, session-sync) as children to bound blast radius #417 — daemon: spawn heavy services (browser IPC, session-sync) as children to bound blast radius

Why now / context

Surfaced during a run of incidents: a stale pre-upgrade daemon kept reading the claude OAuth bundle from the keychain (Touch ID storm), the broker cold-started under load, and manual restarts produced duplicate daemons. Root pattern: long-running background processes need to be one robust supervised backbone, not several ad-hoc services.

Not doing (rejected)

Keeping the broker as its own service "for isolation" — the isolation is largely illusory (both rely on launchd KeepAlive), and it treats the daemon's bugs as permanent instead of fixing them.

[muqsitnawaz]

2026-07-09 status against HEAD: #414 done (claimDaemonInstance daemon.ts:151-163, reapStrayDaemons daemon.ts:178). #415 partial (ensureDaemonStarted wired from secrets unlock, secrets.ts:1740; not yet the universal always-on backbone). #416 and #417 not started — deferred from today's batch because they change the background-process model (launchctl bootout migration is irreversible; #417 needs the parent-child IPC + respawn policy decided). Landing order when picked up: finish #415, then #416, then #417.