Skip to content

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

fix(inventory): keep the snapshot digest stable across identical scans (#1062)

Rudy Mizrahi Celeklicff7076181c0
diff --git a/cli/beacon/internal/endpoint/inventory/heartbeat.go b/cli/beacon/internal/endpoint/inventory/heartbeat.go
index 3537932b..562ab0f5 100644
--- a/cli/beacon/internal/endpoint/inventory/heartbeat.go
+++ b/cli/beacon/internal/endpoint/inventory/heartbeat.go
@@ -6,6 +6,7 @@ import (
"encoding/json"
"os"
"path/filepath"
+ "slices"
"strings"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
@@ -162,16 +163,19 @@ func CountsFor(result Result) Counts {
}
}
+// SnapshotDigest identifies what is on the machine, not how the scan listed it: each list is
+// digested as the sorted hashes of its entries, so no ordering upstream (map iteration, directory
+// walks, a sort with ties) can make an unchanged machine look changed.
func SnapshotDigest(result Result) string {
payload := struct {
- Configs []Config `json:"configs"`
- MCPServers []MCPServer `json:"mcp_servers"`
- Skills []Skill `json:"skills"`
- UserScope UserScope `json:"user_scope"`
+ Configs []string `json:"configs"`
+ MCPServers []string `json:"mcp_servers"`
+ Skills []string `json:"skills"`
+ UserScope UserScope `json:"user_scope"`
}{
- Configs: digestConfigs(existingConfigs(result.Configs)),
- MCPServers: result.MCPServers,
- Skills: existingSkills(result.Skills),
+ Configs: entryHashes(digestConfigs(existingConfigs(result.Configs))),
+ MCPServers: entryHashes(result.MCPServers),
+ Skills: entryHashes(existingSkills(result.Skills)),
UserScope: result.UserScope,
}
data, err := json.Marshal(payload)
@@ -182,6 +186,22 @@ func SnapshotDigest(result Result) string {
return "sha256:" + hex.EncodeToString(sum[:])
}
+// entryHashes returns the sorted SHA-256 of each entry's JSON. An entry that cannot be encoded
+// cannot be one of the inventory types, so it is hashed by its position rather than dropped.
+func entryHashes[T any](entries []T) []string {
+ hashes := make([]string, len(entries))
+ for i, entry := range entries {
+ data, err := json.Marshal(entry)
+ if err != nil {
+ data = []byte(err.Error())
+ }
+ sum := sha256.Sum256(data)
+ hashes[i] = hex.EncodeToString(sum[:])
+ }
+ slices.Sort(hashes)
+ return hashes
+}
+
// digestConfigs strips the raw-file fingerprint from volatile runtime state files so the digest
// reflects inventory (which files exist, what they parse to, which MCP servers they declare) and
// not the runtime's own bookkeeping. ~/.claude.json is rewritten by Claude Code on every session;
diff --git a/cli/beacon/internal/endpoint/inventory/inventory.go b/cli/beacon/internal/endpoint/inventory/inventory.go
index ef9ff086..1cbd4211 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory.go
@@ -991,6 +991,9 @@ func dedupeServers(servers []MCPServer) []MCPServer {
sort.Slice(out, func(i, j int) bool {
if out[i].Runtime == out[j].Runtime {
if out[i].SourcePathHash == out[j].SourcePathHash {
+ if out[i].ServerNameHash == out[j].ServerNameHash {
+ return out[i].DefinitionHash < out[j].DefinitionHash
+ }
return out[i].ServerNameHash < out[j].ServerNameHash
}
return out[i].SourcePathHash < out[j].SourcePathHash
diff --git a/cli/beacon/internal/endpoint/inventory/inventory_test.go b/cli/beacon/internal/endpoint/inventory/inventory_test.go
index 51b0d7c7..0993a992 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory_test.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory_test.go
@@ -5,6 +5,7 @@ import (
"os"
"path/filepath"
"runtime"
+ "slices"
"strings"
"testing"
"time"
@@ -1283,6 +1284,49 @@ func TestStateDigestFallsBackToTheLegacyFieldThenTracksPerHome(t *testing.T) {
}
}
+// Claude Code keeps per-project servers in ~/.claude.json, and the same server name in several
+// projects with different arguments is ordinary. Those entries share runtime, file and name, so
+// their order must not come from map iteration or the digest moves between identical scans.
+func TestSnapshotDigestStableForSameServerNameAcrossProjects(t *testing.T) {
+ home := t.TempDir()
+ writeFile(t, filepath.Join(home, ".claude.json"), `{"projects":{
+ "/w/a":{"mcpServers":{"fs":{"command":"npx","args":["/w/a"]}}},
+ "/w/b":{"mcpServers":{"fs":{"command":"npx","args":["/w/b"]}}},
+ "/w/c":{"mcpServers":{"fs":{"command":"npx","args":["/w/c"]}}},
+ "/w/d":{"mcpServers":{"fs":{"command":"npx","args":["/w/d"]}}}}}`)
+ seen := map[string]bool{}
+ for i := 0; i < 40; i++ {
+ seen[SnapshotDigest(Scan(Options{HomeDir: home, SkipProjectScope: true, Runtimes: []string{"claude_code"}, Now: fixedNow}))] = true
+ }
+ if len(seen) != 1 {
+ t.Fatalf("%d distinct digests over 40 scans of an unchanged home", len(seen))
+ }
+}
+
+// The digest names what is installed, so listing the same entries in another order is the same
+// snapshot, and changing one entry is a different one.
+func TestSnapshotDigestIgnoresListOrder(t *testing.T) {
+ home := t.TempDir()
+ writeFile(t, filepath.Join(home, ".claude.json"), `{"mcpServers":{"a":{"command":"npx"},"b":{"command":"uvx"},"c":{"url":"https://c"}}}`)
+ result := Scan(Options{HomeDir: home, SkipProjectScope: true, Runtimes: []string{"claude_code"}, Now: fixedNow})
+ if len(result.MCPServers) < 3 {
+ t.Fatalf("scan found %d servers, want 3", len(result.MCPServers))
+ }
+ want := SnapshotDigest(result)
+ reordered := result
+ reordered.MCPServers = slices.Clone(result.MCPServers)
+ reordered.Configs = slices.Clone(result.Configs)
+ slices.Reverse(reordered.MCPServers)
+ slices.Reverse(reordered.Configs)
+ if got := SnapshotDigest(reordered); got != want {
+ t.Fatalf("reordered lists changed the digest: %s, want %s", got, want)
+ }
+ reordered.MCPServers[0].DefinitionHash += "x"
+ if SnapshotDigest(reordered) == want {
+ t.Fatal("a changed server definition kept the digest")
+ }
+}
+
// ~/.claude.json is Claude Code's state file and changes on every session. Its raw hash must not
// move the digest; the MCP servers parsed from it must.
func TestSnapshotDigestIgnoresVolatileStateFileChurn(t *testing.T) {