Skip to content

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

Cache the root update check and point other installs at the release

Claude488b27729818
diff --git a/CLAUDE.md b/CLAUDE.md
index 51de1ec2..f3a5d5f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,6 +30,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc
- 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, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. 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 deletes the staged file with the checkpoints before restaging, 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.
- Do not add dependency vulnerability scanning, OSV/GHSA lookups, package remediation, or other vulnerability-enforcement flows to the public hook path.
- Do not add broad runtime enforcement unless explicitly requested. Current control behavior is limited to hook-native approvals/denials exposed by supported agent runtimes.
- Keep destination support shaped like the existing local JSONL and customer-managed forwarding paths. Beacon may render supported packs or token-based endpoint forwarders, but should not add hosted SIEM dependencies or store third-party service credentials beyond the explicit supported configs. Elastic remains a file-tailing pack over local JSONL.
diff --git a/cli/beacon/cmd/root.go b/cli/beacon/cmd/root.go
index 255a37df..07118893 100644
--- a/cli/beacon/cmd/root.go
+++ b/cli/beacon/cmd/root.go
@@ -1,17 +1,20 @@
package cmd
import (
- "context"
"fmt"
"io"
"os"
+ "os/exec"
+ "path/filepath"
"time"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
"golang.org/x/term"
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/selfupdate"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/updatecheck"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
)
@@ -35,13 +38,12 @@ const (
resetColor = "\x1b[0m"
beaconCLIChangelogURL = "https://docs.beacon.sh/changelog/cli"
+ beaconReleasesURL = "https://github.com/asymptote-labs/agent-beacon/releases/latest"
)
var (
- newRootVersionChecker = func(currentVersion string) versionChecker {
- return updatecheck.DefaultChecker(currentVersion)
- }
- rootUpdateCheckTimeout = 2 * time.Second
+ rootNow = time.Now
+ rootStartUpdateRefresh = startDetachedUpdateRefresh
rootDetectInstall = selfupdate.DetectInstall
)
@@ -54,25 +56,56 @@ var beaconBanner = []string{
"╚═════╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝",
}
+// maybePrintRootUpdateNotice follows the Codex/Claude Code pattern: the notice comes from the
+// cached result of an earlier lookup, so bare `beacon` never waits on the network. When the
+// cache is older than updatecheck.CacheTTL it starts a detached `beacon version refresh` that
+// updates the cache for the next run. BEACON_UPDATE_CHECK=0 or CI turns all of it off.
func maybePrintRootUpdateNotice(cmd *cobra.Command) {
in, inOK := cmd.InOrStdin().(*os.File)
out, outOK := cmd.OutOrStdout().(*os.File)
if !inOK || !outOK || !isTerminal(in) || !isTerminal(out) {
return
}
+ showCachedUpdateNotice(out, shouldUseColor(out), os.Getenv)
+}
- parent := cmd.Context()
- if parent == nil {
- parent = context.Background()
+func showCachedUpdateNotice(out io.Writer, color bool, getenv func(string) string) {
+ current := version.GetVersion()
+ if updatecheck.Disabled(getenv) || !updatecheck.CanCheckVersion(current) {
+ return
}
- ctx, cancel := context.WithTimeout(parent, rootUpdateCheckTimeout)
- defer cancel()
- result, err := newRootVersionChecker(version.GetVersion()).Check(ctx)
- if err != nil || !result.UpdateAvailable {
+ path := updateCachePath()
+ cache := updatecheck.LoadCache(path)
+ if cache.Stale(rootNow()) {
+ _ = rootStartUpdateRefresh()
+ }
+ result := cache.Notice(current)
+ if !result.UpdateAvailable {
return
}
- printRootUpdateNotice(out, result, shouldUseColor(out), rootDetectInstall())
+ printRootUpdateNotice(out, result, color, rootDetectInstall())
+}
+
+func updateCachePath() string {
+ return filepath.Join(endpointconfig.BaseDir(true), updatecheck.CacheFile)
+}
+
+// startDetachedUpdateRefresh runs `beacon version refresh` in the background with no standard
+// streams, so it outlives this process and never writes to the terminal.
+func startDetachedUpdateRefresh() error {
+ exe, err := os.Executable()
+ if err != nil {
+ return err
+ }
+ child := exec.Command(exe, "version", "refresh")
+ child.Stdin, child.Stdout, child.Stderr = nil, nil, nil
+ // Its own session, so closing the terminal right after `beacon` does not kill the lookup.
+ child.SysProcAttr = service.DetachedProcAttrs()
+ if err := child.Start(); err != nil {
+ return err
+ }
+ return child.Process.Release()
}
func printRootUpdateNotice(out io.Writer, result updatecheck.Result, color bool, install selfupdate.Install) {
@@ -90,11 +123,20 @@ func printRootUpdateNotice(out io.Writer, result updatecheck.Result, color bool,
case selfupdate.InstallSystemPkg:
fmt.Fprintln(out, "Update with: sudo beacon endpoint update --apply")
default:
- fmt.Fprintln(out, "Update with: beacon endpoint update")
+ // Tarballs, install.sh, go install, the MSI and source builds have no in-place
+ // updater: `beacon endpoint update` only applies to the system package.
+ fmt.Fprintf(out, "Download: %s\n", releaseDownloadURL(result))
}
fmt.Fprintln(out)
}
+func releaseDownloadURL(result updatecheck.Result) string {
+ if result.ReleaseURL != "" {
+ return result.ReleaseURL
+ }
+ return beaconReleasesURL
+}
+
func printRootSplash(cmd *cobra.Command) {
out := cmd.OutOrStdout()
cmd.SetOut(out)
diff --git a/cli/beacon/cmd/root_test.go b/cli/beacon/cmd/root_test.go
index 0704443c..c7072e7a 100644
--- a/cli/beacon/cmd/root_test.go
+++ b/cli/beacon/cmd/root_test.go
@@ -6,10 +6,12 @@ import (
"path/filepath"
"strings"
"testing"
+ "time"
"github.com/spf13/cobra"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/selfupdate"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/updatecheck"
)
@@ -58,7 +60,6 @@ func TestPrintRootUpdateNotice(t *testing.T) {
}{
{name: "homebrew", install: selfupdate.Install{Kind: selfupdate.InstallHomebrew}, command: "brew upgrade beacon"},
{name: "system package", install: selfupdate.Install{Kind: selfupdate.InstallSystemPkg}, command: "sudo beacon endpoint update --apply"},
- {name: "other", install: selfupdate.Install{Kind: selfupdate.InstallOther}, command: "beacon endpoint update"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
@@ -97,13 +98,37 @@ func TestPrintRootUpdateNoticeUsesOrange(t *testing.T) {
}
}
+func TestPrintRootUpdateNoticePointsOtherInstallsAtTheRelease(t *testing.T) {
+ other := selfupdate.Install{Kind: selfupdate.InstallOther}
+ for _, tt := range []struct {
+ name string
+ result updatecheck.Result
+ want string
+ }{
+ {name: "release url", result: updatecheck.Result{CurrentVersion: "v1.3.33", LatestVersion: "v1.3.34", ReleaseURL: "https://example.test/v1.3.34"}, want: "Download: https://example.test/v1.3.34"},
+ {name: "no release url", result: updatecheck.Result{CurrentVersion: "v1.3.33", LatestVersion: "v1.3.34"}, want: "Download: " + beaconReleasesURL},
+ } {
+ t.Run(tt.name, func(t *testing.T) {
+ var out bytes.Buffer
+ printRootUpdateNotice(&out, tt.result, false, other)
+ if !strings.Contains(out.String(), tt.want) {
+ t.Fatalf("notice missing %q:\n%s", tt.want, out.String())
+ }
+ // `beacon endpoint update` cannot update these installs.
+ if strings.Contains(out.String(), "endpoint update") {
+ t.Fatalf("notice offers an updater that does not apply:\n%s", out.String())
+ }
+ })
+ }
+}
+
func TestRootUpdateNoticeSkipsNonInteractiveCommands(t *testing.T) {
- oldChecker := newRootVersionChecker
- t.Cleanup(func() { newRootVersionChecker = oldChecker })
+ oldRefresh := rootStartUpdateRefresh
+ t.Cleanup(func() { rootStartUpdateRefresh = oldRefresh })
called := false
- newRootVersionChecker = func(string) versionChecker {
+ rootStartUpdateRefresh = func() error {
called = true
- return stubVersionChecker{}
+ return nil
}
cmd := &cobra.Command{}
@@ -111,7 +136,7 @@ func TestRootUpdateNoticeSkipsNonInteractiveCommands(t *testing.T) {
cmd.SetOut(&bytes.Buffer{})
maybePrintRootUpdateNotice(cmd)
if called {
- t.Fatal("non-interactive root command performed an update check")
+ t.Fatal("non-interactive root command started an update refresh")
}
}
@@ -154,3 +179,73 @@ func TestIsTerminalRejectsDevNullPipesAndRegularFiles(t *testing.T) {
}
}
}
+
+func TestShowCachedUpdateNoticeReadsTheCacheAndRefreshesWhenStale(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ restoreVersion := setVersionForTest(t, "v1.3.33")
+ defer restoreVersion()
+ now := time.Date(2026, 10, 11, 12, 0, 0, 0, time.UTC)
+ oldNow, oldRefresh, oldDetect := rootNow, rootStartUpdateRefresh, rootDetectInstall
+ t.Cleanup(func() { rootNow, rootStartUpdateRefresh, rootDetectInstall = oldNow, oldRefresh, oldDetect })
+ rootNow = func() time.Time { return now }
+ rootDetectInstall = func() selfupdate.Install { return selfupdate.Install{Kind: selfupdate.InstallHomebrew} }
+ refreshes := 0
+ rootStartUpdateRefresh = func() error {
+ refreshes++
+ return nil
+ }
+ env := map[string]string{}
+ getenv := func(k string) string { return env[k] }
+
+ run := func() string {
+ var out bytes.Buffer
+ showCachedUpdateNotice(&out, false, getenv)
+ return out.String()
+ }
+
+ // No cache yet: nothing to show, one background refresh.
+ if got := run(); got != "" || refreshes != 1 {
+ t.Fatalf("empty cache: output %q, refreshes %d; want no output and 1 refresh", got, refreshes)
+ }
+
+ // A fresh cache with a newer release: the notice, no refresh.
+ if err := updatecheck.SaveCache(updateCachePath(), updatecheck.Cache{LatestVersion: "v1.3.34", LastCheckedAt: now.Add(-time.Hour)}); err != nil {
+ t.Fatal(err)
+ }
+ if got := run(); !strings.Contains(got, "Update available · v1.3.33 → v1.3.34") || refreshes != 1 {
+ t.Fatalf("fresh cache: output %q, refreshes %d; want notice and no refresh", got, refreshes)
+ }
+
+ // A stale cache still shows what it knows and schedules a refresh.
+ if err := updatecheck.SaveCache(updateCachePath(), updatecheck.Cache{LatestVersion: "v1.3.34", LastCheckedAt: now.Add(-25 * time.Hour)}); err != nil {
+ t.Fatal(err)
+ }
+ if got := run(); !strings.Contains(got, "Update available") || refreshes != 2 {
+ t.Fatalf("stale cache: output %q, refreshes %d; want notice and a refresh", got, refreshes)
+ }
+
+ // The opt-out and CI turn off both the notice and the refresh.
+ for _, kv := range [][2]string{{updatecheck.DisableEnv, "0"}, {"CI", "true"}} {
+ env = map[string]string{kv[0]: kv[1]}
+ if got := run(); got != "" || refreshes != 2 {
+ t.Fatalf("%s=%s: output %q, refreshes %d; want nothing", kv[0], kv[1], got, refreshes)
+ }
+ }
+}
+
+func TestShowCachedUpdateNoticeSkipsDevBuilds(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ restoreVersion := setVersionForTest(t, "dev")
+ defer restoreVersion()
+ oldRefresh := rootStartUpdateRefresh
+ t.Cleanup(func() { rootStartUpdateRefresh = oldRefresh })
+ rootStartUpdateRefresh = func() error {
+ t.Fatal("dev build started an update refresh")
+ return nil
+ }
+ var out bytes.Buffer
+ showCachedUpdateNotice(&out, false, func(string) string { return "" })
+ if out.Len() != 0 {
+ t.Fatalf("dev build printed %q", out.String())
+ }
+}
diff --git a/cli/beacon/cmd/version_check.go b/cli/beacon/cmd/version_check.go
index 1db8297e..d1e2af87 100644
--- a/cli/beacon/cmd/version_check.go
+++ b/cli/beacon/cmd/version_check.go
@@ -3,6 +3,7 @@ package cmd
import (
"context"
"fmt"
+ "os"
"time"
"github.com/spf13/cobra"
@@ -31,11 +32,36 @@ var (
versionCheckTimeout = 2 * time.Second
)
+// versionRefreshCmd is the background half of the startup notice: bare `beacon` starts it
+// detached when the cache is stale, and it only updates the cache. It prints nothing, so a
+// failure leaves the previous cached release in place until the next TTL.
+var versionRefreshCmd = &cobra.Command{
+ Use: "refresh",
+ Short: "Refresh the cached update check",
+ Hidden: true,
+ SilenceUsage: true,
+ Args: cobra.NoArgs,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ if updatecheck.Disabled(os.Getenv) || !updatecheck.CanCheckVersion(version.GetVersion()) {
+ return nil
+ }
+ path := updateCachePath()
+ if !updatecheck.LoadCache(path).Stale(rootNow()) {
+ return nil
+ }
+ _, _ = checkAndRecord(cmd)
+ return nil
+ },
+}
+
func init() {
versionCmd.AddCommand(versionCheckCmd)
+ versionCmd.AddCommand(versionRefreshCmd)
}
-func runVersionCheck(cmd *cobra.Command, args []string) error {
+// checkAndRecord runs one release lookup and folds it into the update-check cache, so the
+// explicit check and the background refresh leave the startup notice with the same answer.
+func checkAndRecord(cmd *cobra.Command) (updatecheck.Result, error) {
parent := cmd.Context()
if parent == nil {
parent = context.Background()
@@ -43,7 +69,17 @@ func runVersionCheck(cmd *cobra.Command, args []string) error {
ctx, cancel := context.WithTimeout(parent, versionCheckTimeout)
defer cancel()
- result, err := newVersionChecker(version.GetVersion()).Check(ctx)
+ current := version.GetVersion()
+ result, err := newVersionChecker(current).Check(ctx)
+ if updatecheck.CanCheckVersion(current) {
+ path := updateCachePath()
+ _ = updatecheck.SaveCache(path, updatecheck.LoadCache(path).Record(result, err, rootNow()))
+ }
+ return result, err
+}
+
+func runVersionCheck(cmd *cobra.Command, args []string) error {
+ result, err := checkAndRecord(cmd)
if err != nil {
return fmt.Errorf("unable to check for Beacon updates: %w", err)
}
@@ -60,9 +96,7 @@ func runVersionCheck(cmd *cobra.Command, args []string) error {
if result.UpdateAvailable {
fmt.Fprintf(out, "Beacon %s is available. Current version: %s\n", result.LatestVersion, result.CurrentVersion)
fmt.Fprintln(out, "If installed with Homebrew: brew upgrade beacon")
- if result.ReleaseURL != "" {
- fmt.Fprintf(out, "Download: %s\n", result.ReleaseURL)
- }
+ fmt.Fprintf(out, "Download: %s\n", releaseDownloadURL(result))
return nil
}
fmt.Fprintf(out, "Beacon %s is up to date.\n", result.CurrentVersion)
diff --git a/cli/beacon/cmd/version_check_test.go b/cli/beacon/cmd/version_check_test.go
index 437474a3..4d82ef1f 100644
--- a/cli/beacon/cmd/version_check_test.go
+++ b/cli/beacon/cmd/version_check_test.go
@@ -6,9 +6,11 @@ import (
"errors"
"strings"
"testing"
+ "time"
"github.com/spf13/cobra"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/updatecheck"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
)
@@ -191,6 +193,8 @@ func setVersionForTest(t *testing.T, v string) func() {
func setVersionCheckerForTest(t *testing.T, checker versionChecker) func() {
t.Helper()
+ // A check records its answer in the update cache under the home directory.
+ testenv.SetHome(t, t.TempDir())
old := newVersionChecker
newVersionChecker = func(currentVersion string) versionChecker {
return checker
@@ -204,3 +208,63 @@ func setVersionCheckForTest(t *testing.T, enabled bool) func() {
versionCheck = enabled
return func() { versionCheck = old }
}
+
+func TestVersionCheckRecordsTheAnswerForTheStartupNotice(t *testing.T) {
+ restoreVersion := setVersionForTest(t, "v0.0.10")
+ defer restoreVersion()
+ restoreChecker := setVersionCheckerForTest(t, stubVersionChecker{result: updatecheck.Result{
+ CurrentVersion: "v0.0.10",
+ LatestVersion: "v0.0.12",
+ ReleaseURL: "https://example.test/v0.0.12",
+ UpdateAvailable: true,
+ }})
+ defer restoreChecker()
+
+ cmd := &cobra.Command{}
+ cmd.SetOut(&bytes.Buffer{})
+ if err := runVersionCheck(cmd, nil); err != nil {
+ t.Fatalf("runVersionCheck returned error: %v", err)
+ }
+ cache := updatecheck.LoadCache(updateCachePath())
+ if cache.LatestVersion != "v0.0.12" || cache.ReleaseURL != "https://example.test/v0.0.12" || cache.LastCheckedAt.IsZero() {
+ t.Fatalf("cache = %#v, want the checked release", cache)
+ }
+}
+
+func TestVersionRefreshSkipsAFreshCache(t *testing.T) {
+ restoreVersion := setVersionForTest(t, "v0.0.10")
+ defer restoreVersion()
+ calls := 0
+ restoreChecker := setVersionCheckerForTest(t, stubVersionChecker{err: errors.New("should not run")})
+ defer restoreChecker()
+ newVersionChecker = func(string) versionChecker {
+ calls++
+ return stubVersionChecker{result: updatecheck.Result{LatestVersion: "v0.0.12"}}
+ }
+ t.Setenv(updatecheck.DisableEnv, "")
+ t.Setenv("CI", "")
+
+ if err := updatecheck.SaveCache(updateCachePath(), updatecheck.Cache{LatestVersion: "v0.0.11", LastCheckedAt: time.Now()}); err != nil {
+ t.Fatal(err)
+ }
+ cmd := &cobra.Command{}
+ if err := versionRefreshCmd.RunE(cmd, nil); err != nil {
+ t.Fatal(err)
+ }
+ if calls != 0 {
+ t.Fatalf("refresh of a fresh cache looked up the release %d times", calls)
+ }
+
+ if err := updatecheck.SaveCache(updateCachePath(), updatecheck.Cache{LatestVersion: "v0.0.11", LastCheckedAt: time.Now().Add(-25 * time.Hour)}); err != nil {
+ t.Fatal(err)
+ }
+ if err := versionRefreshCmd.RunE(cmd, nil); err != nil {
+ t.Fatal(err)
+ }
+ if calls != 1 {
+ t.Fatalf("refresh of a stale cache looked up the release %d times, want 1", calls)
+ }
+ if got := updatecheck.LoadCache(updateCachePath()).LatestVersion; got != "v0.0.12" {
+ t.Fatalf("cached latest = %q, want v0.0.12", got)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/service/supervised.go b/cli/beacon/internal/endpoint/service/supervised.go
index 5b496a97..96ab95cb 100644
--- a/cli/beacon/internal/endpoint/service/supervised.go
+++ b/cli/beacon/internal/endpoint/service/supervised.go
@@ -10,6 +10,7 @@ import (
"runtime"
"strconv"
"strings"
+ "syscall"
"time"
)
@@ -270,3 +271,10 @@ func (st supervisedState) running() bool {
func supervisedLogPath(userMode bool) string {
return filepath.Join(stateDir(userMode), "collector.out")
}
+
+// DetachedProcAttrs returns the process attributes that let a background child outlive the
+// CLI invocation and the terminal that started it: its own session on Unix, no console and its
+// own process group on Windows.
+func DetachedProcAttrs() *syscall.SysProcAttr {
+ return detachAttrs()
+}
diff --git a/cli/beacon/internal/updatecheck/cache.go b/cli/beacon/internal/updatecheck/cache.go
new file mode 100644
index 00000000..463ad2a9
--- /dev/null
+++ b/cli/beacon/internal/updatecheck/cache.go
@@ -0,0 +1,123 @@
+package updatecheck
+
+import (
+ "encoding/json"
+ "errors"
+ "os"
+ "path/filepath"
+ "strings"
+ "time"
+)
+
+// CacheFile is the name of the update-check cache under the user's Beacon directory.
+const CacheFile = "update-check.json"
+
+// CacheTTL is how long a cached release lookup is trusted before a refresh is due.
+// Like Codex's version.json, the notice reads the cache and never waits on the network;
+// a stale cache only schedules a background refresh.
+const CacheTTL = 24 * time.Hour
+
+// DisableEnv turns the automatic check off when set to 0, false, off or no.
+// The explicit `beacon version check` still works.
+const DisableEnv = "BEACON_UPDATE_CHECK"
+
+// Cache is the last release lookup, persisted so the startup notice needs no network call.
+// LastCheckedAt records every attempt, including failed ones, so an unreachable or
+// rate-limited release API is retried once per TTL rather than on every run.
+type Cache struct {
+ LatestVersion string `json:"latest_version,omitempty"`
+ ReleaseURL string `json:"release_url,omitempty"`
+ LastCheckedAt time.Time `json:"last_checked_at"`
+}
+
+// Disabled reports whether the automatic update check is turned off by the environment.
+// CI runs never check: nobody is there to read the notice.
+func Disabled(getenv func(string) string) bool {
+ switch strings.ToLower(strings.TrimSpace(getenv(DisableEnv))) {
+ case "0", "false", "off", "no":
+ return true
+ }
+ return strings.TrimSpace(getenv("CI")) != ""
+}
+
+// LoadCache reads the cache at path. A missing or unreadable cache is an empty one.
+func LoadCache(path string) Cache {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return Cache{}
+ }
+ var cache Cache
+ if err := json.Unmarshal(data, &cache); err != nil {
+ return Cache{}
+ }
+ return cache
+}
+
+// SaveCache writes the cache atomically, 0600 under a 0700 directory.
+func SaveCache(path string, cache Cache) error {
+ if path == "" {
+ return errors.New("update cache path is empty")
+ }
+ dir := filepath.Dir(path)
+ if err := os.MkdirAll(dir, 0o700); err != nil {
+ return err
+ }
+ data, err := json.MarshalIndent(cache, "", " ")
+ if err != nil {
+ return err
+ }
+ tmp, err := os.CreateTemp(dir, ".update-check-*.json")
+ if err != nil {
+ return err
+ }
+ tmpName := tmp.Name()
+ defer os.Remove(tmpName)
+ if err := tmp.Chmod(0o600); err != nil {
+ tmp.Close()
+ return err
+ }
+ if _, err := tmp.Write(append(data, '\n')); err != nil {
+ tmp.Close()
+ return err
+ }
+ if err := tmp.Close(); err != nil {
+ return err
+ }
+ return os.Rename(tmpName, path)
+}
+
+// Stale reports whether a refresh is due at now.
+func (c Cache) Stale(now time.Time) bool {
+ if c.LastCheckedAt.IsZero() || c.LastCheckedAt.After(now) {
+ return true
+ }
+ return now.Sub(c.LastCheckedAt) >= CacheTTL
+}
+
+// Notice returns the cached result for currentVersion. UpdateAvailable is set only when the
+// cached release is strictly newer than a comparable current version, so dev and local builds
+// never see a notice.
+func (c Cache) Notice(currentVersion string) Result {
+ result := Result{
+ CurrentVersion: displayVersion(currentVersion),
+ LatestVersion: displayVersion(c.LatestVersion),
+ ReleaseURL: c.ReleaseURL,
+ }
+ if !CanCheckVersion(currentVersion) || c.LatestVersion == "" {
+ return result
+ }
+ cmp, ok := compareVersions(currentVersion, c.LatestVersion)
+ result.UpdateAvailable = ok && cmp < 0
+ return result
+}
+
+// Record folds a check into the cache: a successful lookup replaces the release, a failed one
+// only moves LastCheckedAt so the previous release is still offered.
+func (c Cache) Record(result Result, err error, now time.Time) Cache {
+ c.LastCheckedAt = now.UTC()
+ if err == nil && result.LatestVersion != "" {
+ c.LatestVersion = result.LatestVersion
+ c.ReleaseURL = result.ReleaseURL
+ }
+ return c
+}
diff --git a/cli/beacon/internal/updatecheck/cache_test.go b/cli/beacon/internal/updatecheck/cache_test.go
new file mode 100644
index 00000000..999005e2
--- /dev/null
+++ b/cli/beacon/internal/updatecheck/cache_test.go
@@ -0,0 +1,111 @@
+package updatecheck
+
+import (
+ "errors"
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+func TestCacheRoundTripsWithPrivateModes(t *testing.T) {
+ dir := filepath.Join(t.TempDir(), "endpoint")
+ path := filepath.Join(dir, CacheFile)
+ want := Cache{LatestVersion: "v0.0.12", ReleaseURL: "https://example.test/r", LastCheckedAt: time.Date(2026, 10, 11, 0, 0, 0, 0, time.UTC)}
+ if err := SaveCache(path, want); err != nil {
+ t.Fatal(err)
+ }
+ if got := LoadCache(path); got != want {
+ t.Fatalf("LoadCache = %#v, want %#v", got, want)
+ }
+ if testenv.HasPOSIXFileModes() {
+ for p, mode := range map[string]os.FileMode{dir: 0o700, path: 0o600} {
+ info, err := os.Stat(p)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if info.Mode().Perm() != mode {
+ t.Fatalf("%s mode = %o, want %o", p, info.Mode().Perm(), mode)
+ }
+ }
+ }
+}
+
+func TestLoadCacheTreatsMissingOrCorruptAsEmpty(t *testing.T) {
+ dir := t.TempDir()
+ if got := LoadCache(filepath.Join(dir, "missing.json")); got != (Cache{}) {
+ t.Fatalf("missing cache = %#v", got)
+ }
+ bad := filepath.Join(dir, "bad.json")
+ if err := os.WriteFile(bad, []byte("{"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if got := LoadCache(bad); got != (Cache{}) {
+ t.Fatalf("corrupt cache = %#v", got)
+ }
+}
+
+func TestCacheStale(t *testing.T) {
+ now := time.Date(2026, 10, 11, 12, 0, 0, 0, time.UTC)
+ for _, tt := range []struct {
+ name string
+ checked time.Time
+ want bool
+ }{
+ {name: "never", want: true},
+ {name: "recent", checked: now.Add(-time.Hour), want: false},
+ {name: "expired", checked: now.Add(-CacheTTL), want: true},
+ {name: "future clock", checked: now.Add(time.Hour), want: true},
+ } {
+ if got := (Cache{LastCheckedAt: tt.checked}).Stale(now); got != tt.want {
+ t.Fatalf("%s: Stale = %v, want %v", tt.name, got, tt.want)
+ }
+ }
+}
+
+func TestCacheNotice(t *testing.T) {
+ cache := Cache{LatestVersion: "v0.0.12", ReleaseURL: "https://example.test/r"}
+ if got := cache.Notice("v0.0.10"); !got.UpdateAvailable || got.LatestVersion != "v0.0.12" || got.ReleaseURL != "https://example.test/r" {
+ t.Fatalf("older current: %#v", got)
+ }
+ for _, current := range []string{"v0.0.12", "v0.1.0", "dev", "v0.0.10+local"} {
+ if cache.Notice(current).UpdateAvailable {
+ t.Fatalf("current %q: notice offered an update", current)
+ }
+ }
+ if (Cache{}).Notice("v0.0.10").UpdateAvailable {
+ t.Fatal("empty cache offered an update")
+ }
+}
+
+func TestCacheRecordKeepsTheLastReleaseOnFailure(t *testing.T) {
+ now := time.Date(2026, 10, 11, 12, 0, 0, 0, time.UTC)
+ cache := Cache{LatestVersion: "v0.0.11", ReleaseURL: "old"}
+ failed := cache.Record(Result{}, errors.New("rate limited"), now)
+ if failed.LatestVersion != "v0.0.11" || failed.ReleaseURL != "old" || !failed.LastCheckedAt.Equal(now) {
+ t.Fatalf("failed record = %#v", failed)
+ }
+ ok := cache.Record(Result{LatestVersion: "v0.0.12", ReleaseURL: "new"}, nil, now)
+ if ok.LatestVersion != "v0.0.12" || ok.ReleaseURL != "new" {
+ t.Fatalf("successful record = %#v", ok)
+ }
+}
+
+func TestDisabled(t *testing.T) {
+ for _, tt := range []struct {
+ env map[string]string
+ want bool
+ }{
+ {env: map[string]string{}, want: false},
+ {env: map[string]string{DisableEnv: "1"}, want: false},
+ {env: map[string]string{DisableEnv: "0"}, want: true},
+ {env: map[string]string{DisableEnv: "off"}, want: true},
+ {env: map[string]string{"CI": "true"}, want: true},
+ } {
+ if got := Disabled(func(k string) string { return tt.env[k] }); got != tt.want {
+ t.Fatalf("Disabled(%v) = %v, want %v", tt.env, got, tt.want)
+ }
+ }
+}
diff --git a/docs/cli/version.mdx b/docs/cli/version.mdx
index 131c0e78..21aaa39e 100644
--- a/docs/cli/version.mdx
+++ b/docs/cli/version.mdx
@@ -11,11 +11,25 @@ Display the version number, git commit, and build date of the Agent Beacon CLI,
beacon version
```
-Running `beacon` by itself in an interactive terminal also checks for a newer
-release. When one is available, an orange notice shows the installed and latest
-versions, links to the [CLI changelog](/changelog/cli), and prints the update
-command for the detected installation method. The notice is best-effort and is
-never shown in pipes, redirects, scripts, or other non-interactive commands.
+Running `beacon` by itself in an interactive terminal also tells you when a newer
+release is out. When one is available, an orange notice shows the installed and latest
+versions, links to the [CLI changelog](/changelog/cli), and prints how to update for the
+detected installation: `brew upgrade beacon` for Homebrew,
+`sudo beacon endpoint update --apply` for the system package, and the release download
+for every other install (tarball, `install.sh`, `go install`, the Windows MSI, or a
+source build).
+
+The check works like the update notices in Codex and Claude Code: it never makes
+`beacon` wait on the network. The notice comes from a cached answer in
+`~/.beacon/endpoint/update-check.json`. When that answer is more than a day old,
+`beacon` starts a background lookup of the latest GitHub release, which updates the
+cache for the next run and writes nothing to the terminal. A failed lookup is also
+retried at most once a day. `beacon version check` looks up the release right away and
+refreshes the same cache.
+
+The notice and the background lookup are skipped in pipes, redirects, scripts, other
+commands, CI (`CI` set), and development builds. Set `BEACON_UPDATE_CHECK=0` to turn
+them off; `beacon version check` still works.
<Accordion title="Example output">
```bash title="Example output"