Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Bootstrap user LaunchAgents from a staged copy when HOME is on an external volume

Claude76225641c335
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index 03b20e78..5e47a08e 100644
--- a/cli/beacon/cmd/endpoint_diagnostics.go
+++ b/cli/beacon/cmd/endpoint_diagnostics.go
@@ -1556,6 +1556,13 @@ func planDoctorFixes(result doctorResult, status lifecycle.Status) doctorFixPlan
// Nothing here is Beacon's to repair: the sandbox mode is the operator's choice in dsh, and
// widening it on their behalf would be the wrong fix even if doctor could. Reported as a
// skip so --fix does not read as having found nothing.
+ // A LaunchAgents directory on an external volume is a layout, not damage: when Beacon can
+ // stage the plists (warn) the install already works and there is nothing to repair; when it
+ // cannot (fail) the remedy is the manual bootstrap in the check's action.
+ case "launch_agents_volume":
+ if check.Status == diagnostics.StatusFail {
+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: check.Action})
+ }
case "dsh_hook_capture":
addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: check.Action})
}
diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.go
index 1b058339..1045d052 100644
--- a/cli/beacon/cmd/endpoint_test.go
+++ b/cli/beacon/cmd/endpoint_test.go
@@ -2022,6 +2022,27 @@ func TestPlanDoctorFixesDoesNotTreatMissingEventAsAppliedFix(t *testing.T) {
}
}
+// An external-volume home that Beacon can stage is informational, so --fix must not repair it; one it
+// cannot stage is skipped with the manual bootstrap as the message (#639).
+func TestPlanDoctorFixesTreatsLaunchAgentsVolumeAsManual(t *testing.T) {
+ status := lifecycle.Status{RuntimeLog: lifecycle.RuntimeLogSource{EffectiveUserMode: true}}
+ staged := planDoctorFixes(doctorResult{Checks: []diagnostics.Check{
+ {Name: "launch_agents_volume", Target: "/Volumes/Ext/Library/LaunchAgents", Status: diagnostics.StatusWarn,
+ Evidence: "launch_agents_external_volume_staged", Action: "beacon endpoint repair --user"},
+ }}, status)
+ if len(staged.Fixes) != 0 || len(staged.Skipped) != 0 {
+ t.Fatalf("a staged external-volume home needs no fix: %#v", staged)
+ }
+ unstaged := planDoctorFixes(doctorResult{Checks: []diagnostics.Check{
+ {Name: "launch_agents_volume", Target: "/Volumes/Ext/Library/LaunchAgents", Status: diagnostics.StatusFail,
+ Evidence: "launch_agents_external_volume_unstaged", Action: "install with --no-start, then launchctl bootstrap"},
+ }}, status)
+ if len(unstaged.Fixes) != 0 || len(unstaged.Skipped) != 1 || unstaged.Skipped[0].Action != "manual_fix" ||
+ !strings.Contains(unstaged.Skipped[0].Message, "--no-start") {
+ t.Fatalf("an unstaged external-volume home should be a manual skip: %#v", unstaged)
+ }
+}
+
func TestApplyDoctorFixesContinuesAfterCollectorRepairFailure(t *testing.T) {
home := t.TempDir()
testenv.SetHome(t, home)
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
index 894829e2..718d49dc 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
@@ -51,6 +51,11 @@ func Run(cfg endpointconfig.Config) []Check {
case service.KindLaunchd:
if path, err := mgr.UnitPath(); err == nil {
checks = append(checks, checkFile("launchd_plist", path, true))
+ // A home directory on an external volume is the one layout where the plist being
+ // present says nothing about whether launchd will load it (#639).
+ if cfg.UserMode {
+ checks = append(checks, launchAgentVolumeCheck(service.InspectLaunchAgentVolume(path)))
+ }
}
case service.KindSystemd:
if path, err := mgr.UnitPath(); err == nil {
@@ -66,6 +71,31 @@ func Run(cfg endpointconfig.Config) []Check {
return checks
}
+// launchAgentVolumeCheck reports a LaunchAgents directory off the startup volume. launchd refuses to
+// bootstrap plists from there ("Bootstrap failed: 5: Input/output error"), so Beacon bootstraps a
+// staged copy on the startup volume instead. That works for the running session, but it is a
+// layout worth naming: whether launchd's own login scan loads the canonical plist is not something
+// Beacon can see, and a collector missing after a restart is fixed by a repair, which restages it.
+func launchAgentVolumeCheck(vol service.LaunchAgentVolume) Check {
+ if !vol.External {
+ return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusOK, Severity: SeverityInfo,
+ Message: "LaunchAgents is on the startup volume", Evidence: "launch_agents_startup_volume"}
+ }
+ if vol.StagingDir == "" {
+ return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusFail, Severity: SeverityHigh,
+ Message: vol.Reason + ", so launchd refuses to bootstrap Beacon's LaunchAgents from it, and no private " +
+ "directory on the startup volume was found to bootstrap a copy from",
+ Evidence: "launch_agents_external_volume_unstaged",
+ Action: "install with --no-start, copy the plists from " + vol.PlistDir + " into a private directory on the " +
+ "startup volume, and run `launchctl bootstrap gui/$(id -u) <copied plist>` for each"}
+ }
+ return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusWarn, Severity: SeverityLow,
+ Message: vol.Reason + ", which launchd will not bootstrap LaunchAgents from; Beacon bootstraps copies staged in " +
+ vol.StagingDir + " instead. If the collector is not running after a restart or login, repair the install to restage them",
+ Evidence: "launch_agents_external_volume_staged",
+ Action: "beacon endpoint repair --user"}
+}
+
func lingerCheck() Check {
u, err := user.Current()
if err != nil || u.Username == "" {
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
index 97cbc7d3..3a1c3f76 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
@@ -4,6 +4,7 @@ import (
"os"
"os/user"
"path/filepath"
+ "strings"
"testing"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
@@ -189,3 +190,32 @@ func TestLingerCheckOffersTheSharedRemediation(t *testing.T) {
t.Errorf("doctor action = %q, want the shared remediation %q", check.Action, want)
}
}
+
+func TestLaunchAgentVolumeCheck(t *testing.T) {
+ onBoot := launchAgentVolumeCheck(service.LaunchAgentVolume{PlistDir: "/Users/test/Library/LaunchAgents"})
+ if onBoot.Status != StatusOK || onBoot.Evidence != "launch_agents_startup_volume" {
+ t.Fatalf("startup-volume check = %#v", onBoot)
+ }
+
+ staged := launchAgentVolumeCheck(service.LaunchAgentVolume{
+ PlistDir: "/Volumes/Ext/Library/LaunchAgents",
+ External: true,
+ StagingDir: "/var/folders/xx/T/beacon-launchd-502",
+ Reason: "/Volumes/Ext/Library/LaunchAgents is on a different volume than /Users",
+ })
+ if staged.Status != StatusWarn || staged.Evidence != "launch_agents_external_volume_staged" ||
+ staged.Action != "beacon endpoint repair --user" ||
+ !strings.Contains(staged.Message, "/var/folders/xx/T/beacon-launchd-502") {
+ t.Fatalf("staged external-volume check = %#v", staged)
+ }
+
+ unstaged := launchAgentVolumeCheck(service.LaunchAgentVolume{
+ PlistDir: "/Volumes/Ext/Library/LaunchAgents",
+ External: true,
+ Reason: "/Volumes/Ext/Library/LaunchAgents is under /Volumes",
+ })
+ if unstaged.Status != StatusFail || unstaged.Evidence != "launch_agents_external_volume_unstaged" ||
+ !strings.Contains(unstaged.Action, "--no-start") || !strings.Contains(unstaged.Action, "launchctl bootstrap gui/") {
+ t.Fatalf("unstaged external-volume check = %#v", unstaged)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/service/forwarder.go b/cli/beacon/internal/endpoint/service/forwarder.go
index f64ec5c3..dd346d67 100644
--- a/cli/beacon/internal/endpoint/service/forwarder.go
+++ b/cli/beacon/internal/endpoint/service/forwarder.go
@@ -185,8 +185,7 @@ func (m ForwarderManager) Unload() error {
if runtime.GOOS != "darwin" {
return nil
}
- domain := serviceDomain(m.UserMode)
- return runLaunchctlWithContext(domain, ForwarderLabel, "", "bootout", domain+"/"+ForwarderLabel)
+ return bootoutLaunchdJob(serviceDomain(m.UserMode), ForwarderLabel)
default:
return nil
}
diff --git a/cli/beacon/internal/endpoint/service/inventory.go b/cli/beacon/internal/endpoint/service/inventory.go
index 3c1e7960..4a621963 100644
--- a/cli/beacon/internal/endpoint/service/inventory.go
+++ b/cli/beacon/internal/endpoint/service/inventory.go
@@ -227,8 +227,7 @@ func (m InventoryManager) Unload() error {
if runtime.GOOS != "darwin" {
return nil
}
- domain := serviceDomain(m.UserMode)
- return runLaunchctlWithContext(domain, InventoryLabel, "", "bootout", domain+"/"+InventoryLabel)
+ return bootoutLaunchdJob(serviceDomain(m.UserMode), InventoryLabel)
default:
return nil
}
diff --git a/cli/beacon/internal/endpoint/service/launchd.go b/cli/beacon/internal/endpoint/service/launchd.go
index 11ce3c1c..1fc26e56 100644
--- a/cli/beacon/internal/endpoint/service/launchd.go
+++ b/cli/beacon/internal/endpoint/service/launchd.go
@@ -116,9 +116,7 @@ func (b launchdBackend) load(userMode bool) error {
}
func (b launchdBackend) unload(userMode bool) error {
- domain := serviceDomain(userMode)
- target := domain + "/" + b.label(userMode)
- return runLaunchctlWithContext(domain, b.label(userMode), "", "bootout", target)
+ return bootoutLaunchdJob(serviceDomain(userMode), b.label(userMode))
}
func (b launchdBackend) restart(userMode bool) error {
@@ -164,7 +162,21 @@ func launchctlNoSuchProcess(text string) bool {
return strings.Contains(text, "No such process") || strings.Contains(text, "Could not find service")
}
+// loadLaunchdJob bootstraps plistPath into domain, reloading a job that is already registered.
+//
+// A user LaunchAgent whose plist is off the startup volume is bootstrapped from a staged copy
+// instead (see launchd_volume.go, #639); a failure then carries a note naming the volume and the
+// manual route.
func loadLaunchdJob(domain, label, plistPath string) error {
+ bootstrapPath, note := launchdBootstrapPath(domain, plistPath)
+ err := bootstrapLaunchdJob(domain, label, bootstrapPath)
+ if err != nil && note != "" {
+ return fmt.Errorf("%w\n%s", err, note)
+ }
+ return err
+}
+
+func bootstrapLaunchdJob(domain, label, plistPath string) error {
out, err := runLaunchctlCommand("bootstrap", domain, plistPath)
if err == nil {
return nil
@@ -239,7 +251,7 @@ func launchctlGuidance(output, domain, label string) string {
if target == "" {
target = "the Beacon launchd job"
}
- return fmt.Sprintf("Bootstrap failed: 5 usually means launchd could not read or execute the job. Verify the collector binary referenced by the plist exists and is executable, clear stale state with `launchctl bootout %s`, then inspect launchd logs with `log show --predicate 'process == \"launchd\"' --last 5m`.", target)
+ return fmt.Sprintf("Bootstrap failed: 5 usually means launchd could not read or execute the job. Verify the collector binary referenced by the plist exists and is executable, clear stale state with `launchctl bootout %s`, then inspect launchd logs with `log show --predicate 'process == \"launchd\"' --last 5m`. launchd also refuses plists on an external volume, such as a home directory under /Volumes; `beacon endpoint doctor` reports that case.", target)
}
func serviceDomain(userMode bool) string {
diff --git a/cli/beacon/internal/endpoint/service/launchd_volume.go b/cli/beacon/internal/endpoint/service/launchd_volume.go
new file mode 100644
index 00000000..043061eb
--- /dev/null
+++ b/cli/beacon/internal/endpoint/service/launchd_volume.go
@@ -0,0 +1,221 @@
+package service
+
+import (
+ "errors"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+)
+
+// A user whose home directory lives on an external volume (`/Volumes/<disk>`, with NFSHomeDirectory
+// pointing there) gets every Beacon LaunchAgent refused by launchd: `launchctl bootstrap gui/<uid>
+// ~/Library/LaunchAgents/<label>.plist` fails with "Bootstrap failed: 5: Input/output error", the
+// install rolls back, and the inventory job never loads (#639). The same plist bootstraps cleanly
+// once it is copied to the startup volume, and the job then runs normally with its program and
+// config still on the external volume -- so the refusal is about where the job definition is read
+// from, not about what the job touches. An independent report against another launchd-managed
+// tool shows the same failure and the same cure, with `diskutil enableOwnership` making no
+// difference.
+//
+// Beacon therefore keeps writing the canonical plist to ~/Library/LaunchAgents, where an operator
+// and launchd's own login scan expect it, and hands launchctl a byte-identical copy staged in a
+// private directory on the startup volume whenever the LaunchAgents directory is on a different
+// volume. A home on the startup volume is untouched: its plist is bootstrapped in place as before.
+
+// Seams for tests: which volume a path is on, the path that stands for the startup volume, and
+// where a staged copy may go. /Users is on the startup volume's Data half on every supported macOS
+// (it is a firmlink into /System/Volumes/Data), which is where both TMPDIR and /private/tmp live;
+// "/" itself is the sealed system volume and has a different device number, so it cannot be the
+// reference.
+var (
+ launchdVolumeID = volumeID
+ launchdBootVolumeRef = "/Users"
+ launchdStagingBases = func() []string { return []string{os.TempDir(), "/private/tmp"} }
+)
+
+// LaunchAgentVolume describes where a user LaunchAgent's plist sits relative to the startup volume.
+type LaunchAgentVolume struct {
+ // PlistDir is the LaunchAgents directory that holds the canonical plist.
+ PlistDir string `json:"plist_dir"`
+ // External is true when PlistDir is on a volume other than the startup volume.
+ External bool `json:"external"`
+ // StagingDir is the private startup-volume directory the plist is bootstrapped from when
+ // External is true. Empty when External is false, or when no usable location was found.
+ StagingDir string `json:"staging_dir,omitempty"`
+ // Reason says how External was decided, for diagnostics.
+ Reason string `json:"reason,omitempty"`
+}
+
+// InspectLaunchAgentVolume reports whether plistPath is off the startup volume and, if so, where
+// Beacon will stage the copy it bootstraps.
+func InspectLaunchAgentVolume(plistPath string) LaunchAgentVolume {
+ dir := filepath.Dir(plistPath)
+ vol := LaunchAgentVolume{PlistDir: dir}
+ bootID, bootErr := launchdVolumeID(launchdBootVolumeRef)
+ dirID, dirErr := launchdVolumeID(dir)
+ switch {
+ case bootErr == nil && dirErr == nil:
+ vol.External = dirID != bootID
+ if vol.External {
+ vol.Reason = fmt.Sprintf("%s is on a different volume than %s", dir, launchdBootVolumeRef)
+ }
+ case underVolumes(dir):
+ // No device numbers to compare, so the mount point is the evidence: external and
+ // secondary internal volumes are mounted under /Volumes.
+ vol.External = true
+ vol.Reason = dir + " is under /Volumes"
+ }
+ if !vol.External {
+ return vol
+ }
+ for _, base := range launchdStagingBases() {
+ if strings.TrimSpace(base) == "" {
+ continue
+ }
+ if bootErr == nil {
+ if id, err := launchdVolumeID(base); err != nil || id != bootID {
+ continue
+ }
+ } else if underVolumes(base) {
+ continue
+ }
+ vol.StagingDir = filepath.Join(base, launchdStagingDirName())
+ break
+ }
+ return vol
+}
+
+func underVolumes(path string) bool {
+ if resolved, err := filepath.EvalSymlinks(path); err == nil {
+ path = resolved
+ }
+ return strings.HasPrefix(filepath.Clean(path)+"/", "/Volumes/")
+}
+
+// launchdStagingDirName carries the uid so the /private/tmp fallback cannot collide between users.
+func launchdStagingDirName() string {
+ return fmt.Sprintf("beacon-launchd-%d", os.Getuid())
+}
+
+// launchdBootstrapPath returns the path launchctl should bootstrap for plistPath in domain, and a
+// note to attach to a bootstrap failure. Only user domains are staged: LaunchDaemons live in
+// /Library on the startup volume and are root's.
+func launchdBootstrapPath(domain, plistPath string) (string, string) {
+ if !strings.HasPrefix(domain, "gui/") {
+ return plistPath, ""
+ }
+ vol := InspectLaunchAgentVolume(plistPath)
+ if !vol.External {
+ return plistPath, ""
+ }
+ if vol.StagingDir == "" {
+ return plistPath, externalVolumeNote(domain, vol, "", errors.New("no private directory on the startup volume was found"))
+ }
+ staged, err := stageLaunchdPlist(plistPath, vol.StagingDir)
+ if err != nil {
+ return plistPath, externalVolumeNote(domain, vol, "", err)
+ }
+ return staged, externalVolumeNote(domain, vol, staged, nil)
+}
+
+// externalVolumeNote explains a bootstrap failure for a plist off the startup volume. It is only
+// shown when launchctl fails, so it always ends with the manual route from #639.
+func externalVolumeNote(domain string, vol LaunchAgentVolume, staged string, stageErr error) string {
+ var b strings.Builder
+ fmt.Fprintf(&b, "The LaunchAgents directory %s is not on the startup volume (%s); launchd refuses to bootstrap LaunchAgents from a home directory on an external volume.", vol.PlistDir, vol.Reason)
+ if stageErr != nil {
+ fmt.Fprintf(&b, " A copy could not be staged on the startup volume: %v.", stageErr)
+ } else {
+ fmt.Fprintf(&b, " Beacon bootstrapped a copy staged at %s, and launchd refused that too.", staged)
+ }
+ fmt.Fprintf(&b, " To load it by hand: install with --no-start, copy the plist from %s into a private directory on the startup volume (mkdir -p -m 700 \"$TMPDIR/beacon-launchd\"), then run `launchctl bootstrap %s <copied plist>`.", vol.PlistDir, domain)
+ return b.String()
+}
+
+// stageLaunchdPlist copies plistPath into stagingDir under the same name and returns the copy's path.
+//
+// The directory is a fixed name in a temp directory, so it has to be one this user owns and nobody
+// else can write, or another account could replace the job definition between the copy and the
+// bootstrap and have launchd run its program as this user. The copy is written to a temporary name
+// and renamed into place, which replaces rather than follows anything planted at the final name.
+func stageLaunchdPlist(plistPath, stagingDir string) (string, error) {
+ data, err := os.ReadFile(plistPath)
+ if err != nil {
+ return "", err
+ }
+ if err := os.Mkdir(stagingDir, 0o700); err != nil && !os.IsExist(err) {
+ return "", err
+ }
+ if err := checkPrivateStagingDir(stagingDir); err != nil {
+ return "", err
+ }
+ tmp, err := os.CreateTemp(stagingDir, ".stage-*.plist")
+ if err != nil {
+ return "", err
+ }
+ tmpPath := tmp.Name()
+ defer os.Remove(tmpPath)
+ if _, err := tmp.Write(data); err != nil {
+ _ = tmp.Close()
+ return "", err
+ }
+ // launchd refuses a job definition that is group- or world-writable.
+ if err := tmp.Chmod(0o644); err != nil {
+ _ = tmp.Close()
+ return "", err
+ }
+ if err := tmp.Close(); err != nil {
+ return "", err
+ }
+ dest := filepath.Join(stagingDir, filepath.Base(plistPath))
+ if err := os.Rename(tmpPath, dest); err != nil {
+ return "", err
+ }
+ return dest, nil
+}
+
+// checkPrivateStagingDir refuses anything but a real directory owned by this user with no group or
+// other access.
+func checkPrivateStagingDir(dir string) error {
+ info, err := os.Lstat(dir)
+ if err != nil {
+ return err
+ }
+ if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
+ return fmt.Errorf("%s is not a directory", dir)
+ }
+ if uid, ok := fileOwner(info); ok && uid != os.Getuid() {
+ return fmt.Errorf("%s is owned by uid %d, not this user", dir, uid)
+ }
+ if perm := info.Mode().Perm(); perm&0o077 != 0 {
+ return fmt.Errorf("%s is mode %o; it must not be accessible to other users", dir, perm)
+ }
+ return nil
+}
+
+// removeStagedLaunchdPlist deletes any staged copy of label's plist. launchd holds a job's
+// definition in memory once it is bootstrapped, so the copy only matters for the next bootstrap,
+// which restages it; removing it on bootout keeps an uninstall from leaving it behind.
+func removeStagedLaunchdPlist(label string) {
+ for _, base := range launchdStagingBases() {
+ if strings.TrimSpace(base) == "" {
+ continue
+ }
+ dir := filepath.Join(base, launchdStagingDirName())
+ if checkPrivateStagingDir(dir) != nil {
+ continue
+ }
+ _ = os.Remove(filepath.Join(dir, label+".plist"))
+ }
+}
+
+// bootoutLaunchdJob stops and deregisters a job by label, tolerating one that is not loaded, and
+// removes a user job's staged plist.
+func bootoutLaunchdJob(domain, label string) error {
+ err := runLaunchctlWithContext(domain, label, "", "bootout", domain+"/"+label)
+ if strings.HasPrefix(domain, "gui/") {
+ removeStagedLaunchdPlist(label)
+ }
+ return err
+}
diff --git a/cli/beacon/internal/endpoint/service/launchd_volume_test.go b/cli/beacon/internal/endpoint/service/launchd_volume_test.go
new file mode 100644
index 00000000..b675e5de
--- /dev/null
+++ b/cli/beacon/internal/endpoint/service/launchd_volume_test.go
@@ -0,0 +1,404 @@
+package service
+
+import (
+ "errors"
+ "fmt"
+ "os"
+ "path/filepath"
+ "runtime"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+// volumeFixture lays out a fake startup volume and a fake external volume under one temp dir and
+// points the volume seams at them, so the detection and staging logic runs on any host. Paths under
+// external report device 2; everything else reports device 1, the startup volume.
+type volumeFixture struct {
+ boot string // stands in for the startup (Data) volume
+ external string // stands in for /Volumes/<ExternalDisk>
+ staging string // the private staging directory Beacon should create on the startup volume
+}
+
+func newVolumeFixture(t *testing.T) volumeFixture {
+ t.Helper()
+ root := t.TempDir()
+ f := volumeFixture{
+ boot: filepath.Join(root, "boot"),
+ external: filepath.Join(root, "Volumes", "MacintoshExternalNVME"),
+ }
+ for _, dir := range []string{
+ filepath.Join(f.boot, "Users", "test", "Library", "LaunchAgents"),
+ filepath.Join(f.boot, "tmp"),
+ filepath.Join(f.external, "Library", "LaunchAgents"),
+ } {
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ }
+ f.staging = filepath.Join(f.boot, "tmp", launchdStagingDirName())
+
+ oldID, oldRef, oldBases := launchdVolumeID, launchdBootVolumeRef, launchdStagingBases
+ launchdBootVolumeRef = filepath.Join(f.boot, "Users")
+ launchdStagingBases = func() []string { return []string{filepath.Join(f.boot, "tmp")} }
+ launchdVolumeID = func(path string) (uint64, error) {
+ if _, err := os.Stat(path); err != nil {
+ return 0, err
+ }
+ if strings.HasPrefix(path, f.external) {
+ return 2, nil
+ }
+ return 1, nil
+ }
+ t.Cleanup(func() { launchdVolumeID, launchdBootVolumeRef, launchdStagingBases = oldID, oldRef, oldBases })
+ return f
+}
+
+// externalPlist writes a plist into the external volume's LaunchAgents, the layout from #639.
+func (f volumeFixture) externalPlist(t *testing.T, label string) string {
+ t.Helper()
+ path := filepath.Join(f.external, "Library", "LaunchAgents", label+".plist")
+ if err := os.WriteFile(path, []byte(plist(label, "/opt/homebrew/bin/beacon-otelcol", "/x/otelcol.yaml")), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
+
+func (f volumeFixture) bootPlist(t *testing.T, label string) string {
+ t.Helper()
+ path := filepath.Join(f.boot, "Users", "test", "Library", "LaunchAgents", label+".plist")
+ if err := os.WriteFile(path, []byte(plist(label, "/opt/homebrew/bin/beacon-otelcol", "/x/otelcol.yaml")), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
+
+// recordLaunchctl fakes launchctl with just enough state for the load paths: a bootstrap registers
+// the plist's label (unless bootstrapOut makes it fail), a bootout drops it, and print reports
+// whether the label is registered, with a pid so the forwarder's start wait is satisfied.
+func recordLaunchctl(t *testing.T, bootstrapOut string) *[]string {
+ t.Helper()
+ calls := &[]string{}
+ loaded := map[string]bool{}
+ old := runLaunchctlCommand
+ runLaunchctlCommand = func(args ...string) (string, error) {
+ *calls = append(*calls, strings.Join(args, " "))
+ switch args[0] {
+ case "bootstrap":
+ if bootstrapOut != "" {
+ return bootstrapOut, errors.New("exit status 5")
+ }
+ loaded[strings.TrimSuffix(filepath.Base(args[len(args)-1]), ".plist")] = true
+ return "", nil
+ case "bootout":
+ delete(loaded, filepath.Base(args[len(args)-1]))
+ return "", nil
+ case "print":
+ if loaded[filepath.Base(args[len(args)-1])] {
+ return "state = running\npid = 42\n", nil
+ }
+ return "Could not find service", errors.New("exit status 113")
+ }
+ return "", fmt.Errorf("unexpected launchctl call: %s", strings.Join(args, " "))
+ }
+ t.Cleanup(func() { runLaunchctlCommand = old })
+ return calls
+}
+
+func bootstrapPaths(calls []string) []string {
+ var out []string
+ for _, c := range calls {
+ if fields := strings.Fields(c); len(fields) == 3 && fields[0] == "bootstrap" {
+ out = append(out, fields[2])
+ }
+ }
+ return out
+}
+
+func TestInspectLaunchAgentVolumeFlagsPlistOffTheStartupVolume(t *testing.T) {
+ f := newVolumeFixture(t)
+ vol := InspectLaunchAgentVolume(f.externalPlist(t, UserLabel))
+ if !vol.External {
+ t.Fatalf("plist on the external volume was not flagged: %#v", vol)
+ }
+ if vol.StagingDir != f.staging {
+ t.Fatalf("staging dir = %q, want %q on the startup volume", vol.StagingDir, f.staging)
+ }
+ if !strings.Contains(vol.Reason, "different volume") {
+ t.Fatalf("reason should say why: %q", vol.Reason)
+ }
+}
+
+func TestInspectLaunchAgentVolumeLeavesStartupVolumeHomesAlone(t *testing.T) {
+ f := newVolumeFixture(t)
+ vol := InspectLaunchAgentVolume(f.bootPlist(t, UserLabel))
+ if vol.External || vol.StagingDir != "" {
+ t.Fatalf("a home on the startup volume must not be staged: %#v", vol)
+ }
+}
+
+// When the volume lookup cannot run (a LaunchAgents directory that does not exist yet, or a stat the
+// sandbox refuses), the path is the evidence left: external disks mount under /Volumes.
+func TestInspectLaunchAgentVolumeFallsBackToTheVolumesPrefix(t *testing.T) {
+ oldID := launchdVolumeID
+ launchdVolumeID = func(string) (uint64, error) { return 0, errors.New("stat refused") }
+ t.Cleanup(func() { launchdVolumeID = oldID })
+
+ if vol := InspectLaunchAgentVolume("/Volumes/Ext/Library/LaunchAgents/" + UserLabel + ".plist"); !vol.External {
+ t.Fatalf("/Volumes path not flagged without a volume lookup: %#v", vol)
+ }
+ if vol := InspectLaunchAgentVolume("/Users/test/Library/LaunchAgents/" + UserLabel + ".plist"); vol.External {
+ t.Fatalf("/Users path flagged without evidence: %#v", vol)
+ }
+}
+
+// The #639 reproduction: HOME on /Volumes/<disk>, launchd refuses the plist in place. Beacon must hand
+// launchctl a byte-identical copy on the startup volume and never the external path.
+func TestLoadLaunchdJobBootstrapsAStagedCopyForAnExternalHome(t *testing.T) {
+ testenv.RequirePOSIXFileModes(t)
+ f := newVolumeFixture(t)
+ calls := recordLaunchctl(t, "")
+ source := f.externalPlist(t, UserLabel)
+
+ if err := loadLaunchdJob("gui/502", UserLabel, source); err != nil {
+ t.Fatalf("loadLaunchdJob: %v", err)
+ }
+ staged := filepath.Join(f.staging, UserLabel+".plist")
+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != staged {
+ t.Fatalf("bootstrap paths = %#v, want only the staged copy %s", got, staged)
+ }
+ for _, c := range *calls {
+ if strings.Contains(c, f.external) {
+ t.Fatalf("launchctl was handed the external path: %q", c)
+ }
+ }
+ want, _ := os.ReadFile(source)
+ got, err := os.ReadFile(staged)
+ if err != nil || string(got) != string(want) {
+ t.Fatalf("staged copy differs from the installed plist (err %v)", err)
+ }
+ if info, _ := os.Stat(f.staging); info == nil || info.Mode().Perm() != 0o700 {
+ t.Fatalf("staging dir must be private (0700): %v", info)
+ }
+ // launchd refuses a job definition that is group- or world-writable.
+ if info, _ := os.Stat(staged); info == nil || info.Mode().Perm() != 0o644 {
+ t.Fatalf("staged plist mode = %v, want 0644", info)
+ }
+}
+
+func TestLoadLaunchdJobBootstrapsInPlaceOnTheStartupVolume(t *testing.T) {
+ f := newVolumeFixture(t)
+ calls := recordLaunchctl(t, "")
+ source := f.bootPlist(t, UserLabel)
+
+ if err := loadLaunchdJob("gui/502", UserLabel, source); err != nil {
+ t.Fatalf("loadLaunchdJob: %v", err)
+ }
+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != source {
+ t.Fatalf("bootstrap paths = %#v, want the plist in place", got)
+ }
+ if _, err := os.Stat(f.staging); !os.IsNotExist(err) {
+ t.Fatalf("a startup-volume home must not create a staging dir (stat err %v)", err)
+ }
+}
+
+// LaunchDaemons live in /Library on the startup volume and are root's; staging is a user-domain
+// remedy only.
+func TestLoadLaunchdJobNeverStagesTheSystemDomain(t *testing.T) {
+ f := newVolumeFixture(t)
+ calls := recordLaunchctl(t, "")
+ source := f.externalPlist(t, SystemLabel)
+
+ if err := loadLaunchdJob("system", SystemLabel, source); err != nil {
+ t.Fatalf("loadLaunchdJob: %v", err)
+ }
+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != source {
+ t.Fatalf("bootstrap paths = %#v, want the plist in place for the system domain", got)
+ }
+}
+
+// If launchd still refuses, the error names the external volume, the copy it tried, and the manual
+// route, instead of the generic "verify the collector binary" advice alone.
+func TestLoadLaunchdJobExplainsAnExternalHomeWhenBootstrapStillFails(t *testing.T) {
+ f := newVolumeFixture(t)
+ recordLaunchctl(t, "Bootstrap failed: 5: Input/output error")
+ source := f.externalPlist(t, UserLabel)
+
+ err := loadLaunchdJob("gui/502", UserLabel, source)
+ if err == nil {
+ t.Fatal("loadLaunchdJob succeeded, want the bootstrap failure")
+ }
+ for _, want := range []string{
+ "Bootstrap failed: 5",
+ f.external,
+ "not on the startup volume",
+ filepath.Join(f.staging, UserLabel+".plist"),
+ "--no-start",
+ "launchctl bootstrap gui/502",
+ } {
+ if !strings.Contains(err.Error(), want) {
+ t.Fatalf("error missing %q:\n%v", want, err)
+ }
+ }
+}
+
+// The staging directory is a fixed name in a temp directory, so it must be one this user created
+// and nobody else can write: a planted symlink or a writable directory would let another account
+// swap the job definition between the copy and the bootstrap.
+func TestLoadLaunchdJobRefusesAnUnsafeStagingDirectory(t *testing.T) {
+ testenv.RequirePOSIXFileModes(t)
+ for _, tc := range []struct {
+ name string
+ plant func(t *testing.T, staging, elsewhere string)
+ }{
+ {"symlink", func(t *testing.T, staging, elsewhere string) {
+ if err := os.Symlink(elsewhere, staging); err != nil {
+ t.Fatal(err)
+ }
+ }},
+ {"group writable", func(t *testing.T, staging, _ string) {
+ if err := os.Mkdir(staging, 0o700); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Chmod(staging, 0o770); err != nil {
+ t.Fatal(err)
+ }
+ }},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ f := newVolumeFixture(t)
+ elsewhere := t.TempDir()
+ tc.plant(t, f.staging, elsewhere)
+ calls := recordLaunchctl(t, "Bootstrap failed: 5: Input/output error")
+ source := f.externalPlist(t, UserLabel)
+
+ err := loadLaunchdJob("gui/502", UserLabel, source)
+ if err == nil || !strings.Contains(err.Error(), "could not be staged") {
+ t.Fatalf("error = %v, want it to say the copy could not be staged", err)
+ }
+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != source {
+ t.Fatalf("bootstrap paths = %#v, want the original plist when staging is refused", got)
+ }
+ if entries, _ := os.ReadDir(elsewhere); len(entries) != 0 {
+ t.Fatalf("staging wrote through the planted directory: %v", entries)
+ }
+ })
+ }
+}
+
+// A planted symlink at the staged file's own name is replaced, not followed.
+func TestStageLaunchdPlistReplacesAPlantedSymlink(t *testing.T) {
+ testenv.RequirePOSIXFileModes(t)
+ f := newVolumeFixture(t)
+ source := f.externalPlist(t, UserLabel)
+ if err := os.Mkdir(f.staging, 0o700); err != nil {
+ t.Fatal(err)
+ }
+ victim := filepath.Join(t.TempDir(), "victim")
+ if err := os.WriteFile(victim, []byte("untouched"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ dest := filepath.Join(f.staging, UserLabel+".plist")
+ if err := os.Symlink(victim, dest); err != nil {
+ t.Fatal(err)
+ }
+
+ staged, err := stageLaunchdPlist(source, f.staging)
+ if err != nil || staged != dest {
+ t.Fatalf("stageLaunchdPlist = %q, %v", staged, err)
+ }
+ if got, _ := os.ReadFile(victim); string(got) != "untouched" {
+ t.Fatalf("staging followed the symlink and overwrote %s", victim)
+ }
+ if info, err := os.Lstat(dest); err != nil || info.Mode()&os.ModeSymlink != 0 {
+ t.Fatalf("staged plist should be a regular file: %v %v", info, err)
+ }
+}
+
+func TestBootoutLaunchdJobRemovesTheStagedCopy(t *testing.T) {
+ testenv.RequirePOSIXFileModes(t)
+ f := newVolumeFixture(t)
+ calls := recordLaunchctl(t, "")
+ if err := loadLaunchdJob("gui/502", InventoryLabel, f.externalPlist(t, InventoryLabel)); err != nil {
+ t.Fatal(err)
+ }
+ staged := filepath.Join(f.staging, InventoryLabel+".plist")
+ if _, err := os.Stat(staged); err != nil {
+ t.Fatalf("staged copy missing after load: %v", err)
+ }
+
+ if err := bootoutLaunchdJob("gui/502", InventoryLabel); err != nil {
+ t.Fatalf("bootoutLaunchdJob: %v", err)
+ }
+ if last := (*calls)[len(*calls)-1]; last != "bootout gui/502/"+InventoryLabel {
+ t.Fatalf("last launchctl call = %q, want bootout by label", last)
+ }
+ if _, err := os.Stat(staged); !os.IsNotExist(err) {
+ t.Fatalf("staged copy survived bootout (stat err %v)", err)
+ }
+}
+
+func TestVolumeIDAgreesWithinOneFilesystem(t *testing.T) {
+ if runtime.GOOS == "windows" {
+ t.Skip("launchd volume detection is not built for Windows")
+ }
+ dir := t.TempDir()
+ sub := filepath.Join(dir, "sub")
+ if err := os.Mkdir(sub, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ a, errA := volumeID(dir)
+ b, errB := volumeID(sub)
+ if errA != nil || errB != nil || a != b {
+ t.Fatalf("volumeID(%s)=%d,%v volumeID(%s)=%d,%v; want equal", dir, a, errA, sub, b, errB)
+ }
+ if _, err := volumeID(filepath.Join(dir, "missing")); err == nil {
+ t.Fatal("volumeID of a missing path should fail")
+ }
+}
+
+// End to end through each user LaunchAgent the endpoint installs: collector, forwarder and the
+// inventory job all reached launchd from the external volume in #639. The managers refuse to run
+// off macOS, so this half runs on the macOS CI job; the shared path is covered above everywhere.
+func TestUserLaunchAgentsBootstrapFromAStagedCopyOnAnExternalHome(t *testing.T) {
+ if runtime.GOOS != "darwin" {
+ t.Skip("the launchd managers only run on macOS; loadLaunchdJob covers the shared path elsewhere")
+ }
+ shrinkLaunchdWaits(t)
+ f := newVolumeFixture(t)
+ testenv.SetHome(t, f.external)
+ calls := recordLaunchctl(t, "")
+
+ collector := Manager{UserMode: true, Kind: KindLaunchd}
+ if _, err := collector.WriteUnit("/opt/homebrew/bin/beacon-otelcol", "/x/otelcol.yaml"); err != nil {
+ t.Fatal(err)
+ }
+ if err := collector.Load(); err != nil {
+ t.Fatalf("collector Load: %v", err)
+ }
+ forwarder := ForwarderManager{UserMode: true, Kind: KindLaunchd}
+ if _, err := forwarder.WriteUnit("/opt/beacon/bin/vector", "/x/vector.toml"); err != nil {
+ t.Fatal(err)
+ }
+ if err := forwarder.Load(); err != nil {
+ t.Fatalf("forwarder Load: %v", err)
+ }
+ inventory := InventoryManager{UserMode: true, Kind: KindLaunchd}
+ if _, err := inventory.WriteUnit("/opt/homebrew/bin/beacon", ""); err != nil {
+ t.Fatal(err)
+ }
+ if err := inventory.Load(); err != nil {
+ t.Fatalf("inventory Load: %v", err)
+ }
+ for _, p := range bootstrapPaths(*calls) {
+ if !strings.HasPrefix(p, f.staging+string(filepath.Separator)) {
+ t.Fatalf("bootstrap from %s, want a staged copy under %s", p, f.staging)
+ }
+ }
+ for _, label := range []string{UserLabel, ForwarderLabel, InventoryLabel} {
+ if _, err := os.Stat(filepath.Join(f.staging, label+".plist")); err != nil {
+ t.Fatalf("no staged copy for %s: %v", label, err)
+ }
+ }
+}
diff --git a/cli/beacon/internal/endpoint/service/service_test.go b/cli/beacon/internal/endpoint/service/service_test.go
index 392f7572..ed819667 100644
--- a/cli/beacon/internal/endpoint/service/service_test.go
+++ b/cli/beacon/internal/endpoint/service/service_test.go
@@ -356,6 +356,10 @@ func TestLaunchctlGuidance(t *testing.T) {
if !strings.Contains(withTarget, "launchctl bootout gui/501/"+UserLabel) {
t.Fatalf("guidance missing domain/label target: %q", withTarget)
}
+ // #639: an external-volume home is a known cause of error 5, and doctor names it.
+ if !strings.Contains(withTarget, "/Volumes") || !strings.Contains(withTarget, "beacon endpoint doctor") {
+ t.Fatalf("guidance should mention the external-volume cause: %q", withTarget)
+ }
fallback := launchctlGuidance("Input/output error", "", "")
if !strings.Contains(fallback, "the Beacon launchd job") {
diff --git a/cli/beacon/internal/endpoint/service/volume_unix.go b/cli/beacon/internal/endpoint/service/volume_unix.go
new file mode 100644
index 00000000..9f1534b5
--- /dev/null
+++ b/cli/beacon/internal/endpoint/service/volume_unix.go
@@ -0,0 +1,27 @@
+//go:build !windows
+
+package service
+
+import (
+ "os"
+ "syscall"
+)
+
+// volumeID returns the device number of the filesystem holding path, following symlinks.
+func volumeID(path string) (uint64, error) {
+ var st syscall.Stat_t
+ if err := syscall.Stat(path, &st); err != nil {
+ return 0, &os.PathError{Op: "stat", Path: path, Err: err}
+ }
+ // Dev is int32 on darwin and uint64 on linux; the conversion is a no-op on the latter.
+ return uint64(st.Dev), nil
+}
+
+// fileOwner returns the uid that owns info's file.
+func fileOwner(info os.FileInfo) (int, bool) {
+ st, ok := info.Sys().(*syscall.Stat_t)
+ if !ok {
+ return 0, false
+ }
+ return int(st.Uid), true
+}
diff --git a/cli/beacon/internal/endpoint/service/volume_windows.go b/cli/beacon/internal/endpoint/service/volume_windows.go
new file mode 100644
index 00000000..7221ddbe
--- /dev/null
+++ b/cli/beacon/internal/endpoint/service/volume_windows.go
@@ -0,0 +1,16 @@
+//go:build windows
+
+package service
+
+import (
+ "errors"
+ "os"
+)
+
+// volumeID is only consulted for launchd, which does not exist on Windows.
+func volumeID(string) (uint64, error) {
+ return 0, errors.New("volume lookup is not implemented on Windows")
+}
+
+// fileOwner has no uid to report on Windows.
+func fileOwner(os.FileInfo) (int, bool) { return 0, false }
diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdx
index 443c18d6..1ef006de 100644
--- a/docs/cli/endpoint-paths.mdx
+++ b/docs/cli/endpoint-paths.mdx
@@ -40,6 +40,8 @@ The Beacon forwarder started by `beacon endpoint connect` is a second, resident
The scheduled inventory job is a third, one-shot unit that `beacon endpoint install` writes in both modes and the package postinstall reconciles on every upgrade: `/Library/LaunchDaemons/com.beacon.endpoint.inventory.plist` or `~/Library/LaunchAgents/com.beacon.endpoint.inventory.plist` on macOS, `beacon-inventory.timer` plus `beacon-inventory.service` under `/etc/systemd/system` or `~/.config/systemd/user` on Linux. It writes `inventory_state.jsonl` and its `inventory-state.json` state file beside the runtime log. Like the forwarder it is not offered in supervised mode; run `beacon endpoint inventory heartbeat --scheduled` from your own scheduler there.
+On macOS, when `~/Library/LaunchAgents` is on a volume other than the startup volume, such as a home directory on an external disk, launchd refuses to bootstrap plists from it. Beacon then bootstraps each user LaunchAgent from a copy staged in `$TMPDIR/beacon-launchd-<uid>`, falling back to `/private/tmp/beacon-launchd-<uid>`. The canonical plist stays in `~/Library/LaunchAgents`. See [Home directory on an external volume](/platforms/macos#home-directory-on-an-external-volume).
+
Windows has no unit file to point at: the service definition lives in the registry, so that is what `beacon endpoint status` reports where the other platforms report a path. And there is no counterpart to `systemctl --user` or launchd's per-user domain, so a Windows user-mode install always gets the supervised collector. See [Windows install](/platforms/windows#user-mode-install).
A supervised collector is a plain background process tracked by a pidfile. It works, but nothing restarts it if it exits or when the machine reboots. `beacon endpoint status` says so explicitly rather than reporting the same health as a real service.
diff --git a/docs/platforms/macos.mdx b/docs/platforms/macos.mdx
index ad743731..e41f5d4e 100644
--- a/docs/platforms/macos.mdx
+++ b/docs/platforms/macos.mdx
@@ -68,6 +68,24 @@ If the job or its plist is missing or broken, repair it without reinstalling:
beacon endpoint doctor --fix
```
+### Home directory on an external volume
+
+launchd will not bootstrap a LaunchAgent whose plist is on a volume other than the startup volume. When your home directory is on an external disk (`/Volumes/<disk>`), `launchctl bootstrap gui/<uid> ~/Library/LaunchAgents/<label>.plist` fails with `Bootstrap failed: 5: Input/output error`, even with ownership enabled on the volume.
+
+A user-mode install handles this itself. Beacon still writes the canonical plists to `~/Library/LaunchAgents`, but when that directory is on a different volume from `/Users`, it copies each plist into a private directory on the startup volume and bootstraps the copy instead. That directory is `$TMPDIR/beacon-launchd-<uid>`, with `/private/tmp/beacon-launchd-<uid>` as a fallback, and it must be owned by you with mode `0700`. This applies to the collector, the scheduled inventory job, and the managed forwarder. The program, its config, and the logs stay where they are, and a home on the startup volume is bootstrapped in place as before. `launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"` shows the staged path.
+
+`beacon endpoint doctor` reports this layout as `launch_agents_volume`. If the collector is not running after a restart or login, run `beacon endpoint repair --user`, which stages fresh copies and bootstraps them again. If Beacon cannot stage the copies, doctor reports a failure. In that case, bootstrap them by hand:
+
+```bash title="Manual bootstrap from the startup volume"
+beacon endpoint install --user --no-start
+mkdir -p -m 700 "$TMPDIR/beacon-launchd"
+for label in com.beacon.endpoint.collector.user com.beacon.endpoint.inventory; do
+ cp "$HOME/Library/LaunchAgents/$label.plist" "$TMPDIR/beacon-launchd/"
+ launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+ launchctl bootstrap "gui/$(id -u)" "$TMPDIR/beacon-launchd/$label.plist"
+done
+```
+
## What is macOS-specific
Most of Beacon behaves identically everywhere: the event schema, the collector, hooks, the dashboard, and threat detection. These are the parts that do not: