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
Re-render the Beacon Cloud forwarder config on install, repair and upgrade
Claude0bda3fa94989
diff --git a/CLAUDE.md b/CLAUDE.mdindex 0bb51247..e5c0c289 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -27,7 +27,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc- Beacon is visibility-first endpoint telemetry for local AI agent runtimes, not a hosted policy service or general endpoint protection product.- Preserve the local-only default. The public Beacon build must not require a hosted account, remote policy fetch, hosted dashboard, or external network dependency during normal hook execution, and hooks themselves never touch the network.- `beacon login` is the account-identity channel for interactive users and is required by the interactive `beacon endpoint install` wizard. It uses browser PKCE against beacon.sh and stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory). Signing in alone never starts forwarding. User-mode `beacon endpoint connect` may send that token once to `POST /api/cli/enroll/account` to authorize minting a separate device ingest key, and `beacon mcp token create` may send it to `POST /api/cli/mcp/tokens` (scope `mcp:token:create`, listed on the sign-in page) to mint a personal MCP token that is printed once to stdout and never written to a file, and `beacon share` may send it (scope `traces:write`, also on the sign-in page) to `PUT /v1/traces/{external_id}`, `POST /v1/traces/{external_id}/events/batch` and `GET /v1/traces/{external_id}` on the session's own base URL to upload a shared trace the person chose to publish, as a `beacon.trace.v1` summary and its events (`cli/beacon/internal/account/share.go`; a `bcn_api_` API key from `--key` or `BEACON_API_KEY` may stand in for it, precedence `--key`, then a current sign-in carrying the scope, then the environment). These are explicit, user-initiated requests with redirects refused. Hooks, plugins and background jobs never make them, with one exception: the git pre-push hook, only when the person opted in with `beacon git setup --share-sessions` (public needs confirmation), may make the three share requests during a push the person started, within the hook's budget and never failing the push. Never copy the account token into endpoint config, Vector, hook environments, logs, or command output. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free.-- Beacon Cloud forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, plus the one bounded exception of the session backfill (below), and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. The onboarding wizard preselects Beacon Cloud, and confirming it connects this endpoint in the same command once the local install has succeeded; an endpoint that is already enrolled is never re-enrolled, because enrollment rotates the device key. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, tool descriptions/definitions, retrieval queries/documents, evaluation explanations, agent descriptions, stop sequences, approval/policy reasons, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Every text-shaped event field must be classified in `metadata_fields_test.go` (`metadataOnlyRemoved`, each with its own `del()` in `pack/metadata-transforms.toml`, or `metadataOnlyKept`); a new field fails that test until it is, and `BEACON_TEST_VECTOR_BIN` runs the transform on an event with every field set. Keep the ingest URL `https://`, the wire contract aligned with `beacon-ingest` (`/v1/ingest/{runtime,inventory}` and `/v1/ingest/health`), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only with `BEACON_ORIGIN=cloud`, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there.+- Beacon Cloud forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, plus the one bounded exception of the session backfill (below), and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. The onboarding wizard preselects Beacon Cloud, and confirming it connects this endpoint in the same command once the local install has succeeded; an endpoint that is already enrolled is never re-enrolled, because enrollment rotates the device key. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, tool descriptions/definitions, retrieval queries/documents, evaluation explanations, agent descriptions, stop sequences, approval/policy reasons, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Every text-shaped event field must be classified in `metadata_fields_test.go` (`metadataOnlyRemoved`, each with its own `del()` in `pack/metadata-transforms.toml`, or `metadataOnlyKept`); a new field fails that test until it is, and `BEACON_TEST_VECTOR_BIN` runs the transform on an event with every field set. `vector.toml` is not rendered only at connect: `asymptote.ReconcileForwarder` re-renders it in place for a connected endpoint from the current pack with the enrollment's ingest URL and recorded privacy mode, validates it with the forwarder's own Vector exactly as connect does, atomically replaces it, and restarts the forwarder only when the content changed and the service is loaded. It never enrolls, reads or rewrites the secrets file, makes a network request, or touches `vector-data/` (checkpoints stay, so pack changes must keep source ids and fingerprinting stable), and a rejected config is a warning that keeps the old one; it is a no-op when not connected, after an incomplete connect, without an installed unit, or where `ForwarderManager` is unsupported (supervised mode). `lifecycle.Install` runs it last when services are started (so install, repair and the Linux package upgrade), repair's teardown keeps the forwarder (`UninstallOptions.KeepManagedIngest`) instead of disconnecting it, and the macOS postinstall, which installs with `--no-start`, runs the hidden `beacon endpoint asymptote reconcile --system`. Keep the ingest URL `https://`, the wire contract aligned with `beacon-ingest` (`/v1/ingest/{runtime,inventory}` and `/v1/ingest/health`), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only with `BEACON_ORIGIN=cloud`, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there.- Session backfill (`cli/beacon/cmd/endpoint_backfill.go`; docs in `docs/cli/endpoint-install.mdx#session-backfill` and `docs/cli/endpoint-connect.mdx#session-backfill`): after every successful install (user or system mode), every session-store collector runs once with `CollectOptions.Since` (30 days; `sessionwindow.Recent` keeps those sessions, newest first, and never touches the cursors of the rest) and a shared `writer.Budget` (24 MiB, at most 12 MiB per runtime through `Budget.Sub`; a refused append returns `writer.ErrBudgetSpent`, the collector stops with cursors past only what was written, and a manual sync reads the rest). A new session-store collector takes both fields and joins `endpointBackfillRunners`. Every connect, first or re-connect, user or system, runs the same sweep before enrollment (skipped when install just ran it) and, before the forwarder starts, `asymptote.StageBackfill` copies the window's `harness.collection_method=poll` lines into `cloud-backfill.jsonl` beside the runtime log, which the `beacon_backfill` Vector source (fingerprinted `device_and_inode`, so each atomically restaged copy is a new file) reads from the beginning into the runtime sink through the same privacy transform. Live hook/OTLP/plugin history before the connection point stays local. Re-connects restage, so a resend of already-shipped lines is expected and rests on the deterministic `event.id`; a privacy-mode change clears the checkpoints and the restage renames the new-mode copy over the old one (kept until then so the copy is always a new inode; deleted instead when nothing restages), and `disconnect` removes it. System mode runs the collectors under `withUserHome` for the active console user (`activeConsoleUser`), with cursors under the system base directory, and reports a skip when nobody is logged in. The wizard's confirm screen names the upload (`WizardOptions.BackfillDays`). Dry-run, `--no-backfill` and `BEACON_BACKFILL=0` skip all of it; the cmd tests run with `BEACON_BACKFILL=0` set in `TestMain`.- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Cloud, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Signing in alone still moves no telemetry. Confirming Beacon Cloud does: the confirm screen states that it installs Beacon and starts forwarding, and names what the selected privacy mode sends, so that screen is the consent point. The managed destination is recorded only after enrollment succeeds, so a failed enrollment leaves a working local install, prints `beacon endpoint connect` as the retry, and re-offers the question on the next install. The onboarding record is written only after `lifecycle.Install` returns, because a profile written first left a failed install looking onboarded and silently skipped the wizard on the retry. Explicit `install --connect` is unchanged. The wizard is skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`; those unattended paths must never gain an account or browser dependency. Legacy `BEACON_ONBOARDING_EMAIL`/`USAGE` submissions remain only for fleet compatibility. After the destination, the wizard shows an agent tools screen; every row is preselected (opt-out, space toggles). Beacon Cloud MCP is offered only with Beacon Cloud and runs the `beacon mcp connect` flow (`connectCloudMCP` with `yes`, OAuth, detected harnesses) only after the endpoint is connected (or already was), via `finishCloudSetup`; a failed enrollment skips it and names the retry. The Beacon Agent Skills are offered for either destination and installed user-wide into `~/.agents/skills` and, when Claude Code is set up, `~/.claude/skills` (`cli/beacon/internal/agentskills`, `beacon skills install|uninstall`; a `.beacon-managed` marker decides what Beacon may replace or remove; install and repair refresh only copies Beacon already wrote). Both run after `lifecycle.Install` returns and warn rather than fail. The answers are recorded as `onboarding.cloud_mcp`/`agent_skills`. Implementation lives in `cli/beacon/internal/onboarding`, `cli/beacon/cmd/endpoint_onboarding.go`, `cli/beacon/cmd/endpoint_install.go` and `cli/beacon/cmd/agent_tools.go`; keep `docs/cli/endpoint-onboarding.mdx` and `docs/cli/skills.mdx` in sync.- The update notice on bare interactive `beacon` (`cli/beacon/cmd/root.go`, cache in `cli/beacon/internal/updatecheck/cache.go`; docs in `docs/cli/version.mdx`) follows the Codex/Claude Code pattern: it reads `~/.beacon/endpoint/update-check.json` and never waits on the network, and only when that cache is a day old does it start a detached `beacon version refresh` (hidden) that asks GitHub for the latest release and rewrites the cache, failures included. It is the CLI's one background network call; it never runs from hooks, other commands, non-TTY output, CI or dev builds, and `BEACON_UPDATE_CHECK=0` turns it off. Installs other than Homebrew and the system package get the release download, because `beacon endpoint update` applies only to the system package.@@ -62,7 +62,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.- 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`, 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.+- 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.- Elasticsearch/Filebeat content pack generation for forwarding local Beacon JSONL into customer-managed Elastic deployments or the bundled loopback-only development stack.- A local-only dashboard served by `beacon endpoint dashboard`, bound to loopback by default and backed by the runtime JSONL log.diff --git a/cli/beacon/cmd/endpoint_asymptote_reconcile.go b/cli/beacon/cmd/endpoint_asymptote_reconcile.gonew file mode 100644index 00000000..7cb69280--- /dev/null+++ b/cli/beacon/cmd/endpoint_asymptote_reconcile.go@@ -0,0 +1,74 @@+package cmd++import (+ "encoding/json"+ "fmt"+ "io"++ "github.com/spf13/cobra"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/asymptote"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"+)++// reconcileManagedForwarder is indirected so the command can be tested without a connected+// endpoint or a service manager.+var reconcileManagedForwarder = asymptote.ReconcileForwarder++// addAsymptoteReconcileCommand attaches `beacon endpoint asymptote reconcile`, which the macOS+// package postinstall runs (it installs with --no-start, so Install's own reconcile does not+// run there) and which operators can run by hand. Install and repair reconcile on their own.+func addAsymptoteReconcileCommand(group *cobra.Command) {+ cmd := &cobra.Command{+ Use: "reconcile",+ Short: "Internal: re-render a connected endpoint's Beacon Cloud forwarder config in place",+ Long: `Re-render vector.toml for a connected endpoint from the pack this version carries,+keeping the recorded ingest URL and privacy mode. Vector validates the new config+before it replaces the old one, and the forwarder restarts only when it changed.+Nothing is enrolled, the device key is not touched, and no network request is made.`,+ Hidden: true,+ SilenceUsage: true,+ RunE: runAsymptoteReconcile,+ }+ addEndpointPathFlags(cmd)+ cmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print output as JSON")+ group.AddCommand(cmd)+}++func runAsymptoteReconcile(cmd *cobra.Command, args []string) error {+ userMode := endpointUserMode()+ if !userMode && !lifecycle.HasSystemPrivileges() {+ return fmt.Errorf("reconciling the system forwarder needs elevated privileges; %s", lifecycle.SystemPrivilegeHint())+ }+ logPath := endpointOpts.logPath+ if logPath == "" {+ logPath = loadOrDefaultConfig().LogPath+ }+ result, err := reconcileManagedForwarder(asymptote.ReconcileOptions{UserMode: userMode, LogPath: logPath})+ if endpointOpts.jsonOutput {+ if encodeErr := json.NewEncoder(cmd.OutOrStdout()).Encode(result); encodeErr != nil && err == nil {+ err = encodeErr+ }+ return err+ }+ if err != nil {+ return err+ }+ if message := result.Message(); message != "" {+ fmt.Fprintln(cmd.OutOrStdout(), message)+ }+ return nil+}++// reportManagedForwarder prints the install or repair reconcile outcome when there is something+// to say: an endpoint that is not connected hears nothing about Beacon Cloud.+func reportManagedForwarder(out, errOut io.Writer, result *asymptote.ReconcileResult) {+ if result == nil || result.Skipped != "" || result.Unchanged {+ return+ }+ if result.Warning != "" {+ fmt.Fprintln(errOut, "Warning: "+result.Message())+ return+ }+ fmt.Fprintln(out, result.Message())+}diff --git a/cli/beacon/cmd/endpoint_asymptote_reconcile_test.go b/cli/beacon/cmd/endpoint_asymptote_reconcile_test.gonew file mode 100644index 00000000..9a39e4d6--- /dev/null+++ b/cli/beacon/cmd/endpoint_asymptote_reconcile_test.go@@ -0,0 +1,70 @@+package cmd++import (+ "bytes"+ "strings"+ "testing"++ "github.com/spf13/cobra"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/asymptote"+)++func TestAsymptoteReconcileCommandIsRegisteredAndHidden(t *testing.T) {+ cmd, _, err := rootCmd.Find([]string{"endpoint", "asymptote", "reconcile"})+ if err != nil || cmd == nil || cmd.Name() != "reconcile" {+ t.Fatalf("endpoint asymptote reconcile not found: %v", err)+ }+ if !cmd.Hidden {+ t.Fatal("endpoint asymptote reconcile is an internal command and must stay hidden")+ }+}++func TestAsymptoteReconcileReconcilesTheRequestedMode(t *testing.T) {+ oldOpts := endpointOpts+ oldReconcile := reconcileManagedForwarder+ t.Cleanup(func() {+ endpointOpts = oldOpts+ reconcileManagedForwarder = oldReconcile+ })+ var got asymptote.ReconcileOptions+ reconcileManagedForwarder = func(opts asymptote.ReconcileOptions) (asymptote.ReconcileResult, error) {+ got = opts+ return asymptote.ReconcileResult{VectorConfig: "/fake/vector.toml", Updated: true, Restarted: true}, nil+ }+ endpointOpts.userMode, endpointOpts.systemMode = true, false+ endpointOpts.logPath = "/tmp/scratch/runtime.jsonl"+ endpointOpts.jsonOutput = false+ out := &bytes.Buffer{}+ cmd := &cobra.Command{}+ cmd.SetOut(out)+ if err := runAsymptoteReconcile(cmd, nil); err != nil {+ t.Fatal(err)+ }+ if !got.UserMode || got.LogPath != "/tmp/scratch/runtime.jsonl" {+ t.Fatalf("reconcile options = %+v", got)+ }+ if !strings.Contains(out.String(), "updated and the forwarder restarted") {+ t.Fatalf("output = %q", out.String())+ }+}++func TestReportManagedForwarderStaysQuietUnlessSomethingChanged(t *testing.T) {+ for _, result := range []*asymptote.ReconcileResult{nil, {Skipped: "not connected"}, {Unchanged: true}} {+ out, errOut := &bytes.Buffer{}, &bytes.Buffer{}+ reportManagedForwarder(out, errOut, result)+ if out.Len() != 0 || errOut.Len() != 0 {+ t.Fatalf("result %+v printed %q / %q", result, out.String(), errOut.String())+ }+ }+ out, errOut := &bytes.Buffer{}, &bytes.Buffer{}+ reportManagedForwarder(out, errOut, &asymptote.ReconcileResult{Warning: "kept the existing config because Vector rejected the new one"})+ if out.Len() != 0 || !strings.Contains(errOut.String(), "Warning: Beacon Cloud forwarder: kept the existing config") {+ t.Fatalf("warning printed %q / %q", out.String(), errOut.String())+ }+ out.Reset()+ reportManagedForwarder(out, errOut, &asymptote.ReconcileResult{VectorConfig: "/v.toml", Updated: true, Restarted: true})+ if !strings.Contains(out.String(), "/v.toml") {+ t.Fatalf("update printed %q", out.String())+ }+}diff --git a/cli/beacon/cmd/endpoint_destinations.go b/cli/beacon/cmd/endpoint_destinations.goindex 164cc6af..5d930c90 100644--- a/cli/beacon/cmd/endpoint_destinations.go+++ b/cli/beacon/cmd/endpoint_destinations.go@@ -336,6 +336,7 @@ var siemDestinations = []siemDestination{fmt.Printf("Confirm delivery at %s by searching for \"Beacon endpoint Asymptote validation event\"; forwarded events appear within a minute or two.\n", dashboardHomeURL(""))},},+ extra: addAsymptoteReconcileCommand,},{name: "sentinel",diff --git a/cli/beacon/cmd/endpoint_install.go b/cli/beacon/cmd/endpoint_install.goindex b16d1bef..da4bb933 100644--- a/cli/beacon/cmd/endpoint_install.go+++ b/cli/beacon/cmd/endpoint_install.go@@ -178,6 +178,7 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {case result.InventoryJobDetail != "":fmt.Printf("Scheduled inventory job not installed: %s\n", result.InventoryJobDetail)}+ reportManagedForwarder(os.Stdout, cmd.ErrOrStderr(), result.ManagedForwarder)printLingerGap(cmd.ErrOrStderr(), result)installHookTargetsFromEndpointInstall(cmd.ErrOrStderr(), selection.Hooks)refreshAgentSkills(cmd.ErrOrStderr())@@ -361,6 +362,7 @@ func runEndpointRepair(cmd *cobra.Command, args []string) error {return err}fmt.Printf("Endpoint repaired. Manifest: %s\n", result.ManifestPath)+ reportManagedForwarder(os.Stdout, cmd.ErrOrStderr(), result.ManagedForwarder)printLingerGap(cmd.ErrOrStderr(), result)installHookTargetsFromEndpointInstall(cmd.ErrOrStderr(), selection.Hooks)refreshAgentSkills(cmd.ErrOrStderr())diff --git a/cli/beacon/internal/endpoint/asymptote/reconcile.go b/cli/beacon/internal/endpoint/asymptote/reconcile.gonew file mode 100644index 00000000..3be4ca72--- /dev/null+++ b/cli/beacon/internal/endpoint/asymptote/reconcile.go@@ -0,0 +1,193 @@+package asymptote++import (+ "bytes"+ "fmt"+ "os"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/managedprivacy"+)++// ReconcileOptions drives ReconcileForwarder.+type ReconcileOptions struct {+ UserMode bool+ // LogPath is the runtime log the forwarder tails. Empty uses config.json's, then the mode's+ // default, which is what connect renders.+ LogPath string+ // Forwarder overrides the service manager; nil uses service.ForwarderManager.+ Forwarder Forwarder+}++// ReconcileResult reports what ReconcileForwarder did.+type ReconcileResult struct {+ VectorConfig string `json:"vector_config,omitempty"`+ PrivacyMode string `json:"privacy_mode,omitempty"`+ // Skipped names why nothing was checked: the endpoint is not connected, the forwarder is not+ // installed, or the service manager cannot run it here.+ Skipped string `json:"skipped,omitempty"`+ // Unchanged is true when the rendered config already matched the one on disk.+ Unchanged bool `json:"unchanged,omitempty"`+ // Updated is true when a validated config replaced the old one.+ Updated bool `json:"updated,omitempty"`+ // Restarted is true when the forwarder was restarted to load the updated config.+ Restarted bool `json:"restarted,omitempty"`+ // Warning says why a connected forwarder kept its old config, or why an updated one was not+ // restarted. The old config stays in place and keeps running in either case.+ Warning string `json:"warning,omitempty"`+}++// Message is a one-line description of the outcome for install, repair and the package scripts.+func (r ReconcileResult) Message() string {+ switch {+ case r.Warning != "":+ return "Beacon Cloud forwarder: " + r.Warning+ case r.Updated && r.Restarted:+ return "Beacon Cloud forwarder config updated and the forwarder restarted (" + r.VectorConfig + ")."+ case r.Updated:+ return "Beacon Cloud forwarder config updated (" + r.VectorConfig + "); it takes effect when the forwarder next starts."+ case r.Unchanged:+ return "Beacon Cloud forwarder config is current."+ case r.Skipped != "":+ return "Beacon Cloud forwarder not reconciled: " + r.Skipped+ }+ return ""+}++// ReconcileForwarder re-renders a connected endpoint's vector.toml from the pack this binary+// carries, so a pack fix (such as a Metadata-only transform that strips more fields) reaches an+// endpoint that was connected by an older version without a re-connect, which would rotate the+// device key. Install, repair and the package upgrade call it.+//+// It uses only what connect recorded: the enrollment's ingest URL, its privacy mode (changing+// the mode is a connect-time decision, because connect clears the buffer when it does), and the+// endpoint's runtime log. It never enrolls, never reads the device key or rewrites the secrets+// file, makes no network request, and leaves the Vector data directory and its checkpoints+// alone. The new config is validated by Vector exactly as connect validates it before it+// replaces the old one, and the forwarder is restarted only when the content changed. A config+// Vector rejects is reported as a warning and the running forwarder keeps the old one.+//+// The returned error is reserved for a failure that leaves something to fix by hand (the+// validated config could not be written); every reason to leave a working forwarder alone is a+// Skipped or Warning result.+func ReconcileForwarder(opts ReconcileOptions) (ReconcileResult, error) {+ var result ReconcileResult+ // Not connected comes first, before the service manager is asked anything: most endpoints+ // are local-only and this runs on every install.+ if !Connected(opts.UserMode) {+ result.Skipped = "not connected"+ return result, nil+ }+ manager := opts.Forwarder+ if manager == nil {+ manager = service.ForwarderManager{UserMode: opts.UserMode}+ }+ if !manager.Supported() {+ result.Skipped = manager.UnsupportedReason()+ return result, nil+ }+ if unitPath, err := manager.UnitPath(); err != nil || unitPath == "" {+ result.Skipped = "forwarder service is not installed"+ return result, nil+ } else if _, err := os.Stat(unitPath); err != nil {+ result.Skipped = "forwarder service is not installed (" + unitPath + ")"+ return result, nil+ }+ configPath := VectorConfigPath(opts.UserMode)+ result.VectorConfig = configPath++ enrollment, err := LoadEnrollment(opts.UserMode)+ if err != nil {+ result.Warning = fmt.Sprintf("kept the existing config: %v", err)+ return result, nil+ }+ if !IsSecureURL(enrollment.IngestURL) {+ result.Warning = "kept the existing config: the enrollment record has no usable ingest URL; run `beacon endpoint connect` to repair it"+ return result, nil+ }+ privacyMode, err := managedprivacy.Normalize(enrollment.PrivacyMode)+ if err != nil {+ result.Warning = fmt.Sprintf("kept the existing config: the enrollment record's privacy mode is not valid: %v", err)+ return result, nil+ }+ cfg, cfgErr := endpointconfig.Load(opts.UserMode)+ if cfgErr == nil && cfg.ManagedIngest != nil && cfg.ManagedIngest.PrivacyMode != "" {+ recorded, err := managedprivacy.Normalize(cfg.ManagedIngest.PrivacyMode)+ if err != nil || recorded != privacyMode {+ // Two records that disagree are not ours to settle: the mode decides what leaves the+ // machine, and choosing it is connect's job.+ result.Warning = fmt.Sprintf("kept the existing config: config.json records privacy mode %q but the enrollment records %q; run `beacon endpoint connect --privacy-mode <mode>` to choose one", cfg.ManagedIngest.PrivacyMode, enrollment.PrivacyMode)+ return result, nil+ }+ }+ result.PrivacyMode = privacyMode+ logPath := opts.LogPath+ if logPath == "" && cfgErr == nil {+ logPath = cfg.LogPath+ }+ if logPath == "" {+ logPath = endpointconfig.Default(opts.UserMode, "").LogPath+ }++ // Validate with the Vector the service runs. A recorded binary that has gone means the+ // forwarder is already broken, and a different Vector proving the config would prove nothing.+ if enrollment.VectorBin != "" {+ if _, err := os.Stat(enrollment.VectorBin); err != nil {+ result.Warning = fmt.Sprintf("kept the existing config: the forwarder's Vector %s is missing; reinstall Beacon or run `beacon endpoint connect`", enrollment.VectorBin)+ return result, nil+ }+ }+ vector, err := FindVector(enrollment.VectorBin)+ if err != nil {+ result.Warning = fmt.Sprintf("kept the existing config: %v", err)+ return result, nil+ }++ dataDir := DataDir(opts.UserMode)+ rendered, err := RenderVectorConfig(RenderOptions{+ LogPath: logPath,+ IngestURL: enrollment.IngestURL,+ SecretsFile: SecretsPath(opts.UserMode),+ DataDir: dataDir,+ PrivacyMode: privacyMode,+ })+ if err != nil {+ result.Warning = fmt.Sprintf("kept the existing config: %v", err)+ return result, nil+ }+ current, err := os.ReadFile(configPath)+ if err != nil {+ result.Warning = fmt.Sprintf("kept the existing config: %v", err)+ return result, nil+ }+ if bytes.Equal(current, []byte(rendered)) {+ result.Unchanged = true+ return result, nil+ }+ // Vector refuses a data_dir that does not exist. Creating a missing one loses nothing: its+ // checkpoints were already gone. An existing one is never cleared here.+ if err := os.MkdirAll(dataDir, 0o700); err != nil {+ result.Warning = fmt.Sprintf("kept the existing config: %v", err)+ return result, nil+ }+ if err := preValidateVectorConfig(vector.Path, configPath, []byte(rendered)); err != nil {+ result.Warning = fmt.Sprintf("kept the existing config because Vector rejected the new one: %v", err)+ return result, nil+ }+ if err := writeFileAtomic(configPath, []byte(rendered), 0o644); err != nil {+ return result, fmt.Errorf("could not write the validated forwarder config %s: %w", configPath, err)+ }+ result.Updated = true+ // Restart only a forwarder that is registered, so reconcile never starts one an operator+ // stopped. An unregistered one picks the new config up when it is next started.+ if !manager.Status().Loaded {+ return result, nil+ }+ if err := manager.Load(); err != nil {+ result.Warning = fmt.Sprintf("config updated (%s) but the forwarder could not be restarted: %v", configPath, err)+ return result, nil+ }+ result.Restarted = true+ return result, nil+}diff --git a/cli/beacon/internal/endpoint/asymptote/reconcile_test.go b/cli/beacon/internal/endpoint/asymptote/reconcile_test.gonew file mode 100644index 00000000..1a56ecb0--- /dev/null+++ b/cli/beacon/internal/endpoint/asymptote/reconcile_test.go@@ -0,0 +1,322 @@+package asymptote++import (+ "bytes"+ "context"+ "os"+ "path/filepath"+ "strings"+ "testing"+ "time"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/managedprivacy"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// reconcileFixture is an endpoint connected by a successful Connect, with a forwarder whose unit+// file exists, a checkpoint in Vector's data directory, and the enrollment server shut down so+// any network request a reconcile made would fail.+type reconcileFixture struct {+ fwd *fakeForwarder+ vector string+ secrets []byte+ secretsMod time.Time+ checkpoint string+}++func newReconcileFixture(t *testing.T, privacyMode string) *reconcileFixture {+ t.Helper()+ testenv.SetHome(t, t.TempDir())+ isolateVectorDiscovery(t)+ fd := newFakeDashboard(t)+ fwd := &fakeForwarder{supported: true, unitPath: filepath.Join(t.TempDir(), "forwarder.plist")}+ vector := fakeVector(t, "0.56.0", 0)+ opts := connectOptions(t, fd, fwd, vector)+ opts.PrivacyMode = privacyMode+ if _, err := Connect(context.Background(), opts); err != nil {+ t.Fatalf("connect: %v", err)+ }+ fd.server.Close()+ checkpoint := filepath.Join(DataDir(true), "beacon_runtime", "checkpoints.json")+ if err := os.MkdirAll(filepath.Dir(checkpoint), 0o700); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(checkpoint, []byte(`{"checkpoints":[{"fingerprint":{"device_and_inode":[1,2]},"position":42}]}`), 0o600); err != nil {+ t.Fatal(err)+ }+ secrets, err := os.ReadFile(SecretsPath(true))+ if err != nil {+ t.Fatal(err)+ }+ info, err := os.Stat(SecretsPath(true))+ if err != nil {+ t.Fatal(err)+ }+ return &reconcileFixture{fwd: fwd, vector: vector, secrets: secrets, secretsMod: info.ModTime(), checkpoint: checkpoint}+}++// assertCredentialsAndCheckpointsUntouched pins what a reconcile must never change.+func (f *reconcileFixture) assertCredentialsAndCheckpointsUntouched(t *testing.T) {+ t.Helper()+ secrets, err := os.ReadFile(SecretsPath(true))+ if err != nil || !bytes.Equal(secrets, f.secrets) {+ t.Fatalf("the secrets file changed: %v", err)+ }+ if info, err := os.Stat(SecretsPath(true)); err != nil || !info.ModTime().Equal(f.secretsMod) {+ t.Fatalf("the secrets file was rewritten: %v", err)+ }+ if data, err := os.ReadFile(f.checkpoint); err != nil || !strings.Contains(string(data), `"position":42`) {+ t.Fatalf("Vector's checkpoints were reset: %q %v", data, err)+ }+ if ConnectIncomplete(true) || !Connected(true) {+ t.Fatal("a reconcile must leave the endpoint connected")+ }+}++// staleTransform stands in for vector.toml as an older version rendered it: the Metadata-only+// transform before it stripped every content field.+func writeStaleConfig(t *testing.T) []byte {+ t.Helper()+ current, err := os.ReadFile(VectorConfigPath(true))+ if err != nil {+ t.Fatal(err)+ }+ stale := bytes.Replace(current, []byte("[transforms.beacon_runtime_metadata]"), []byte("# stale pack\n[transforms.beacon_runtime_metadata]"), 1)+ if bytes.Equal(stale, current) {+ t.Fatal("fixture: the rendered config has no Metadata-only transform to make stale")+ }+ if err := os.WriteFile(VectorConfigPath(true), stale, 0o644); err != nil {+ t.Fatal(err)+ }+ return stale+}++func expectedRender(t *testing.T, privacyMode string) string {+ t.Helper()+ enrollment, err := LoadEnrollment(true)+ if err != nil {+ t.Fatal(err)+ }+ cfg, err := endpointconfig.Load(true)+ if err != nil {+ t.Fatal(err)+ }+ rendered, err := RenderVectorConfig(RenderOptions{+ LogPath: cfg.LogPath,+ IngestURL: enrollment.IngestURL,+ SecretsFile: SecretsPath(true),+ DataDir: DataDir(true),+ PrivacyMode: privacyMode,+ })+ if err != nil {+ t.Fatal(err)+ }+ return rendered+}++func TestReconcileReplacesAStaleTransformAndRestartsTheForwarder(t *testing.T) {+ f := newReconcileFixture(t, "metadata-only")+ writeStaleConfig(t)+ loads, unloads := f.fwd.loads, f.fwd.unloads++ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if !result.Updated || !result.Restarted || result.Warning != "" {+ t.Fatalf("result = %+v, want updated and restarted", result)+ }+ if result.PrivacyMode != managedprivacy.MetadataOnly {+ t.Fatalf("privacy mode = %q, want the recorded metadata_only", result.PrivacyMode)+ }+ got, _ := os.ReadFile(VectorConfigPath(true))+ if string(got) != expectedRender(t, managedprivacy.MetadataOnly) {+ t.Fatal("vector.toml is not the current pack's Metadata-only render")+ }+ if info, err := os.Stat(VectorConfigPath(true)); err != nil || (testenv.HasPOSIXFileModes() && info.Mode().Perm() != 0o644) {+ t.Fatalf("vector.toml mode: %v %v", info, err)+ }+ if f.fwd.loads != loads+1 || f.fwd.unloads != unloads {+ t.Fatalf("forwarder loads %d->%d unloads %d->%d, want exactly one restart", loads, f.fwd.loads, unloads, f.fwd.unloads)+ }+ if strings.Contains(string(got), "bcn_device") {+ t.Fatal("the rendered config carries the device key")+ }+ f.assertCredentialsAndCheckpointsUntouched(t)+ leftovers, _ := filepath.Glob(filepath.Join(Dir(true), ".vector-*"))+ if len(leftovers) != 0 {+ t.Fatalf("reconcile left temporary files: %v", leftovers)+ }+}++func TestReconcileLeavesACurrentConfigAndTheForwarderAlone(t *testing.T) {+ f := newReconcileFixture(t, "standard")+ before, _ := os.ReadFile(VectorConfigPath(true))+ beforeInfo, _ := os.Stat(VectorConfigPath(true))+ loads, unloads := f.fwd.loads, f.fwd.unloads++ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if !result.Unchanged || result.Updated || result.Restarted {+ t.Fatalf("result = %+v, want unchanged", result)+ }+ after, _ := os.ReadFile(VectorConfigPath(true))+ afterInfo, _ := os.Stat(VectorConfigPath(true))+ if !bytes.Equal(before, after) || !afterInfo.ModTime().Equal(beforeInfo.ModTime()) {+ t.Fatal("an unchanged config was rewritten")+ }+ if f.fwd.loads != loads || f.fwd.unloads != unloads {+ t.Fatal("an unchanged config restarted the forwarder")+ }+ f.assertCredentialsAndCheckpointsUntouched(t)+}++func TestReconcileKeepsTheOldConfigWhenVectorRejectsTheNewOne(t *testing.T) {+ f := newReconcileFixture(t, "metadata-only")+ stale := writeStaleConfig(t)+ // The forwarder's own Vector now refuses every config.+ enrollment, err := LoadEnrollment(true)+ if err != nil {+ t.Fatal(err)+ }+ enrollment.VectorBin = fakeVector(t, "0.56.0", 78)+ if err := SaveEnrollment(true, *enrollment); err != nil {+ t.Fatal(err)+ }+ loads := f.fwd.loads++ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if result.Updated || result.Restarted || !strings.Contains(result.Warning, "Vector rejected") {+ t.Fatalf("result = %+v, want a kept config with a warning", result)+ }+ got, _ := os.ReadFile(VectorConfigPath(true))+ if !bytes.Equal(got, stale) {+ t.Fatal("a rejected render replaced the running config")+ }+ if f.fwd.loads != loads {+ t.Fatal("a rejected render restarted the forwarder")+ }+ f.assertCredentialsAndCheckpointsUntouched(t)+ leftovers, _ := filepath.Glob(filepath.Join(Dir(true), ".vector-*"))+ if len(leftovers) != 0 {+ t.Fatalf("reconcile left temporary files: %v", leftovers)+ }+}++func TestReconcileIsANoOpWhenNotConnected(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ isolateVectorDiscovery(t)+ fwd := &fakeForwarder{supported: true}+ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: fwd})+ if err != nil {+ t.Fatal(err)+ }+ if result.Skipped == "" || result.Updated || result.Warning != "" {+ t.Fatalf("result = %+v, want skipped", result)+ }+ if fwd.loads != 0 || fwd.unloads != 0 || len(fwd.written) != 0 {+ t.Fatal("a reconcile on an endpoint that is not connected touched the service manager")+ }+ if _, err := os.Stat(Dir(true)); !os.IsNotExist(err) {+ t.Fatalf("a reconcile on an endpoint that is not connected created %s", Dir(true))+ }+}++func TestReconcileSkipsAnIncompleteConnect(t *testing.T) {+ f := newReconcileFixture(t, "metadata-only")+ stale := writeStaleConfig(t)+ if err := markConnectPending(true, time.Now(), true); err != nil {+ t.Fatal(err)+ }+ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if result.Skipped == "" || result.Updated {+ t.Fatalf("result = %+v, want skipped", result)+ }+ if got, _ := os.ReadFile(VectorConfigPath(true)); !bytes.Equal(got, stale) {+ t.Fatal("an incomplete connect's config was rewritten")+ }+}++func TestReconcileSkipsWhenTheServiceManagerCannotRunTheForwarder(t *testing.T) {+ f := newReconcileFixture(t, "metadata-only")+ stale := writeStaleConfig(t)+ f.fwd.supported = false+ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if result.Skipped != "fake forwarder unsupported" || result.Updated {+ t.Fatalf("result = %+v, want skipped as unsupported", result)+ }+ if got, _ := os.ReadFile(VectorConfigPath(true)); !bytes.Equal(got, stale) {+ t.Fatal("an unsupported service manager's config was rewritten")+ }+}++func TestReconcileWarnsWhenVectorIsMissing(t *testing.T) {+ f := newReconcileFixture(t, "metadata-only")+ stale := writeStaleConfig(t)+ if err := os.Remove(f.vector); err != nil {+ t.Fatal(err)+ }+ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if result.Warning == "" || result.Updated {+ t.Fatalf("result = %+v, want a warning", result)+ }+ if got, _ := os.ReadFile(VectorConfigPath(true)); !bytes.Equal(got, stale) {+ t.Fatal("the config was rewritten without a Vector to validate it")+ }+ f.assertCredentialsAndCheckpointsUntouched(t)+}++func TestReconcileKeepsTheRecordedPrivacyModeAndRefusesConflictingRecords(t *testing.T) {+ f := newReconcileFixture(t, "standard")+ cfg, err := endpointconfig.Load(true)+ if err != nil {+ t.Fatal(err)+ }+ cfg.ManagedIngest.PrivacyMode = managedprivacy.MetadataOnly+ if _, err := endpointconfig.Save(cfg); err != nil {+ t.Fatal(err)+ }+ before, _ := os.ReadFile(VectorConfigPath(true))+ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if result.Warning == "" || result.Updated {+ t.Fatalf("result = %+v, want conflicting privacy records to be refused", result)+ }+ if after, _ := os.ReadFile(VectorConfigPath(true)); !bytes.Equal(before, after) {+ t.Fatal("conflicting privacy records changed the config")+ }+}++func TestReconcileUpdatesAStoppedForwarderWithoutStartingIt(t *testing.T) {+ f := newReconcileFixture(t, "metadata-only")+ writeStaleConfig(t)+ f.fwd.loads = 0 // the fake reports Loaded only after a Load+ result, err := ReconcileForwarder(ReconcileOptions{UserMode: true, Forwarder: f.fwd})+ if err != nil {+ t.Fatal(err)+ }+ if !result.Updated || result.Restarted {+ t.Fatalf("result = %+v, want updated without a restart", result)+ }+ if f.fwd.loads != 0 {+ t.Fatal("reconcile started a forwarder that was not running")+ }+ f.assertCredentialsAndCheckpointsUntouched(t)+}diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.goindex 9d166168..1b651040 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go@@ -52,6 +52,11 @@ var (// helpers install, so tests can see whether an uninstall reaches them without touching// /Library.removeScriptForwarders = service.RemoveScriptForwarders+ // reconcileManagedForwarder is the seam for the Beacon Cloud forwarder reconcile, so tests can+ // see whether Install reaches it without a connected endpoint or a service manager.+ reconcileManagedForwarder = func(userMode bool, logPath string) (asymptote.ReconcileResult, error) {+ return asymptote.ReconcileForwarder(asymptote.ReconcileOptions{UserMode: userMode, LogPath: logPath})+ })// inventoryJobController is what lifecycle needs from service.InventoryManager.@@ -216,6 +221,10 @@ type UninstallOptions struct {// sets it: it uninstalls and reinstalls the endpoint, and nothing in Install puts those// forwarders back.KeepForwarders bool+ // KeepManagedIngest leaves the Beacon Cloud forwarder, its config, its Vector checkpoints and+ // its credentials in place. Repair sets it: Install re-renders that config in place instead,+ // and nothing short of a re-connect, which rotates the device key, could bring it back.+ KeepManagedIngest bool}type InstallResult struct {@@ -236,6 +245,9 @@ type InstallResult struct {// reports why in InventoryJobDetail and the install still succeeds.InventoryJobPath string `json:"inventory_job_path,omitempty"`InventoryJobDetail string `json:"inventory_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"`}type Status struct {@@ -569,7 +581,21 @@ func Install(opts InstallOptions) (InstallResult, error) {tx.Rollback(manifest)return InstallResult{}, err}+ // Bring a connected endpoint's Beacon Cloud forwarder config up to this version's pack, in+ // place and without re-enrolling. After everything else, so it can never be the reason an+ // install rolls back; and only when services are started, since it may restart the forwarder+ // (the macOS package installs with --no-start and runs `beacon endpoint asymptote reconcile`+ // itself once the collector is back).+ var managedForwarder *asymptote.ReconcileResult+ if opts.StartService {+ reconciled, err := reconcileManagedForwarder(cfg.UserMode, cfg.LogPath)+ if err != nil && reconciled.Warning == "" {+ reconciled.Warning = err.Error()+ }+ managedForwarder = &reconciled+ }return InstallResult{+ ManagedForwarder: managedForwarder,ConfigPath: configPath,CollectorConfigPath: cfg.Collector.ConfigPath,PlistPath: plistPath,@@ -630,12 +656,14 @@ func Uninstall(opts UninstallOptions) error {fail("remove package forwarders", removeScriptForwarders(opts.KeepConfig))}// The managed-ingest forwarder and its credentials go with the endpoint; server-side the- // device stays registered until it is revoked from the dashboard.- fail("disconnect managed ingest", asymptote.Disconnect(asymptote.DisconnectOptions{- UserMode: cfg.UserMode,- LogPath: cfg.LogPath,- KeepCredentials: opts.KeepConfig,- }))+ // device stays registered until it is revoked from the dashboard. Repair keeps all of it.+ if !opts.KeepManagedIngest {+ fail("disconnect managed ingest", asymptote.Disconnect(asymptote.DisconnectOptions{+ UserMode: cfg.UserMode,+ LogPath: cfg.LogPath,+ KeepCredentials: opts.KeepConfig,+ }))+ }manifest, _ := ReadManifest(cfg.UserMode)if !opts.KeepConfig {restoreBackups(manifest.Backups)@@ -696,12 +724,13 @@ func runtimeLogFiles(logPath string) []string {// and everything it does not recreate stays.func repairUninstallOptions(opts InstallOptions) UninstallOptions {return UninstallOptions{- UserMode: opts.UserMode,- LogPath: opts.LogPath,- KeepLogs: true,- KeepConfig: true,- KeepUpdater: true,- KeepForwarders: true,+ UserMode: opts.UserMode,+ LogPath: opts.LogPath,+ KeepLogs: true,+ KeepConfig: true,+ KeepUpdater: true,+ KeepForwarders: true,+ KeepManagedIngest: true,}}diff --git a/cli/beacon/internal/endpoint/lifecycle/managed_forwarder_test.go b/cli/beacon/internal/endpoint/lifecycle/managed_forwarder_test.gonew file mode 100644index 00000000..19b2958c--- /dev/null+++ b/cli/beacon/internal/endpoint/lifecycle/managed_forwarder_test.go@@ -0,0 +1,117 @@+package lifecycle++import (+ "os"+ "path/filepath"+ "runtime"+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/asymptote"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// writeConnectedState lays down what a finished connect leaves behind, without a service.+func writeConnectedState(t *testing.T) map[string][]byte {+ t.Helper()+ if err := asymptote.SaveEnrollment(true, asymptote.Enrollment{InstallID: "i", IngestURL: "https://ingest.example", DeviceID: "d", OrganizationID: "o", PrivacyMode: "metadata_only"}); err != nil {+ t.Fatal(err)+ }+ if err := asymptote.WriteSecrets(true, "bcn_device_test_key"); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(asymptote.VectorConfigPath(true), []byte("# rendered\n"), 0o644); err != nil {+ t.Fatal(err)+ }+ checkpoint := filepath.Join(asymptote.DataDir(true), "beacon_runtime", "checkpoints.json")+ if err := os.MkdirAll(filepath.Dir(checkpoint), 0o700); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(checkpoint, []byte(`{"position":42}`), 0o600); err != nil {+ t.Fatal(err)+ }+ files := map[string][]byte{}+ for _, path := range []string{asymptote.EnrollmentPath(true), asymptote.SecretsPath(true), asymptote.VectorConfigPath(true), checkpoint} {+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatal(err)+ }+ files[path] = data+ }+ return files+}++// Repair used to tear the Beacon Cloud forwarder down with the rest of the endpoint: the+// uninstall half removed vector.toml and Vector's checkpoints and stopped the service, and the+// install half never put them back, so a repaired endpoint silently stopped forwarding until a+// re-connect rotated its key. The teardown now keeps all of it for Install to reconcile.+func TestRepairTeardownKeepsTheManagedForwarder(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ opts := repairUninstallOptions(InstallOptions{UserMode: true})+ if !opts.KeepManagedIngest {+ t.Fatal("repair's uninstall step must keep the Beacon Cloud forwarder")+ }+ files := writeConnectedState(t)+ if err := Uninstall(opts); err != nil {+ t.Fatal(err)+ }+ for path, want := range files {+ got, err := os.ReadFile(path)+ if err != nil || string(got) != string(want) {+ t.Fatalf("repair's teardown changed %s: %v", path, err)+ }+ }+ if !asymptote.Connected(true) {+ t.Fatal("the endpoint must still be connected after repair's teardown")+ }+}++func TestUninstallStillDisconnectsTheManagedForwarder(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ writeConnectedState(t)+ if err := Uninstall(UninstallOptions{UserMode: true}); err != nil {+ t.Fatal(err)+ }+ if _, err := os.Stat(asymptote.Dir(true)); !os.IsNotExist(err) {+ t.Fatalf("uninstall left %s behind: %v", asymptote.Dir(true), err)+ }+}++// The macOS package installs with --no-start and runs `beacon endpoint asymptote reconcile`+// itself, so Install must not restart the forwarder when it is asked to start nothing.+func TestInstallWithoutStartingServicesLeavesTheForwarderToTheCaller(t *testing.T) {+ if runtime.GOOS != "darwin" {+ t.Skip("install preflight is macOS-only")+ }+ home := t.TempDir()+ testenv.SetHome(t, home)+ collectorPath := filepath.Join(home, "bin", "beacon-otelcol")+ if err := os.MkdirAll(filepath.Dir(collectorPath), 0o755); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(collectorPath, []byte("#!/bin/sh\n"), 0o755); err != nil {+ t.Fatal(err)+ }+ installFakeInventoryJob(t, true)+ old := reconcileManagedForwarder+ called := false+ reconcileManagedForwarder = func(bool, string) (asymptote.ReconcileResult, error) {+ called = true+ return asymptote.ReconcileResult{}, nil+ }+ t.Cleanup(func() { reconcileManagedForwarder = old })+ result, err := Install(InstallOptions{+ UserMode: true,+ LogPath: filepath.Join(home, ".beacon", "endpoint", "logs", "runtime.jsonl"),+ Harnesses: []string{},+ GRPCPort: freePort(t),+ HTTPPort: freePort(t),+ CollectorPath: collectorPath,+ StartService: false,+ })+ if err != nil {+ t.Fatalf("Install: %v", err)+ }+ if called || result.ManagedForwarder != nil {+ t.Fatal("a --no-start install reconciled the forwarder")+ }+}diff --git a/docs/cli/endpoint-connect.mdx b/docs/cli/endpoint-connect.mdxindex 813329df..79bce462 100644--- a/docs/cli/endpoint-connect.mdx+++ b/docs/cli/endpoint-connect.mdx@@ -80,11 +80,36 @@ The onboarding wizard records one of two modes. `connect` uses that choice unles| `metadata-only` | Omits prompts, responses, reasoning, tool arguments/results, command output, raw event fields, diffs, inventory file contents, and MCP definitions. It also removes tool descriptions and definitions (`gen_ai.tool.description`, `gen_ai.tool.definitions`), retrieval queries and documents (`gen_ai.retrieval`), evaluation explanations, agent descriptions, request stop sequences, and the free-text reason on approvals and policy decisions (`approval.reason`, `policy.reason`), which can hold an operator's typed feedback; the decision itself remains. Stable ids, hashes, byte counts, actions, timestamps, harness/session/trace identity, the `prompt.id` that groups a turn, token usage, commands, file paths, and other structured metadata remain. |The transform runs locally in Vector before batching, buffering, or HTTPS upload.-Changing modes requires rerunning `beacon endpoint connect`; the rendered config and+Changing modes requires rerunning `beacon endpoint connect`; install, repair and package+upgrades re-render the config but always keep the recorded mode. The rendered config andstatus output record the active choice. A mode change stops the forwarder and clears itsdisk buffer before the new config is installed, so events queued under the previous modeare not uploaded under the new one.+## Keeping the forwarder config current++`connect` is not the only time `vector.toml` is written. `beacon endpoint install`,+`beacon endpoint repair`, and the macOS, `.deb` and `.rpm` package upgrades re-render it in place+for an endpoint that is already connected, so a fix to the forwarder pack, such as a+Metadata-only transform that removes more fields, reaches the endpoint without a re-connect,+which would rotate the device key. The re-render:++- keeps the recorded ingest URL and privacy mode (changing the mode is still a `connect`+ decision), and refuses to guess when `enrollment.json` and `config.json` disagree about it;+- never enrolls, makes no network request, and does not read or rewrite the secrets file;+- leaves `vector-data/`, and with it Vector's checkpoints and buffer, as it is;+- validates the new config with the forwarder's own Vector exactly as `connect` does, and only+ then replaces the old file atomically. A config Vector rejects is reported as a warning, and the+ running forwarder keeps the old one;+- restarts the forwarder only when the content changed and the service is loaded.++It does nothing on an endpoint that is not connected, after a connect that did not finish, when+the forwarder service is not installed, or where the service manager cannot run it (supervised+mode); when Vector is missing it warns and keeps the old config. An install run with+`--no-start` leaves the forwarder alone; the macOS package installs that way and then runs+`beacon endpoint asymptote reconcile --system` itself. Run that command by hand (add `--json` for+the result) to reconcile without reinstalling.+## Files and services| Item | User mode | System mode (macOS) | System mode (Linux) |diff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdxindex 61e35fc3..83e03b75 100644--- a/docs/cli/endpoint-repair.mdx+++ b/docs/cli/endpoint-repair.mdx@@ -15,6 +15,8 @@ Repair preserves runtime logs while reinstalling managed endpoint files. By defaDuring repair, Beacon removes the existing managed service before reinstalling it so an unhealthy collector can release local OTLP ports. If reinstall cannot complete, Beacon restores the previous endpoint configuration so local state is not left partially rolled back.+On an endpoint connected to Beacon Cloud, repair leaves the forwarder service, the device key, and Vector's checkpoints and buffer in place, and re-renders `vector.toml` from this version's forwarder pack with the recorded ingest URL and privacy mode. Vector validates the new config before it replaces the old one; the forwarder restarts only when the content changed, and a config Vector rejects is reported as a warning while the forwarder keeps running on the old one. Repair never re-enrolls the device or rotates its key, and `--no-start` leaves the forwarder untouched. See [Keeping the forwarder config current](/cli/endpoint-connect#keeping-the-forwarder-config-current).+## Flags| Flag | Description |diff --git a/docs/cli/upgrade.mdx b/docs/cli/upgrade.mdxindex f1bdd25e..cd95acdb 100644--- a/docs/cli/upgrade.mdx+++ b/docs/cli/upgrade.mdx@@ -45,7 +45,9 @@ the package artifact for the local architecture, downloads it into the endpointupdate staging directory, verifies the manifest checksum, Developer ID Installersignature, and Gatekeeper install assessment, then runs Apple's `installer`. Thepackage postinstall restarts the local collector, restores configured Vector-forwarders, reconciles the updater LaunchDaemon, and the updater health-checks+forwarders, re-renders a connected endpoint's Beacon Cloud forwarder config from+the new version's pack (see [Keeping the forwarder config current](/cli/endpoint-connect#keeping-the-forwarder-config-current)),+reconciles the updater LaunchDaemon, and the updater health-checksthe new install. If the new install is unhealthy, Beacon restores the previous`/opt/beacon` tree.@@ -166,7 +168,7 @@ beacon endpoint repairbeacon endpoint status```-`beacon endpoint repair` preserves runtime logs while reapplying service files, collector configuration, harness telemetry settings, and forwarding destinations.+`beacon endpoint repair` preserves runtime logs while reapplying service files, collector configuration, harness telemetry settings, and forwarding destinations. On an endpoint connected to Beacon Cloud it keeps the forwarder, its device key and its Vector checkpoints, and re-renders `vector.toml` from the upgraded version's pack with the recorded privacy mode, so a Homebrew or archive upgrade picks up forwarder fixes without a re-connect. See [Keeping the forwarder config current](/cli/endpoint-connect#keeping-the-forwarder-config-current).<Note>On v0.0.43 or newer, use `beacon endpoint doctor --fix` when you only need supported health-check drift remediated without a full repair.diff --git a/packaging/macos/README.md b/packaging/macos/README.mdindex 03a12fa4..d22eb037 100644--- a/packaging/macos/README.md+++ b/packaging/macos/README.md@@ -47,7 +47,11 @@ in the active console user's browser and then adds a second resident service,running the bundled `/opt/beacon/bin/vector` with the config, disk buffer,enrollment record and `0600` device key below`/Library/Application Support/Beacon/Endpoint/asymptote/`. `beacon endpoint-disconnect --system` and `beacon endpoint uninstall --system` remove it.+disconnect --system` and `beacon endpoint uninstall --system` remove it. A package+upgrade keeps it and runs `beacon endpoint asymptote reconcile --system`, which+re-renders its `vector.toml` from the new version's pack with the recorded privacy+mode, validates it with Vector, and restarts the forwarder only when it changed; the+device key, the enrollment and Vector's checkpoints are left as they are.The package postinstall also repairs endpoint user configuration for the activeconsole user when one is logged in. This user-context step points Claude Code anddiff --git a/packaging/macos/scripts/postinstall b/packaging/macos/scripts/postinstallindex 729daaef..a1aaecdb 100755--- a/packaging/macos/scripts/postinstall+++ b/packaging/macos/scripts/postinstall@@ -129,6 +129,12 @@ 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+ # 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, and+ # a no-op on an endpoint that is not connected. Non-fatal: a rejected config keeps the old one.+ "${BEACON_BIN:-/opt/beacon/bin/beacon}" endpoint asymptote reconcile --system || \+ echo "Warning: Beacon Cloud forwarder config not reconciled (endpoint is installed and running)" >&2fiexit 0diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.shindex 5c719912..d50c48d8 100644--- a/packaging/macos/test-endpoint-scripts.sh+++ b/packaging/macos/test-endpoint-scripts.sh@@ -34,6 +34,10 @@ if ! grep -q 'restore_existing_forwarder' "$ROOT_DIR/packaging/macos/scripts/posecho "postinstall should restore existing optional forwarders" >&2exit 1fi+if ! grep -q 'endpoint asymptote reconcile --system' "$ROOT_DIR/packaging/macos/scripts/postinstall"; then+ echo "postinstall should re-render a connected endpoint's Beacon Cloud forwarder config" >&2+ exit 1+fiif ! grep -q 'endpoint user-config repair-installed' "$ROOT_DIR/packaging/macos/scripts/postinstall"; thenecho "postinstall should refresh installed user endpoint configuration after package install" >&2exit 1