The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Add an opt-in scheduled session-sync job (#1158)
Justin D'Souzaa50bf4dc345e
diff --git a/CLAUDE.md b/CLAUDE.mdindex 0c4844ce..8d39b2e5 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -66,6 +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.- 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.go b/cli/beacon/cmd/endpoint.goindex bc6fe724..fa8f33ec 100644--- a/cli/beacon/cmd/endpoint.go+++ b/cli/beacon/cmd/endpoint.go@@ -42,6 +42,8 @@ var endpointOpts struct {onboardingResend boolconnect boolnoBackfill bool+ sessionSync bool+ noSessionSync boolnoBrowser boolfix boolallTargets bool@@ -459,6 +461,7 @@ func init() {registerSplunkFlags(endpointInstallCmd)registerFalconFlags(endpointInstallCmd)registerOTLPForwardFlags(endpointInstallCmd)+ registerSessionSyncFlags(endpointInstallCmd)endpointRepairCmd.Flags().StringVar(&endpointOpts.harnesses, "harness", endpointHarnessAuto, "Harnesses to configure: auto (detected runtimes), all, or a comma-separated list")endpointRepairCmd.Flags().IntVar(&endpointOpts.grpcPort, "otlp-grpc-port", endpointconfig.DefaultGRPCPort, "Local OTLP gRPC port")endpointRepairCmd.Flags().IntVar(&endpointOpts.httpPort, "otlp-http-port", endpointconfig.DefaultHTTPPort, "Local OTLP HTTP port")@@ -477,6 +480,7 @@ func init() {registerSplunkFlags(endpointRepairCmd)registerFalconFlags(endpointRepairCmd)registerOTLPForwardFlags(endpointRepairCmd)+ registerSessionSyncFlags(endpointRepairCmd)endpointDashboardCmd.Flags().BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")endpointDashboardCmd.Flags().BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths and the system collector service")endpointDashboardCmd.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")@@ -796,6 +800,11 @@ func registerFalconFlags(cmd *cobra.Command) {cmd.Flags().StringVar(&endpointOpts.falconCAFile, "falcon-ca-file", "", "Optional CA certificate path for Falcon LogScale HEC TLS verification")}+func registerSessionSyncFlags(cmd *cobra.Command) {+ cmd.Flags().BoolVar(&endpointOpts.sessionSync, "session-sync", false, "Turn on the scheduled session sync: every 15 minutes, read new records from the agent runtimes' local session stores into the runtime log (kept by repair and upgrades)")+ cmd.Flags().BoolVar(&endpointOpts.noSessionSync, "no-session-sync", false, "Turn off the scheduled session sync")+}+func registerOTLPForwardFlags(cmd *cobra.Command) {cmd.Flags().StringVar(&endpointOpts.otlpForwardEndpoint, "otlp-forward-endpoint", "", "Also forward Claude Code and Codex OTLP the local collector receives, with secrets redacted, to this OTLP endpoint (host:port or URL for grpc, base URL for http/protobuf)")cmd.Flags().StringVar(&endpointOpts.otlpForwardProtocol, "otlp-forward-protocol", endpointconfig.OTLPForwardProtocolGRPC, "OTLP forward protocol: grpc or http/protobuf")diff --git a/cli/beacon/cmd/endpoint_backfill.go b/cli/beacon/cmd/endpoint_backfill.goindex 11baafe5..732a61c3 100644--- a/cli/beacon/cmd/endpoint_backfill.go+++ b/cli/beacon/cmd/endpoint_backfill.go@@ -1,6 +1,8 @@package cmdimport (+ "context"+ "encoding/json""errors""fmt""io"@@ -30,6 +32,7 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon/internal/primesession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionfs""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionsync"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/filelock")// The install-time session backfill reads recent history from every agent's own session store,@@ -72,6 +75,12 @@ type endpointBackfillRunner struct {Sync string// Run sweeps the store once and reports how many events it wrote.Run func(endpointBackfillRun) (int, error)+ // State lists the cursor files Run saves for a mode, resolved in the home the sweep reads. A+ // skipped backfill floors only the runtimes with none of them (recordSkippedBackfill).+ State func(userMode bool) []string+ // SQLite says the store is a SQLite database, which a confined (system) sweep reads from a+ // private copy; the scheduled session sync takes that copy at most every endpointSnapshotInterval.+ SQLite bool}// endpointBackfillRunners lists every session-store collector, a seam for tests. Each one runs with@@ -80,69 +89,71 @@ type endpointBackfillRunner struct {// collector joins the list in sessionfs's collectors_test.go too.var endpointBackfillRunners = func() []endpointBackfillRunner {return []endpointBackfillRunner{- {Name: "Claude Code", Sync: "beacon endpoint claude sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Claude Code", Sync: "beacon endpoint claude sync", State: func(m bool) []string { return []string{resolveClaudeStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := claudesession.CollectOnce(claudesession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveClaudeStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Codex CLI", Sync: "beacon endpoint codex sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Codex CLI", Sync: "beacon endpoint codex sync", State: func(m bool) []string { return []string{resolveCodexStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := codexsession.CollectOnce(codexsession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveCodexStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Cursor", Sync: "beacon endpoint cursor sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Cursor", Sync: "beacon endpoint cursor sync", State: func(m bool) []string { return []string{resolveCursorStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := cursorsession.CollectOnce(cursorsession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveCursorStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err- }},- {Name: "OpenCode", Sync: "beacon endpoint opencode sync", Run: func(r endpointBackfillRun) (int, error) {+ }, SQLite: true},+ {Name: "OpenCode", Sync: "beacon endpoint opencode sync", State: func(m bool) []string { return []string{resolveOpenCodeStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := opencodesession.CollectOnce(opencodesession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveOpenCodeStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err- }},- {Name: "GitHub Copilot CLI", Sync: "beacon endpoint copilot sync", Run: func(r endpointBackfillRun) (int, error) {+ }, SQLite: true},+ {Name: "GitHub Copilot CLI", Sync: "beacon endpoint copilot sync", State: func(m bool) []string { return []string{resolveCopilotStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := copilotsession.CollectOnce(copilotsession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveCopilotStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Cline", Sync: "beacon endpoint cline sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Cline", Sync: "beacon endpoint cline sync", State: func(m bool) []string { return []string{resolveClineStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := clinesession.CollectOnce(clinesession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveClineStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Factory Droid", Sync: "beacon endpoint factory sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Factory Droid", Sync: "beacon endpoint factory sync", State: func(m bool) []string { return []string{resolveFactoryStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := factorysession.CollectOnce(factorysession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveFactoryStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Pi", Sync: "beacon endpoint pi sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Pi", Sync: "beacon endpoint pi sync", State: func(m bool) []string { return []string{resolvePiStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := pisession.CollectOnce(pisession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolvePiStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Prime Agent", Sync: "beacon endpoint prime sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Prime Agent", Sync: "beacon endpoint prime sync", State: func(m bool) []string { return []string{resolvePrimeStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := primesession.CollectOnce(primesession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolvePrimeStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Hermes Agent", Sync: "beacon endpoint hermes sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Hermes Agent", Sync: "beacon endpoint hermes sync", State: func(m bool) []string {+ return []string{resolveHermesStatePath("", "", m), legacyHermesStatePath("", "", m)}+ }, Run: func(r endpointBackfillRun) (int, error) {s, err := hermessession.CollectOnce(hermessession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveHermesStatePath("", "", r.UserMode), LegacyStatePath: legacyHermesStatePath("", "", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err- }},- {Name: "Devin CLI", Sync: "beacon endpoint devin sync", Run: func(r endpointBackfillRun) (int, error) {+ }, SQLite: true},+ {Name: "Devin CLI", Sync: "beacon endpoint devin sync", State: func(m bool) []string { return []string{resolveEndpointDevinStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := devinsession.CollectOnce(devinsession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveEndpointDevinStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget, LiveCoverage: endpointDevinLiveCoverage(r.LogPath)})return s.EventsEmitted, err- }},- {Name: "DeepSeek Harness", Sync: "beacon endpoint dsh sync", Run: func(r endpointBackfillRun) (int, error) {+ }, SQLite: true},+ {Name: "DeepSeek Harness", Sync: "beacon endpoint dsh sync", State: func(m bool) []string { return []string{resolveDshStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := dshsession.CollectOnce(dshsession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveDshStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "fx", Sync: "beacon endpoint fx sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "fx", Sync: "beacon endpoint fx sync", State: func(m bool) []string { return []string{resolveFxStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := fxsession.CollectOnce(fxsession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveFxStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Grok Build", Sync: "beacon endpoint grok sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Grok Build", Sync: "beacon endpoint grok sync", State: func(m bool) []string { return []string{resolveGrokStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := groksession.CollectOnce(groksession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveGrokStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},- {Name: "Harness²", Sync: "beacon endpoint harness2 sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "Harness²", Sync: "beacon endpoint harness2 sync", State: func(m bool) []string { return []string{resolveHarness2StatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {opts := harness2session.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveHarness2StatePath("", r.UserMode), Since: r.Since, Budget: r.Budget}opts.ExtraRoots = harness2BackfillExtraRoots(r.UserMode)s, err := harness2session.CollectOnce(opts)return s.EventsEmitted, err}},- {Name: "OpenClaw Gateway", Sync: "beacon endpoint integrations openclaw sessions sync", Run: func(r endpointBackfillRun) (int, error) {+ {Name: "OpenClaw Gateway", Sync: "beacon endpoint integrations openclaw sessions sync", State: func(m bool) []string { return []string{resolveOpenClawSessionsStatePath("", m)} }, Run: func(r endpointBackfillRun) (int, error) {s, err := openclawsession.CollectOnce(openclawsession.CollectOptions{Write: true, UserMode: r.UserMode, LogPath: r.LogPath, StatePath: resolveOpenClawSessionsStatePath("", r.UserMode), Since: r.Since, Budget: r.Budget})return s.EventsEmitted, err}},@@ -198,6 +209,9 @@ type endpointBackfillResult struct {// names a few of them with the reason.Refused intRefusedExamples []string+ // Floored is the earliest floor a skipped backfill left that limited a runtime in this sweep,+ // or zero.+ Floored time.Time}// endpointBackfillEnabled reports whether this install or connect should backfill. Every real@@ -228,8 +242,247 @@ func endpointBackfillDays() int {// hook repair and inventory resolve, while its cursors stay under the system base directory. With// nobody to read for, it reads nothing and says so.func runEndpointBackfill(logPath string, userMode bool) endpointBackfillResult {+ return runEndpointBackfillLocked(logPath, userMode, endpointSweepLockWait, sweepBackfill)+}++// endpointSweepKind is who runs a sweep, which decides the window it reads and how it treats the+// session sync floor and SQLite copies.+type endpointSweepKind int++const (+ // sweepBackfill is install or connect: the whole window, and it lifts the session sync floor.+ sweepBackfill endpointSweepKind = iota+ // sweepManualSync is `beacon endpoint sessions sync` run by hand: it honours the floor.+ sweepManualSync+ // sweepScheduledSync is the scheduled job: it honours the floor and, confined, copies each+ // SQLite store at most every endpointSnapshotInterval.+ sweepScheduledSync+)++// runEndpointBackfillLocked is runEndpointBackfill with an explicit wait for the sweep lock. Every+// sweep (install, connect, `beacon endpoint sessions sync` and its scheduled job) and every+// per-runtime `beacon endpoint <runtime> sync` that writes (collectUnderSweepLock) holds one+// exclusive lock per mode for its whole run, because each collector loads its cursors at the start+// and saves them at the end: two sweeps running together would both start from the same cursors+// and append the same records twice. A sweep that waits for another starts from the cursors that+// one saved and reads only what is new. wait <= 0 does not wait: the scheduled job skips a run+// while another sweep holds the lock, since the next run picks up whatever it leaves.+//+// A session sync (manual or scheduled) reads no session older than the floor a skipped backfill+// recorded (recordSkippedBackfill). An install or connect backfill reads the whole window, so it+// lifts that floor.+func runEndpointBackfillLocked(logPath string, userMode bool, wait time.Duration, kind endpointSweepKind) endpointBackfillResult {+ release, err := acquireEndpointSweepLock(userMode, wait)+ if err != nil {+ return endpointBackfillResult{Skipped: err.Error()}+ }+ defer release()+ sweep := endpointSweep{ThrottleSnapshots: kind == sweepScheduledSync && !userMode}+ if kind == sweepBackfill {+ _ = os.Remove(sessionSyncFloorPath(userMode))+ } else {+ sweep.Floors = readSessionSyncFloors(userMode)+ }+ return runEndpointBackfillUnlocked(logPath, userMode, sweep)+}++// endpointSweep is what a sweep reads beyond the window: for a runtime with a floor, no session+// older than it, and, with ThrottleSnapshots, a SQLite store only if its private copy is due.+type endpointSweep struct {+ Floors map[string]time.Time+ ThrottleSnapshots bool+}++// endpointSnapshotInterval is how often the scheduled system session sync copies a SQLite store+// (Cursor's state.vscdb, OpenCode, Devin CLI, Hermes Agent) to read it. A copy can approach+// sessionfs.MaxSnapshotBytes, and those runtimes are captured live by their hooks or plugins, so+// their stores are read hourly rather than every run. JSONL stores, which are read in place, are+// read every run.+const endpointSnapshotInterval = time.Hour++// endpointSnapshotTimesPath records when the scheduled system session sync last copied each+// runtime's SQLite store, beside the lock.+func endpointSnapshotTimesPath() string {+ return filepath.Join(filepath.Dir(endpointSweepLockPath(false)), "session-sync-snapshots.json")+}++func readEndpointSnapshotTimes() map[string]time.Time {+ times := map[string]time.Time{}+ if data, err := os.ReadFile(endpointSnapshotTimesPath()); err == nil {+ _ = json.Unmarshal(data, ×)+ }+ return times+}++func writeEndpointSnapshotTimes(times map[string]time.Time) {+ path := endpointSnapshotTimesPath()+ data, err := json.Marshal(times)+ if err != nil || os.MkdirAll(filepath.Dir(path), 0o700) != nil {+ return+ }+ tmp := path + ".tmp"+ if os.WriteFile(tmp, data, 0o600) != nil || os.Rename(tmp, path) != nil {+ _ = os.Remove(tmp)+ }+}++// sessionSyncFloorPath records, per runtime, when an install or connect skipped its backfill,+// beside the lock.+func sessionSyncFloorPath(userMode bool) string {+ return filepath.Join(filepath.Dir(endpointSweepLockPath(userMode)), "session-sync-floor.json")+}++type sessionSyncFloors struct {+ NotBefore map[string]time.Time `json:"not_before"`+}++// recordSkippedBackfill notes that an install or connect skipped its backfill (--no-backfill or+// BEACON_BACKFILL=0). A runtime no sweep has read has no cursors, so without a floor the next+// session sync would read its whole window, which the operator opted out of, and on a connected+// endpoint forward it, as lines written after the connection point. With one, a session sync reads+// only that runtime's sessions active since.+//+// The floor is per runtime and set once. A runtime whose cursors exist reads on from them, and a+// floor set then would drop every session that went idle with records its cursors have not+// reached; so a runtime with cursors gets none, and an existing floor is never moved later. A dry+// run records nothing.+func recordSkippedBackfill(out io.Writer, userMode bool) {+ if endpointOpts.dryRun {+ return+ }+ floors := readSessionSyncFloors(userMode)+ now := endpointBackfillNow().UTC()+ changed := false+ withSweepHome(userMode, func() {+ for _, runner := range endpointBackfillRunners() {+ if _, ok := floors[runner.Name]; ok || runnerHasCursors(runner, userMode) {+ continue+ }+ floors[runner.Name] = now+ changed = true+ }+ })+ if !changed {+ return+ }+ path := sessionSyncFloorPath(userMode)+ data, _ := json.Marshal(sessionSyncFloors{NotBefore: floors})+ tmp := path + ".tmp"+ err := os.MkdirAll(filepath.Dir(path), 0o700)+ if err == nil {+ err = os.WriteFile(tmp, append(data, '\n'), 0o600)+ }+ if err == nil {+ err = os.Rename(tmp, path)+ }+ if err != nil {+ _ = os.Remove(tmp)+ fmt.Fprintf(out, "Warning: could not record the skipped session backfill (%v); a scheduled session sync may read the last %d days.\n", err, int(endpointBackfillWindow/(24*time.Hour)))+ }+}++// withSweepHome runs fn in the home a sweep for the mode reads: the invoking user's, or for a system+// endpoint the console user's, which some cursor paths are keyed by (Hermes). With nobody logged in+// it runs in place.+func withSweepHome(userMode bool, fn func()) {+ if !userMode {+ if info, ok, err := activeConsoleUser(); err == nil && ok && strings.TrimSpace(info.HomeDir) != "" {+ _, _ = withUserHome(info.HomeDir, func() (struct{}, error) { fn(); return struct{}{}, nil })+ return+ }+ }+ fn()+}++// runnerHasCursors reports whether a sweep has saved any of runner's cursor files for the mode.+func runnerHasCursors(runner endpointBackfillRunner, userMode bool) bool {+ if runner.State == nil {+ return false+ }+ for _, path := range runner.State(userMode) {+ if path == "" {+ continue+ }+ if _, err := os.Stat(path); err == nil {+ return true+ }+ }+ return false+}++// readSessionSyncFloors is the per-runtime floors recordSkippedBackfill left, never nil.+func readSessionSyncFloors(userMode bool) map[string]time.Time {+ var floors sessionSyncFloors+ if data, err := os.ReadFile(sessionSyncFloorPath(userMode)); err == nil {+ _ = json.Unmarshal(data, &floors)+ }+ if floors.NotBefore == nil {+ return map[string]time.Time{}+ }+ return floors.NotBefore+}++// collectUnderSweepLock runs one per-runtime sync (`beacon endpoint <runtime> sync`, once or per+// --watch tick) under the sweep lock, so it never overlaps the scheduled session sync or an install+// backfill reading the same cursor files. A run that writes nothing (--print) moves no cursors and+// takes no lock. A one-shot sync waits like install does; a watch tick passes wait 0 and reports+// the busy lock as that tick's error, and the next tick reads what the other sweep left.+func collectUnderSweepLock[O, S any](write, userMode bool, wait time.Duration, collect func(O) (S, error), opts O) (S, error) {+ if !write {+ return collect(opts)+ }+ release, err := acquireEndpointSweepLock(userMode, wait)+ if err != nil {+ var zero S+ return zero, err+ }+ defer release()+ return collect(opts)+}++// endpointSweepLockWait bounds how long an install, connect or manual sync waits for a sweep that+// is already running (normally a scheduled run).+var endpointSweepLockWait = 10 * time.Minute++// errEndpointSweepBusy is the skip reason when another sweep holds the lock.+var errEndpointSweepBusy = errors.New("another session sync is already running; its cursors carry over to the next run")++// endpointSweepLockPath is the lock file every sweep for the mode takes, beside the cursors. A+// seam for tests, which must not create the system base directory.+var endpointSweepLockPath = func(userMode bool) string {+ return filepath.Join(endpointconfig.BaseDir(userMode), "state", "session-sweep.lock")+}++func acquireEndpointSweepLock(userMode bool, wait time.Duration) (func(), error) {+ path := endpointSweepLockPath(userMode)+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {+ return nil, fmt.Errorf("could not create the session sync lock directory: %w", err)+ }+ f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, 0o600)+ if err != nil {+ return nil, fmt.Errorf("could not open the session sync lock: %w", err)+ }+ var lock *filelock.Lock+ if wait <= 0 {+ lock, err = filelock.TryExclusive(f)+ } else {+ ctx, cancel := context.WithTimeout(context.Background(), wait)+ lock, err = filelock.ExclusiveContext(ctx, f)+ cancel()+ }+ if err != nil {+ _ = f.Close()+ return nil, errEndpointSweepBusy+ }+ return func() {+ _ = lock.Release()+ _ = f.Close()+ }, nil+}++func runEndpointBackfillUnlocked(logPath string, userMode bool, sweep endpointSweep) endpointBackfillResult {if userMode {- return sweepEndpointBackfill(logPath, true)+ return sweepEndpointBackfill(logPath, true, sweep)}info, ok, err := activeConsoleUser()switch {@@ -251,18 +504,39 @@ func runEndpointBackfill(logPath string, userMode bool) endpointBackfillResult {}defer confined.Release()result, _ := withUserHome(info.HomeDir, func() (endpointBackfillResult, error) {- return sweepEndpointBackfill(logPath, false), nil+ return sweepEndpointBackfill(logPath, false, sweep), nil})result.Refused, result.RefusedExamples = confined.Refused()return result}-func sweepEndpointBackfill(logPath string, userMode bool) endpointBackfillResult {- result := endpointBackfillResult{Since: endpointBackfillNow().Add(-endpointBackfillWindow)}+// sweepEndpointBackfill reads sessions active within the window, or since sweep.Floor when that is+// later.+func sweepEndpointBackfill(logPath string, userMode bool, sweep endpointSweep) endpointBackfillResult {+ now := endpointBackfillNow()+ result := endpointBackfillResult{Since: now.Add(-endpointBackfillWindow)}+ var copied map[string]time.Time+ if sweep.ThrottleSnapshots {+ copied = readEndpointSnapshotTimes()+ defer writeEndpointSnapshotTimes(copied)+ }total := writer.NewBudget(endpointBackfillMaxBytes)for _, runner := range endpointBackfillRunners() {+ if sweep.ThrottleSnapshots && runner.SQLite {+ if last, ok := copied[runner.Name]; ok && now.Sub(last) < endpointSnapshotInterval && !last.After(now) {+ continue+ }+ copied[runner.Name] = now+ }+ since := result.Since+ if floor := sweep.Floors[runner.Name]; floor.After(since) {+ since = floor+ if result.Floored.IsZero() || floor.Before(result.Floored) {+ result.Floored = floor+ }+ }share := total.Sub(endpointBackfillShareBytes)- events, err := runner.Run(endpointBackfillRun{LogPath: logPath, UserMode: userMode, Since: result.Since, Budget: share})+ events, err := runner.Run(endpointBackfillRun{LogPath: logPath, UserMode: userMode, Since: since, Budget: share})// A confined (system) sweep reads SQLite stores through private snapshots; drop each// runtime's before the next one runs. A no-op otherwise.sessionfs.DropSnapshots()@@ -302,13 +576,20 @@ func onlyStopped(err error) bool {// reportEndpointBackfill prints what a backfill wrote: one line when it went cleanly, plus a line// per runtime that hit the limit or failed, each naming the command that picks up from there.func reportEndpointBackfill(out io.Writer, result endpointBackfillResult) {- days := int(endpointBackfillWindow / (24 * time.Hour))+ reportSessionSweep(out, "Session backfill", result)+}++// reportSessionSweep is reportEndpointBackfill under another name: `beacon endpoint sessions sync`+// and its scheduled job run the same sweep and say "Session sync".+func reportSessionSweep(out io.Writer, label string, result endpointBackfillResult) {+ window := fmt.Sprintf("from the last %d days", int(endpointBackfillWindow/(24*time.Hour)))if result.Skipped != "" {- fmt.Fprintf(out, "Session backfill skipped: %s.\n", result.Skipped)+ fmt.Fprintf(out, "%s skipped: %s.\n", label, result.Skipped)return}if result.Events == 0 && !result.Limited && len(result.Runtimes) == 0 {- fmt.Fprintf(out, "Session backfill: no new agent session activity from the last %d days.\n", days)+ fmt.Fprintf(out, "%s: no new agent session activity %s.\n", label, window)+ reportSessionSyncFloor(out, result)reportEndpointBackfillRefusals(out, result)return}@@ -318,7 +599,7 @@ func reportEndpointBackfill(out io.Writer, result endpointBackfillResult) {parts = append(parts, fmt.Sprintf("%s %d", r.Name, r.Events))}}- line := fmt.Sprintf("Session backfill: %d events from the last %d days", result.Events, days)+ line := fmt.Sprintf("%s: %d events %s", label, result.Events, window)if len(parts) > 0 {line += " (" + strings.Join(parts, ", ") + ")"}@@ -338,9 +619,17 @@ func reportEndpointBackfill(out io.Writer, result endpointBackfillResult) {fmt.Fprintf(out, " %s: stopped at the backfill size limit; `%s` reads the rest.\n", r.Name, r.Sync)}}+ reportSessionSyncFloor(out, result)reportEndpointBackfillRefusals(out, result)}+// reportSessionSyncFloor says when a skipped backfill limited what some runtimes read.+func reportSessionSyncFloor(out io.Writer, result endpointBackfillResult) {+ if !result.Floored.IsZero() {+ fmt.Fprintf(out, " Runtimes not read before the skipped backfill at %s read only sessions active since.\n", result.Floored.Format(time.RFC3339))+ }+}+// endpointConnectBackfill is the backfill a connect ships, or nil when it ships none. Every connect// ships one, first or not, user or system: the staged lines keep the deterministic event.id they// were written with, so history the forwarder already shipped is the same event to the ingest side@@ -348,6 +637,7 @@ func reportEndpointBackfill(out io.Writer, result endpointBackfillResult) {// connect does not sweep again and spend a second budget; it still stages what the first sweep wrote.func endpointConnectBackfill(out io.Writer, userMode bool, logPath string, synced bool) *asymptote.ConnectBackfill {if !endpointBackfillEnabled() {+ recordSkippedBackfill(out, userMode)return nil}backfill := &asymptote.ConnectBackfill{Options: asymptote.BackfillOptions{diff --git a/cli/beacon/cmd/endpoint_claude.go b/cli/beacon/cmd/endpoint_claude.goindex 107ed7ee..0b9e5bcc 100644--- a/cli/beacon/cmd/endpoint_claude.go+++ b/cli/beacon/cmd/endpoint_claude.go@@ -114,7 +114,7 @@ func runEndpointClaudeSync(cmd *cobra.Command, args []string) error {return watchClaude(ctx, cmd, opts)}- summary, err := claudesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, claudesession.CollectOnce, opts)reportClaudeSweep(cmd, summary)return err}@@ -125,7 +125,7 @@ func watchClaude(ctx context.Context, cmd *cobra.Command, opts claudesession.Colinterval = 5 * time.Second}for {- summary, err := claudesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, claudesession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "claude sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_cline.go b/cli/beacon/cmd/endpoint_cline.goindex e8b11313..fe0bdbd2 100644--- a/cli/beacon/cmd/endpoint_cline.go+++ b/cli/beacon/cmd/endpoint_cline.go@@ -97,7 +97,7 @@ func runEndpointClineSync(cmd *cobra.Command, args []string) error {if endpointClineOpts.watch && !endpointClineOpts.print {return watchCline(ctx, cmd, opts)}- summary, err := clinesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, clinesession.CollectOnce, opts)reportClineSweep(cmd, summary)return err}@@ -108,7 +108,7 @@ func watchCline(ctx context.Context, cmd *cobra.Command, opts clinesession.Colleinterval = 5 * time.Second}for {- summary, err := clinesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, clinesession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "cline sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_codex.go b/cli/beacon/cmd/endpoint_codex.goindex 9066ddcf..0a8e8429 100644--- a/cli/beacon/cmd/endpoint_codex.go+++ b/cli/beacon/cmd/endpoint_codex.go@@ -98,7 +98,7 @@ func runEndpointCodexSync(cmd *cobra.Command, args []string) error {return watchCodex(ctx, cmd, opts)}- summary, err := codexsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, codexsession.CollectOnce, opts)reportCodexSweep(cmd, summary)return err}@@ -109,7 +109,7 @@ func watchCodex(ctx context.Context, cmd *cobra.Command, opts codexsession.Colleinterval = 5 * time.Second}for {- summary, err := codexsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, codexsession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "codex sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_copilot.go b/cli/beacon/cmd/endpoint_copilot.goindex 31563a7c..dadb571f 100644--- a/cli/beacon/cmd/endpoint_copilot.go+++ b/cli/beacon/cmd/endpoint_copilot.go@@ -102,7 +102,7 @@ func runEndpointCopilotSync(cmd *cobra.Command, args []string) error {if endpointCopilotOpts.watch && !endpointCopilotOpts.print {return watchCopilot(ctx, cmd, opts)}- summary, err := copilotsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, copilotsession.CollectOnce, opts)reportCopilotSweep(cmd, summary)return err}@@ -113,7 +113,7 @@ func watchCopilot(ctx context.Context, cmd *cobra.Command, opts copilotsession.Cinterval = 5 * time.Second}for {- summary, err := copilotsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, copilotsession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "copilot sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_cursor.go b/cli/beacon/cmd/endpoint_cursor.goindex b22446e3..3069e5aa 100644--- a/cli/beacon/cmd/endpoint_cursor.go+++ b/cli/beacon/cmd/endpoint_cursor.go@@ -107,7 +107,7 @@ func runEndpointCursorSync(cmd *cobra.Command, args []string) error {if endpointCursorOpts.watch && !endpointCursorOpts.print {return watchCursor(ctx, cmd, opts)}- summary, err := cursorsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, cursorsession.CollectOnce, opts)reportCursorSweep(cmd, summary)return err}@@ -118,7 +118,7 @@ func watchCursor(ctx context.Context, cmd *cobra.Command, opts cursorsession.Colinterval = 5 * time.Second}for {- summary, err := cursorsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, cursorsession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "cursor sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_devin.go b/cli/beacon/cmd/endpoint_devin.goindex 0bb207ac..8ca79a5e 100644--- a/cli/beacon/cmd/endpoint_devin.go+++ b/cli/beacon/cmd/endpoint_devin.go@@ -130,7 +130,7 @@ func runEndpointDevinSync(cmd *cobra.Command, args []string) error {return watchEndpointDevin(ctx, cmd, opts)}- summary, err := devinsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, devinsession.CollectOnce, opts)reportEndpointDevinSweep(cmd, summary)return err}@@ -141,7 +141,7 @@ func watchEndpointDevin(ctx context.Context, cmd *cobra.Command, opts devinsessiinterval = 5 * time.Second}for {- summary, err := devinsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, devinsession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "Devin CLI sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.goindex bacc1505..02f492d7 100644--- a/cli/beacon/cmd/endpoint_diagnostics.go+++ b/cli/beacon/cmd/endpoint_diagnostics.go@@ -932,6 +932,25 @@ func plannedInstallActions(repair bool, kind service.Kind, otlpTargets, hookTargplannedAction{Action: "write_file", Target: endpointconfig.ConfigPath(cfg.UserMode), Message: "endpoint configuration"},inventoryAction,)+ // The session sync job follows --session-sync/--no-session-sync, or else the setting the+ // endpoint already records, as buildConfig resolves it.+ sessionSync, sessionSyncChosen := false, false+ if existing, err := endpointconfig.Load(cfg.UserMode); err == nil {+ sessionSync = endpointconfig.SessionSyncEnabled(existing)+ }+ if on, _ := sessionSyncOption(); on != nil {+ sessionSync, sessionSyncChosen = *on, true+ }+ switch {+ case sessionSync:+ sessionSyncAction := plannedAction{Action: "write_unit", Message: "scheduled session sync job"}+ if unitPath, err := (service.SessionSyncManager{UserMode: cfg.UserMode, Kind: kind}).UnitPath(); err == nil {+ sessionSyncAction.Target = unitPath+ }+ actions = append(actions, sessionSyncAction)+ case sessionSyncChosen:+ actions = append(actions, plannedAction{Action: "unload_service", Message: "remove scheduled session sync job if present"})+ }for _, h := range otlpTargets {actions = append(actions, plannedAction{Action: "configure_harness", Target: h})}@@ -943,6 +962,9 @@ func plannedInstallActions(repair bool, kind service.Kind, otlpTargets, hookTargplannedAction{Action: "load_service", Message: "start endpoint collector service"},plannedAction{Action: "load_service", Message: "start scheduled inventory heartbeat job"},)+ if sessionSync {+ actions = append(actions, plannedAction{Action: "load_service", Message: "start scheduled session sync job"})+ }}return actions}@@ -952,6 +974,7 @@ func plannedUninstallActions() []plannedAction {actions := []plannedAction{{Action: "unload_service", Message: "stop endpoint collector service if present"},{Action: "unload_service", Message: "remove scheduled inventory heartbeat job if present"},+ {Action: "unload_service", Message: "remove scheduled session sync job if present"},}if !cfg.UserMode && runtime.GOOS == "darwin" {actions = append(actions, plannedAction{Action: "unload_service", Message: "stop and remove the S3, GCS and Falcon forwarders if present"})diff --git a/cli/beacon/cmd/endpoint_dsh.go b/cli/beacon/cmd/endpoint_dsh.goindex 3612b46c..56052422 100644--- a/cli/beacon/cmd/endpoint_dsh.go+++ b/cli/beacon/cmd/endpoint_dsh.go@@ -102,7 +102,7 @@ func runEndpointDshSync(cmd *cobra.Command, args []string) error {if endpointDshOpts.watch && !endpointDshOpts.print {return watchDsh(ctx, cmd, opts)}- summary, err := dshsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, dshsession.CollectOnce, opts)reportDshSweep(cmd, summary)return err}@@ -113,7 +113,7 @@ func watchDsh(ctx context.Context, cmd *cobra.Command, opts dshsession.CollectOpinterval = 5 * time.Second}for {- summary, err := dshsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, dshsession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "dsh sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_enforcement.go b/cli/beacon/cmd/endpoint_enforcement.goindex 38688c44..6344d7d5 100644--- a/cli/beacon/cmd/endpoint_enforcement.go+++ b/cli/beacon/cmd/endpoint_enforcement.go@@ -216,7 +216,7 @@ func userModeActiveError(who string, found []string) error {fmt.Fprintf(&b, " - %s\n", f)}fmt.Fprintf(&b, "Stop user mode first. As %s:\n", who)- for _, label := range []string{service.UserLabel, service.ForwarderLabel, service.InventoryLabel} {+ for _, label := range []string{service.UserLabel, service.ForwarderLabel, service.InventoryLabel, service.SessionSyncLabel} {fmt.Fprintf(&b, " launchctl bootout gui/$(id -u)/%s; launchctl disable gui/$(id -u)/%s\n", label, label)}fmt.Fprintf(&b, "then point the hooks at system mode and run this again:\n")diff --git a/cli/beacon/cmd/endpoint_factory.go b/cli/beacon/cmd/endpoint_factory.goindex a4085a6f..175eb0c4 100644--- a/cli/beacon/cmd/endpoint_factory.go+++ b/cli/beacon/cmd/endpoint_factory.go@@ -97,7 +97,7 @@ func runEndpointFactorySync(cmd *cobra.Command, args []string) error {if endpointFactoryOpts.watch && !endpointFactoryOpts.print {return watchFactory(ctx, cmd, opts)}- summary, err := factorysession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, factorysession.CollectOnce, opts)reportFactorySweep(cmd, summary)return err}@@ -108,7 +108,7 @@ func watchFactory(ctx context.Context, cmd *cobra.Command, opts factorysession.Cinterval = 5 * time.Second}for {- summary, err := factorysession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, factorysession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "Factory sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_fx.go b/cli/beacon/cmd/endpoint_fx.goindex 93a1a9ad..6a1cabd1 100644--- a/cli/beacon/cmd/endpoint_fx.go+++ b/cli/beacon/cmd/endpoint_fx.go@@ -112,7 +112,7 @@ func runEndpointFxSync(cmd *cobra.Command, args []string) error {return watchFx(ctx, cmd, opts)}- summary, err := fxsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, fxsession.CollectOnce, opts)// The summary is reported even when the sweep hit an error, because a sweep that collected// nine sessions and failed on the tenth did nine sessions' worth of work.reportFxSweep(cmd, summary)@@ -127,7 +127,7 @@ func watchFx(ctx context.Context, cmd *cobra.Command, opts fxsession.CollectOptiinterval = 5 * time.Second}for {- summary, err := fxsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, fxsession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "fx sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_grok.go b/cli/beacon/cmd/endpoint_grok.goindex c6a23b7d..889d2633 100644--- a/cli/beacon/cmd/endpoint_grok.go+++ b/cli/beacon/cmd/endpoint_grok.go@@ -97,7 +97,7 @@ func runEndpointGrokSync(cmd *cobra.Command, args []string) error {if endpointGrokOpts.watch && !endpointGrokOpts.print {return watchGrok(ctx, cmd, opts)}- summary, err := groksession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, groksession.CollectOnce, opts)reportGrokSweep(cmd, summary)return err}@@ -108,7 +108,7 @@ func watchGrok(ctx context.Context, cmd *cobra.Command, opts groksession.Collectinterval = 5 * time.Second}for {- summary, err := groksession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, groksession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "grok sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_harness2.go b/cli/beacon/cmd/endpoint_harness2.goindex 5b8f322e..0130f148 100644--- a/cli/beacon/cmd/endpoint_harness2.go+++ b/cli/beacon/cmd/endpoint_harness2.go@@ -118,7 +118,7 @@ func runEndpointHarness2Sync(cmd *cobra.Command, args []string) error {return watchHarness2(ctx, cmd, opts)}- summary, err := harness2session.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, harness2session.CollectOnce, opts)// Reported even when the sweep hit an error: a sweep that read nine rollouts and failed on the// tenth did nine rollouts' worth of work.reportHarness2Sweep(cmd, summary)@@ -150,7 +150,7 @@ func watchHarness2(ctx context.Context, cmd *cobra.Command, opts harness2sessioninterval = 5 * time.Second}for {- summary, err := harness2session.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, harness2session.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "Harness² sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_hermes.go b/cli/beacon/cmd/endpoint_hermes.goindex bf9f2af8..9dd1e791 100644--- a/cli/beacon/cmd/endpoint_hermes.go+++ b/cli/beacon/cmd/endpoint_hermes.go@@ -101,7 +101,7 @@ func runEndpointHermesSync(cmd *cobra.Command, args []string) error {if endpointHermesOpts.watch && !endpointHermesOpts.print {return watchHermes(ctx, cmd, opts)}- summary, err := hermessession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, hermessession.CollectOnce, opts)reportHermesSweep(cmd, summary)return err}@@ -112,7 +112,7 @@ func watchHermes(ctx context.Context, cmd *cobra.Command, opts hermessession.Colinterval = 5 * time.Second}for {- summary, err := hermessession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, hermessession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "Hermes sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_install.go b/cli/beacon/cmd/endpoint_install.goindex 8579fe2a..567840ad 100644--- a/cli/beacon/cmd/endpoint_install.go+++ b/cli/beacon/cmd/endpoint_install.go@@ -121,6 +121,7 @@ func endpointInstallOptions(selection endpointTargetSelection, serviceKind serviharnesses := append([]string{}, selection.OTLP...)// Install and repair validate the forward flags before anything is written.otlpForward, _ := otlpForwardOptions()+ sessionSync, _ := sessionSyncOption()return lifecycle.InstallOptions{UserMode: endpointUserMode(),LogPath: endpointOpts.logPath,@@ -136,6 +137,7 @@ func endpointInstallOptions(selection endpointTargetSelection, serviceKind serviSplunkHEC: splunkHECOptions(),FalconHEC: falconHECOptions(),OTLPForward: otlpForward,+ SessionSync: sessionSync,ServiceKind: serviceKind,LogAccess: strings.ToLower(strings.TrimSpace(endpointOpts.logAccess)),}@@ -203,6 +205,9 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {if _, err := otlpForwardOptions(); err != nil {return err}+ if _, err := sessionSyncOption(); err != nil {+ return err+ }warnMissingOTLPForwardHeaders(cmd.ErrOrStderr())if endpointOpts.dryRun {return printPlannedActions(plannedInstallActions(false, serviceKind, selection.OTLP, selection.Hooks))@@ -253,6 +258,7 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {case result.InventoryJobDetail != "":fmt.Fprintf(details, "Scheduled inventory job not installed: %s\n", result.InventoryJobDetail)}+ reportSessionSyncJob(details, result)reportLogAccess(details, result)reportManagedForwarder(details, cmd.ErrOrStderr(), result.ManagedForwarder)printLingerGap(cmd.ErrOrStderr(), result)@@ -270,6 +276,8 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {}reportEndpointBackfill(backfillOut, runEndpointBackfill(result.LogPath, endpointUserMode()))backfilled = true+ } else {+ recordSkippedBackfill(cmd.ErrOrStderr(), endpointUserMode())}finishCloudSetup(cmd, onboarded, connectAfterInstall, summary, func() error {return connectEndpointFor(cmd, endpointUserMode(), result.LogPath, backfilled, summary)@@ -427,6 +435,7 @@ func runEndpointStatus(cmd *cobra.Command, args []string) error {fmt.Println(line)}fmt.Println(inventoryHeartbeatStatusLine(status.InventoryHeartbeat))+ fmt.Println(sessionSyncStatusLine(status.SessionSync))return nil}@@ -506,6 +515,9 @@ func runEndpointRepair(cmd *cobra.Command, args []string) error {if _, err := otlpForwardOptions(); err != nil {return err}+ if _, err := sessionSyncOption(); err != nil {+ return err+ }warnMissingOTLPForwardHeaders(cmd.ErrOrStderr())if endpointOpts.dryRun {return printPlannedActions(plannedInstallActions(true, serviceKind, selection.OTLP, selection.Hooks))@@ -518,6 +530,7 @@ func runEndpointRepair(cmd *cobra.Command, args []string) error {return err}fmt.Printf("Endpoint repaired. Manifest: %s\n", result.ManifestPath)+ reportSessionSyncJob(os.Stdout, result)reportLogAccess(os.Stdout, result)reportManagedForwarder(os.Stdout, cmd.ErrOrStderr(), result.ManagedForwarder)printLingerGap(cmd.ErrOrStderr(), result)@@ -526,6 +539,17 @@ func runEndpointRepair(cmd *cobra.Command, args []string) error {return nil}+// reportSessionSyncJob says where the scheduled session sync job was installed, or why it was not,+// when the setting is on; with it off (the default) install and repair say nothing about it.+func reportSessionSyncJob(out io.Writer, result lifecycle.InstallResult) {+ switch {+ case result.SessionSyncJobPath != "":+ fmt.Fprintf(out, "Scheduled session sync job: %s\n", result.SessionSyncJobPath)+ case result.SessionSyncJobDetail != "":+ fmt.Fprintf(out, "Scheduled session sync job not installed: %s\n", result.SessionSyncJobDetail)+ }+}+func reportEndpointTargetSelection(cmd *cobra.Command, selection endpointTargetSelection) {if !selection.Automatic {returndiff --git a/cli/beacon/cmd/endpoint_openclaw_sessions.go b/cli/beacon/cmd/endpoint_openclaw_sessions.goindex a60ae726..74bd67f8 100644--- a/cli/beacon/cmd/endpoint_openclaw_sessions.go+++ b/cli/beacon/cmd/endpoint_openclaw_sessions.go@@ -99,7 +99,7 @@ func runEndpointOpenClawSessionsSync(cmd *cobra.Command, args []string) error {if endpointOpenClawSessionsOpts.watch && !endpointOpenClawSessionsOpts.print {return watchOpenClawSessions(ctx, cmd, opts)}- summary, err := openclawsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, openclawsession.CollectOnce, opts)reportOpenClawSessionsSweep(cmd, summary)return err}@@ -110,7 +110,7 @@ func watchOpenClawSessions(ctx context.Context, cmd *cobra.Command, opts openclainterval = 5 * time.Second}for {- summary, err := openclawsession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, openclawsession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "openclaw sessions sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_opencode.go b/cli/beacon/cmd/endpoint_opencode.goindex 6874972f..564c400d 100644--- a/cli/beacon/cmd/endpoint_opencode.go+++ b/cli/beacon/cmd/endpoint_opencode.go@@ -96,7 +96,7 @@ func runEndpointOpenCodeSync(cmd *cobra.Command, args []string) error {if endpointOpenCodeOpts.watch && !endpointOpenCodeOpts.print {return watchOpenCode(ctx, cmd, opts)}- summary, err := opencodesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, opencodesession.CollectOnce, opts)reportOpenCodeSweep(cmd, summary)return err}@@ -107,7 +107,7 @@ func watchOpenCode(ctx context.Context, cmd *cobra.Command, opts opencodesessioninterval = 5 * time.Second}for {- summary, err := opencodesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, opencodesession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "opencode sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_pi.go b/cli/beacon/cmd/endpoint_pi.goindex ed3959bc..8dfa9345 100644--- a/cli/beacon/cmd/endpoint_pi.go+++ b/cli/beacon/cmd/endpoint_pi.go@@ -97,7 +97,7 @@ func runEndpointPiSync(cmd *cobra.Command, args []string) error {if endpointPiOpts.watch && !endpointPiOpts.print {return watchPi(ctx, cmd, opts)}- summary, err := pisession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, pisession.CollectOnce, opts)reportPiSweep(cmd, summary)return err}@@ -108,7 +108,7 @@ func watchPi(ctx context.Context, cmd *cobra.Command, opts pisession.CollectOptiinterval = 5 * time.Second}for {- summary, err := pisession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, pisession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "Pi sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_prime.go b/cli/beacon/cmd/endpoint_prime.goindex de86c701..7f70506a 100644--- a/cli/beacon/cmd/endpoint_prime.go+++ b/cli/beacon/cmd/endpoint_prime.go@@ -100,7 +100,7 @@ func runEndpointPrimeSync(cmd *cobra.Command, args []string) error {if endpointPrimeOpts.watch && !endpointPrimeOpts.print {return watchPrime(ctx, cmd, opts)}- summary, err := primesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, endpointSweepLockWait, primesession.CollectOnce, opts)reportPrimeSweep(cmd, summary)return err}@@ -111,7 +111,7 @@ func watchPrime(ctx context.Context, cmd *cobra.Command, opts primesession.Colleinterval = 5 * time.Second}for {- summary, err := primesession.CollectOnce(opts)+ summary, err := collectUnderSweepLock(opts.Write, opts.UserMode, 0, primesession.CollectOnce, opts)if err != nil {fmt.Fprintf(cmd.ErrOrStderr(), "Prime Agent sync error: %v\n", err)}diff --git a/cli/beacon/cmd/endpoint_session_sync.go b/cli/beacon/cmd/endpoint_session_sync.gonew file mode 100644index 00000000..8a7a3539--- /dev/null+++ b/cli/beacon/cmd/endpoint_session_sync.go@@ -0,0 +1,153 @@+package cmd++import (+ "fmt"++ "github.com/spf13/cobra"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"+)++// `beacon endpoint sessions` holds the scheduled session-store sync: the same sweep an install+// runs once (every session-store collector, the last 30 days, a size budget, cursors so each run+// reads only what is new), run by the `com.beacon.endpoint.session-sync` job when+// `session_sync.enabled` is on. See docs/cli/endpoint-install.mdx#scheduled-session-sync.+var endpointSessionsCmd = &cobra.Command{+ Use: "sessions",+ Short: "Read agent runtimes' local session stores into the runtime log",+}++var endpointSessionsSyncCmd = &cobra.Command{+ Use: "sync",+ Short: "Read new records from every agent runtime's session store into the runtime log",+ Long: "Runs every session-store collector once (Claude Code, Codex CLI, Cursor, OpenCode and the rest), " ++ "reading only what each has not read yet, from sessions active in the last 30 days and within a size budget. " ++ "A system endpoint reads the logged-in console user's stores, confined to files that user owns. " ++ "The scheduled session sync job runs this every 15 minutes when it is turned on with " ++ "`beacon endpoint install|repair --session-sync`.",+ SilenceUsage: true,+ RunE: runEndpointSessionsSync,+}++var endpointSessionsInstallDaemonCmd = &cobra.Command{+ Use: "install-daemon",+ Short: "Internal: reconcile the scheduled session sync job with the endpoint config",+ Hidden: true,+ SilenceUsage: true,+ RunE: runSessionsInstallDaemon,+}++var endpointSessionsOpts struct {+ scheduled bool+}++func init() {+ endpointCmd.AddCommand(endpointSessionsCmd)+ endpointSessionsCmd.AddCommand(endpointSessionsSyncCmd)+ endpointSessionsCmd.AddCommand(endpointSessionsInstallDaemonCmd)+ for _, c := range []*cobra.Command{endpointSessionsSyncCmd, endpointSessionsInstallDaemonCmd} {+ 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")+ }+ endpointSessionsSyncCmd.Flags().BoolVar(&endpointSessionsOpts.scheduled, "scheduled", false, "Run as the scheduled job (set by the job's unit)")+ _ = endpointSessionsSyncCmd.Flags().MarkHidden("scheduled")+}++// runSessionSweep is the seam tests replace. The scheduled job does not wait for a sweep that is+// already running (the next run picks up what that one leaves); a manual run waits like install.+var runSessionSweep = func(logPath string, userMode, scheduled bool) endpointBackfillResult {+ if scheduled {+ return runEndpointBackfillLocked(logPath, userMode, 0, sweepScheduledSync)+ }+ return runEndpointBackfillLocked(logPath, userMode, endpointSweepLockWait, sweepManualSync)+}++func runEndpointSessionsSync(cmd *cobra.Command, args []string) error {+ userMode := endpointUserMode()+ if !userMode && !lifecycle.HasSystemPrivileges() {+ return fmt.Errorf("syncing session stores into the system log needs elevated privileges; %s", lifecycle.SystemPrivilegeHint())+ }+ cfg := loadConfigForMode(userMode, endpointOpts.logPath)+ if endpointSessionsOpts.scheduled {+ // The setting governs the job and what it does: a job that outlived the setting (config+ // edited to off without a repair, or an unload that failed) writes nothing. A manual run is+ // not gated, as with any runtime's own sync command.+ if !endpointconfig.SessionSyncEnabled(cfg) {+ fmt.Fprintln(cmd.OutOrStdout(), "Session sync is off in the endpoint config; nothing read. `beacon endpoint repair` removes this job.")+ return nil+ }+ }+ result := runSessionSweep(cfg.LogPath, userMode, endpointSessionsOpts.scheduled)+ reportSessionSweep(cmd.OutOrStdout(), "Session sync", result)+ // A runtime that failed is reported above and the rest still ran. The scheduled job exits+ // cleanly so the scheduler keeps it on its interval; a manual run says it failed.+ if !endpointSessionsOpts.scheduled {+ for _, runtime := range result.Runtimes {+ if runtime.Err != nil {+ return fmt.Errorf("%s: %w", runtime.Name, runtime.Err)+ }+ }+ }+ return nil+}++// reconcileSessionSyncJob is indirected so the command can be tested without a scheduler.+var reconcileSessionSyncJob = lifecycle.ReconcileSessionSyncJob++func runSessionsInstallDaemon(cmd *cobra.Command, args []string) error {+ userMode := endpointUserMode()+ if !userMode && !lifecycle.HasSystemPrivileges() {+ return fmt.Errorf("managing the system session sync job needs elevated privileges; %s", lifecycle.SystemPrivilegeHint())+ }+ result, err := reconcileSessionSyncJob(lifecycle.InventoryJobOptions{+ UserMode: userMode,+ Program: lifecycle.DefaultInventoryJobProgram(userMode),+ LogPath: endpointOpts.logPath,+ Load: true,+ })+ 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."+ case result.Skipped != "":+ return "Scheduled session sync job not installed: " + result.Skipped+ default:+ return "Scheduled session sync job installed (" + result.UnitPath + ")."+ }+}++func sessionSyncStatusLine(status lifecycle.SessionSyncStatus) string {+ if !status.Enabled {+ return "Session sync: off"+ }+ line := fmt.Sprintf("Session sync: every %s; job loaded=%t", status.Interval, status.Job.Loaded)+ if !status.Job.Loaded && status.Job.Message != "" {+ line += " (" + status.Job.Message + ")"+ }+ return line+}++// sessionSyncOption turns --session-sync / --no-session-sync into the install option: nil when+// neither was given, so repair and package upgrades keep the recorded setting.+func sessionSyncOption() (*bool, error) {+ switch {+ case endpointOpts.sessionSync && endpointOpts.noSessionSync:+ return nil, fmt.Errorf("--session-sync and --no-session-sync cannot be combined")+ case endpointOpts.sessionSync:+ on := true+ return &on, nil+ case endpointOpts.noSessionSync:+ off := false+ return &off, nil+ }+ return nil, nil+}diff --git a/cli/beacon/cmd/endpoint_session_sync_test.go b/cli/beacon/cmd/endpoint_session_sync_test.gonew file mode 100644index 00000000..d3103f00--- /dev/null+++ b/cli/beacon/cmd/endpoint_session_sync_test.go@@ -0,0 +1,343 @@+package cmd++import (+ "bytes"+ "errors"+ "os"+ "path/filepath"+ "regexp"+ "strings"+ "testing"+ "time"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++func TestSessionSyncOption(t *testing.T) {+ old := endpointOpts+ t.Cleanup(func() { endpointOpts = old })++ endpointOpts.sessionSync, endpointOpts.noSessionSync = false, false+ if got, err := sessionSyncOption(); err != nil || got != nil {+ t.Fatalf("no flag = %v, %v; want nil so repair keeps the setting", got, err)+ }+ endpointOpts.sessionSync = true+ if got, err := sessionSyncOption(); err != nil || got == nil || !*got {+ t.Fatalf("--session-sync = %v, %v", got, err)+ }+ endpointOpts.sessionSync, endpointOpts.noSessionSync = false, true+ if got, err := sessionSyncOption(); err != nil || got == nil || *got {+ t.Fatalf("--no-session-sync = %v, %v", got, err)+ }+ endpointOpts.sessionSync = true+ if _, err := sessionSyncOption(); err == nil {+ t.Fatal("both flags together should be refused")+ }+}++// The scheduled job reports a runtime that failed and still exits cleanly, so the scheduler keeps+// running it; run by hand, the same failure is an error.+func TestSessionsSyncReportsAndOnlyFailsByHand(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ enableSessionSyncConfig(t, true)+ oldOpts, oldSweep := endpointOpts, runSessionSweep+ t.Cleanup(func() { endpointOpts, runSessionSweep = oldOpts, oldSweep; endpointSessionsOpts.scheduled = false })+ endpointOpts.userMode, endpointOpts.systemMode = true, false++ var gotLog string+ var gotScheduled []bool+ runSessionSweep = func(logPath string, userMode, scheduled bool) endpointBackfillResult {+ gotLog = logPath+ gotScheduled = append(gotScheduled, scheduled)+ return endpointBackfillResult{Events: 3, Runtimes: []endpointBackfillRuntimeResult{+ {Name: "Claude Code", Sync: "beacon endpoint claude sync", Events: 3},+ {Name: "Codex CLI", Sync: "beacon endpoint codex sync", Err: errors.New("store unreadable")},+ }}+ }++ var out bytes.Buffer+ endpointSessionsSyncCmd.SetOut(&out)+ endpointSessionsOpts.scheduled = true+ if err := runEndpointSessionsSync(endpointSessionsSyncCmd, nil); err != nil {+ t.Fatalf("scheduled run returned %v", err)+ }+ if !strings.Contains(out.String(), "Claude Code 3") || !strings.Contains(out.String(), "Codex CLI: store unreadable") {+ t.Fatalf("report = %q", out.String())+ }+ if !strings.HasSuffix(gotLog, "runtime.jsonl") {+ t.Fatalf("swept into %q, want the endpoint's runtime log", gotLog)+ }++ endpointSessionsOpts.scheduled = false+ if err := runEndpointSessionsSync(endpointSessionsSyncCmd, nil); err == nil || !strings.Contains(err.Error(), "Codex CLI") {+ t.Fatalf("manual run error = %v, want the failed runtime named", err)+ }+ if len(gotScheduled) != 2 || !gotScheduled[0] || gotScheduled[1] {+ t.Fatalf("sweeps scheduled = %v, want [true false]", gotScheduled)+ }+}++// A job that outlived the setting writes nothing; a manual run is not gated.+func TestScheduledSessionsSyncHonoursConfigOff(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ enableSessionSyncConfig(t, false)+ oldOpts, oldSweep := endpointOpts, runSessionSweep+ t.Cleanup(func() { endpointOpts, runSessionSweep = oldOpts, oldSweep; endpointSessionsOpts.scheduled = false })+ endpointOpts.userMode, endpointOpts.systemMode = true, false++ swept := 0+ runSessionSweep = func(string, bool, bool) endpointBackfillResult { swept++; return endpointBackfillResult{} }+ var out bytes.Buffer+ endpointSessionsSyncCmd.SetOut(&out)+ endpointSessionsOpts.scheduled = true+ if err := runEndpointSessionsSync(endpointSessionsSyncCmd, nil); err != nil {+ t.Fatal(err)+ }+ if swept != 0 || !strings.Contains(out.String(), "Session sync is off") {+ t.Fatalf("scheduled run with the setting off swept %d time(s), output %q", swept, out.String())+ }+ endpointSessionsOpts.scheduled = false+ if err := runEndpointSessionsSync(endpointSessionsSyncCmd, nil); err != nil || swept != 1 {+ t.Fatalf("manual run: err=%v swept=%d", err, swept)+ }+}++// Two sweeps never run together: the second waits for, or (not waiting) skips, the first.+func TestEndpointSweepLockSerializes(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ release, err := acquireEndpointSweepLock(true, time.Second)+ if err != nil {+ t.Fatal(err)+ }+ if _, err := acquireEndpointSweepLock(true, 0); !errors.Is(err, errEndpointSweepBusy) {+ t.Fatalf("second sweep without waiting = %v, want busy", err)+ }+ if _, err := acquireEndpointSweepLock(true, 50*time.Millisecond); !errors.Is(err, errEndpointSweepBusy) {+ t.Fatalf("second sweep after a short wait = %v, want busy", err)+ }+ result := runEndpointBackfillLocked(filepath.Join(t.TempDir(), "runtime.jsonl"), true, 0, sweepScheduledSync)+ if result.Skipped == "" || result.Events != 0 {+ t.Fatalf("locked-out sweep = %+v, want skipped", result)+ }+ release()+ again, err := acquireEndpointSweepLock(true, 0)+ if err != nil {+ t.Fatalf("after release: %v", err)+ }+ again()+}++// A per-runtime sync shares the sweep's cursor files, so it takes the same lock: while a sweep runs,+// a sync that writes waits and then gives up without reading or writing anything, and a --print dry+// run, which moves no cursor, is not held up.+func TestPerRuntimeSyncWaitsForTheSweepLock(t *testing.T) {+ f := newClaudeCommandFixture(t)+ oldWait := endpointSweepLockWait+ t.Cleanup(func() { endpointSweepLockWait = oldWait; endpointClaudeOpts.print = false })+ endpointSweepLockWait = 50 * time.Millisecond+ release, err := acquireEndpointSweepLock(true, time.Second)+ if err != nil {+ t.Fatal(err)+ }++ if _, err := runClaudeSync(t); !errors.Is(err, errEndpointSweepBusy) {+ t.Fatalf("sync during a sweep = %v, want busy", err)+ }+ if _, statErr := os.Stat(f.logPath); !os.IsNotExist(statErr) {+ t.Fatal("a sync that could not take the lock wrote the runtime log")+ }+ endpointClaudeOpts.print = true+ if out, err := runClaudeSync(t); err != nil || !strings.Contains(out, "sess-1") {+ t.Fatalf("--print during a sweep: err=%v out=%q", err, out)+ }+ endpointClaudeOpts.print = false++ release()+ if _, err := runClaudeSync(t); err != nil {+ t.Fatalf("sync after the sweep: %v", err)+ }+ if _, statErr := os.Stat(f.statePath); statErr != nil {+ t.Fatalf("sync after the sweep did not save its cursor: %v", statErr)+ }+}++// Every per-runtime sync command reaches its collector through collectUnderSweepLock, so a new+// `beacon endpoint <runtime> sync` cannot race the scheduled session sync by calling it directly.+// The backfill runners are exempt: runEndpointBackfillLocked holds the lock around all of them.+func TestPerRuntimeSyncCommandsTakeTheSweepLock(t *testing.T) {+ files, err := filepath.Glob("*.go")+ if err != nil {+ t.Fatal(err)+ }+ direct := regexp.MustCompile(`\b\w+session\.CollectOnce\(`)+ for _, file := range files {+ if strings.HasSuffix(file, "_test.go") || file == "endpoint_backfill.go" {+ continue+ }+ data, err := os.ReadFile(file)+ if err != nil {+ t.Fatal(err)+ }+ for i, line := range strings.Split(string(data), "\n") {+ if direct.MatchString(line) {+ t.Errorf("%s:%d calls a session-store collector without the sweep lock; use collectUnderSweepLock", file, i+1)+ }+ }+ }+}++// An install or connect that skipped its backfill floors each runtime no sweep has read: a session+// sync then reads only its sessions active since, instead of the 30 days the operator opted out of.+// A backfill that runs reads the whole window again and lifts the floors.+func TestSkippedBackfillFloorsTheSessionSync(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ isolateSweepState(t)+ var since time.Time+ stubBackfill(t, 1<<20, 1<<20, writingRunner("Claude", 1, &since))+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ now := endpointBackfillNow()+ window := now.Add(-endpointBackfillWindow)++ recordSkippedBackfill(&bytes.Buffer{}, true)+ result := runSessionSweep(logPath, true, true)+ if !since.Equal(now) || !result.Floored.Equal(now) {+ t.Fatalf("session sync after a skipped backfill read from %s (floored %s), want %s", since, result.Floored, now)+ }+ var out bytes.Buffer+ reportSessionSweep(&out, "Session sync", result)+ if !strings.Contains(out.String(), "skipped backfill at "+now.UTC().Format(time.RFC3339)) {+ t.Fatalf("report = %q", out.String())+ }++ runEndpointBackfill(logPath, true)+ if !since.Equal(window) {+ t.Fatalf("backfill read from %s, want the whole window from %s", since, window)+ }+ if result := runSessionSweep(logPath, true, true); !since.Equal(window) || !result.Floored.IsZero() {+ t.Fatalf("session sync after a backfill read from %s (floored %s), want the window again", since, result.Floored)+ }++ // A dry run records nothing.+ old := endpointOpts+ t.Cleanup(func() { endpointOpts = old })+ endpointOpts.dryRun = true+ recordSkippedBackfill(&bytes.Buffer{}, true)+ if _, err := os.Stat(sessionSyncFloorPath(true)); !os.IsNotExist(err) {+ t.Fatalf("a dry run recorded a floor: %v", err)+ }+}++// The floor is per runtime and set once. A runtime whose own cursor exists gets none, since a floor+// would drop its sessions that went idle with records the cursor has not reached; another runtime+// with no cursor still gets one; and a later skip never moves a floor.+func TestSkippedBackfillFloorsOnlyRuntimesWithoutCursors(t *testing.T) {+ isolateSweepState(t)+ cursors := t.TempDir()+ withState := func(name string) endpointBackfillRunner {+ state := filepath.Join(cursors, name+".json")+ return endpointBackfillRunner{Name: name, Sync: "beacon endpoint x sync",+ State: func(bool) []string { return []string{"", state} },+ Run: func(endpointBackfillRun) (int, error) { return 0, nil }}+ }+ stubBackfill(t, 1<<20, 1<<20, withState("Claude Code"), withState("Codex CLI"))+ if err := os.WriteFile(filepath.Join(cursors, "Claude Code.json"), []byte("{}"), 0o600); err != nil {+ t.Fatal(err)+ }+ first := endpointBackfillNow()++ recordSkippedBackfill(&bytes.Buffer{}, true)+ floors := readSessionSyncFloors(true)+ if _, ok := floors["Claude Code"]; ok || !floors["Codex CLI"].Equal(first) {+ t.Fatalf("floors = %v, want only Codex CLI at %s", floors, first)+ }++ endpointBackfillNow = func() time.Time { return first.Add(time.Hour) }+ recordSkippedBackfill(&bytes.Buffer{}, true)+ if got := readSessionSyncFloors(true)["Codex CLI"]; !got.Equal(first) {+ t.Fatalf("a second skipped backfill moved the floor to %s, want %s", got, first)+ }+}++// Every session-store runner names its cursor files in both modes, so a skipped backfill can tell+// which runtimes a sweep has already read.+func TestEveryBackfillRunnerNamesItsCursors(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ for _, runner := range endpointBackfillRunners() {+ for _, userMode := range []bool{true, false} {+ if runner.State == nil {+ t.Fatalf("%s has no State", runner.Name)+ }+ named := 0+ for _, path := range runner.State(userMode) {+ if path != "" {+ named+++ }+ }+ if named == 0 {+ t.Errorf("%s names no cursor file (userMode=%t)", runner.Name, userMode)+ }+ }+ }+}++// The scheduled system sync copies a SQLite store at most once an hour; JSONL stores, read in place,+// are read every run. Nothing else throttles.+func TestScheduledSystemSyncCopiesSQLiteStoresHourly(t *testing.T) {+ isolateSweepState(t)+ runs := map[string]int{}+ runner := func(name string, sqlite bool) endpointBackfillRunner {+ return endpointBackfillRunner{Name: name, Sync: "beacon endpoint x sync", SQLite: sqlite, Run: func(endpointBackfillRun) (int, error) {+ runs[name]+++ return 0, nil+ }}+ }+ stubBackfill(t, 1<<20, 1<<20, runner("Claude Code", false), runner("Cursor", true))+ start := endpointBackfillNow()+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ throttled := endpointSweep{ThrottleSnapshots: true}++ for _, offset := range []time.Duration{0, 15 * time.Minute, 45 * time.Minute, time.Hour} {+ endpointBackfillNow = func() time.Time { return start.Add(offset) }+ sweepEndpointBackfill(logPath, false, throttled)+ }+ if runs["Claude Code"] != 4 || runs["Cursor"] != 2 {+ t.Fatalf("runs = %v, want Claude Code every run and Cursor at 0 and 60 minutes", runs)+ }++ sweepEndpointBackfill(logPath, false, endpointSweep{})+ if runs["Cursor"] != 3 {+ t.Fatalf("an unthrottled sweep skipped the SQLite store: runs = %v", runs)+ }+}++// isolateSweepState gives a test its own sweep lock and floor, away from the directory TestMain shares+// with every install test (each of which skips its backfill and so may leave a floor there).+func isolateSweepState(t *testing.T) {+ t.Helper()+ old := endpointSweepLockPath+ t.Cleanup(func() { endpointSweepLockPath = old })+ dir := t.TempDir()+ endpointSweepLockPath = func(bool) string { return filepath.Join(dir, "session-sweep.lock") }+}++func enableSessionSyncConfig(t *testing.T, enabled bool) {+ t.Helper()+ cfg := endpointconfig.Default(true, filepath.Join(endpointconfig.BaseDir(true), "logs", "runtime.jsonl"))+ cfg.SessionSync = &endpointconfig.SessionSync{Enabled: enabled}+ if _, err := endpointconfig.Save(cfg); err != nil {+ t.Fatal(err)+ }+}++func TestSessionSyncStatusLine(t *testing.T) {+ if got := sessionSyncStatusLine(lifecycle.SessionSyncStatus{}); got != "Session sync: off" {+ t.Fatalf("off = %q", got)+ }+ on := lifecycle.SessionSyncStatus{Enabled: true, Interval: "15m0s"}+ on.Job.Loaded = true+ if got := sessionSyncStatusLine(on); got != "Session sync: every 15m0s; job loaded=true" {+ t.Fatalf("on = %q", got)+ }+}diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.goindex 1ba312bd..8d578c55 100644--- a/cli/beacon/cmd/endpoint_test.go+++ b/cli/beacon/cmd/endpoint_test.go@@ -227,6 +227,42 @@ func TestPlannedInstallActionsSeparatesHookHarnesses(t *testing.T) {}}+// The plan names the session sync job only when the install will turn it on or remove it.+func TestPlannedInstallActionsFollowSessionSync(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ old := endpointOpts+ t.Cleanup(func() { endpointOpts = old })+ endpointOpts.userMode, endpointOpts.systemMode = true, false+ endpointOpts.logPath = filepath.Join(t.TempDir(), "runtime.jsonl")+ endpointOpts.noStart = false++ plan := func() (units, loads, removals int) {+ for _, action := range plannedInstallActions(false, service.KindAuto, nil, nil) {+ switch {+ case action.Action == "write_unit" && action.Message == "scheduled session sync job":+ units+++ case action.Action == "load_service" && action.Message == "start scheduled session sync job":+ loads+++ case action.Action == "unload_service" && action.Message == "remove scheduled session sync job if present":+ removals+++ }+ }+ return units, loads, removals+ }+ endpointOpts.sessionSync, endpointOpts.noSessionSync = false, false+ if u, l, r := plan(); u+l+r != 0 {+ t.Fatalf("default plan names the session sync job: units=%d loads=%d removals=%d", u, l, r)+ }+ endpointOpts.sessionSync = true+ if u, l, r := plan(); u != 1 || l != 1 || r != 0 {+ t.Fatalf("--session-sync plan: units=%d loads=%d removals=%d", u, l, r)+ }+ endpointOpts.sessionSync, endpointOpts.noSessionSync = false, true+ if u, l, r := plan(); u != 0 || l != 0 || r != 1 {+ t.Fatalf("--no-session-sync plan: units=%d loads=%d removals=%d", u, l, r)+ }+}+// writeNativeConfigInProcess runs native config repair in this process, the non-root path, so a// test that checks what the writers produce does not depend on whether the suite runs as root.func writeNativeConfigInProcess(t *testing.T) {diff --git a/cli/beacon/cmd/history_env_test.go b/cli/beacon/cmd/history_env_test.goindex 76735ea8..2891e348 100644--- a/cli/beacon/cmd/history_env_test.go+++ b/cli/beacon/cmd/history_env_test.go@@ -19,7 +19,9 @@ import (// system) enrollment and privacy mode, and no BEACON_API_URL, so neither changes what a test sends// or where; a test that needs a connection sets shareAutoCloud itself. PATH is an empty directory,// so harness discovery finds what a test puts there and nothing the machine has installed; a test-// that runs a real command declares it with testenv.RequireCommands.+// that runs a real command declares it with testenv.RequireCommands. The session sweep lock lives+// in the same temporary directory, so a sync under test never creates the system base directory+// (which a non-root runner cannot) or a lock in the developer's real home.func TestMain(m *testing.M) {dir, err := os.MkdirTemp("", "beacon-cmd-test")if err != nil {@@ -32,6 +34,12 @@ func TestMain(m *testing.M) {}_ = os.Setenv(endpointconfig.HistoryStoreEnv, filepath.Join(dir, "absent", "history.db"))_ = os.Setenv(endpointBackfillEnv, "0")+ endpointSweepLockPath = func(userMode bool) string {+ if userMode {+ return filepath.Join(dir, "sweep-lock", "user", "session-sweep.lock")+ }+ return filepath.Join(dir, "sweep-lock", "system", "session-sweep.lock")+ }// A wizard install under test that reaches the end of a Beacon Cloud connect must not open// the developer's browser; tests that check the opening stub this themselves.onboardingOpenDashboard = func(string) error { return nil }diff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.goindex 52d084d0..201b247c 100644--- a/cli/beacon/internal/endpoint/collector/collector.go+++ b/cli/beacon/internal/endpoint/collector/collector.go@@ -24,6 +24,7 @@ const (var (lookPath = exec.LookPathcurrentExecutable = os.Executable+ discoverSiblingBinary = siblingBinarydiscoverDefaultBinaryCandidates = defaultBinaryCandidates// pollInterval is how often the readiness and port waits re-check; tests shorten it.pollInterval = 250 * time.Millisecond@@ -60,6 +61,13 @@ func DiscoverBinary(configured string) string {return configured}}+ // The collector beside this CLI comes from the same release, so it comes before PATH. An older+ // beacon-otelcol earlier on PATH (a Homebrew install on a Mac that also has the package, which+ // sudo finds first) can lack components this CLI's collector config needs, and a repair that+ // took it refused to install.+ if sibling := discoverSiblingBinary(); sibling != "" && validateExecutable(sibling) == nil {+ return sibling+ }if path, err := lookPath(BinaryName); err == nil && validateExecutable(path) == nil {return path}@@ -71,7 +79,7 @@ func DiscoverBinary(configured string) string {return ""}-// defaultBinaryCandidates lists where to look for the collector when it is not on PATH.+// defaultBinaryCandidates lists where to look for the collector besides PATH.//// A sibling of the running CLI comes first, because that is what an extracted release archive looks// like: beacon and beacon-otelcol next to each other in whatever directory the user unpacked them@@ -83,17 +91,23 @@ func DiscoverBinary(configured string) string {// collector at all.func defaultBinaryCandidates() []string {paths := packagedBinaryPaths()- // A Homebrew CLI runs from its versioned keg, and the collector path found here goes into- // the service unit, so it is mapped to the <prefix>/bin link that survives `brew upgrade`.- // PATH usually finds that link first, but not under sudo, whose secure_path leaves out the- // Linuxbrew prefix.- if executable, err := currentExecutable(); err == nil {- sibling := brewpath.Stable(filepath.Join(filepath.Dir(executable), binaryFileName()))+ if sibling := siblingBinary(); sibling != "" {paths = append([]string{sibling}, paths...)}return paths}+// siblingBinary is the collector beside the running CLI, or "" when the executable is unknown.+// A Homebrew CLI runs from its versioned keg, and the collector path found here goes into the+// service unit, so it is mapped to the <prefix>/bin link that survives `brew upgrade`.+func siblingBinary() string {+ executable, err := currentExecutable()+ if err != nil {+ return ""+ }+ return brewpath.Stable(filepath.Join(filepath.Dir(executable), binaryFileName()))+}+func validateExecutable(path string) error {info, err := os.Stat(path)if err != nil {diff --git a/cli/beacon/internal/endpoint/collector/collector_test.go b/cli/beacon/internal/endpoint/collector/collector_test.goindex 757d005b..e4b21601 100644--- a/cli/beacon/internal/endpoint/collector/collector_test.go+++ b/cli/beacon/internal/endpoint/collector/collector_test.go@@ -405,9 +405,31 @@ func TestDiscoverBinaryFindsAdjacentBeaconOtelcol(t *testing.T) {}}+// A package CLI run under sudo on a Mac with a Homebrew Beacon finds Homebrew's older+// beacon-otelcol first on PATH. The collector beside the CLI is the one from its own release, so+// it wins; a repair that took the PATH one refused to install and left the endpoint without its+// collector.+func TestDiscoverBinaryPrefersTheCollectorBesideTheCLIOverPath(t *testing.T) {+ onPath := filepath.Join(t.TempDir(), stubCollectorName())+ beside := filepath.Join(t.TempDir(), stubCollectorName())+ for _, bin := range []string{onPath, beside} {+ if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0755); err != nil {+ t.Fatalf("write fake collector: %v", err)+ }+ }+ t.Setenv("PATH", filepath.Dir(onPath))+ withCollectorDiscovery(t, nil, nil)+ discoverSiblingBinary = func() string { return beside }++ if got := DiscoverBinary(""); got != beside {+ t.Fatalf("DiscoverBinary = %q, want the collector beside the CLI %q", got, beside)+ }+}+func withCollectorDiscovery(t *testing.T, lookup func(string) (string, error), candidates func() []string) {t.Helper()oldLookPath := lookPath+ oldSibling := discoverSiblingBinaryoldCandidates := discoverDefaultBinaryCandidatesif lookup == nil {lookup = execLookPath@@ -416,9 +438,11 @@ func withCollectorDiscovery(t *testing.T, lookup func(string) (string, error), ccandidates = func() []string { return nil }}lookPath = lookup+ discoverSiblingBinary = func() string { return "" }discoverDefaultBinaryCandidates = candidatest.Cleanup(func() {lookPath = oldLookPath+ discoverSiblingBinary = oldSiblingdiscoverDefaultBinaryCandidates = oldCandidates})}diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.goindex ca4d6044..e65beb8b 100644--- a/cli/beacon/internal/endpoint/config/config.go+++ b/cli/beacon/internal/endpoint/config/config.go@@ -112,11 +112,14 @@ type Config struct {EventCategories []string `json:"event_categories,omitempty"`// ClaudeCaptureModelContext is the --claude-capture-model-context opt-in, recorded so the per-user// config repair writes Claude Code's settings the way the install did.- ClaudeCaptureModelContext bool `json:"claude_capture_model_context,omitempty"`- Inventory *Inventory `json:"inventory_heartbeat,omitempty"`- Destinations *Destinations `json:"destinations,omitempty"`- ManagedIngest *ManagedIngest `json:"managed_ingest,omitempty"`- AutoUpdate *AutoUpdate `json:"auto_update,omitempty"`+ ClaudeCaptureModelContext bool `json:"claude_capture_model_context,omitempty"`+ Inventory *Inventory `json:"inventory_heartbeat,omitempty"`+ // SessionSync turns on the scheduled job that reads the agent runtimes' own session stores+ // into the runtime log. Off unless set: see SessionSync.+ SessionSync *SessionSync `json:"session_sync,omitempty"`+ Destinations *Destinations `json:"destinations,omitempty"`+ ManagedIngest *ManagedIngest `json:"managed_ingest,omitempty"`+ AutoUpdate *AutoUpdate `json:"auto_update,omitempty"`// LogAccess is the system log's access mode: "shared" (empty, the default) or "restricted".// Read it through RestrictedLogAccess, which also accounts for user mode.LogAccess string `json:"log_access,omitempty"`@@ -162,6 +165,19 @@ type Collector struct {IncludeCodexSpans bool `json:"include_codex_spans,omitempty"`}+// SessionSync is the `session_sync` block. Unlike the inventory heartbeat it is opt-in: the job+// re-reads session stores that hooks and OTLP already capture live, so turning it on adds poll+// events (`harness.collection_method=poll`) alongside the live ones, which a deployment that+// forwards the runtime log elsewhere chooses deliberately.+type SessionSync struct {+ Enabled bool `json:"enabled"`+}++// SessionSyncEnabled reports whether cfg turns the scheduled session sync on.+func SessionSyncEnabled(cfg Config) bool {+ return cfg.SessionSync != nil && cfg.SessionSync.Enabled+}+// Inventory is the `inventory_heartbeat` block. `enabled` nil means enabled; it governs both the// scheduled job and the writer. A `ttl_seconds` key written by older versions is ignored: the// heartbeat runs on the scheduler's interval, not a TTL.diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.goindex 37dabb5f..69c362e0 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go@@ -328,6 +328,9 @@ type InstallOptions struct {// LogAccess sets the system log's access mode, "shared" or "restricted". Empty keeps what the// existing config records, so repair and a package upgrade never change it.LogAccess string+ // SessionSync turns the scheduled session-store sync on or off; nil keeps what the existing+ // config records (off for a new install), so repair and package upgrades never change it.+ SessionSync *bool}type UninstallOptions struct {@@ -369,6 +372,10 @@ type InstallResult struct {// is readable by, which then has no members yet.LogReadersGroupCreated bool `json:"log_readers_group_created,omitempty"`InventoryJobDetail string `json:"inventory_job_detail,omitempty"`+ // SessionSyncJobPath is the scheduled session sync unit when `session_sync.enabled` is on;+ // SessionSyncJobDetail says why it is not installed on a host without a scheduler.+ SessionSyncJobPath string `json:"session_sync_job_path,omitempty"`+ SessionSyncJobDetail string `json:"session_sync_job_detail,omitempty"`// ManagedForwarder reports the Beacon Cloud forwarder reconcile. It never fails the install:// a config Vector rejects leaves the running forwarder on its old one and is reported here.ManagedForwarder *asymptote.ReconcileResult `json:"managed_forwarder,omitempty"`@@ -390,6 +397,8 @@ type Status struct {ManagedIngest asymptote.ManagedIngestStatus `json:"managed_ingest"`// InventoryHeartbeat follows the requested mode, like ManagedIngest: each mode has its own job.InventoryHeartbeat InventoryHeartbeatStatus `json:"inventory_heartbeat"`+ // SessionSync follows the requested mode too.+ SessionSync SessionSyncStatus `json:"session_sync"`// ScriptForwarders are the S3, GCS and Falcon forwarders the package helpers install, one entry// per forwarder that is set up on this machine.ScriptForwarders []service.Status `json:"script_forwarders,omitempty"`@@ -474,8 +483,16 @@ type installRollback struct {InventoryJob inventoryJobControllerInventoryLoaded boolInventoryWasLoaded bool- Manager serviceController- ServiceLoaded bool+ // SessionSyncJob and the two flags beside it do the same for the scheduled session sync.+ // SessionSyncRemoved records that this install unloaded and removed the job (the setting+ // turned off): unlike the inventory job, off is an ordinary choice here, so a rollback has to+ // put back a job that was scheduled before as well as unload one it started.+ SessionSyncJob inventoryJobController+ SessionSyncLoaded bool+ SessionSyncRemoved bool+ SessionSyncWasLoaded bool+ Manager serviceController+ ServiceLoaded bool// ServiceWasRunning records whether a collector was already up when this install began.//// It decides what rollback owes the machine. Unloading is right for a service this transaction@@ -530,6 +547,9 @@ func (r *installRollback) Rollback(manifest Manifest) {if r.InventoryLoaded && r.InventoryJob != nil && !r.InventoryWasLoaded {_ = r.InventoryJob.Unload()}+ if r.SessionSyncLoaded && r.SessionSyncJob != nil && !r.SessionSyncWasLoaded {+ _ = r.SessionSyncJob.Unload()+ }restoreBackups(manifest.Backups)for i := len(r.files) - 1; i >= 0; i-- {@@ -560,17 +580,17 @@ func (r *installRollback) Rollback(manifest Manifest) {if r.InventoryLoaded && r.InventoryWasLoaded && r.InventoryJob != nil {_ = r.InventoryJob.Load()}+ if (r.SessionSyncLoaded || r.SessionSyncRemoved) && r.SessionSyncWasLoaded && r.SessionSyncJob != nil {+ _ = r.SessionSyncJob.Load()+ }}-func Install(opts InstallOptions) (InstallResult, error) {- cfg := buildConfig(opts)- if err := preflight(cfg, opts.StartService, opts.ServiceKind); err != nil {- return InstallResult{}, err- }- manager := service.Manager{UserMode: cfg.UserMode, Kind: opts.ServiceKind}+// usableCollectorBinary resolves the collector an install of cfg runs and checks that it has every+// component cfg's collector config needs.+func usableCollectorBinary(cfg endpointconfig.Config) (string, error) {collectorBinary, err := endpointcollector.ResolveBinary(cfg.Collector.BinaryPath)if err != nil {- return InstallResult{}, err+ return "", err}var extensions []stringif cfg.RestrictedLogAccess() {@@ -582,6 +602,19 @@ func Install(opts InstallOptions) (InstallResult, error) {exporters = append(exporters, endpointcollector.OTLPForwardExporters[cfg.Destinations.OTLPForward.Protocol])}if err := endpointcollector.CheckComponentsFor(collectorBinary, extensions, processors, exporters); err != nil {+ return "", err+ }+ return collectorBinary, nil+}++func Install(opts InstallOptions) (InstallResult, error) {+ cfg := buildConfig(opts)+ if err := preflight(cfg, opts.StartService, opts.ServiceKind); err != nil {+ return InstallResult{}, err+ }+ manager := service.Manager{UserMode: cfg.UserMode, Kind: opts.ServiceKind}+ collectorBinary, err := usableCollectorBinary(cfg)+ if err != nil {return InstallResult{}, err}@@ -687,6 +720,28 @@ func Install(opts InstallOptions) (InstallResult, error) {inventoryDetail = "scheduled inventory job: " + inventoryErr.Error()}+ // The scheduled session sync is opt-in (`session_sync.enabled`) and reconciled the same way:+ // installed and loaded when on, removed when off, never failing the install.+ sessionSyncJob := newSessionSyncJob(cfg.UserMode, opts.ServiceKind)+ for _, path := range sessionSyncJob.UnitPaths() {+ tx.Track(path)+ }+ tx.SessionSyncJob = sessionSyncJob+ tx.SessionSyncWasLoaded = sessionSyncJob.Status().Loaded+ sessionSyncResult, sessionSyncErr := reconcileSessionSyncJobWith(sessionSyncJob, InventoryJobOptions{+ UserMode: cfg.UserMode,+ Kind: opts.ServiceKind,+ Program: DefaultInventoryJobProgram(cfg.UserMode),+ LogPath: cfg.LogPath,+ Load: opts.StartService,+ })+ tx.SessionSyncLoaded = sessionSyncResult.Loaded+ tx.SessionSyncRemoved = sessionSyncResult.Removed+ if sessionSyncErr != nil {+ sessionSyncResult.UnitPath = ""+ sessionSyncResult.Skipped = "scheduled session sync job: " + sessionSyncErr.Error()+ }+harnessPaths, err := configureHarnesses(cfg)manifest.HarnessConfigs = harnessPathsmanifest.Backups = discoverBackups(harnessPaths)@@ -795,6 +850,8 @@ func Install(opts InstallOptions) (InstallResult, error) {LingerRemediation: lingerOutcome.Remediation,InventoryJobPath: inventoryResult.UnitPath,InventoryJobDetail: inventoryDetail,+ SessionSyncJobPath: sessionSyncResult.UnitPath,+ SessionSyncJobDetail: sessionSyncResult.Skipped,LogAccess: logAccessOf(cfg),LogReadersGroupCreated: logReadersGroupCreated,}, nil@@ -839,6 +896,7 @@ func Uninstall(opts UninstallOptions) error {removeUpdaterJob()}removeInventoryJob(cfg.UserMode)+ removeSessionSyncJob(cfg.UserMode)// The S3, GCS and Falcon forwarders run from /opt/beacon and read the customer's credentials// from their env files, so they go with the endpoint the same way the managed forwarder does.if !cfg.UserMode && !opts.KeepForwarders {@@ -957,6 +1015,12 @@ func Repair(opts InstallOptions) (InstallResult, error) {priorAutoUpdateMode = mode}}+ // The teardown below removes the collector's unit and config, and a failed install restores+ // only the endpoint config, so a collector the install would refuse is refused first, while+ // the endpoint still runs.+ if _, err := usableCollectorBinary(buildConfig(opts)); err != nil {+ return InstallResult{}, err+ }_ = Uninstall(repairUninstallOptions(opts))result, err := Install(opts)if err != nil {@@ -1086,6 +1150,7 @@ func buildStatus(requestedUserMode bool, effectiveCfg endpointconfig.Config, runDestinations: destinationStatus(effectiveCfg),ManagedIngest: asymptote.Status(requestedUserMode, managedOpts),InventoryHeartbeat: inventoryHeartbeatStatus(requestedUserMode, runtimeLog.RequestedLogPath),+ SessionSync: sessionSyncStatus(requestedUserMode, runtimeLog.RequestedLogPath),ScriptForwarders: scriptForwarderStatuses(),LogAccess: logAccessOf(effectiveCfg),}@@ -1148,6 +1213,9 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {if existing.Inventory != nil {cfg.Inventory = existing.Inventory}+ if existing.SessionSync != nil {+ cfg.SessionSync = existing.SessionSync+ }// The OTLP forward replaces the export a runtime had to another backend before Beacon// pointed it at the collector. An upgrade or repair that dropped it would silently cut that// backend off, so it is kept until --no-otlp-forward removes it.@@ -1166,6 +1234,9 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {if opts.LogAccess != "" {cfg.LogAccess = opts.LogAccess}+ if opts.SessionSync != nil {+ cfg.SessionSync = &endpointconfig.SessionSync{Enabled: *opts.SessionSync}+ }if opts.Harnesses != nil {cfg.Harnesses = opts.Harnesses}diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.goindex 2d4fd7c1..f968239b 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go@@ -612,6 +612,61 @@ func TestRepairPreservesExistingConfigWhenReinstallFails(t *testing.T) {}}+// Repair tears the endpoint down before it reinstalls, and a failed reinstall restores only the+// endpoint config. A collector the reinstall would refuse (an older beacon-otelcol, as sudo finds+// Homebrew's on a Mac that also has the package) left the endpoint with no collector unit or+// config, so repair refuses it before the teardown.+func TestRepairRefusesAnOlderCollectorBeforeTearingDown(t *testing.T) {+ if runtime.GOOS != "darwin" {+ t.Skip("install preflight is macOS-only")+ }+ testenv.RequirePOSIXExecutableFixtures(t)+ home := t.TempDir()+ testenv.SetHome(t, home)+ logPath := filepath.Join(home, ".beacon", "endpoint", "logs", "runtime.jsonl")+ bin := filepath.Join(home, "bin")+ if err := os.MkdirAll(bin, 0755); err != nil {+ t.Fatal(err)+ }+ current := filepath.Join(bin, "beacon-otelcol")+ if err := os.WriteFile(current, []byte("#!/bin/sh\n"), 0755); err != nil {+ t.Fatal(err)+ }+ older := filepath.Join(bin, "beacon-otelcol-older")+ if err := os.WriteFile(older, []byte("#!/bin/sh\n[ \"$1\" = components ] && printf 'processors:\\n - name: batch\\n'\n"), 0755); err != nil {+ t.Fatal(err)+ }+ opts := InstallOptions{+ UserMode: true,+ LogPath: logPath,+ Harnesses: []string{},+ GRPCPort: freePort(t),+ HTTPPort: freePort(t),+ CollectorPath: current,+ StartService: false,+ }+ if _, err := Install(opts); err != nil {+ t.Fatalf("Install: %v", err)+ }+ cfg := endpointconfig.Default(true, logPath)+ installed := []string{endpointconfig.ConfigPath(true), cfg.Collector.ConfigPath, manifestPath(true)}+ for _, path := range installed {+ if _, err := os.Stat(path); err != nil {+ t.Fatalf("install did not write %s: %v", path, err)+ }+ }++ opts.CollectorPath = older+ if _, err := Repair(opts); err == nil || !strings.Contains(err.Error(), "older than this beacon CLI") {+ t.Fatalf("Repair error = %v, want the older collector refused", err)+ }+ for _, path := range installed {+ if _, err := os.Stat(path); err != nil {+ t.Fatalf("a refused repair removed %s: %v", path, err)+ }+ }+}+var (freePortsMu sync.MutexfreePortsIssued = map[int]bool{}diff --git a/cli/beacon/internal/endpoint/lifecycle/session_sync.go b/cli/beacon/internal/endpoint/lifecycle/session_sync.gonew file mode 100644index 00000000..9d7a68d6--- /dev/null+++ b/cli/beacon/internal/endpoint/lifecycle/session_sync.go@@ -0,0 +1,143 @@+package lifecycle++import (+ "encoding/json"+ "os"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"+)++var (+ // newSessionSyncJob and removeSessionSyncJob are the seams tests replace so Install,+ // Uninstall and Repair can be exercised without touching launchd or systemd.+ newSessionSyncJob = func(userMode bool, kind service.Kind) inventoryJobController {+ return service.SessionSyncManager{UserMode: userMode, Kind: kind, Env: sessionSyncJobEnv(userMode)}+ }+ removeSessionSyncJob = func(userMode bool) {+ job := newSessionSyncJob(userMode, service.KindAuto)+ _ = job.Unload()+ job.RemoveUnits()+ }+)++// sessionSyncJobPathEnv are the directory variables a session-store collector reads beyond the+// ones the inventory scan does. launchd and systemd do not pass a shell's exports to the job, so a+// user-mode job records each one set at install, as the inventory job does, or a store moved with+// it would be read at install and never again.+var sessionSyncJobPathEnv = []string{+ "COPILOT_HOME", // GitHub Copilot CLI+ "XDG_DATA_HOME", // OpenCode and Devin on Linux+ "HARNESS2_RUNS_DIR", // Harness²+}++// sessionSyncJobNameEnv are read as names, not paths, and recorded exactly as set: OPENCODE_DB is+// resolved against OpenCode's data directory when relative.+var sessionSyncJobNameEnv = []string{"OPENCODE_DB"}++// sessionSyncJobEnv is the inventory job's environment plus the variables only a session-store+// collector reads. System mode records nothing, like inventoryJobEnv: the process's environment is+// root's, not the console user's.+func sessionSyncJobEnv(userMode bool) map[string]string {+ if !userMode {+ return nil+ }+ env := inventoryJobEnv(true)+ if env == nil {+ env = map[string]string{}+ }+ for _, name := range sessionSyncJobPathEnv {+ if value, ok := os.LookupEnv(name); ok {+ env[name] = inventoryJobPathValue(value)+ }+ }+ for _, name := range sessionSyncJobNameEnv {+ if value, ok := os.LookupEnv(name); ok {+ env[name] = value+ }+ }+ if len(env) == 0 {+ return nil+ }+ return env+}++// SessionSyncJobResult reports what ReconcileSessionSyncJob did.+type SessionSyncJobResult struct {+ Enabled bool `json:"enabled"`+ UnitPath string `json:"unit_path,omitempty"`+ Loaded bool `json:"loaded"`+ Removed bool `json:"removed"`+ // Skipped names why no job was installed on a host without a scheduler.+ Skipped string `json:"skipped,omitempty"`+}++// ReconcileSessionSyncJob makes the scheduled session sync job match the endpoint config for the+// mode: installed and loaded when `session_sync.enabled` is true, removed otherwise (the default).+// It runs on every install, repair and package upgrade, so turning the setting on or off with+// `--session-sync`/`--no-session-sync` takes effect in the same command.+func ReconcileSessionSyncJob(opts InventoryJobOptions) (SessionSyncJobResult, error) {+ return reconcileSessionSyncJobWith(newSessionSyncJob(opts.UserMode, opts.Kind), opts)+}++func reconcileSessionSyncJobWith(job inventoryJobController, opts InventoryJobOptions) (SessionSyncJobResult, error) {+ result := SessionSyncJobResult{Enabled: sessionSyncEnabledFromConfigFile(endpointconfig.ConfigPath(opts.UserMode))}+ if !result.Enabled {+ // Removing is safe with or without a scheduler, and it is what turning the setting off+ // has to do wherever a job was installed before.+ if job.Supported() {+ _ = job.Unload()+ }+ job.RemoveUnits()+ result.Removed = true+ return result, nil+ }+ if !job.Supported() {+ result.Skipped = job.UnsupportedReason()+ return result, nil+ }+ path, err := job.WriteUnit(opts.Program, opts.LogPath)+ if err != nil {+ return result, err+ }+ result.UnitPath = path+ if opts.Load {+ if err := job.Load(); err != nil {+ return result, err+ }+ result.Loaded = true+ }+ return result, nil+}++// 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 {+ data, err := os.ReadFile(path)+ if err != nil {+ return false+ }+ var partial struct {+ SessionSync *endpointconfig.SessionSync `json:"session_sync"`+ }+ if err := json.Unmarshal(data, &partial); err != nil || partial.SessionSync == nil {+ return false+ }+ return partial.SessionSync.Enabled+}++// SessionSyncStatus is the status view of the scheduled session sync job.+type SessionSyncStatus struct {+ Enabled bool `json:"enabled"`+ Interval string `json:"interval"`+ Job service.Status `json:"job"`+}++func sessionSyncStatus(requestedUserMode bool, logPath string) SessionSyncStatus {+ cfg := loadOrDefault(requestedUserMode, logPath)+ return SessionSyncStatus{+ Enabled: endpointconfig.SessionSyncEnabled(cfg),+ Interval: service.SessionSyncInterval().String(),+ Job: newSessionSyncJob(requestedUserMode, service.KindAuto).Status(),+ }+}diff --git a/cli/beacon/internal/endpoint/lifecycle/session_sync_test.go b/cli/beacon/internal/endpoint/lifecycle/session_sync_test.gonew file mode 100644index 00000000..44544284--- /dev/null+++ b/cli/beacon/internal/endpoint/lifecycle/session_sync_test.go@@ -0,0 +1,159 @@+package lifecycle++import (+ "os"+ "path/filepath"+ "reflect"+ "regexp"+ "strings"+ "testing"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// The session sync is opt-in: with no config, or a config without the block, it is off, and+// reconciling removes any job a previous setting installed.+func TestReconcileSessionSyncJobIsOffByDefault(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ for _, body := range []string{"", `{"user_mode":true}`, `{"user_mode":true,"session_sync":{"enabled":false}}`} {+ if body != "" {+ writeInventoryConfig(t, true, body)+ }+ calls := &[]string{}+ result, err := reconcileSessionSyncJobWith(recordingInventoryJob{calls: calls, supported: true, unitPath: "/fake/s.plist"},+ InventoryJobOptions{UserMode: true, Program: "/bin/beacon", Load: true})+ if err != nil {+ t.Fatal(err)+ }+ if result.Enabled || !result.Removed || !reflect.DeepEqual(*calls, []string{"unload", "remove"}) {+ t.Fatalf("config %q: result %+v calls %v, want the job removed", body, result, *calls)+ }+ }+}++func TestReconcileSessionSyncJobWritesAndLoadsWhenEnabled(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ writeInventoryConfig(t, true, `{"user_mode":true,"session_sync":{"enabled":true}}`)+ calls := &[]string{}+ result, err := reconcileSessionSyncJobWith(recordingInventoryJob{calls: calls, supported: true, unitPath: "/fake/s.plist"},+ InventoryJobOptions{UserMode: true, Program: "/bin/beacon", LogPath: "/l/runtime.jsonl", Load: true})+ if err != nil {+ t.Fatal(err)+ }+ if !result.Enabled || !result.Loaded || result.UnitPath != "/fake/s.plist" {+ t.Fatalf("result = %+v", result)+ }+ if want := []string{"write /bin/beacon /l/runtime.jsonl", "load"}; !reflect.DeepEqual(*calls, want) {+ t.Fatalf("calls = %v, want %v", *calls, want)+ }++ // --no-start writes the unit and leaves it unloaded.+ *calls = nil+ if result, err = reconcileSessionSyncJobWith(recordingInventoryJob{calls: calls, supported: true, unitPath: "/fake/s.plist"},+ InventoryJobOptions{UserMode: true, Program: "/bin/beacon"}); err != nil || result.Loaded {+ t.Fatalf("no-start: %+v, %v", result, err)+ }++ // No scheduler: reported, not an error.+ *calls = nil+ result, err = reconcileSessionSyncJobWith(recordingInventoryJob{calls: calls, supported: false},+ InventoryJobOptions{UserMode: true, Program: "/bin/beacon", Load: true})+ if err != nil || result.Skipped == "" || len(*calls) != 0 {+ t.Fatalf("unsupported: %+v %v calls %v", result, err, *calls)+ }+}++// Repair and package upgrades run install with no session sync flag; they must keep the setting.+func TestBuildConfigKeepsSessionSyncUntilChanged(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ writeInventoryConfig(t, true, `{"user_mode":true,"log_path":"/tmp/runtime.jsonl","session_sync":{"enabled":true}}`)+ if cfg := buildConfig(InstallOptions{UserMode: true}); !endpointconfig.SessionSyncEnabled(cfg) {+ t.Fatalf("buildConfig dropped session_sync: %+v", cfg.SessionSync)+ }+ off := false+ if cfg := buildConfig(InstallOptions{UserMode: true, SessionSync: &off}); endpointconfig.SessionSyncEnabled(cfg) {+ t.Fatal("--no-session-sync did not turn it off")+ }+ on := true+ testenv.SetHome(t, t.TempDir())+ if cfg := buildConfig(InstallOptions{UserMode: true}); endpointconfig.SessionSyncEnabled(cfg) {+ t.Fatal("a fresh install turned session sync on by default")+ }+ if cfg := buildConfig(InstallOptions{UserMode: true, SessionSync: &on}); !endpointconfig.SessionSyncEnabled(cfg) {+ t.Fatal("--session-sync did not turn it on")+ }+}++// A user-mode job carries the store-locating variables set at install, including the ones only a+// session-store collector reads.+func TestSessionSyncJobEnvCarriesCollectorVariables(t *testing.T) {+ for _, name := range append(append([]string{}, sessionSyncJobPathEnv...), sessionSyncJobNameEnv...) {+ t.Setenv(name, "")+ }+ abs := filepath.Join(t.TempDir(), "copilot")+ t.Setenv("COPILOT_HOME", abs)+ t.Setenv("HARNESS2_RUNS_DIR", "relative-runs")+ t.Setenv("OPENCODE_DB", "custom.db")+ env := sessionSyncJobEnv(true)+ if env["COPILOT_HOME"] != abs || env["OPENCODE_DB"] != "custom.db" || !filepath.IsAbs(env["HARNESS2_RUNS_DIR"]) {+ t.Fatalf("env = %v", env)+ }+ if sessionSyncJobEnv(false) != nil {+ t.Fatal("system mode records root's environment")+ }+}++// Every variable a session-store collector reads to find its store is one the job carries, so a+// store moved by one is read on schedule as well as at install. APPDATA and LOCALAPPDATA are+// Windows-only, where no job is installed.+func TestSessionSyncJobEnvCoversEveryCollectorVariable(t *testing.T) {+ carried := map[string]bool{+ "CODEX_HOME": true, "HERMES_HOME": true, "HERMES_DATA_DIR_SUFFIX": true, "CLINE_DIR": true,+ "GEMINI_CLI_HOME": true, "CLAUDE_CONFIG_DIR": true, "APPDATA": true, "LOCALAPPDATA": true,+ }+ for _, list := range [][]string{inventoryJobPathEnv, inventoryJobNameEnv, sessionSyncJobPathEnv, sessionSyncJobNameEnv} {+ for _, name := range list {+ carried[name] = true+ }+ }+ files, err := filepath.Glob(filepath.Join("..", "..", "*session", "*.go"))+ if err != nil || len(files) == 0 {+ t.Fatalf("no collector sources found: %v", err)+ }+ read := regexp.MustCompile(`os\.(?:Getenv|LookupEnv)\("([A-Z0-9_]+)"\)`)+ for _, file := range files {+ if strings.HasSuffix(file, "_test.go") {+ continue+ }+ data, err := os.ReadFile(file)+ if err != nil {+ t.Fatal(err)+ }+ for _, m := range read.FindAllStringSubmatch(string(data), -1) {+ if !carried[m[1]] {+ t.Errorf("%s reads %s, which the scheduled session sync job does not carry; add it to sessionSyncJobPathEnv or sessionSyncJobNameEnv", file, m[1])+ }+ }+ }+}++// A repair that turned the setting off and then failed puts back the job that was scheduled+// before; one that never touched a scheduled job leaves it alone.+func TestRollbackRestoresSessionSyncJobTurnedOff(t *testing.T) {+ calls := &[]string{}+ tx := &installRollback{snapshots: map[string]fileSnapshot{},+ SessionSyncJob: recordingInventoryJob{calls: calls, supported: true}, SessionSyncRemoved: true, SessionSyncWasLoaded: true}+ tx.Rollback(Manifest{})+ if !reflect.DeepEqual(*calls, []string{"load"}) {+ t.Fatalf("calls = %v, want the previously scheduled job loaded again", *calls)+ }++ *calls = nil+ tx = &installRollback{snapshots: map[string]fileSnapshot{},+ SessionSyncJob: recordingInventoryJob{calls: calls, supported: true}, SessionSyncRemoved: true}+ tx.Rollback(Manifest{})+ if len(*calls) != 0 {+ t.Fatalf("calls = %v, want nothing for a job that was not scheduled before", *calls)+ }+}diff --git a/cli/beacon/internal/endpoint/service/inventory.go b/cli/beacon/internal/endpoint/service/inventory.goindex 7f7c3e84..0ad64876 100644--- a/cli/beacon/internal/endpoint/service/inventory.go+++ b/cli/beacon/internal/endpoint/service/inventory.go@@ -1,13 +1,6 @@package serviceimport (- "fmt"- "maps"- "os"- "path/filepath"- "runtime"- "slices"- "strconv""strings""time")@@ -30,22 +23,25 @@ const (// InventoryInterval is how often the scheduled heartbeat runs. The plist, the systemd timer and// the status line all read it here so they can never disagree.func InventoryInterval() time.Duration {- if raw := strings.TrimSpace(os.Getenv(InventoryIntervalEnv)); raw != "" {- if secs, err := strconv.Atoi(raw); err == nil && secs > 0 {- return time.Duration(secs) * time.Second- }- }- return defaultInventoryInterval+ return intervalFromEnv(InventoryIntervalEnv, defaultInventoryInterval)+}++var inventorySpec = jobSpec{+ label: InventoryLabel,+ serviceUnit: InventoryServiceUnit,+ timerUnit: InventoryTimerUnit,+ description: "inventory heartbeat",+ name: "scheduled inventory job",+ docs: "https://docs.asymptotelabs.ai/cli/endpoint-inventory",+ manualHint: "Run `beacon endpoint inventory heartbeat` from your own scheduler.",+ interval: InventoryInterval,+ args: inventoryJobArgs,+ runAtLoad: true,}-// InventoryManager manages the scheduled job that writes inventory heartbeats. It is a one-shot-// job on a timer, like the updater, but unlike the updater it exists in both user and system-// modes, like the forwarder, because a per-user Beacon install inventories that user's runtimes.-//-// The job fires once when loaded (install, boot, package upgrade) and then every-// InventoryInterval. There is no jitter: launchd measures StartInterval from the moment the job-// was loaded, and systemd's OnUnitActiveSec from the last run, so a fleet installed at different-// times is naturally staggered.+// InventoryManager manages the scheduled job that writes inventory heartbeats, in both user and+// system modes, because a per-user Beacon install inventories that user's runtimes. See+// scheduledJob for how the job is installed, loaded and reported.type InventoryManager struct {UserMode bool// Kind selects the backend; the zero value auto-detects.@@ -56,98 +52,30 @@ type InventoryManager struct {Env map[string]string}-func (m InventoryManager) resolvedKind() Kind {- if m.Kind != KindAuto {- return m.Kind- }- return DetectKind()-}--// Supported reports whether a scheduled inventory job can be installed here.-//-// Supervised mode has no scheduler, so there is deliberately no fallback: a timer that silently-// never fires would be worse than refusing to install one.-func (m InventoryManager) Supported() bool {- switch m.resolvedKind() {- case KindLaunchd:- return runtime.GOOS == "darwin"- case KindSystemd:- return systemdIsInit()- default:- return false- }-}--// UnsupportedReason explains why Supported is false.-func (m InventoryManager) UnsupportedReason() string {- switch m.resolvedKind() {- case KindLaunchd:- return "launchd service management is supported only on macOS"- case KindSystemd:- return "systemd is not PID 1 on this host, so the scheduled inventory job cannot be installed"- default:- return "the scheduled inventory job needs launchd or systemd; a supervised collector has no scheduler. " +- "Run `beacon endpoint inventory heartbeat` from your own scheduler."- }-}--// Label is the service identifier for status output.-func (m InventoryManager) Label() string {- if m.resolvedKind() == KindSystemd {- return InventoryTimerUnit- }- return InventoryLabel-}--// UnitPath returns where the job's service definition lives. On systemd this is the timer,-// since that is the unit an administrator enables and inspects.-func (m InventoryManager) UnitPath() (string, error) {- switch m.resolvedKind() {- case KindSystemd:- if m.UserMode {- home, err := os.UserHomeDir()- if err != nil {- return "", err- }- return filepath.Join(home, ".config", "systemd", "user", InventoryTimerUnit), nil- }- return filepath.Join("/etc/systemd/system", InventoryTimerUnit), nil- default:- if m.UserMode {- home, err := os.UserHomeDir()- if err != nil {- return "", err- }- return filepath.Join(home, "Library", "LaunchAgents", InventoryLabel+".plist"), nil- }- return filepath.Join("/Library/LaunchDaemons", InventoryLabel+".plist"), nil- }+func (m InventoryManager) job() scheduledJob {+ return scheduledJob{spec: inventorySpec, userMode: m.UserMode, kind: m.Kind, env: m.Env}}-// UnitPaths returns every file WriteUnit installs: the timer and the oneshot service on systemd,-// the plist on launchd. Removal sites must use this, not UnitPath, or the service unit is left-// behind (the updater made exactly that mistake).-func (m InventoryManager) UnitPaths() []string {- path, err := m.UnitPath()- if err != nil {- return nil- }- if m.resolvedKind() == KindSystemd {- return []string{path, filepath.Join(filepath.Dir(path), InventoryServiceUnit)}- }- return []string{path}-}--// RemoveUnits deletes every file WriteUnit installed. Missing files are not an error.-func (m InventoryManager) RemoveUnits() {- for _, path := range m.UnitPaths() {- _ = os.Remove(path)- }+func (m InventoryManager) Supported() bool { return m.job().Supported() }+func (m InventoryManager) UnsupportedReason() string { return m.job().UnsupportedReason() }+func (m InventoryManager) Label() string { return m.job().Label() }+func (m InventoryManager) UnitPath() (string, error) { return m.job().UnitPath() }+func (m InventoryManager) UnitPaths() []string { return m.job().UnitPaths() }+func (m InventoryManager) RemoveUnits() { m.job().RemoveUnits() }+func (m InventoryManager) Load() error { return m.job().Load() }+func (m InventoryManager) Unload() error { return m.job().Unload() }+func (m InventoryManager) Status() Status { return m.job().Status() }+func (m InventoryManager) WriteUnit(program, logPath string) (string, error) {+ return m.job().WriteUnit(program, logPath)}// inventoryJobArgs is the argument vector the scheduler invokes, after the program itself.func inventoryJobArgs(userMode bool, logPath string) []string {- args := []string{"endpoint", "inventory", "heartbeat", "--scheduled"}+ return modeJobArgs([]string{"endpoint", "inventory", "heartbeat", "--scheduled"}, userMode, logPath)+}++// modeJobArgs appends the mode and log-path flags every scheduled job takes.+func modeJobArgs(args []string, userMode bool, logPath string) []string {if userMode {args = append(args, "--user")} else {@@ -159,205 +87,13 @@ func inventoryJobArgs(userMode bool, logPath string) []string {return args}-// WriteUnit installs the job definition that runs `program endpoint inventory heartbeat-// --scheduled` for this mode. logPath, when set, pins the runtime log the inventory log sits-// beside; empty means the mode's default.-func (m InventoryManager) WriteUnit(program, logPath string) (string, error) {- if !m.Supported() {- return "", fmt.Errorf("%s", m.UnsupportedReason())- }- path, err := m.UnitPath()- if err != nil {- return "", err- }- if err := ensureDir(path); err != nil {- return "", err- }- args := inventoryJobArgs(m.UserMode, logPath)- if m.resolvedKind() == KindSystemd {- svc := filepath.Join(filepath.Dir(path), InventoryServiceUnit)- if err := os.WriteFile(svc, []byte(inventoryServiceUnit(program, args, m.UserMode, m.Env)), 0o644); err != nil {- return "", err- }- if err := os.WriteFile(path, []byte(inventoryTimerUnit(InventoryInterval())), 0o644); err != nil {- return "", err- }- if out, err := runSystemctlCommand(systemctlArgs(m.UserMode, "daemon-reload")...); err != nil {- return path, systemctlError(out, err, "daemon-reload")- }- return path, nil- }- if err := ensureLaunchdLogDir(m.UserMode, InventoryLabel); err != nil {- return "", err- }- stdout, stderr, err := launchdLogPaths(m.UserMode, InventoryLabel)- if err != nil {- return "", err- }- content := inventoryPlist(InventoryLabel, program, args, InventoryInterval(), stdout, stderr, m.Env)- if err := os.WriteFile(path, []byte(content), 0o644); err != nil {- return "", err- }- return path, nil-}--// Load activates the schedule. Loading fires the job once (RunAtLoad on launchd, an already-// elapsed OnBootSec on systemd), so every install, repair and package upgrade writes a heartbeat-// right away. An already-loaded launchd job is re-bootstrapped so a rewritten unit takes effect;-// the job exits in about a second, so there is nothing to wait for.-func (m InventoryManager) Load() error {- if !m.Supported() {- return fmt.Errorf("%s", m.UnsupportedReason())- }- if m.resolvedKind() == KindSystemd {- if out, err := runSystemctlCommand(systemctlArgs(m.UserMode, "enable", "--now", InventoryTimerUnit)...); err != nil {- return systemctlError(out, err, "enable --now "+InventoryTimerUnit)- }- return nil- }- path, err := m.UnitPath()- if err != nil {- return err- }- return loadLaunchdJob(serviceDomain(m.UserMode), InventoryLabel, path)-}--// Unload deactivates the schedule. A missing unit is not an error.-func (m InventoryManager) Unload() error {- switch m.resolvedKind() {- case KindSystemd:- if !systemdIsInit() {- return nil- }- if out, err := runSystemctlCommand(systemctlArgs(m.UserMode, "stop", InventoryTimerUnit)...); err != nil && !systemdUnitMissing(out) {- return systemctlError(out, err, "stop "+InventoryTimerUnit)- }- if out, err := runSystemctlCommand(systemctlArgs(m.UserMode, "disable", InventoryTimerUnit)...); err != nil && !systemdUnitMissing(out) {- return systemctlError(out, err, "disable "+InventoryTimerUnit)- }- return nil- case KindLaunchd:- if runtime.GOOS != "darwin" {- return nil- }- return bootoutLaunchdJob(serviceDomain(m.UserMode), InventoryLabel)- default:- return nil- }-}--// Status reports whether the schedule is active. For a one-shot job "running" means the timer-// is armed (systemd) or the job is registered with launchd; it does not mean a heartbeat is-// being written this instant.-func (m InventoryManager) Status() Status {- kind := m.resolvedKind()- if !m.Supported() {- return Status{Label: m.Label(), Kind: string(kind), Message: m.UnsupportedReason()}- }- if kind == KindSystemd {- status := Status{Label: InventoryTimerUnit, Kind: string(KindSystemd)}- enabledOut, _ := runSystemctlCommand(systemctlArgs(m.UserMode, "is-enabled", InventoryTimerUnit)...)- switch strings.TrimSpace(enabledOut) {- case "enabled", "enabled-runtime", "static":- status.Loaded = true- }- activeOut, _ := runSystemctlCommand(systemctlArgs(m.UserMode, "is-active", InventoryTimerUnit)...)- status.Running = strings.TrimSpace(activeOut) == "active"- if status.Running {- status.Loaded = true- }- if !status.Loaded && !status.Running {- status.Message = "scheduled inventory job not installed"- }- return status- }- status := Status{Label: InventoryLabel, Kind: string(KindLaunchd)}- out, err := runLaunchctlCommand("print", serviceDomain(m.UserMode)+"/"+InventoryLabel)- if err != nil {- status.Message = strings.TrimSpace(out)- return status- }- status.Loaded = true- status.Running = strings.Contains(out, "state = running") || strings.Contains(out, "pid =")- return status-}--// inventoryServiceUnit is the oneshot job the timer triggers.+// The renderers under their inventory names, which the inventory tests pin.func inventoryServiceUnit(program string, args []string, userMode bool, env map[string]string) string {- var b strings.Builder- b.WriteString("[Unit]\n")- b.WriteString("Description=Beacon endpoint inventory heartbeat\n")- b.WriteString("Documentation=https://docs.asymptotelabs.ai/cli/endpoint-inventory\n")- b.WriteString("\n[Service]\n")- b.WriteString("Type=oneshot\n")- for _, key := range slices.Sorted(maps.Keys(env)) {- fmt.Fprintf(&b, "Environment=%s\n", systemdArg(key+"="+env[key]))- }- fmt.Fprintf(&b, "ExecStart=%s", systemdArg(program))- for _, arg := range args {- fmt.Fprintf(&b, " %s", systemdArg(arg))- }- b.WriteString("\n")- b.WriteString("StandardOutput=journal\n")- b.WriteString("StandardError=journal\n")- if !userMode {- // System mode writes /var/log/beacon-agent, which root owns.- b.WriteString("User=root\n")- }- return b.String()+ return jobServiceUnit(inventorySpec, program, args, userMode, env)}-// inventoryTimerUnit schedules the job: shortly after the timer starts (so enabling it after-// boot fires at once), then every interval. Persistent=true runs a firing missed while asleep.-func inventoryTimerUnit(interval time.Duration) string {- return fmt.Sprintf(`[Unit]-Description=Beacon endpoint inventory heartbeat--[Timer]-OnBootSec=2min-OnUnitActiveSec=%ds-Persistent=true-Unit=%s--[Install]-WantedBy=timers.target-`, int(interval.Seconds()), InventoryServiceUnit)-}+func inventoryTimerUnit(interval time.Duration) string { return jobTimerUnit(inventorySpec, interval) }-// inventoryPlist renders the launchd job: one shot at load, then every interval. No KeepAlive,-// so launchd does not restart a job that exited normally.func inventoryPlist(label, program string, args []string, interval time.Duration, stdoutPath, stderrPath string, env map[string]string) string {- var argv strings.Builder- fmt.Fprintf(&argv, " <string>%s</string>\n", xmlEscape(program))- for _, arg := range args {- fmt.Fprintf(&argv, " <string>%s</string>\n", xmlEscape(arg))- }- var envBlock strings.Builder- if len(env) > 0 {- envBlock.WriteString(" <key>EnvironmentVariables</key>\n <dict>\n")- for _, key := range slices.Sorted(maps.Keys(env)) {- fmt.Fprintf(&envBlock, " <key>%s</key>\n <string>%s</string>\n", xmlEscape(key), xmlEscape(env[key]))- }- envBlock.WriteString(" </dict>\n")- }- return fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?>-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">-<plist version="1.0">-<dict>- <key>Label</key>- <string>%s</string>- <key>ProgramArguments</key>- <array>-%s </array>-%s <key>RunAtLoad</key>- <true/>- <key>StartInterval</key>- <integer>%d</integer>- <key>StandardOutPath</key>- <string>%s</string>- <key>StandardErrorPath</key>- <string>%s</string>-</dict>-</plist>-`, xmlEscape(label), argv.String(), envBlock.String(), int(interval.Seconds()), xmlEscape(stdoutPath), xmlEscape(stderrPath))+ return jobPlist(label, program, args, interval, inventorySpec.runAtLoad, stdoutPath, stderrPath, env)}diff --git a/cli/beacon/internal/endpoint/service/scheduled_job.go b/cli/beacon/internal/endpoint/service/scheduled_job.gonew file mode 100644index 00000000..8f547e49--- /dev/null+++ b/cli/beacon/internal/endpoint/service/scheduled_job.go@@ -0,0 +1,360 @@+package service++import (+ "fmt"+ "maps"+ "os"+ "path/filepath"+ "runtime"+ "slices"+ "strconv"+ "strings"+ "time"+)++// jobSpec names one scheduled one-shot job: what launchd and systemd call it, what it runs, and+// how often. The inventory heartbeat and the session sync are both one of these; everything else+// about installing, loading and reporting them is shared.+type jobSpec struct {+ // label is the launchd label: a LaunchAgent in user mode, a LaunchDaemon in system mode.+ label string+ // serviceUnit and timerUnit are the systemd pair; systemd splits what to run from when.+ serviceUnit string+ timerUnit string+ // description is the systemd Description ("Beacon endpoint <description>").+ description string+ // name is how messages refer to the job, for example "scheduled inventory job".+ name string+ // docs is the systemd Documentation URL.+ docs string+ // manualHint is what UnsupportedReason tells someone on a host with no scheduler to run instead.+ manualHint string+ // interval is how often the job runs.+ interval func() time.Duration+ // runAtLoad fires the job once when it is loaded (install, boot, package upgrade) as well as+ // every interval. Without it the first run is one interval after loading.+ runAtLoad bool+ // args is the argument vector after the program, for this mode and runtime log.+ args func(userMode bool, logPath string) []string+}++// intervalFromEnv reads a positive number of seconds from env, falling back to def.+func intervalFromEnv(env string, def time.Duration) time.Duration {+ if raw := strings.TrimSpace(os.Getenv(env)); raw != "" {+ if secs, err := strconv.Atoi(raw); err == nil && secs > 0 {+ return time.Duration(secs) * time.Second+ }+ }+ return def+}++// scheduledJob is one jobSpec installed in one mode. It is a one-shot job on a timer, like the+// updater, but it exists in both user and system modes, like the forwarder.+//+// The job runs every interval, and with spec.runAtLoad also once when loaded (install, boot,+// package upgrade). There is no jitter: launchd measures StartInterval from the moment the job was+// loaded, and systemd's OnUnitActiveSec from the last run, so a fleet installed at different times+// is naturally staggered.+type scheduledJob struct {+ spec jobSpec+ userMode bool+ kind Kind+ // env is set in the job's environment. launchd and systemd start the job without the+ // installing user's shell environment, so anything the job reads from it has to be written+ // into the unit.+ env map[string]string+}++func (m scheduledJob) resolvedKind() Kind {+ if m.kind != KindAuto {+ return m.kind+ }+ return DetectKind()+}++// Supported reports whether the scheduled job can be installed here.+//+// Supervised mode has no scheduler, so there is deliberately no fallback: a timer that silently+// never fires would be worse than refusing to install one.+func (m scheduledJob) Supported() bool {+ switch m.resolvedKind() {+ case KindLaunchd:+ return runtime.GOOS == "darwin"+ case KindSystemd:+ return systemdIsInit()+ default:+ return false+ }+}++// UnsupportedReason explains why Supported is false.+func (m scheduledJob) UnsupportedReason() string {+ switch m.resolvedKind() {+ case KindLaunchd:+ return "launchd service management is supported only on macOS"+ case KindSystemd:+ return "systemd is not PID 1 on this host, so the " + m.spec.name + " cannot be installed"+ default:+ return "the " + m.spec.name + " needs launchd or systemd; a supervised collector has no scheduler. " + m.spec.manualHint+ }+}++// Label is the service identifier for status output.+func (m scheduledJob) Label() string {+ if m.resolvedKind() == KindSystemd {+ return m.spec.timerUnit+ }+ return m.spec.label+}++// UnitPath returns where the job's service definition lives. On systemd this is the timer,+// since that is the unit an administrator enables and inspects.+func (m scheduledJob) UnitPath() (string, error) {+ switch m.resolvedKind() {+ case KindSystemd:+ if m.userMode {+ home, err := os.UserHomeDir()+ if err != nil {+ return "", err+ }+ return filepath.Join(home, ".config", "systemd", "user", m.spec.timerUnit), nil+ }+ return filepath.Join("/etc/systemd/system", m.spec.timerUnit), nil+ default:+ if m.userMode {+ home, err := os.UserHomeDir()+ if err != nil {+ return "", err+ }+ return filepath.Join(home, "Library", "LaunchAgents", m.spec.label+".plist"), nil+ }+ return filepath.Join("/Library/LaunchDaemons", m.spec.label+".plist"), nil+ }+}++// UnitPaths returns every file WriteUnit installs: the timer and the oneshot service on systemd,+// the plist on launchd. Removal sites must use this, not UnitPath, or the service unit is left+// behind (the updater made exactly that mistake).+func (m scheduledJob) UnitPaths() []string {+ path, err := m.UnitPath()+ if err != nil {+ return nil+ }+ if m.resolvedKind() == KindSystemd {+ return []string{path, filepath.Join(filepath.Dir(path), m.spec.serviceUnit)}+ }+ return []string{path}+}++// RemoveUnits deletes every file WriteUnit installed. Missing files are not an error.+func (m scheduledJob) RemoveUnits() {+ for _, path := range m.UnitPaths() {+ _ = os.Remove(path)+ }+}++// WriteUnit installs the job definition that runs program with the spec's arguments for this+// mode. logPath, when set, pins the runtime log; empty means the mode's default.+func (m scheduledJob) WriteUnit(program, logPath string) (string, error) {+ if !m.Supported() {+ return "", fmt.Errorf("%s", m.UnsupportedReason())+ }+ path, err := m.UnitPath()+ if err != nil {+ return "", err+ }+ if err := ensureDir(path); err != nil {+ return "", err+ }+ args := m.spec.args(m.userMode, logPath)+ if m.resolvedKind() == KindSystemd {+ svc := filepath.Join(filepath.Dir(path), m.spec.serviceUnit)+ if err := os.WriteFile(svc, []byte(jobServiceUnit(m.spec, program, args, m.userMode, m.env)), 0o644); err != nil {+ return "", err+ }+ if err := os.WriteFile(path, []byte(jobTimerUnit(m.spec, m.spec.interval())), 0o644); err != nil {+ return "", err+ }+ if out, err := runSystemctlCommand(systemctlArgs(m.userMode, "daemon-reload")...); err != nil {+ return path, systemctlError(out, err, "daemon-reload")+ }+ return path, nil+ }+ if err := ensureLaunchdLogDir(m.userMode, m.spec.label); err != nil {+ return "", err+ }+ stdout, stderr, err := launchdLogPaths(m.userMode, m.spec.label)+ if err != nil {+ return "", err+ }+ content := jobPlist(m.spec.label, program, args, m.spec.interval(), m.spec.runAtLoad, stdout, stderr, m.env)+ if err := os.WriteFile(path, []byte(content), 0o644); err != nil {+ return "", err+ }+ return path, nil+}++// Load activates the schedule. With spec.runAtLoad, loading fires the job once (RunAtLoad on+// launchd, an already elapsed OnBootSec on systemd). An already-loaded launchd job is+// re-bootstrapped so a rewritten unit takes effect.+func (m scheduledJob) Load() error {+ if !m.Supported() {+ return fmt.Errorf("%s", m.UnsupportedReason())+ }+ if m.resolvedKind() == KindSystemd {+ if out, err := runSystemctlCommand(systemctlArgs(m.userMode, "enable", "--now", m.spec.timerUnit)...); err != nil {+ return systemctlError(out, err, "enable --now "+m.spec.timerUnit)+ }+ return nil+ }+ path, err := m.UnitPath()+ if err != nil {+ return err+ }+ return loadLaunchdJob(serviceDomain(m.userMode), m.spec.label, path)+}++// Unload deactivates the schedule. A missing unit is not an error.+func (m scheduledJob) Unload() error {+ switch m.resolvedKind() {+ case KindSystemd:+ if !systemdIsInit() {+ return nil+ }+ if out, err := runSystemctlCommand(systemctlArgs(m.userMode, "stop", m.spec.timerUnit)...); err != nil && !systemdUnitMissing(out) {+ return systemctlError(out, err, "stop "+m.spec.timerUnit)+ }+ if out, err := runSystemctlCommand(systemctlArgs(m.userMode, "disable", m.spec.timerUnit)...); err != nil && !systemdUnitMissing(out) {+ return systemctlError(out, err, "disable "+m.spec.timerUnit)+ }+ return nil+ case KindLaunchd:+ if runtime.GOOS != "darwin" {+ return nil+ }+ return bootoutLaunchdJob(serviceDomain(m.userMode), m.spec.label)+ default:+ return nil+ }+}++// Status reports whether the schedule is active. For a one-shot job "running" means the timer+// is armed (systemd) or the job is registered with launchd; it does not mean the job is running+// this instant.+func (m scheduledJob) Status() Status {+ kind := m.resolvedKind()+ if !m.Supported() {+ return Status{Label: m.Label(), Kind: string(kind), Message: m.UnsupportedReason()}+ }+ if kind == KindSystemd {+ status := Status{Label: m.spec.timerUnit, Kind: string(KindSystemd)}+ enabledOut, _ := runSystemctlCommand(systemctlArgs(m.userMode, "is-enabled", m.spec.timerUnit)...)+ switch strings.TrimSpace(enabledOut) {+ case "enabled", "enabled-runtime", "static":+ status.Loaded = true+ }+ activeOut, _ := runSystemctlCommand(systemctlArgs(m.userMode, "is-active", m.spec.timerUnit)...)+ status.Running = strings.TrimSpace(activeOut) == "active"+ if status.Running {+ status.Loaded = true+ }+ if !status.Loaded && !status.Running {+ status.Message = m.spec.name + " not installed"+ }+ return status+ }+ status := Status{Label: m.spec.label, Kind: string(KindLaunchd)}+ out, err := runLaunchctlCommand("print", serviceDomain(m.userMode)+"/"+m.spec.label)+ if err != nil {+ status.Message = strings.TrimSpace(out)+ return status+ }+ status.Loaded = true+ status.Running = strings.Contains(out, "state = running") || strings.Contains(out, "pid =")+ return status+}++// jobServiceUnit is the oneshot job the timer triggers.+func jobServiceUnit(spec jobSpec, program string, args []string, userMode bool, env map[string]string) string {+ var b strings.Builder+ b.WriteString("[Unit]\n")+ fmt.Fprintf(&b, "Description=Beacon endpoint %s\n", spec.description)+ fmt.Fprintf(&b, "Documentation=%s\n", spec.docs)+ b.WriteString("\n[Service]\n")+ b.WriteString("Type=oneshot\n")+ for _, key := range slices.Sorted(maps.Keys(env)) {+ fmt.Fprintf(&b, "Environment=%s\n", systemdArg(key+"="+env[key]))+ }+ fmt.Fprintf(&b, "ExecStart=%s", systemdArg(program))+ for _, arg := range args {+ fmt.Fprintf(&b, " %s", systemdArg(arg))+ }+ b.WriteString("\n")+ b.WriteString("StandardOutput=journal\n")+ b.WriteString("StandardError=journal\n")+ if !userMode {+ // System mode writes /var/log/beacon-agent, which root owns.+ b.WriteString("User=root\n")+ }+ return b.String()+}++// jobTimerUnit schedules the job every interval. With spec.runAtLoad the first firing is shortly+// after boot (so enabling the timer after boot fires at once); without it, one interval after the+// timer starts. Persistent=true runs a firing missed while asleep.+func jobTimerUnit(spec jobSpec, interval time.Duration) string {+ first := "OnBootSec=2min"+ if !spec.runAtLoad {+ first = fmt.Sprintf("OnActiveSec=%ds", int(interval.Seconds()))+ }+ return fmt.Sprintf(`[Unit]+Description=Beacon endpoint %s++[Timer]+%s+OnUnitActiveSec=%ds+Persistent=true+Unit=%s++[Install]+WantedBy=timers.target+`, spec.description, first, int(interval.Seconds()), spec.serviceUnit)+}++// jobPlist renders the launchd job: every interval, and with runAtLoad one shot at load too. No+// KeepAlive, so launchd does not restart a job that exited normally.+func jobPlist(label, program string, args []string, interval time.Duration, runAtLoad bool, stdoutPath, stderrPath string, env map[string]string) string {+ var argv strings.Builder+ fmt.Fprintf(&argv, " <string>%s</string>\n", xmlEscape(program))+ for _, arg := range args {+ fmt.Fprintf(&argv, " <string>%s</string>\n", xmlEscape(arg))+ }+ var envBlock strings.Builder+ if len(env) > 0 {+ envBlock.WriteString(" <key>EnvironmentVariables</key>\n <dict>\n")+ for _, key := range slices.Sorted(maps.Keys(env)) {+ fmt.Fprintf(&envBlock, " <key>%s</key>\n <string>%s</string>\n", xmlEscape(key), xmlEscape(env[key]))+ }+ envBlock.WriteString(" </dict>\n")+ }+ return fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?>+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">+<plist version="1.0">+<dict>+ <key>Label</key>+ <string>%s</string>+ <key>ProgramArguments</key>+ <array>+%s </array>+%s <key>RunAtLoad</key>+ <%t/>+ <key>StartInterval</key>+ <integer>%d</integer>+ <key>StandardOutPath</key>+ <string>%s</string>+ <key>StandardErrorPath</key>+ <string>%s</string>+</dict>+</plist>+`, xmlEscape(label), argv.String(), envBlock.String(), runAtLoad, int(interval.Seconds()), xmlEscape(stdoutPath), xmlEscape(stderrPath))+}diff --git a/cli/beacon/internal/endpoint/service/session_sync.go b/cli/beacon/internal/endpoint/service/session_sync.gonew file mode 100644index 00000000..a8b85897--- /dev/null+++ b/cli/beacon/internal/endpoint/service/session_sync.go@@ -0,0 +1,72 @@+package service++import "time"++const (+ // SessionSyncLabel is the launchd label of the scheduled session-store sync job. It is a+ // LaunchAgent for a user-mode endpoint and a LaunchDaemon for a system-mode one.+ SessionSyncLabel = "com.beacon.endpoint.session-sync"+ // SessionSyncServiceUnit and SessionSyncTimerUnit are the systemd equivalents.+ SessionSyncServiceUnit = "beacon-session-sync.service"+ SessionSyncTimerUnit = "beacon-session-sync.timer"++ // SessionSyncIntervalEnv overrides the sync interval, in seconds. It exists for tests and+ // smoke checks; a fleet should run the default.+ SessionSyncIntervalEnv = "BEACON_SESSION_SYNC_INTERVAL_SECONDS"+ defaultSessionSyncInterval = 15 * time.Minute+)++// SessionSyncInterval is how often the scheduled session sync runs.+func SessionSyncInterval() time.Duration {+ return intervalFromEnv(SessionSyncIntervalEnv, defaultSessionSyncInterval)+}++// The session sync does not run at load. An install that turns it on runs its own backfill right+// after loading the job, and a run fired at load would take that sweep's lock first, leaving the+// install to wait for it and then report nothing new; the first scheduled run comes one interval+// later and reads what has changed since.+var sessionSyncSpec = jobSpec{+ label: SessionSyncLabel,+ serviceUnit: SessionSyncServiceUnit,+ timerUnit: SessionSyncTimerUnit,+ description: "session-store sync",+ name: "scheduled session sync job",+ docs: "https://docs.asymptotelabs.ai/cli/endpoint-install#scheduled-session-sync",+ manualHint: "Run `beacon endpoint sessions sync` from your own scheduler.",+ interval: SessionSyncInterval,+ args: sessionSyncJobArgs,+}++// SessionSyncManager manages the opt-in scheduled job that reads the agent runtimes' own session+// stores (Claude Code transcripts, Codex sessions and the rest) into the runtime log, the same+// sweep an install runs once. See scheduledJob for how the job is installed, loaded and reported.+type SessionSyncManager struct {+ UserMode bool+ // Kind selects the backend; the zero value auto-detects.+ Kind Kind+ // Env is set in the job's environment: the store-locating variables a session-store collector+ // reads, which launchd and systemd do not pass from the installing user's shell.+ Env map[string]string+}++func (m SessionSyncManager) job() scheduledJob {+ return scheduledJob{spec: sessionSyncSpec, userMode: m.UserMode, kind: m.Kind, env: m.Env}+}++func (m SessionSyncManager) Supported() bool { return m.job().Supported() }+func (m SessionSyncManager) UnsupportedReason() string { return m.job().UnsupportedReason() }+func (m SessionSyncManager) Label() string { return m.job().Label() }+func (m SessionSyncManager) UnitPath() (string, error) { return m.job().UnitPath() }+func (m SessionSyncManager) UnitPaths() []string { return m.job().UnitPaths() }+func (m SessionSyncManager) RemoveUnits() { m.job().RemoveUnits() }+func (m SessionSyncManager) Load() error { return m.job().Load() }+func (m SessionSyncManager) Unload() error { return m.job().Unload() }+func (m SessionSyncManager) Status() Status { return m.job().Status() }+func (m SessionSyncManager) WriteUnit(program, logPath string) (string, error) {+ return m.job().WriteUnit(program, logPath)+}++// sessionSyncJobArgs is the argument vector the scheduler invokes, after the program itself.+func sessionSyncJobArgs(userMode bool, logPath string) []string {+ return modeJobArgs([]string{"endpoint", "sessions", "sync", "--scheduled"}, userMode, logPath)+}diff --git a/cli/beacon/internal/endpoint/service/session_sync_test.go b/cli/beacon/internal/endpoint/service/session_sync_test.gonew file mode 100644index 00000000..4c2a3f77--- /dev/null+++ b/cli/beacon/internal/endpoint/service/session_sync_test.go@@ -0,0 +1,66 @@+package service++import (+ "path/filepath"+ "strings"+ "testing"+ "time"+)++func TestSessionSyncUnitsRunTheScheduledSweep(t *testing.T) {+ args := sessionSyncJobArgs(false, "")+ if got := strings.Join(args, " "); got != "endpoint sessions sync --scheduled --system" {+ t.Fatalf("args = %q", got)+ }+ if got := strings.Join(sessionSyncJobArgs(true, "/u/runtime.jsonl"), " "); got != "endpoint sessions sync --scheduled --user --log-path /u/runtime.jsonl" {+ t.Fatalf("user args = %q", got)+ }++ plist := jobPlist(SessionSyncLabel, "/opt/beacon/bin/beacon", args, 15*time.Minute, sessionSyncSpec.runAtLoad, "/l.out", "/l.err", nil)+ for _, want := range []string{+ "<string>com.beacon.endpoint.session-sync</string>",+ "<string>endpoint</string>\n <string>sessions</string>\n <string>sync</string>\n <string>--scheduled</string>\n <string>--system</string>",+ "<key>RunAtLoad</key>\n <false/>",+ "<key>StartInterval</key>\n <integer>900</integer>",+ } {+ if !strings.Contains(plist, want) {+ t.Fatalf("plist missing %q:\n%s", want, plist)+ }+ }+ if strings.Contains(plist, "KeepAlive") {+ t.Fatalf("a one-shot job must not be kept alive:\n%s", plist)+ }++ svc := jobServiceUnit(sessionSyncSpec, "/opt/beacon/bin/beacon", args, false, nil)+ for _, want := range []string{"Description=Beacon endpoint session-store sync", "Type=oneshot", `ExecStart="/opt/beacon/bin/beacon" "endpoint" "sessions" "sync" "--scheduled" "--system"`, "User=root"} {+ if !strings.Contains(svc, want) {+ t.Fatalf("service unit missing %q:\n%s", want, svc)+ }+ }+ timer := jobTimerUnit(sessionSyncSpec, SessionSyncInterval())+ if !strings.Contains(timer, "OnActiveSec=900s") || strings.Contains(timer, "OnBootSec") ||+ !strings.Contains(timer, "OnUnitActiveSec=900s") || !strings.Contains(timer, "Unit=beacon-session-sync.service") {+ t.Fatalf("timer = %s", timer)+ }+}++func TestSessionSyncIntervalOverride(t *testing.T) {+ t.Setenv(SessionSyncIntervalEnv, "60")+ if got := SessionSyncInterval(); got != time.Minute {+ t.Fatalf("interval = %s", got)+ }+ t.Setenv(SessionSyncIntervalEnv, "nonsense")+ if got := SessionSyncInterval(); got != 15*time.Minute {+ t.Fatalf("interval = %s, want the default on a bad value", got)+ }+}++func TestSessionSyncAndInventoryJobsDoNotCollide(t *testing.T) {+ if sessionSyncSpec.label == inventorySpec.label || sessionSyncSpec.timerUnit == inventorySpec.timerUnit || sessionSyncSpec.serviceUnit == inventorySpec.serviceUnit {+ t.Fatal("the session sync job reuses an inventory job name")+ }+ m := SessionSyncManager{UserMode: false, Kind: KindLaunchd}+ if path, err := m.UnitPath(); err != nil || filepath.ToSlash(path) != "/Library/LaunchDaemons/com.beacon.endpoint.session-sync.plist" {+ t.Fatalf("unit path = %q, %v", path, err)+ }+}diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdxindex 6ca50513..d23f7f46 100644--- a/docs/changelog/cli.mdx+++ b/docs/changelog/cli.mdx@@ -11,6 +11,7 @@ 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).- **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).- **Inherited per-signal OTLP settings no longer divert Claude telemetry** · An `OTEL_EXPORTER_OTLP_{LOGS,METRICS,TRACES}_ENDPOINT`, protocol or headers setting in the environment or Claude's settings sent Claude's telemetry past Beacon's collector, in `beacon ci` and with `beacon endpoint`, which still reported telemetry as enabled. Beacon now overrides them, and `beacon endpoint status` flags one that points elsewhere.diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex 957c77cb..334069c8 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -30,7 +30,7 @@ The `claude` harness writes both Claude Code's OpenTelemetry settings and its us| `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` || `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` || `--health-port <port>` | Local collector health-check port. Defaults to `13133`, moved by the same amount as `--otlp-http-port` when that is changed (HTTP port `4328` gives `13143`), so a second collector on alternate OTLP ports does not collide with the first |-| `--collector <path>` | Path to a `beacon-otelcol` binary |+| `--collector <path>` | Path to a `beacon-otelcol` binary. Without it, Beacon uses the one beside the `beacon` CLI, then one on `PATH` || `--no-start` | Write files without starting the collector service || `--no-browser` | During interactive setup, print the sign-in URL instead of opening a browser, and do not open the hosted dashboard when setup finishes. Useful where no browser can be opened. Open the URL on this machine, or on another computer after forwarding the port it names over SSH || `--service <kind>` | Service manager to use: `auto` (default), `launchd`, `systemd`, or `none` for a supervised collector process |@@ -60,6 +60,8 @@ The `claude` harness writes both Claude Code's OpenTelemetry settings and its us| `--otlp-forward-insecure-skip-verify` | Skip TLS certificate verification for the forward || `--otlp-forward-ca-file <path>` | Optional CA certificate path for the forward's TLS verification || `--no-otlp-forward` | Remove a configured OTLP forward |+| `--session-sync` | Turn on the [scheduled session sync](#scheduled-session-sync): every 15 minutes, read new records from the agent runtimes' local session stores into the runtime log. Kept by repair and package upgrades |+| `--no-session-sync` | Turn the scheduled session sync off and remove its job || `--log-access <mode>` | System log access: `shared` (the default) or `restricted`. See [Restricted log access](#restricted-log-access). Omitted, an install keeps the mode the endpoint already has. System installs on macOS and Linux only || `--no-backfill` | Skip the [session backfill](#session-backfill). `BEACON_BACKFILL=0` does the same || `--connect` | After a successful install, attempt to connect this endpoint to Beacon Cloud ingest. User mode uses the signed-in CLI account; system mode opens browser approval. A connection failure does not roll back or fail the completed local install; verify with `beacon endpoint status --json` and retry with [`beacon endpoint connect`](/cli/endpoint-connect) |@@ -102,6 +104,20 @@ reads the sessions. `--dry-run` installs skip it, and `--no-backfill` or `BEACONoff. If this install also connects to Beacon Cloud, the same history is[uploaded by the connect](/cli/endpoint-connect#session-backfill).+## Scheduled session sync++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+```++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.++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.+## Interactive onboarding wizardOn a first interactive install the [onboarding wizard](/cli/endpoint-onboarding)diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdxindex f4c5d0e4..ce59ba93 100644--- a/docs/cli/endpoint-paths.mdx+++ b/docs/cli/endpoint-paths.mdx@@ -41,6 +41,8 @@ The Beacon forwarder started by `beacon endpoint connect` is a second, residentThe 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.+The [scheduled session sync](/cli/endpoint-install#scheduled-session-sync), when turned on with `--session-sync`, is a fourth one-shot unit in the same places: `com.beacon.endpoint.session-sync.plist` on macOS, `beacon-session-sync.timer` plus `beacon-session-sync.service` on Linux. Its lock, `state/session-sweep.lock` under the endpoint base directory, sits beside the session-store cursors. It is not offered in supervised mode either; run `beacon endpoint sessions sync` 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 for the current login session from a copy staged in `$TMPDIR/beacon-launchd-<uid>`, falling back to `/private/tmp/beacon-launchd-<uid>`. The canonical plist stays in `~/Library/LaunchAgents`; automatic loading after logout or restart is not guaranteed for this layout. 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).diff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdxindex 8b1f3f4b..bd96e40d 100644--- a/docs/cli/endpoint-repair.mdx+++ b/docs/cli/endpoint-repair.mdx@@ -28,7 +28,7 @@ On an endpoint connected to Beacon Cloud, repair leaves the forwarder service, t| `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` || `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` || `--health-port <port>` | Local collector health-check port. Defaults to `13133`, moved by the same amount as `--otlp-http-port` when that is changed (HTTP port `4328` gives `13143`), so a second collector on alternate OTLP ports does not collide with the first |-| `--collector <path>` | Path to a `beacon-otelcol` binary |+| `--collector <path>` | Path to a `beacon-otelcol` binary. Without it, Beacon uses the one beside the `beacon` CLI, then one on `PATH` || `--no-start` | Write files without starting the collector service || `--log-access <mode>` | Change the system log's access mode to `shared` or `restricted`. Omitted, repair keeps the current mode. See [Restricted log access](/cli/endpoint-install#restricted-log-access) || `--service <kind>` | Service manager to use: `auto` (default), `launchd`, `systemd`, or `none` for a supervised collector process |@@ -58,6 +58,8 @@ On an endpoint connected to Beacon Cloud, repair leaves the forwarder service, t| `--otlp-forward-insecure-skip-verify` | Skip TLS certificate verification for the forward || `--otlp-forward-ca-file <path>` | Optional CA certificate path for the forward's TLS verification || `--no-otlp-forward` | Remove a configured OTLP forward |+| `--session-sync` | Turn on the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync): every 15 minutes, read new records from the agent runtimes' local session stores into the runtime log. Kept by repair and package upgrades |+| `--no-session-sync` | Turn the scheduled session sync off and remove its job |## Examplesdiff --git a/docs/guides/kandji-otlp-forward-mdm.mdx b/docs/guides/kandji-otlp-forward-mdm.mdxindex 33d6ca00..b0510d51 100644--- a/docs/guides/kandji-otlp-forward-mdm.mdx+++ b/docs/guides/kandji-otlp-forward-mdm.mdx@@ -14,7 +14,7 @@ flowchart LRClaude[Claude Code] -->|OTLP| Collector["Beacon collector<br/>127.0.0.1:4317"]Codex[Codex CLI] -->|OTLP| CollectorHooks[Claude Code / Codex hooks] --> RuntimeLog["runtime.jsonl"]- Sync[Session-file backfill] --> RuntimeLog+ Sync["Session sync<br/>(install backfill, then every 15 min)"] --> RuntimeLogCollector --> RuntimeLogInventoryJob[Inventory job] --> InventoryLog["inventory_state.jsonl"]RuntimeLog --> Vector[Vector GCS forwarder]@@ -25,7 +25,7 @@ flowchart LR| Destination | What it receives | How || --- | --- | --- |-| GCS bucket | Everything Beacon records: Claude Code and Codex OTLP (normalized into Beacon events), hook events (prompts, tools, commands, files, sessions), session-file backfill, and endpoint inventory | The packaged Vector forwarder, `com.beacon.endpoint.gcs-forwarder`, tails the local JSONL logs and uploads them |+| GCS bucket | Everything Beacon records: Claude Code and Codex OTLP (normalized into Beacon events), hook events (prompts, tools, commands, files, sessions), records read from the runtimes' local session files, and endpoint inventory | The packaged Vector forwarder, `com.beacon.endpoint.gcs-forwarder`, tails the local JSONL logs and uploads them || Existing OTLP backend | The Claude Code and Codex OTLP it received before Beacon, with secrets redacted | The collector's OTLP forward |The two are independent: the GCS forwarder reads Beacon's local logs, and the forward runs inside the collector. Either keeps working when the other's destination is down, and repairs and package upgrades keep both.@@ -195,6 +195,7 @@ BEACON=/opt/beacon/bin/beaconargs=(endpoint repair --system--collector /opt/beacon/bin/beacon-otelcol--harness claude,codex+ --session-sync--otlp-forward-endpoint "$OTLP_FORWARD_ENDPOINT"--otlp-forward-protocol "$OTLP_FORWARD_PROTOCOL")for header in ${OTLP_FORWARD_HEADERS[@]+"${OTLP_FORWARD_HEADERS[@]}"}; do@@ -208,6 +209,8 @@ done"$BEACON" endpoint user-config repair-installed --system --harness claude,codex```+`--session-sync` turns on the [scheduled session sync](/cli/endpoint-install#scheduled-session-sync): every 15 minutes a root job reads new records from the logged-in user's Claude Code and Codex session files into the runtime log, so what only those files hold, such as per-request token usage and full assistant replies, reaches GCS too. It is off by default; repairs and upgrades keep it once set.+`beacon endpoint repair` stores the forward in `/Library/Application Support/Beacon/Endpoint/config.json` and renders it into the collector config next to it. Header values are usually credentials, so they go to a root-only file beside it, `otlp-forward-headers.json` (`0600`), and into the collector config, which is also `0600`. `config.json` keeps only the header names and stays readable, because the logged-in user's `beacon` commands read it to find the system log. Package upgrades and later repairs, including the GCS helper's, keep the forward; you do not pass the flags again. To remove it, run `beacon endpoint repair --system --no-otlp-forward`.Flags you may also need:@@ -269,7 +272,7 @@ OTLP_FORWARD_HEADERS=(export BEACON_GCS_BUCKET="<bucket>"export BEACON_GCS_PREFIX="beacon-prod"export BEACON_GCS_STORAGE_CLASS="STANDARD"-export BEACON_VECTOR_READ_FROM="end"+export BEACON_VECTOR_READ_FROM="beginning"export GOOGLE_APPLICATION_CREDENTIALS="/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json"BEACON=/opt/beacon/bin/beacon@@ -281,6 +284,7 @@ test -x "$BEACON" || { echo "Beacon is not installed yet" >&2; exit 1; }args=(endpoint repair --system--collector /opt/beacon/bin/beacon-otelcol--harness claude,codex+ --session-sync--otlp-forward-endpoint "$OTLP_FORWARD_ENDPOINT"--otlp-forward-protocol "$OTLP_FORWARD_PROTOCOL")for header in ${OTLP_FORWARD_HEADERS[@]+"${OTLP_FORWARD_HEADERS[@]}"}; do@@ -315,7 +319,7 @@ The GCS helper (`repair-hooks-and-forwarder.sh`, under `/opt/beacon/jamf` for co- writes and validates `/Library/Application Support/Beacon/Forwarders/gcs-vector.toml` and starts `com.beacon.endpoint.gcs-forwarder`, which uploads the runtime log under `<prefix>/runtime/` and the inventory log under `<prefix>/inventory/`;- repairs the endpoint and installs Claude Code hooks for the logged-in user, keeping the forward from step 1.-Runtime upload starts at the end of the log (`BEACON_VECTOR_READ_FROM=end`), so history from before the forwarder started is not uploaded; inventory starts at the beginning so the first snapshot is not missed. When nobody is logged in, the forwarder is configured but the hook step fails, so the script reports a failure until a user logs in and the next run completes.+Runtime upload starts at the beginning of the log (`BEACON_VECTOR_READ_FROM=beginning`), so the 30-day session backfill the package install wrote reaches GCS as well as everything after it. This applies only the first time the forwarder starts; after that Vector resumes from its checkpoint, so re-running the script uploads nothing twice. Set it to `end` to upload only what is written after the forwarder starts. Inventory always starts at the beginning so the first snapshot is not missed. When nobody is logged in, the forwarder is configured but the hook step fails, so the script reports a failure until a user logs in and the next run completes.## Validate a pilot Macdiff --git a/packaging/linux/nfpm/postinstall.sh b/packaging/linux/nfpm/postinstall.shindex 48157919..7f85d6f9 100755--- a/packaging/linux/nfpm/postinstall.sh+++ b/packaging/linux/nfpm/postinstall.sh@@ -37,6 +37,9 @@ if [ -x /opt/beacon/bin/beacon ]; then# this re-reconcile is idempotent and covers an upgrade that skipped install./opt/beacon/bin/beacon endpoint inventory install-daemon --system >/dev/null 2>&1 || \echo "beacon: scheduled inventory job not configured (endpoint is installed and running)" >&2+ # The scheduled session sync is opt-in (--session-sync); reconciled the same way, kept on upgrade.+ /opt/beacon/bin/beacon endpoint sessions install-daemon --system >/dev/null 2>&1 || \+ echo "beacon: scheduled session sync job not configured (endpoint is installed and running)" >&2fiecho "beacon: endpoint installed. Check it with: beacon endpoint status --system"diff --git a/packaging/linux/smoke-systemd.sh b/packaging/linux/smoke-systemd.shindex 62564a39..a208d332 100755--- a/packaging/linux/smoke-systemd.sh+++ b/packaging/linux/smoke-systemd.sh@@ -113,6 +113,40 @@ after="$(in_container 'systemctl show -p MainPID --value beacon-collector.servic|| fail "Restart=always did not restart the collector (before=$before after=$after)"echo "ok: Restart=always restarted the collector ($before -> $after)"+# The scheduled session sync: opt-in, kept by repair, a timer that does not fire at load (the+# install backfill owns that moment), a unit that runs as root, and a confined sweep of the console+# user's session store that writes each record once.+in_container '/beacon/beacon endpoint repair --system --harness claude --collector /beacon/beacon-otelcol --session-sync' \+ | grep -q 'Scheduled session sync job: /etc/systemd/system/beacon-session-sync.timer' \+ || fail "repair --session-sync did not install the session sync job"+[ "$(in_container 'systemctl is-enabled beacon-session-sync.timer' || true)" = "enabled" ] \+ && [ "$(in_container 'systemctl is-active beacon-session-sync.timer' || true)" = "active" ] \+ || fail "session sync timer is not enabled and active"+in_container "grep -q '^OnActiveSec=900s' /etc/systemd/system/beacon-session-sync.timer && ! grep -q OnBootSec /etc/systemd/system/beacon-session-sync.timer" \+ || fail "session sync timer would fire at load"+[ -z "$(in_container 'systemctl show -p ExecMainStartTimestamp --value beacon-session-sync.service')" ] \+ || fail "session sync ran at load"+in_container "grep -q '\"--scheduled\" \"--system\"' /etc/systemd/system/beacon-session-sync.service && grep -q '^User=root' /etc/systemd/system/beacon-session-sync.service" \+ || fail "session sync service does not run the scheduled system sweep as root"+in_container '/beacon/beacon endpoint status --system' | grep -q 'Session sync: every 15m0s; job loaded=true' \+ || fail "status does not report the session sync job"+in_container 'systemctl start beacon-session-sync.service' || fail "session sync service failed"+[ "$(in_container 'systemctl show -p Result --value beacon-session-sync.service')" = "success" ] \+ || fail "session sync service did not succeed"+echo "ok: session sync timer installed, not fired at load, and its unit runs"++ts="$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"+in_container "useradd -m alice && mkdir -p /home/alice/.claude/projects/-tmp-repo && printf '%s\n' '{\"type\":\"user\",\"message\":{\"role\":\"user\",\"content\":\"hello from alice\"},\"uuid\":\"u1\",\"timestamp\":\"$ts\",\"cwd\":\"/tmp/repo\",\"sessionId\":\"sess-alice\",\"version\":\"2.1.154\"}' > /home/alice/.claude/projects/-tmp-repo/sess-alice.jsonl && chown -R alice:alice /home/alice/.claude" \+ || fail "could not create the console user's session"+in_container 'SUDO_USER=alice /beacon/beacon endpoint sessions sync --system' | grep -q 'Session sync: [1-9][0-9]* events' \+ || fail "system session sync did not read the console user's session"+first="$(in_container 'grep -c sess-alice /var/log/beacon-agent/runtime.jsonl' || true)"+in_container 'SUDO_USER=alice /beacon/beacon endpoint sessions sync --system' >/dev/null || fail "second session sync failed"+second="$(in_container 'grep -c sess-alice /var/log/beacon-agent/runtime.jsonl' || true)"+[ "$first" -gt 0 ] && [ "$first" = "$second" ] \+ || fail "session sync wrote the session $first then $second times; cursors should make the second run read nothing"+echo "ok: session sync read the console user's session once ($first events)"+in_container '/beacon/beacon endpoint doctor --system' >/dev/null 2>&1 \|| echo "note: doctor reported warnings (expected: no agent session ran here)"@@ -132,6 +166,8 @@ in_container 'test ! -f /etc/systemd/system/beacon-collector.service' || fail "uin_container 'test ! -f /etc/beacon/endpoint/config.json' || fail "config survived uninstall"[ "$(in_container 'systemctl is-enabled beacon-collector.service 2>&1' || true)" = "not-found" ] \|| fail "unit still known to systemd after uninstall"+in_container 'test ! -e /etc/systemd/system/beacon-session-sync.timer && test ! -e /etc/systemd/system/beacon-session-sync.service' \+ || fail "session sync units survived uninstall"listed_after="$(in_container 'systemctl list-unit-files beacon-collector.service --no-legend 2>&1' || true)"[ -z "$(printf '%s' "$listed_after" | tr -d '[:space:]')" ] \diff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstallindex 55e90650..f40ba10b 100755--- a/packaging/macos/scripts/postinstall+++ b/packaging/macos/scripts/postinstall@@ -130,6 +130,10 @@ if command -v launchctl >/dev/null 2>&1; then# Non-fatal: the endpoint is installed and collecting either way."${BEACON_BIN:-/opt/beacon/bin/beacon}" endpoint inventory install-daemon --system || \echo "Warning: scheduled inventory job not configured (endpoint is installed and running)" >&2+ # The scheduled session sync is opt-in (`session_sync.enabled`, set with --session-sync). This+ # loads it when on and removes it when off, so an upgrade keeps whatever the endpoint chose.+ "${BEACON_BIN:-/opt/beacon/bin/beacon}" endpoint sessions install-daemon --system || \+ echo "Warning: scheduled session sync job not configured (endpoint is installed and running)" >&2# A connected endpoint's Beacon Cloud forwarder config is re-rendered from this version's pack,# validated, and swapped in with a forwarder restart only when it changed. The install above ran# with --no-start, so it left this to the package. Never enrolls or touches the device key, anddiff --git a/packaging/macos/smoke-endpoint.sh b/packaging/macos/smoke-endpoint.shindex 3adabfd5..f8c004a9 100755--- a/packaging/macos/smoke-endpoint.sh+++ b/packaging/macos/smoke-endpoint.sh@@ -63,6 +63,7 @@ run_beacon endpoint install \--collector "$COLLECTOR_BIN" \--log-path "$LOG_PATH" \--harness claude,codex \+ --session-sync \--otlp-grpc-port 55317 \--otlp-http-port 55318 >"$INSTALL_OUTPUT" 2>&1cat "$INSTALL_OUTPUT"@@ -78,6 +79,18 @@ if ! grep -q -- "--scheduled" "$INVENTORY_PLIST" || ! grep -q -- "$LOG_PATH" "$Iecho "scheduled inventory job must invoke the heartbeat with --scheduled and this install's log path" >&2exit 1fi+# --session-sync writes the opt-in session sync job the same way. Unlike inventory it does not run+# at load, so the install backfill is the only sweep at install time.+SESSION_SYNC_PLIST="$HOME_DIR/Library/LaunchAgents/com.beacon.endpoint.session-sync.plist"+test -f "$SESSION_SYNC_PLIST"+if ! grep -q -- "<string>--scheduled</string>" "$SESSION_SYNC_PLIST" || ! grep -q -- "$LOG_PATH" "$SESSION_SYNC_PLIST"; then+ echo "scheduled session sync job must run the sync with --scheduled and this install's log path" >&2+ exit 1+fi+if ! tr -d ' \n' <"$SESSION_SYNC_PLIST" | grep -q '<key>RunAtLoad</key><false/>'; then+ echo "scheduled session sync job must not run at load" >&2+ exit 1+fitest -f "$LOG_PATH"# A non-interactive install must never ask for an email or record an onboarding@@ -103,6 +116,11 @@ if ! grep -q '^Inventory heartbeat: scheduled every' "$STATUS_OUTPUT"; thencat "$STATUS_OUTPUT" >&2exit 1fi+if ! grep -q '^Session sync: every 15m0s' "$STATUS_OUTPUT"; then+ echo "endpoint status must report the scheduled session sync job" >&2+ cat "$STATUS_OUTPUT" >&2+ exit 1+fiecho "Writing Wazuh validation event..."run_beacon endpoint wazuh validate --user --log-path "$LOG_PATH" >/dev/null@@ -202,6 +220,11 @@ if [ -f "$INVENTORY_PLIST" ]; thenexit 1fiecho "ok: the scheduled inventory job plist was removed"+if [ -f "$SESSION_SYNC_PLIST" ]; then+ echo "scheduled session sync job plist survived uninstall: $SESSION_SYNC_PLIST" >&2+ exit 1+fi+echo "ok: the scheduled session sync job plist was removed"# Deliberately not asked of launchd. This install passes --no-start into a temporary HOME, so no job is# ever bootstrapped -- which means any answer launchctl gave would be about some *other* install of thediff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.shindex 859ffe47..862a315c 100644--- a/packaging/macos/test-endpoint-scripts.sh+++ b/packaging/macos/test-endpoint-scripts.sh@@ -1390,6 +1390,7 @@ for expected in \'endpoint user-config repair-installed --system --harness claude,codex' \'endpoint update install-daemon' \'endpoint inventory install-daemon --system' \+ 'endpoint sessions install-daemon --system' \'endpoint asymptote reconcile --system'doif ! grep -qxF "$expected" "$POSTINSTALL_BEACON_LOG"; thendiff --git a/rules/risky-command/telemetry-or-history-tampering.rule.yaml b/rules/risky-command/telemetry-or-history-tampering.rule.yamlindex 8dfa0b05..6b2f5531 100644--- a/rules/risky-command/telemetry-or-history-tampering.rule.yaml+++ b/rules/risky-command/telemetry-or-history-tampering.rule.yaml@@ -23,10 +23,10 @@ match: >e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?truncate\\b[^;&|\\n#]*[ \\t][\\\"\\x27]?(?:(?:[^\\s;&|\\\"\\x27<>]*/)?(?:\\.beacon(?:/[^\\s;&|\\\"\\x27<>]*)?|runtime\\.jsonl(?:\\.[^\\s;&|\\\"\\x27<>]*)?|var/log/beacon-agent(?:/[^\\s;&|\\\"\\x27<>]*)?)|[^\\s;&|\\\"\\x27<>]*/(?:plugins?|extensions)/beacon(?:-endpoint)?(?:\\.[jt]s|/[^\\s;&|\\\"\\x27<>]*)?|[^\\s;&|\\\"\\x27<>]*/\\.(?:bash_history|zsh_history|sh_history))[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?(?:cat[ \\t]+/dev/null|:|true|(?:echo|printf)(?:[ \\t]+[\\\"\\x27][\\\"\\x27])?)[ \\t]*>[ \\t]*[\\\"\\x27]?(?:(?:[^\\s;&|\\\"\\x27<>]*/)?(?:\\.beacon(?:/[^\\s;&|\\\"\\x27<>]*)?|runtime\\.jsonl(?:\\.[^\\s;&|\\\"\\x27<>]*)?|var/log/beacon-agent(?:/[^\\s;&|\\\"\\x27<>]*)?)|[^\\s;&|\\\"\\x27<>]*/(?:plugins?|extensions)/beacon(?:-endpoint)?(?:\\.[jt]s|/[^\\s;&|\\\"\\x27<>]*)?|[^\\s;&|\\\"\\x27<>]*/\\.(?:bash_history|zsh_history|sh_history))[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?>[ \\t]*[\\\"\\x27]?(?:(?:[^\\s;&|\\\"\\x27<>]*/)?(?:\\.beacon(?:/[^\\s;&|\\\"\\x27<>]*)?|runtime\\.jsonl(?:\\.[^\\s;&|\\\"\\x27<>]*)?|var/log/beacon-agent(?:/[^\\s;&|\\\"\\x27<>]*)?)|[^\\s;&|\\\"\\x27<>]*/(?:plugins?|extensions)/beacon(?:-endpoint)?(?:\\.[jt]s|/[^\\s;&|\\\"\\x27<>]*)?|[^\\s;&|\\\"\\x27<>]*/\\.(?:bash_history|zsh_history|sh_history))[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||- e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?systemctl[ \\t]+(?:--user[ \\t]+)?(?:stop|disable|mask|kill)\\b[^;&|\\n#]*[ \\t][\\\"\\x27]?(?:[^\\s;&|\\\"\\x27]*/)?(?:com\\.beacon\\.endpoint\\.[\\w.*-]+|beacon-(?:collector|otelcol|asymptote-forwarder|inventory|updater)(?:\\.(?:service|timer))?)[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||+ e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?systemctl[ \\t]+(?:--user[ \\t]+)?(?:stop|disable|mask|kill)\\b[^;&|\\n#]*[ \\t][\\\"\\x27]?(?:[^\\s;&|\\\"\\x27]*/)?(?:com\\.beacon\\.endpoint\\.[\\w.*-]+|beacon-(?:collector|otelcol|asymptote-forwarder|inventory|session-sync|updater)(?:\\.(?:service|timer))?)[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?service[ \\t]+beacon-collector[ \\t]+stop(?:[ \\t]|$|[;&|\\n<>#])") ||- e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?launchctl[ \\t]+(?:unload|bootout|remove|stop|kill)\\b[^;&|\\n#]*[ \\t][\\\"\\x27]?(?:[^\\s;&|\\\"\\x27]*/)?(?:com\\.beacon\\.endpoint\\.[\\w.*-]+|beacon-(?:collector|otelcol|asymptote-forwarder|inventory|updater)(?:\\.(?:service|timer))?)[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||- e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?(?:pkill|killall)\\b[^;&|\\n#]*[ \\t][\\\"\\x27]?(?:[^\\s;&|\\\"\\x27]*/)?(?:com\\.beacon\\.endpoint\\.[\\w.*-]+|beacon-(?:collector|otelcol|asymptote-forwarder|inventory|updater)(?:\\.(?:service|timer))?)[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||+ e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?launchctl[ \\t]+(?:unload|bootout|remove|stop|kill)\\b[^;&|\\n#]*[ \\t][\\\"\\x27]?(?:[^\\s;&|\\\"\\x27]*/)?(?:com\\.beacon\\.endpoint\\.[\\w.*-]+|beacon-(?:collector|otelcol|asymptote-forwarder|inventory|session-sync|updater)(?:\\.(?:service|timer))?)[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||+ e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?(?:pkill|killall)\\b[^;&|\\n#]*[ \\t][\\\"\\x27]?(?:[^\\s;&|\\\"\\x27]*/)?(?:com\\.beacon\\.endpoint\\.[\\w.*-]+|beacon-(?:collector|otelcol|asymptote-forwarder|inventory|session-sync|updater)(?:\\.(?:service|timer))?)[\\\"\\x27]?(?:[ \\t]|$|[;&|\\n<>#])") ||e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?beacon[ \\t]+endpoint[ \\t]+(?:uninstall|disconnect|hooks[ \\t]+uninstall)(?:[ \\t]|$|[;&|\\n<>#])") ||e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?history[ \\t]+(?:-c|-w[ \\t]+/dev/null)(?:[ \\t]|$|[;&|\\n<>#])") ||e.command.command.matches("(^|[;&|\\n])[ \\t]*(?:(?:then|do|else)[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*(?:sudo[ \\t]+(?:(?:-[ugCDRTp][ \\t]*(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|--(?:user|group|close-from|chdir|chroot|command-timeout|prompt)(?:=|[ \\t]+)(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+|-[nEHkPSb]+|--(?:non-interactive|preserve-env(?:=[A-Za-z0-9_,]+)?|set-home|reset-timestamp|stdin|background))[ \\t]+)*(?:--[ \\t]+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:(?:[^\\s;&|<>#\\x27\"`]+|\\x27[^\\x27\\n]*\\x27|\"[^\"\\n]*\")+)?[ \\t]+)*)?(?:[^\\s;&|<>#\\x27\"`=]*/)?(?:unset[ \\t]+HISTFILE|(?:export[ \\t]+)?(?:HISTFILE[ \\t]*=[ \\t]*(?:/dev/null|[\\\"\\x27][\\\"\\x27])|(?:HISTSIZE|HISTFILESIZE)[ \\t]*=[ \\t]*0))(?:[ \\t]|$|[;&|\\n<>#])") ||@@ -459,6 +459,18 @@ tests:- event: { action: command.executed }command: { command: "systemctl mask beacon-inventory.timer" }session: { id: s1 }+ - name: stop_session_sync_timer+ verdict: match+ events:+ - event: { action: command.executed }+ command: { command: "systemctl stop beacon-session-sync.timer" }+ session: { id: s1 }+ - name: mask_session_sync_service+ verdict: match+ events:+ - event: { action: command.executed }+ command: { command: "sudo systemctl mask beacon-session-sync.service" }+ session: { id: s1 }- name: stop_inventory_serviceverdict: matchevents: