Skip to content

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

Session sync follow-ups: sessions enable|disable, BEACON_SESSION_SYNC, docs (#1174)

Shukan Shah3871eb34da55
diff --git a/CLAUDE.md b/CLAUDE.md
index 8d39b2e5..72d6a752 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -66,7 +66,7 @@ Supported runtime surfaces today:
- Browser chat telemetry through an optional MV3 extension (`browser-extension/`; Chrome, with a beta Firefox build) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. The one build serves every Chromium browser; each event names the browser it came from in the typed `user_agent.name`/`user_agent.version` fields (OTel semconv, promoted by the exporter so Metadata-only forwarding keeps them), resolved in `browser-extension/src/shared/browser-identity.ts` from UA Client Hints brands, with a UA-string fallback that also names Firefox. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented. Per-browser differences live only in `browser-extension/tools/targets.mjs` (one entry per target, deriving its manifest from `src/manifest.json`; Chrome ships that file verbatim to `dist/`, Firefox gets `dist-firefox/`), and every extension API call goes through the `src/shared/browser.ts` shim (a unit test fails on direct `chrome.*` use). The Firefox Gecko ID `[email protected]` is pinned and must never change.
- `beaconjson` OpenTelemetry Collector exporter that converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL.
- OTLP forward (`beacon endpoint install|repair --otlp-forward-endpoint`, `--otlp-forward-protocol grpc|http/protobuf`, `--otlp-forward-harness`, repeatable `--otlp-forward-header`, `--no-otlp-forward`; `config.json` `destinations.otlp_forward`): for machines whose runtimes already exported OTLP to another backend before Beacon pointed them at its collector. The collector renders an `otlp/forward` or `otlphttp/forward` exporter (both in `collector-builder/builder.yaml`) on `logs/forward`, `traces/forward` and `metrics/forward` pipelines fed by the same receiver: `memory_limiter`, `beacon_forward_filter` (`forwardfilterprocessor`; keeps only resources whose harness, resolved like beaconjson resolves it, is listed, default Claude Code and Codex, so browser-extension chats and other runtimes never leave), `claude_api_body` on logs, `beacon_privacy`, `batch`. The exporter's queue and retries are bounded so a down backend sheds data instead of pushing `memory_limiter` into refusing Beacon's own pipelines. It is a customer-chosen destination like the HEC exporters, not a Beacon network channel, and carries no hook or session-store data. Install and repair carry it over (`buildConfig`) until `--no-otlp-forward` removes it. Header values never go in `config.json` (ordinary accounts read the system one to find the system log): they live in `OTLPForwardSecretsPath` (`otlp-forward-headers.json`, 0600) and the 0600 collector config, `config.json` keeps `header_names`, and status, doctor and `config show` show names only. Guide: `docs/guides/kandji-otlp-forward-mdm.mdx`.
-- Scheduled session sync (`beacon endpoint install|repair --session-sync`, `--no-session-sync`; `config.json` `session_sync.enabled`, opt-in; docs in `docs/cli/endpoint-install.mdx#scheduled-session-sync`): a one-shot job, `com.beacon.endpoint.session-sync` / `beacon-session-sync.timer` (`service.SessionSyncManager`), every 15 minutes starting one interval after load (`jobSpec.runAtLoad` false, unlike inventory: a run fired at load would take the sweep lock ahead of the install backfill that follows it), running the hidden-flagged `beacon endpoint sessions sync --scheduled` (`cli/beacon/cmd/endpoint_session_sync.go`), which is `runEndpointBackfill`: the install backfill's sweep, window, budget and system-mode confinement, with cursors so each run reads only what is new. `lifecycle.ReconcileSessionSyncJob` installs it when on and removes it when off on every install, repair and package upgrade (`beacon endpoint sessions install-daemon`), and `buildConfig` carries the setting. It and the inventory job share `service.scheduledJob` (`jobSpec` per job). The scheduled run reports failures and exits 0 so the scheduler keeps it; a manual run fails on them. Every sweep (install, connect, manual and scheduled) and every writing `beacon endpoint <runtime> sync` (through `collectUnderSweepLock`, once or per `--watch` tick; a test fails on a collector called directly from `cmd`) holds `<BaseDir>/state/session-sweep.lock` for its whole run, because collectors load cursors at the start and save them at the end; the scheduled run and watch ticks skip when it is held, `--print` takes no lock, and the scheduled run returns early unless `session_sync.enabled` is on. An install or connect that skips its backfill (`--no-backfill`, `BEACON_BACKFILL=0`) records per-runtime floors in `session-sync-floor.json` beside the lock (`recordSkippedBackfill`), and a session sync then reads only that runtime's sessions active since (`sessionwindow.Recent` is per session, so an ongoing one is read whole); only a runtime with none of its own cursor files (`endpointBackfillRunner.State`, resolved in the console user's home for a system endpoint) gets one, an existing floor is never moved later, and a backfill that runs removes them all. A scheduled system run copies each `SQLite` runner's store at most every `endpointSnapshotInterval` (an hour; times in `session-sync-snapshots.json`), because the confined copy can approach `sessionfs.MaxSnapshotBytes`. Tests point `endpointSweepLockPath` at a temp dir in `TestMain`. A user-mode job carries `sessionSyncJobEnv` (the inventory job's variables plus `sessionSyncJobPathEnv`/`sessionSyncJobNameEnv`), and a test fails when a session-store collector reads a variable it does not carry.
+- Scheduled session sync (`beacon endpoint install|repair --session-sync`, `--no-session-sync`; `config.json` `session_sync.enabled`, opt-in; docs in `docs/cli/endpoint-install.mdx#scheduled-session-sync`): a one-shot job, `com.beacon.endpoint.session-sync` / `beacon-session-sync.timer` (`service.SessionSyncManager`), every 15 minutes starting one interval after load (`jobSpec.runAtLoad` false, unlike inventory: a run fired at load would take the sweep lock ahead of the install backfill that follows it), running the hidden-flagged `beacon endpoint sessions sync --scheduled` (`cli/beacon/cmd/endpoint_session_sync.go`), which is `runEndpointBackfill`: the install backfill's sweep, window, budget and system-mode confinement, with cursors so each run reads only what is new. `lifecycle.ReconcileSessionSyncJob` installs it when on and removes it when off on every install, repair and package upgrade (`beacon endpoint sessions install-daemon`), and `buildConfig` carries the setting. It and the inventory job share `service.scheduledJob` (`jobSpec` per job). The scheduled run reports failures and exits 0 so the scheduler keeps it; a manual run fails on them. Every sweep (install, connect, manual and scheduled) and every writing `beacon endpoint <runtime> sync` (through `collectUnderSweepLock`, once or per `--watch` tick; a test fails on a collector called directly from `cmd`) holds `<BaseDir>/state/session-sweep.lock` for its whole run, because collectors load cursors at the start and save them at the end; the scheduled run and watch ticks skip when it is held, `--print` takes no lock, and the scheduled run returns early unless `session_sync.enabled` is on. An install or connect that skips its backfill (`--no-backfill`, `BEACON_BACKFILL=0`) records per-runtime floors in `session-sync-floor.json` beside the lock (`recordSkippedBackfill`), and a session sync then reads only that runtime's sessions active since (`sessionwindow.Recent` is per session, so an ongoing one is read whole); only a runtime with none of its own cursor files (`endpointBackfillRunner.State`, resolved in the console user's home for a system endpoint) gets one, an existing floor is never moved later, and a backfill that runs removes them all. A scheduled system run copies each `SQLite` runner's store at most every `endpointSnapshotInterval` (an hour; times in `session-sync-snapshots.json`), because the confined copy can approach `sessionfs.MaxSnapshotBytes`. Tests point `endpointSweepLockPath` at a temp dir in `TestMain`. `beacon endpoint sessions enable|disable` (`lifecycle.SetSessionSync`) changes only that key of config.json (`setConfigFileKey`) and reconciles the job, because a repair rebuilds the config from its flags and resets harnesses, ports and HEC destinations it is not given. Package installs set it with `BEACON_SESSION_SYNC=1|0` (unset keeps it) in `install-endpoint.sh` (macOS and Linux). A user-mode job carries `sessionSyncJobEnv` (the inventory job's variables plus `sessionSyncJobPathEnv`/`sessionSyncJobNameEnv`), and a test fails when a session-store collector reads a variable it does not carry.
- Endpoint inventory (`inventory.heartbeat` / `inventory.snapshot` in `inventory_state.jsonl`) is written by a scheduled job, `com.beacon.endpoint.inventory` (`service.InventoryManager`, user LaunchAgent or system LaunchDaemon, `beacon-inventory.timer` on systemd), every six hours and once at load, on by default and reconciled by `lifecycle.ReconcileInventoryJob` on every install, repair and package upgrade (`beacon endpoint inventory install-daemon`). Agent hooks do not trigger inventory any more; the hook binary's `--cli` flag and `inventory-heartbeat` subcommand survive only as no-ops for hook commands written by older versions, and `beacon endpoint inventory heartbeat --trigger hook` is likewise retired. A system-mode run inventories the active console user's home and still writes the liveness heartbeat when nobody is logged in; the scheduled scan has no working directory, so project-scoped config is only in `beacon endpoint inventory`.
- Beacon Cloud forwarding, the one Beacon-hosted network channel for endpoint telemetry: user-mode `beacon endpoint connect` authorizes device enrollment with the signed-in CLI account; system mode uses browser PKCE at `/cli/enroll`. Both store only the per-device key in `<BaseDir>/asymptote/vector-secrets.json` (0600, 0700 dir), render the selected privacy mode into `vector.toml` (re-rendered in place by install, repair and package upgrades, see above), validate it, and run Vector as `com.beacon.endpoint.asymptote-forwarder` / `beacon-asymptote-forwarder.service` through `service.ForwarderManager` (refused in supervised mode). `enrollment.json` and `config.json`'s `managed_ingest` block carry only non-secret identity and privacy mode; `beacon endpoint status` reports forwarder state and a live credential check (`GET /v1/ingest/health`, 3 s timeout); `disconnect` and `uninstall` remove the forwarder and credentials but never revoke server-side.
- Asymptote Observe TypeScript SDK instrumentation for cloud applications, starting from OpenTelemetry/OpenLLMetry patterns and `observe()` wrappers.
diff --git a/cli/beacon/cmd/endpoint_session_sync.go b/cli/beacon/cmd/endpoint_session_sync.go
index 8a7a3539..6a6f2fdb 100644
--- a/cli/beacon/cmd/endpoint_session_sync.go
+++ b/cli/beacon/cmd/endpoint_session_sync.go
@@ -38,6 +38,26 @@ var endpointSessionsInstallDaemonCmd = &cobra.Command{
RunE: runSessionsInstallDaemon,
}
+var endpointSessionsEnableCmd = &cobra.Command{
+ Use: "enable",
+ Short: "Turn the scheduled session sync on for the installed endpoint",
+ Long: "Records `session_sync.enabled` in the endpoint config and installs and loads the scheduled session sync job. " +
+ "Every other setting is left as it is: unlike `beacon endpoint repair --session-sync`, it does not rebuild the config, " +
+ "collector or hooks, so it cannot reset harnesses or ports or drop a HEC destination.",
+ Args: cobra.NoArgs,
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error { return runSessionsSet(cmd, true) },
+}
+
+var endpointSessionsDisableCmd = &cobra.Command{
+ Use: "disable",
+ Short: "Turn the scheduled session sync off and remove its job",
+ Long: "Records `session_sync.enabled: false` in the endpoint config and unloads and removes the scheduled session sync job, leaving every other setting as it is.",
+ Args: cobra.NoArgs,
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error { return runSessionsSet(cmd, false) },
+}
+
var endpointSessionsOpts struct {
scheduled bool
}
@@ -46,7 +66,9 @@ func init() {
endpointCmd.AddCommand(endpointSessionsCmd)
endpointSessionsCmd.AddCommand(endpointSessionsSyncCmd)
endpointSessionsCmd.AddCommand(endpointSessionsInstallDaemonCmd)
- for _, c := range []*cobra.Command{endpointSessionsSyncCmd, endpointSessionsInstallDaemonCmd} {
+ endpointSessionsCmd.AddCommand(endpointSessionsEnableCmd)
+ endpointSessionsCmd.AddCommand(endpointSessionsDisableCmd)
+ for _, c := range []*cobra.Command{endpointSessionsSyncCmd, endpointSessionsInstallDaemonCmd, endpointSessionsEnableCmd, endpointSessionsDisableCmd} {
c.Flags().BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")
c.Flags().BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths")
c.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")
@@ -114,10 +136,31 @@ func runSessionsInstallDaemon(cmd *cobra.Command, args []string) error {
return nil
}
+// setSessionSync is indirected so the commands can be tested without a scheduler.
+var setSessionSync = lifecycle.SetSessionSync
+
+func runSessionsSet(cmd *cobra.Command, enabled bool) error {
+ userMode := endpointUserMode()
+ if !userMode && !lifecycle.HasSystemPrivileges() {
+ return fmt.Errorf("changing the system session sync needs elevated privileges; %s", lifecycle.SystemPrivilegeHint())
+ }
+ result, err := setSessionSync(lifecycle.InventoryJobOptions{
+ UserMode: userMode,
+ Program: lifecycle.DefaultInventoryJobProgram(userMode),
+ LogPath: endpointOpts.logPath,
+ Load: true,
+ }, enabled)
+ if err != nil {
+ return err
+ }
+ fmt.Fprintln(cmd.OutOrStdout(), sessionSyncReconcileMessage(result))
+ return nil
+}
+
func sessionSyncReconcileMessage(result lifecycle.SessionSyncJobResult) string {
switch {
case !result.Enabled:
- return "Session sync is off (turn it on with `beacon endpoint repair --session-sync`); no scheduled job installed."
+ return "Session sync is off (turn it on with `beacon endpoint sessions enable`); no scheduled job installed."
case result.Skipped != "":
return "Scheduled session sync job not installed: " + result.Skipped
default:
diff --git a/cli/beacon/cmd/endpoint_session_sync_test.go b/cli/beacon/cmd/endpoint_session_sync_test.go
index d3103f00..81808191 100644
--- a/cli/beacon/cmd/endpoint_session_sync_test.go
+++ b/cli/beacon/cmd/endpoint_session_sync_test.go
@@ -341,3 +341,38 @@ func TestSessionSyncStatusLine(t *testing.T) {
t.Fatalf("on = %q", got)
}
}
+
+// `sessions enable|disable` hand the setting to lifecycle.SetSessionSync and report the job.
+func TestSessionsEnableAndDisable(t *testing.T) {
+ oldOpts, oldSet := endpointOpts, setSessionSync
+ t.Cleanup(func() { endpointOpts, setSessionSync = oldOpts, oldSet })
+ endpointOpts.userMode, endpointOpts.systemMode = true, false
+
+ var got []bool
+ setSessionSync = func(opts lifecycle.InventoryJobOptions, enabled bool) (lifecycle.SessionSyncJobResult, error) {
+ if !opts.UserMode || !opts.Load {
+ t.Fatalf("options = %+v, want a user-mode job that is loaded", opts)
+ }
+ got = append(got, enabled)
+ if enabled {
+ return lifecycle.SessionSyncJobResult{Enabled: true, UnitPath: "/fake/session-sync.plist", Loaded: true}, nil
+ }
+ return lifecycle.SessionSyncJobResult{Removed: true}, nil
+ }
+ var out bytes.Buffer
+ endpointSessionsEnableCmd.SetOut(&out)
+ if err := endpointSessionsEnableCmd.RunE(endpointSessionsEnableCmd, nil); err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(out.String(), "Scheduled session sync job installed (/fake/session-sync.plist)") {
+ t.Fatalf("enable output %q", out.String())
+ }
+ out.Reset()
+ endpointSessionsDisableCmd.SetOut(&out)
+ if err := endpointSessionsDisableCmd.RunE(endpointSessionsDisableCmd, nil); err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(out.String(), "Session sync is off") || len(got) != 2 || !got[0] || got[1] {
+ t.Fatalf("disable output %q, calls %v", out.String(), got)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.go
index e65beb8b..4df6cf21 100644
--- a/cli/beacon/internal/endpoint/config/config.go
+++ b/cli/beacon/internal/endpoint/config/config.go
@@ -293,9 +293,13 @@ func saveOTLPForwardSecrets(cfg Config) error {
// credential or was already private, and otherwise readable like any config.json. Writing it with
// atomicfile.Write alone gave a Windows file the tree's DACL, so every user could read a HEC token.
func RewriteSystemConfig(path string, data []byte, wasPrivate bool) error {
- secret := wasPrivate || rawConfigHoldsCredential(data)
- if secret {
- return writeSecretFile(false, path, data)
+ return RewriteConfig(false, path, data, wasPrivate)
+}
+
+// RewriteConfig is RewriteSystemConfig for either mode: a private user config is written 0600.
+func RewriteConfig(userMode bool, path string, data []byte, wasPrivate bool) error {
+ if wasPrivate || rawConfigHoldsCredential(data) {
+ return writeSecretFile(userMode, path, data)
}
return atomicfile.Write(path, data, 0644)
}
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
index 69c362e0..6e59497b 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
@@ -1080,6 +1080,12 @@ func autoUpdateModeFromConfigFile(path string) (string, error) {
}
func setAutoUpdateModeInConfigFile(path, mode string) error {
+ return setConfigFileKey(false, path, "auto_update", endpointconfig.AutoUpdate{Mode: mode})
+}
+
+// setConfigFileKey replaces one top-level key of config.json and leaves every other key as it is,
+// where install and repair rebuild the whole config from their flags.
+func setConfigFileKey(userMode bool, path, key string, value any) error {
data, err := os.ReadFile(path)
if err != nil {
return err
@@ -1088,16 +1094,16 @@ func setAutoUpdateModeInConfigFile(path, mode string) error {
if err := json.Unmarshal(data, &raw); err != nil {
return err
}
- autoUpdate, err := json.Marshal(endpointconfig.AutoUpdate{Mode: mode})
+ encoded, err := json.Marshal(value)
if err != nil {
return err
}
- raw["auto_update"] = autoUpdate
+ raw[key] = encoded
out, err := json.MarshalIndent(raw, "", " ")
if err != nil {
return err
}
- return endpointconfig.RewriteSystemConfig(path, out, configIsPrivate(path))
+ return endpointconfig.RewriteConfig(userMode, path, out, configIsPrivate(path))
}
// configIsPrivate reports whether the file at path is readable by its owner only. Only POSIX modes
diff --git a/cli/beacon/internal/endpoint/lifecycle/session_sync.go b/cli/beacon/internal/endpoint/lifecycle/session_sync.go
index 9d7a68d6..f2569cf1 100644
--- a/cli/beacon/internal/endpoint/lifecycle/session_sync.go
+++ b/cli/beacon/internal/endpoint/lifecycle/session_sync.go
@@ -2,6 +2,9 @@ package lifecycle
import (
"encoding/json"
+ "errors"
+ "fmt"
+ "io/fs"
"os"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
@@ -110,6 +113,24 @@ func reconcileSessionSyncJobWith(job inventoryJobController, opts InventoryJobOp
return result, nil
}
+// SetSessionSync turns the scheduled session sync on or off on an installed endpoint. A repair
+// rebuilds the config from its flags, so one run without the flags an endpoint was set up with
+// resets its harnesses and ports and drops its HEC destinations; this records only
+// `session_sync.enabled` in config.json, leaves every other key as it is, and reconciles the job.
+func SetSessionSync(opts InventoryJobOptions, enabled bool) (SessionSyncJobResult, error) {
+ path := endpointconfig.ConfigPath(opts.UserMode)
+ if err := setConfigFileKey(opts.UserMode, path, "session_sync", endpointconfig.SessionSync{Enabled: enabled}); err != nil {
+ if errors.Is(err, fs.ErrNotExist) {
+ return SessionSyncJobResult{}, fmt.Errorf("no endpoint is installed here (%s): install it first; `beacon endpoint install --session-sync` turns the sync on with it", path)
+ }
+ return SessionSyncJobResult{}, err
+ }
+ if opts.LogPath == "" {
+ opts.LogPath = loadOrDefault(opts.UserMode, "").LogPath
+ }
+ return ReconcileSessionSyncJob(opts)
+}
+
// sessionSyncEnabledFromConfigFile reads `session_sync.enabled` from the config on disk. A
// missing or unreadable config means off: the job is opt-in.
func sessionSyncEnabledFromConfigFile(path string) bool {
diff --git a/cli/beacon/internal/endpoint/lifecycle/session_sync_test.go b/cli/beacon/internal/endpoint/lifecycle/session_sync_test.go
index 44544284..478c673a 100644
--- a/cli/beacon/internal/endpoint/lifecycle/session_sync_test.go
+++ b/cli/beacon/internal/endpoint/lifecycle/session_sync_test.go
@@ -1,6 +1,7 @@
package lifecycle
import (
+ "encoding/json"
"os"
"path/filepath"
"reflect"
@@ -9,6 +10,7 @@ import (
"testing"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
)
@@ -157,3 +159,69 @@ func TestRollbackRestoresSessionSyncJobTurnedOff(t *testing.T) {
t.Fatalf("calls = %v, want nothing for a job that was not scheduled before", *calls)
}
}
+
+// Turning the sync on or off changes session_sync and nothing else. A repair would rebuild the
+// config from its flags, resetting harnesses and ports and dropping a HEC destination.
+func TestSetSessionSyncChangesOnlyItsOwnKey(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ const body = `{"user_mode":true,"log_path":"/l/runtime.jsonl","harnesses":["claude","cursor"],` +
+ `"collector":{"grpc_port":5317,"http_port":5318},` +
+ `"destinations":{"splunk_hec":{"enabled":true,"endpoint":"https://splunk.example:8088","token":"hec-token"}},` +
+ `"not_yet_known":{"kept":true}}`
+ writeInventoryConfig(t, true, body)
+ calls := &[]string{}
+ old := newSessionSyncJob
+ newSessionSyncJob = func(bool, service.Kind) inventoryJobController {
+ return recordingInventoryJob{calls: calls, supported: true, unitPath: "/fake/s.plist"}
+ }
+ t.Cleanup(func() { newSessionSyncJob = old })
+
+ result, err := SetSessionSync(InventoryJobOptions{UserMode: true, Program: "/bin/beacon", Load: true}, true)
+ if err != nil || !result.Enabled || !result.Loaded {
+ t.Fatalf("enable: %+v, %v", result, err)
+ }
+ // The job takes the config's log path when none is given.
+ if want := []string{"write /bin/beacon /l/runtime.jsonl", "load"}; !reflect.DeepEqual(*calls, want) {
+ t.Fatalf("calls = %v, want %v", *calls, want)
+ }
+ path := endpointconfig.ConfigPath(true)
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var before, after map[string]any
+ if err := json.Unmarshal([]byte(body), &before); err != nil {
+ t.Fatal(err)
+ }
+ if err := json.Unmarshal(data, &after); err != nil {
+ t.Fatal(err)
+ }
+ if !reflect.DeepEqual(after["session_sync"], map[string]any{"enabled": true}) {
+ t.Fatalf("session_sync = %v", after["session_sync"])
+ }
+ delete(after, "session_sync")
+ if !reflect.DeepEqual(before, after) {
+ t.Fatalf("other keys changed:\nbefore %v\nafter %v", before, after)
+ }
+ // It holds a HEC token, so the rewrite keeps it private.
+ if testenv.HasPOSIXFileModes() {
+ if info, err := os.Stat(path); err != nil || info.Mode().Perm() != 0o600 {
+ t.Fatalf("config mode = %v, %v; want 0600", info.Mode().Perm(), err)
+ }
+ }
+
+ *calls = nil
+ if result, err = SetSessionSync(InventoryJobOptions{UserMode: true, Program: "/bin/beacon", Load: true}, false); err != nil || !result.Removed {
+ t.Fatalf("disable: %+v, %v", result, err)
+ }
+ if want := []string{"unload", "remove"}; !reflect.DeepEqual(*calls, want) {
+ t.Fatalf("calls = %v, want %v", *calls, want)
+ }
+}
+
+func TestSetSessionSyncNeedsAnInstalledEndpoint(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ if _, err := SetSessionSync(InventoryJobOptions{UserMode: true, Program: "/bin/beacon"}, true); err == nil || !strings.Contains(err.Error(), "install it first") {
+ t.Fatalf("err = %v, want a pointer to install", err)
+ }
+}
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index f107a1df..8794d34c 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -12,6 +12,8 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
## Unreleased
- **Scheduled session sync** · `beacon endpoint install|repair --session-sync` turns on a job that runs every 15 minutes and reads new records from the agent runtimes' local session stores into the runtime log. It runs the same bounded, confined sweep install already runs once, so session-store data keeps reaching the log, and any forwarder reading it, after install. Off by default; repair and upgrades keep the setting, and `--no-session-sync` removes the job. See [Scheduled session sync](/cli/endpoint-install#scheduled-session-sync).
+- **Turn session sync on or off without a repair** · `beacon endpoint sessions enable|disable` changes only the scheduled session sync setting and installs or removes its job. `beacon endpoint repair --session-sync` rebuilds the endpoint from its flags, so run without the ones an endpoint was set up with it reset harnesses and OTLP ports and dropped Splunk or Falcon HEC destinations. For package and MDM installs, `BEACON_SESSION_SYNC=1` in the environment of `/opt/beacon/scripts/install-endpoint.sh` (macOS and Linux) turns it on, and `0` turns it off; unset keeps the endpoint's own setting, so package upgrades never change it.
+- **Repair keeps the collector it came with** · Without `--collector`, `beacon endpoint repair` and `install` now use the `beacon-otelcol` beside the `beacon` CLI before one on `PATH`, and repair checks the collector before it takes the endpoint down. Under `sudo` on a Mac that also had Homebrew Beacon, repair found Homebrew's older collector first, refused it after removing the collector's service and config, and left the endpoint without its collector.
- **Windows session backfill keeps its copies of your sessions from other users** · To read the SQLite session stores of Cursor, OpenCode, Devin CLI and Hermes Agent, a system install's session backfill copies them into `%ProgramData%\Beacon\Endpoint\state\backfill-snapshots`. On Windows that directory let every local account read the copies until they were deleted, and indefinitely when a run was stopped partway. It is now readable by SYSTEM and Administrators only, and the backfill copies nothing when it cannot make it so.
- **Windows system installs keep destination credentials from other users** · On Windows the 0600 mode Beacon asked for has no effect, and `%ProgramData%\Beacon` lets every user read the files below it, so any local account could read a Splunk or Falcon HEC token in `config.json` and `otelcol.yaml`, and the OTLP forward's headers. Those files are now created with access for SYSTEM and Administrators only, at creation, so there is no moment they are readable. A `config.json` with no credential in it stays readable, as before, so other accounts still find the system log through it.
- **Forward OTLP to a second backend** · Macs that already sent Claude Code or Codex OpenTelemetry to another backend lost that export when Beacon pointed the runtimes at its collector. `beacon endpoint install|repair --otlp-forward-endpoint <endpoint>` (with `--otlp-forward-protocol grpc|http/protobuf` and repeatable `--otlp-forward-header name=value`) now has the collector send that OTLP on to the endpoint as well, through pipelines of its own. The forward carries only Claude Code and Codex by default (`--otlp-forward-harness` changes the list), so browser-extension chats and other runtimes stay local. Secrets are redacted, raw API bodies are dropped, and the queue is bounded, so a down backend never holds up Beacon's own capture. Header values are kept in a root-only `otlp-forward-headers.json` beside `config.json`. Repair and package upgrades keep it; `--no-otlp-forward` removes it. See [Kandji, GCS and an existing OTLP backend](/guides/kandji-otlp-forward-mdm).
diff --git a/docs/cli/endpoint-connect.mdx b/docs/cli/endpoint-connect.mdx
index 5df21555..550b85c5 100644
--- a/docs/cli/endpoint-connect.mdx
+++ b/docs/cli/endpoint-connect.mdx
@@ -11,7 +11,9 @@ Forwarding is opt-in and revocable. Runtime telemetry starts at the end of the
existing runtime log, so pre-connect runtime events are not sent, with one bounded
exception: every connect uploads the last 30 days of agent sessions read
from the runtimes' own session stores, so the dashboard shows your recent work at once
-(see [Session backfill](#session-backfill)). Inventory starts
+(see [Session backfill](#session-backfill)). With the
+[scheduled session sync](/cli/endpoint-install#scheduled-session-sync) on, its later runs keep adding
+session-store records to the log, and those are forwarded as they are written. Inventory starts
at the beginning of `inventory_state.jsonl` so the dashboard receives the endpoint's
current inventory baseline, including inventory records written before connection.
Revoking the device from the dashboard stops ingestion within about a minute.
@@ -69,6 +71,12 @@ the dashboard collapses a re-sent event on it. A privacy-mode change clears the
replaces the staged file, so the backfill is resent in the new mode. `disconnect` removes the file.
`--no-backfill` or `BEACON_BACKFILL=0` connects without uploading any history.
+The backfill is a one-time upload per connect. With the
+[scheduled session sync](/cli/endpoint-install#scheduled-session-sync) on, the job keeps reading the
+session stores every 15 minutes, and the forwarder ships what it writes as ordinary new runtime
+events. When the backfill stopped at its size limit, the job's first runs also read the rest of the
+last 30 days, so that history arrives over the next runs rather than not at all.
+
## Privacy modes
The onboarding wizard records one of two modes. `connect` uses that choice unless
diff --git a/docs/cli/endpoint-copilot.mdx b/docs/cli/endpoint-copilot.mdx
index 63982659..42cbb76e 100644
--- a/docs/cli/endpoint-copilot.mdx
+++ b/docs/cli/endpoint-copilot.mdx
@@ -64,7 +64,7 @@ beacon endpoint copilot sync --print
beacon endpoint copilot sync --watch --interval 5m
```
-Nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running in the account that owns the Copilot directory. A scheduler that starts `sync` without your shell's environment needs `COPILOT_HOME` set in it, or `--copilot-dir`.
+Unless the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync) is on, nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running in the account that owns the Copilot directory. A scheduler that starts `sync` without your shell's environment needs `COPILOT_HOME` set in it, or `--copilot-dir`.
## Status
diff --git a/docs/cli/endpoint-cursor.mdx b/docs/cli/endpoint-cursor.mdx
index 054063ee..86c3f3bc 100644
--- a/docs/cli/endpoint-cursor.mdx
+++ b/docs/cli/endpoint-cursor.mdx
@@ -36,7 +36,7 @@ beacon endpoint cursor sync --print
beacon endpoint cursor sync --watch --interval 5m
```
-`--print` neither writes the runtime log nor advances the cursor, so running it twice shows the same events. Nothing sweeps on its own: run `sync` on a schedule, or leave `--watch` running in the account that owns the Cursor data. [`beacon endpoint install`](/cli/endpoint-install#session-backfill) runs the same sweep once for the last 30 days.
+`--print` neither writes the runtime log nor advances the cursor, so running it twice shows the same events. Unless the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync) is on, nothing sweeps on its own: run `sync` on a schedule, or leave `--watch` running in the account that owns the Cursor data. [`beacon endpoint install`](/cli/endpoint-install#session-backfill) runs the same sweep once for the last 30 days. On a system install, the backfill and the scheduled session sync skip a Cursor database over 512 MiB, so run `sync` as the user there.
```bash title="Show Cursor's stores and collection progress"
beacon endpoint cursor status
diff --git a/docs/cli/endpoint-fx.mdx b/docs/cli/endpoint-fx.mdx
index 0dc324a6..a97a88e7 100644
--- a/docs/cli/endpoint-fx.mdx
+++ b/docs/cli/endpoint-fx.mdx
@@ -62,7 +62,7 @@ beacon endpoint fx sync --print
beacon endpoint fx sync --watch --interval 5m
```
-Nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running.
+Unless the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync) is on, nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running.
A sweep prints what it did, and says out loud the two conditions a counter would hide:
diff --git a/docs/cli/endpoint-harness2.mdx b/docs/cli/endpoint-harness2.mdx
index 72b3613d..5891a56b 100644
--- a/docs/cli/endpoint-harness2.mdx
+++ b/docs/cli/endpoint-harness2.mdx
@@ -70,7 +70,7 @@ beacon endpoint harness2 sync --print
beacon endpoint harness2 sync --watch --interval 1m
```
-Nothing sweeps on its own. Run `sync` after an experiment, under whatever scheduler the platform already uses, or leave `--watch` running during one.
+Unless the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync) is on, nothing sweeps on its own. Run `sync` after an experiment, under whatever scheduler the platform already uses, or leave `--watch` running during one.
```text
Harness² sync: 48 rollouts, 12 changed, 1934 events, 0 errors
diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdx
index 334069c8..9d7527f2 100644
--- a/docs/cli/endpoint-install.mdx
+++ b/docs/cli/endpoint-install.mdx
@@ -109,14 +109,30 @@ off. If this install also connects to Beacon Cloud, the same history is
The session backfill runs once, at install. To keep reading the runtimes' session stores after that, turn on the scheduled session sync:
```bash
-sudo beacon endpoint install --system --session-sync # or: sudo beacon endpoint repair --system --session-sync
+sudo beacon endpoint sessions enable --system # an endpoint that is already installed
+sudo beacon endpoint sessions disable --system # turn it off and remove the job
```
-It installs a job that runs `beacon endpoint sessions sync` every 15 minutes, the first time 15 minutes after the job is loaded (by the install, a repair, a reboot or a package upgrade): `com.beacon.endpoint.session-sync` (a LaunchDaemon in system mode, a LaunchAgent in user mode) or `beacon-session-sync.timer` on systemd. Each run is the same sweep as the backfill above, with the same 30-day window, size budget and, in system mode, the same confined read of the console user's stores. Each runtime's cursor makes a run read only what is new. In system mode a SQLite store (Cursor, OpenCode, Devin CLI, Hermes Agent) is read from a private copy, as the backfill does. A copy can approach 512 MiB and those runtimes are captured live by their hooks or plugins, so the scheduled job copies each one at most once an hour; a store over 512 MiB is skipped and named in the job's output. With nobody logged in, a system run reads nothing. When the install or a later connect skipped the backfill (`--no-backfill` or `BEACON_BACKFILL=0`), each runtime no sync had read yet is limited to sessions active since that skip, not the last 30 days; a session that continues past it is read from its start. A runtime that was already synced reads on from where it was. A later backfill lifts the limit. Only one sync runs at a time: an install, connect, `beacon endpoint sessions sync` or `beacon endpoint <runtime> sync` waits for a sync already in progress and then reads only what it left, a scheduled run or a `--watch` sweep skips its turn while another sync is running, and `--print` dry runs never wait. A user-mode job keeps the store locations the install saw (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `XDG_DATA_HOME`, `OPENCODE_DB` and the rest), because the scheduler does not pass a shell's environment.
+`sessions enable` and `disable` change only this setting and the job. `install` and `repair` take `--session-sync` and `--no-session-sync` too, but repair rebuilds the endpoint from its flags: run without the ones the endpoint was set up with, it resets the harnesses and OTLP ports and drops a Splunk or Falcon HEC destination. For a package or MDM rollout, set `BEACON_SESSION_SYNC=1` in the environment of the package's install script (`/opt/beacon/scripts/install-endpoint.sh`), or run `/opt/beacon/bin/beacon endpoint sessions enable --system` on Macs that already have Beacon. `BEACON_SESSION_SYNC=0` turns it off, and leaving it unset keeps what the endpoint already has, so a package upgrade never changes it.
It is off by default. Hooks and OTLP already capture sessions live, and the session stores add what only they record, such as Claude Code's per-request token usage and complete assistant text from its transcripts. Turning it on writes those records as poll events (`harness.collection_method=poll`) alongside the live ones, which matters when the runtime log is forwarded elsewhere. Token reports keep live usage authoritative over poll usage for the same session.
-The setting is `session_sync.enabled` in `config.json`. Repair and package upgrades keep it, and `--no-session-sync` turns it off and removes the job. A scheduled run also checks the setting, so a job left behind after the config was set to off reads nothing. `beacon endpoint status` shows it, and `beacon endpoint sessions sync` runs the same sweep by hand. A host without launchd or systemd cannot run the job; run `beacon endpoint sessions sync` from your own scheduler there.
+### How it runs
+
+- The job runs `beacon endpoint sessions sync` every 15 minutes: `com.beacon.endpoint.session-sync` (a LaunchDaemon in system mode, a LaunchAgent in user mode) or `beacon-session-sync.timer` on systemd. The first run is 15 minutes after the job is loaded by the install, a repair, a reboot or a package upgrade, never at load.
+- Each run is the same sweep as the backfill above, with the same 30-day window, size budget and, in system mode, the same confined read of the console user's stores. Each runtime's cursor makes a run read only what is new. With nobody logged in, a system run reads nothing.
+- In system mode a SQLite store (Cursor, OpenCode, Devin CLI, Hermes Agent) is read from a private copy, as the backfill does. A copy can approach 512 MiB and those runtimes are captured live by their hooks or plugins, so the scheduled job copies each one at most once an hour. A store over 512 MiB is skipped and named in the job's output; run that runtime's sync command as the user to read it.
+- Only one sync runs at a time. An install, connect, `beacon endpoint sessions sync` or `beacon endpoint <runtime> sync` waits for a sync already in progress and then reads only what it left. A scheduled run or a `--watch` sweep skips its turn while another sync is running, and `--print` dry runs never wait.
+- When the install or a later connect skipped the backfill (`--no-backfill` or `BEACON_BACKFILL=0`), each runtime no sync had read yet is limited to sessions active since that skip, not the last 30 days. A session that continues past the skip is read from its start, a runtime that was already synced reads on from where it was, and a later backfill lifts the limit.
+- A user-mode job keeps the store locations the install saw (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `XDG_DATA_HOME`, `OPENCODE_DB` and the rest), because the scheduler does not pass a shell's environment.
+
+### What to expect when you turn it on
+
+The first runs catch up. When the backfill stopped at its size limit, the rest of the last 30 days is left for the job, and each run writes up to another 12 MiB per runtime (24 MiB in all) until it has read everything. After that, a run writes only what the agents recorded since the previous one. On a machine with a lot of agent history the catch-up takes a few runs, and because the runtime log rotates at 10 MiB and keeps five archives, it pushes older local events out of the log sooner than live telemetry alone would. A connected endpoint forwards the catch-up like any other new events.
+
+### Settings and status
+
+The setting is `session_sync.enabled` in `config.json`. Repair and package upgrades keep it, and `beacon endpoint sessions disable` or `--no-session-sync` turns it off and removes the job. A scheduled run also checks the setting, so a job left behind after the config was set to off reads nothing. `beacon endpoint status` shows `Session sync: every 15m0s; job loaded=true`, and `beacon endpoint sessions sync` runs the same sweep by hand. A host without launchd or systemd cannot run the job; run `beacon endpoint sessions sync` from your own scheduler there.
## Interactive onboarding wizard
diff --git a/docs/cli/endpoint-opencode.mdx b/docs/cli/endpoint-opencode.mdx
index 38ebf31b..b799bcfb 100644
--- a/docs/cli/endpoint-opencode.mdx
+++ b/docs/cli/endpoint-opencode.mdx
@@ -62,7 +62,7 @@ beacon endpoint opencode sync --print
beacon endpoint opencode sync --watch --interval 5m
```
-Nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running in the user context that owns OpenCode's data directory.
+Unless the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync) is on, nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running in the user context that owns OpenCode's data directory.
A tool call that OpenCode has started but not finished is written twice: once as the invocation, and again with its output, exit code, and diff when it returns. Beacon emits both. The invocation arrives as `tool.invoked` on the sweep that first sees it, and the completion arrives on a later sweep as `command.executed`, `file.modified`, or whichever action the finished call turns out to be. OpenCode rewrites the record in place for the second one, so the cursor tracks the events it has already written by id rather than how far it read: a repeated sweep over an unchanged session writes nothing, and one over a session whose call has since returned writes only the completion.
diff --git a/docs/cli/endpoint-pi.mdx b/docs/cli/endpoint-pi.mdx
index b89c48ee..859754a3 100644
--- a/docs/cli/endpoint-pi.mdx
+++ b/docs/cli/endpoint-pi.mdx
@@ -62,7 +62,7 @@ beacon endpoint pi sync --print
beacon endpoint pi sync --watch --interval 5m
```
-Nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running.
+Unless the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync) is on, nothing sweeps on its own. Run `sync` under whatever scheduler the platform already uses, or leave `--watch` running.
## Status
diff --git a/docs/cli/endpoint-status.mdx b/docs/cli/endpoint-status.mdx
index 769218a5..c1a06f48 100644
--- a/docs/cli/endpoint-status.mdx
+++ b/docs/cli/endpoint-status.mdx
@@ -63,6 +63,7 @@ Status includes:
- Last Beacon event in the runtime log, when present
- Beacon Cloud: whether this endpoint is connected (a connect that failed after the server issued the device key is reported as not connected, with `connect_incomplete: true` and the retry command), organization and device id, active privacy mode, forwarder service state, whether the device key is still accepted (`valid`, `revoked`, or `unknown` when offline), and disk-buffer size. In `--json` this is the `managed_ingest` object; account and device keys are never included. The line reports the connection for the install mode you asked about (`--user` or `--system`), even when the collector view switches to the system install because it holds the OTLP ports.
- Inventory heartbeat: whether the scheduled inventory job is enabled and loaded, its interval, and when it last wrote. In `--json` this is the `inventory_heartbeat` object (`enabled`, `scheduled`, `interval`, `job`, `last_emitted_at`, `log_path`), reported for the requested install mode like managed ingest.
+- Session sync: `off`, or how often the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync) runs and whether its job is loaded (`Session sync: every 15m0s; job loaded=true`). In `--json` this is the `session_sync` object (`enabled`, `interval`, `job`).
When Splunk HEC is configured, `--json` includes a `destinations.splunk_hec` object with `configured: true` and the non-secret destination settings. When Falcon LogScale HEC is configured, `--json` includes `destinations.falcon_hec` with the same non-secret fields. HEC tokens are not printed. File-based destinations such as Wazuh, Elastic, Datadog, Sumo Logic, Rapid7, Microsoft Sentinel, and AWS S3 validate against the configured runtime log path and their generated shipper configuration.
diff --git a/docs/cli/endpoint-uninstall.mdx b/docs/cli/endpoint-uninstall.mdx
index 94554d02..44cb2ed6 100644
--- a/docs/cli/endpoint-uninstall.mdx
+++ b/docs/cli/endpoint-uninstall.mdx
@@ -57,7 +57,7 @@ sudo beacon endpoint uninstall --system --keep-logs
## Removed paths
-Beacon removes files listed in its install manifest, including managed config, collector config, and service files. Unless `--keep-logs` is set, it also removes the configured runtime JSONL log.
+Beacon removes files listed in its install manifest, including managed config, collector config, and service files, and unloads and removes the scheduled inventory and session sync jobs. Unless `--keep-logs` is set, it also removes the configured runtime JSONL log.
On a macOS system install, uninstall also stops and removes the S3, GCS, and Falcon forwarders that the package's MDM helpers install (`com.beacon.endpoint.s3-forwarder`, `gcs-forwarder`, and `falcon-forwarder`). Unless `--keep-config` is set, it deletes `/Library/Application Support/Beacon/Forwarders`, which holds their credentials. `beacon endpoint repair` leaves these forwarders running.
diff --git a/docs/guides/fleet-s3-mdm.mdx b/docs/guides/fleet-s3-mdm.mdx
index 66d2f0d7..8861b034 100644
--- a/docs/guides/fleet-s3-mdm.mdx
+++ b/docs/guides/fleet-s3-mdm.mdx
@@ -511,6 +511,7 @@ When you remove Beacon everywhere, also delete the IAM access key and the two Fl
| `/opt/beacon/bin/beacon`, `beacon-otelcol`, `vector` | The CLI, the collector, and the forwarder |
| `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist` | The collector service |
| `/Library/LaunchDaemons/com.beacon.endpoint.inventory.plist` | The inventory job, every 6 hours |
+| `/Library/LaunchDaemons/com.beacon.endpoint.session-sync.plist` | The [session sync](/cli/endpoint-install#scheduled-session-sync) job, every 15 minutes, only when you turn it on |
| `/Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist` | The S3 forwarder, after step 5 |
| `/Library/Application Support/Beacon/Endpoint/` | Beacon's configuration |
| `/Library/Application Support/Beacon/Forwarders/s3-vector.env` | The AWS keys, readable only by root |
diff --git a/docs/mdm/fleet.mdx b/docs/mdm/fleet.mdx
index 653848e0..ec0ccf42 100644
--- a/docs/mdm/fleet.mdx
+++ b/docs/mdm/fleet.mdx
@@ -32,6 +32,7 @@ The package postinstall runs a system-mode install and configures Claude Code an
/Library/Application Support/Beacon/Endpoint/config.json
/Library/LaunchDaemons/com.beacon.endpoint.collector.plist
/Library/LaunchDaemons/com.beacon.endpoint.inventory.plist
+/Library/LaunchDaemons/com.beacon.endpoint.session-sync.plist only with session sync on
/var/log/beacon-agent/runtime.jsonl
/var/log/beacon-agent/inventory_state.jsonl
```
diff --git a/docs/mdm/jamf.mdx b/docs/mdm/jamf.mdx
index 024b00f6..cfee5d47 100644
--- a/docs/mdm/jamf.mdx
+++ b/docs/mdm/jamf.mdx
@@ -218,6 +218,21 @@ including Claude Code, Codex, and Cursor setup.
logged in still heartbeats, with `user_scope.mode` set to `no_console_user`,
and writes a snapshot the next time a user is at the console.
</Accordion>
+ <Accordion title="Session sync is not running">
+ The scheduled session sync is off unless turned on (see [Repair and uninstall](#repair-and-uninstall)). When it is on, a root job, `com.beacon.endpoint.session-sync`, runs every 15 minutes, starting 15 minutes after it is loaded. Confirm it is loaded and how its last run ended:
+
+ ```bash
+ sudo launchctl print system/com.beacon.endpoint.session-sync | grep -E 'state|runs|last exit'
+ sudo /opt/beacon/bin/beacon endpoint status --system | grep 'Session sync'
+ sudo tail -n 5 /Library/Logs/Beacon/com.beacon.endpoint.session-sync.out
+ ```
+
+ If the job is missing, turn the setting on again, which reinstalls and loads it:
+
+ ```bash
+ sudo /opt/beacon/bin/beacon endpoint sessions enable --system
+ ```
+ </Accordion>
<Accordion title="Configured harnesses are wrong">
Check Jamf parameter 4 on the install policy. The default is `claude,codex`; set the parameter explicitly when you want a narrower or broader harness list. Include `gemini` when Gemini CLI telemetry should be managed. Do not include GitHub Copilot CLI in this list; manage Copilot's OTel environment separately.
@@ -262,6 +277,15 @@ including Claude Code, Codex, and Cursor setup.
Use `/opt/beacon/jamf/scripts/repair.sh` as a remediation policy for Macs where extension attributes report a stale or unhealthy install.
+To turn on the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync), which reads new records from the agents' session files every 15 minutes, run this once from a Jamf script policy. It changes only that setting, and package upgrades keep it:
+
+```bash
+#!/bin/sh
+/opt/beacon/bin/beacon endpoint sessions enable --system
+```
+
+`sessions disable --system` turns it off. For new installs, set `BEACON_SESSION_SYNC=1` in the environment of the install helper instead.
+
Use `/opt/beacon/jamf/scripts/uninstall.sh` to remove endpoint service files. Set `BEACON_KEEP_LOGS=1` or Jamf parameter 4 to preserve runtime logs during removal. Set `BEACON_KEEP_CONFIG=1` or Jamf parameter 5 to preserve harness telemetry configuration.
## Related
diff --git a/docs/platforms/macos.mdx b/docs/platforms/macos.mdx
index c264f693..f29669d6 100644
--- a/docs/platforms/macos.mdx
+++ b/docs/platforms/macos.mdx
@@ -73,7 +73,7 @@ beacon endpoint doctor --fix
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 the current login session 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.
+A user-mode install handles the current login session 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, the scheduled session sync job when it is on, 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.
The explicit bootstrap registration belongs to the current launchd login domain. Beacon cannot guarantee that launchd will reload the canonical external-volume plists automatically after logout or restart. `beacon endpoint doctor` therefore reports this layout as a medium-severity `launch_agents_volume` warning even when staging works. 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 safely create and write the staging directory, doctor reports a failure with the rejected path and reason. In that case, bootstrap the plists by hand:
diff --git a/packaging/linux/install-endpoint.sh b/packaging/linux/install-endpoint.sh
index 968c616a..c7240aa1 100755
--- a/packaging/linux/install-endpoint.sh
+++ b/packaging/linux/install-endpoint.sh
@@ -30,6 +30,9 @@ BEACON_SPLUNK_CA_FILE="${BEACON_SPLUNK_CA_FILE:-}"
# shared or restricted; empty keeps the mode the endpoint already has, so a package upgrade never
# changes it.
BEACON_LOG_ACCESS="${BEACON_LOG_ACCESS:-}"
+# 1 turns the scheduled session sync on and 0 turns it off; empty keeps what the endpoint already
+# has, so a package upgrade never changes it.
+BEACON_SESSION_SYNC="${BEACON_SESSION_SYNC:-}"
# The packaged collector sits beside the CLI. Auto-detected rather than required, so a manual
# invocation without BEACON_COLLECTOR still works.
@@ -47,6 +50,14 @@ set -- endpoint install --system \
[ -n "$BEACON_SERVICE" ] && set -- "$@" --service "$BEACON_SERVICE"
[ "$BEACON_NO_START" = "1" ] && set -- "$@" --no-start
[ -n "$BEACON_LOG_ACCESS" ] && set -- "$@" --log-access "$BEACON_LOG_ACCESS"
+case "$BEACON_SESSION_SYNC" in
+ 1|true|TRUE|yes|YES)
+ set -- "$@" --session-sync
+ ;;
+ 0|false|FALSE|no|NO)
+ set -- "$@" --no-session-sync
+ ;;
+esac
[ -n "$BEACON_SPLUNK_HEC_ENDPOINT" ] && set -- "$@" --splunk-hec-endpoint "$BEACON_SPLUNK_HEC_ENDPOINT"
[ -n "$BEACON_SPLUNK_HEC_TOKEN" ] && set -- "$@" --splunk-hec-token "$BEACON_SPLUNK_HEC_TOKEN"
diff --git a/packaging/macos/install-endpoint.sh b/packaging/macos/install-endpoint.sh
index f13def4a..5fb80ed7 100755
--- a/packaging/macos/install-endpoint.sh
+++ b/packaging/macos/install-endpoint.sh
@@ -31,6 +31,9 @@ BEACON_FALCON_CA_FILE="${BEACON_FALCON_CA_FILE:-}"
# shared or restricted; empty keeps the mode the endpoint already has, so a package upgrade never
# changes it.
BEACON_LOG_ACCESS="${BEACON_LOG_ACCESS:-}"
+# 1 turns the scheduled session sync on and 0 turns it off; empty keeps what the endpoint already
+# has, so a package upgrade never changes it.
+BEACON_SESSION_SYNC="${BEACON_SESSION_SYNC:-}"
if [ -z "$BEACON_COLLECTOR" ] && [ -x "/opt/beacon/bin/beacon-otelcol" ]; then
BEACON_COLLECTOR="/opt/beacon/bin/beacon-otelcol"
@@ -50,6 +53,15 @@ if [ -n "$BEACON_LOG_ACCESS" ]; then
set -- "$@" --log-access "$BEACON_LOG_ACCESS"
fi
+case "$BEACON_SESSION_SYNC" in
+ 1|true|TRUE|yes|YES)
+ set -- "$@" --session-sync
+ ;;
+ 0|false|FALSE|no|NO)
+ set -- "$@" --no-session-sync
+ ;;
+esac
+
if [ -n "$BEACON_SPLUNK_HEC_ENDPOINT" ]; then
set -- "$@" --splunk-hec-endpoint "$BEACON_SPLUNK_HEC_ENDPOINT"
fi
diff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstall
index f40ba10b..e7adac93 100755
--- a/packaging/macos/scripts/postinstall
+++ b/packaging/macos/scripts/postinstall
@@ -15,6 +15,7 @@ BEACON_SPLUNK_SOURCETYPE="${BEACON_SPLUNK_SOURCETYPE:-}" \
BEACON_SPLUNK_INSECURE_SKIP_VERIFY="${BEACON_SPLUNK_INSECURE_SKIP_VERIFY:-0}" \
BEACON_SPLUNK_CA_FILE="${BEACON_SPLUNK_CA_FILE:-}" \
BEACON_LOG_ACCESS="${BEACON_LOG_ACCESS:-}" \
+BEACON_SESSION_SYNC="${BEACON_SESSION_SYNC:-}" \
BEACON_NO_START=1 \
/opt/beacon/scripts/install-endpoint.sh
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index 862a315c..11786d41 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -418,6 +418,29 @@ case "$INSTALL_ARGS" in
;;
esac
+# BEACON_SESSION_SYNC turns the scheduled session sync on or off from MDM; unset keeps the
+# endpoint's own setting, so no flag is passed (the cases above).
+for value in 1 0; do
+ BEACON_BIN="$STUB_BIN" \
+ BEACON_COLLECTOR="/tmp/beacon-otelcol" \
+ BEACON_SESSION_SYNC="$value" \
+ STUB_LOG="$STUB_LOG" \
+ "$INSTALL_SCRIPT"
+
+ case "$value" in
+ 1) want_flag="--session-sync" ;;
+ 0) want_flag="--no-session-sync" ;;
+ esac
+ INSTALL_ARGS="$(cat "$STUB_LOG")"
+ case "$INSTALL_ARGS" in
+ "endpoint install --system --harness claude,codex --otlp-grpc-port 4317 --otlp-http-port 4318 --collector /tmp/beacon-otelcol $want_flag") ;;
+ *)
+ echo "unexpected session sync install args for BEACON_SESSION_SYNC=$value: $INSTALL_ARGS" >&2
+ exit 1
+ ;;
+ esac
+done
+
BEACON_BIN="$STUB_BIN" \
BEACON_KEEP_LOGS="1" \
BEACON_KEEP_CONFIG="1" \