Skip to content

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

Make confined SQLite snapshots consistent and bounded

Claude5a4097786f34
diff --git a/CLAUDE.md b/CLAUDE.md
index 0d5b04ea..8d8f650e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc
- 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, 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, reads its store only through `internal/sessionfs` (a test parses every collector package to enforce it), and joins `endpointBackfillRunners` and that test's list. 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; root is reading a home the console user controls, so the sweep runs under `sessionfs.Confine` (an `os.Root` on that home, files owned by the home's owner only, non-blocking opens that refuse FIFOs/devices, SQLite read from a private snapshot), and refused paths read as absent and are listed in the report. User-mode sync and backfill stay unconfined. 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`.
+- 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, reads its store only through `internal/sessionfs` (a test parses every collector package to enforce it), and joins `endpointBackfillRunners` and that test's list. 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; root is reading a home the console user controls, so the sweep runs under `sessionfs.Confine` (an `os.Root` on that home, files owned by the home's owner only, non-blocking opens that refuse FIFOs/devices, SQLite read from a private snapshot under `<SystemBaseDir>/state/backfill-snapshots`, retried until the database size/change counter and WAL header are unchanged across the copy, and refused past `sessionfs.MaxSnapshotBytes` (512 MiB with its WAL) with the runtime's sync command named in the report), and refused paths read as absent and are listed in the report. User-mode sync and backfill stay unconfined. 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.
diff --git a/cli/beacon/cmd/endpoint_backfill.go b/cli/beacon/cmd/endpoint_backfill.go
index dfbd2008..3bfc4bf2 100644
--- a/cli/beacon/cmd/endpoint_backfill.go
+++ b/cli/beacon/cmd/endpoint_backfill.go
@@ -5,6 +5,7 @@ import (
"fmt"
"io"
"os"
+ "path/filepath"
"strings"
"time"
@@ -15,6 +16,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/cursorsession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/asymptote"
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/factorysession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/fxsession"
@@ -134,6 +136,13 @@ var endpointBackfillRunners = func() []endpointBackfillRunner {
}
}
+// endpointBackfillScratchDir is where a system backfill copies SQLite stores it reads as root: under
+// the root-owned system base directory, on disk, rather than a /tmp that is often memory-backed. A
+// seam for tests.
+var endpointBackfillScratchDir = func() string {
+ return filepath.Join(endpointconfig.BaseDir(false), "state", "backfill-snapshots")
+}
+
// endpointBackfillNow is time.Now, a seam for tests.
var endpointBackfillNow = time.Now
@@ -144,6 +153,9 @@ type endpointBackfillRuntimeResult struct {
Events int
Limited bool
Err error
+ // Oversized names the databases a system backfill would not copy because they are too large;
+ // Sync, run as the user, reads them in place.
+ Oversized []string
}
// endpointBackfillResult is what one backfill wrote.
@@ -206,7 +218,7 @@ func runEndpointBackfill(logPath string, userMode bool) endpointBackfillResult {
if err != nil {
return endpointBackfillResult{Skipped: fmt.Sprintf("could not read the owner of the console user's home: %v", err)}
}
- confined, err := sessionfs.Confine(info.HomeDir, uid)
+ confined, err := sessionfs.Confine(info.HomeDir, uid, sessionfs.Options{ScratchDir: endpointBackfillScratchDir()})
if err != nil {
return endpointBackfillResult{Skipped: err.Error()}
}
@@ -227,7 +239,7 @@ func sweepEndpointBackfill(logPath string, userMode bool) endpointBackfillResult
// A confined (system) sweep reads SQLite stores through private snapshots; drop each
// runtime's before the next one runs. A no-op otherwise.
sessionfs.DropSnapshots()
- runtime := endpointBackfillRuntimeResult{Name: runner.Name, Sync: runner.Sync, Events: events}
+ runtime := endpointBackfillRuntimeResult{Name: runner.Name, Sync: runner.Sync, Events: events, Oversized: sessionfs.TakeOversized()}
if errors.Is(err, writer.ErrBudgetSpent) || share.Refused() {
runtime.Limited = true
result.Limited = true
@@ -236,7 +248,7 @@ func sweepEndpointBackfill(logPath string, userMode bool) endpointBackfillResult
runtime.Err = err
}
result.Events += events
- if events > 0 || runtime.Limited || runtime.Err != nil {
+ if events > 0 || runtime.Limited || runtime.Err != nil || len(runtime.Oversized) > 0 {
result.Runtimes = append(result.Runtimes, runtime)
}
}
@@ -282,7 +294,12 @@ func reportEndpointBackfill(out io.Writer, result endpointBackfillResult) {
}
fmt.Fprintln(out, line+".")
for _, r := range result.Runtimes {
+ for _, path := range r.Oversized {
+ fmt.Fprintf(out, " %s: %s is too large for a system backfill to copy; run `%s` as the console user to read it.\n", r.Name, path, r.Sync)
+ }
switch {
+ case r.Err != nil && len(r.Oversized) > 0:
+ // The error is the collector failing to open the store named just above.
case r.Err != nil:
fmt.Fprintf(out, " %s: %v; retry with `%s`.\n", r.Name, r.Err, r.Sync)
case r.Limited:
@@ -319,7 +336,7 @@ func reportEndpointBackfillRefusals(out io.Writer, result endpointBackfillResult
if result.Refused == 0 {
return
}
- fmt.Fprintf(out, " Skipped %d session store path(s) a system backfill does not read as root (links leading out of the console user's home, files that user does not own, or special files):\n", result.Refused)
+ fmt.Fprintf(out, " Skipped %d session store path(s) a system backfill does not read as root (links leading out of the console user's home, files that user does not own, special files, or stores too large to copy):\n", result.Refused)
for _, example := range result.RefusedExamples {
fmt.Fprintf(out, " %s\n", example)
}
diff --git a/cli/beacon/cmd/endpoint_backfill_confined_test.go b/cli/beacon/cmd/endpoint_backfill_confined_test.go
index 31dcb6fc..7c7b8bce 100644
--- a/cli/beacon/cmd/endpoint_backfill_confined_test.go
+++ b/cli/beacon/cmd/endpoint_backfill_confined_test.go
@@ -11,6 +11,67 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionfs"
)
+// A store too large for the system backfill to copy is named with the sync command that reads it
+// in place, and the stores it does copy go under the system base directory, not /tmp.
+func TestSystemEndpointBackfillNamesTheSyncForAStoreTooLargeToCopy(t *testing.T) {
+ home := t.TempDir()
+ big := filepath.Join(home, ".cursor", "state.vscdb")
+ if err := os.MkdirAll(filepath.Dir(big), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ f, err := os.Create(big)
+ if err != nil {
+ t.Fatal(err)
+ }
+ // Sparse: past the cap by size, nearly nothing on disk, and refused before any byte is copied.
+ if err := f.Truncate(sessionfs.MaxSnapshotBytes + 1); err != nil {
+ t.Fatal(err)
+ }
+ f.Close()
+ small := filepath.Join(home, ".hermes", "state.db")
+ if err := os.MkdirAll(filepath.Dir(small), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(small, []byte("small"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+
+ var bigErr error
+ var smallSnap string
+ stubBackfill(t, 1<<20, 1<<20,
+ endpointBackfillRunner{Name: "Cursor", Sync: "beacon endpoint cursor sync", Run: func(endpointBackfillRun) (int, error) {
+ _, bigErr = sessionfs.SQLitePath(big)
+ return 0, bigErr
+ }},
+ endpointBackfillRunner{Name: "Hermes Agent", Sync: "beacon endpoint hermes sync", Run: func(endpointBackfillRun) (int, error) {
+ var err error
+ smallSnap, err = sessionfs.SQLitePath(small)
+ return 0, err
+ }},
+ )
+ scratch := endpointBackfillScratchDir()
+ stubConsoleUser(t, consoleUserInfo{Username: "alice", HomeDir: home}, true, nil)
+
+ var out strings.Builder
+ reportEndpointBackfill(&out, runEndpointBackfill(filepath.Join(t.TempDir(), "runtime.jsonl"), false))
+ if !os.IsNotExist(bigErr) {
+ t.Fatalf("an oversized store was opened: %v", bigErr)
+ }
+ want := " Cursor: " + big + " is too large for a system backfill to copy; run `beacon endpoint cursor sync` as the console user to read it."
+ if !strings.Contains(out.String(), want) {
+ t.Fatalf("report does not name the sync command:\n%s", out.String())
+ }
+ if strings.Contains(out.String(), "retry with `beacon endpoint cursor sync`") {
+ t.Fatalf("report also lists the oversized store as a failure:\n%s", out.String())
+ }
+ if !strings.HasPrefix(smallSnap, scratch+string(filepath.Separator)) {
+ t.Fatalf("snapshot %s is not under the system scratch directory %s", smallSnap, scratch)
+ }
+ if left, _ := os.ReadDir(scratch); len(left) != 0 {
+ t.Fatalf("snapshots survived the backfill: %v", left)
+ }
+}
+
// A system backfill reads the console user's home as root, so it confines every store read to that
// home and to files that user owns; a user backfill reads the user's own home unconfined.
func TestSystemEndpointBackfillConfinesReadsToTheConsoleUsersHome(t *testing.T) {
diff --git a/cli/beacon/cmd/endpoint_backfill_test.go b/cli/beacon/cmd/endpoint_backfill_test.go
index d4b49e34..1276671d 100644
--- a/cli/beacon/cmd/endpoint_backfill_test.go
+++ b/cli/beacon/cmd/endpoint_backfill_test.go
@@ -30,6 +30,10 @@ func stubBackfill(t *testing.T, maxBytes, shareBytes int64, runners ...endpointB
endpointBackfillRunners = func() []endpointBackfillRunner { return runners }
endpointBackfillMaxBytes, endpointBackfillShareBytes = maxBytes, shareBytes
endpointBackfillNow = func() time.Time { return time.Date(2026, 10, 5, 12, 0, 0, 0, time.UTC) }
+ oldScratch := endpointBackfillScratchDir
+ t.Cleanup(func() { endpointBackfillScratchDir = oldScratch })
+ scratch := filepath.Join(t.TempDir(), "backfill-snapshots")
+ endpointBackfillScratchDir = func() string { return scratch }
}
func writingRunner(name string, events int, since *time.Time) endpointBackfillRunner {
diff --git a/cli/beacon/internal/claudesession/confined_test.go b/cli/beacon/internal/claudesession/confined_test.go
index 31dec141..493c784e 100644
--- a/cli/beacon/internal/claudesession/confined_test.go
+++ b/cli/beacon/internal/claudesession/confined_test.go
@@ -33,7 +33,7 @@ func TestConfinedCollectSkipsWhatTheConsoleUserPlanted(t *testing.T) {
t.Fatalf("mkfifo: %v", err)
}
- confined, err := sessionfs.Confine(home, os.Getuid())
+ confined, err := sessionfs.Confine(home, os.Getuid(), sessionfs.Options{})
if err != nil {
t.Fatal(err)
}
@@ -78,7 +78,7 @@ func TestConfinedCollectReadsNothingThroughALinkedStore(t *testing.T) {
if err := os.Symlink(filepath.Join(outside, ".claude"), filepath.Join(home, ".claude")); err != nil {
t.Fatal(err)
}
- confined, err := sessionfs.Confine(home, os.Getuid())
+ confined, err := sessionfs.Confine(home, os.Getuid(), sessionfs.Options{})
if err != nil {
t.Fatal(err)
}
diff --git a/cli/beacon/internal/sessionfs/sessionfs.go b/cli/beacon/internal/sessionfs/sessionfs.go
index 9c915880..056795cd 100644
--- a/cli/beacon/internal/sessionfs/sessionfs.go
+++ b/cli/beacon/internal/sessionfs/sessionfs.go
@@ -55,13 +55,24 @@ type Confinement struct {
// snapshots maps a database path to its copy, so a store that opens one database several times
// copies it once.
snapshots map[string]string
+ // scratchParent is where snapshot directories are made; empty means os.TempDir().
+ scratchParent string
+ // oversized lists databases refused as too large to snapshot, until TakeOversized.
+ oversized []string
+}
+
+// Options configures a confinement.
+type Options struct {
+ // ScratchDir is the parent of the private directory SQLite snapshots are copied into. It
+ // should be root-owned and on disk; empty means os.TempDir().
+ ScratchDir string
}
var active atomic.Pointer[Confinement]
// Confine confines every read through this package to home, admitting only files owned by uid (a
// negative uid skips the ownership check), until Release. Only one confinement can be active.
-func Confine(home string, uid int) (*Confinement, error) {
+func Confine(home string, uid int, opts Options) (*Confinement, error) {
home = strings.TrimSpace(home)
if home == "" || !filepath.IsAbs(home) {
return nil, fmt.Errorf("confine session reads: home %q is not an absolute path", home)
@@ -71,7 +82,7 @@ func Confine(home string, uid int) (*Confinement, error) {
if err != nil {
return nil, fmt.Errorf("confine session reads to %s: %w", home, err)
}
- c := &Confinement{home: home, root: root, uid: uid}
+ c := &Confinement{home: home, root: root, uid: uid, scratchParent: opts.ScratchDir}
if !active.CompareAndSwap(nil, c) {
_ = root.Close()
return nil, errors.New("confine session reads: a confinement is already active")
@@ -325,8 +336,14 @@ func WalkDir(root string, fn fs.WalkDirFunc) error {
// Unconfined it is path itself. Confined, the driver cannot be trusted with the user's path: it
// opens it, and its -wal and -shm files, by name, following any symlink, and in read-only mode it
// still creates a -shm file beside the database. So the database and its -wal file are read through
-// the confinement into a private directory, and the driver opens that copy; DropSnapshots removes
-// it. A WAL file that is refused is left out, which loses at most the writes not yet checkpointed.
+// the confinement into the confinement's private scratch directory, and the driver opens that copy;
+// DropSnapshots removes it. A WAL file that is refused is left out, which loses at most the writes
+// not yet checkpointed.
+//
+// The copy is checked for consistency (see snapshotFingerprint) and retried while the runtime keeps
+// changing the store underneath it. A database that does not settle, or that with its WAL is larger
+// than MaxSnapshotBytes, is refused like an unreadable store; an oversized one is also reported by
+// TakeOversized so the backfill can name the sync command that reads it in place.
func SQLitePath(path string) (string, error) {
c := active.Load()
if c == nil {
@@ -335,6 +352,64 @@ func SQLitePath(path string) (string, error) {
return c.snapshotSQLite(path)
}
+// MaxSnapshotBytes caps a database plus its WAL that a confined read copies. The whole backfill
+// writes at most 24 MiB of events and a runtime at most 12 MiB, so a store past this size is mostly
+// data the window does not need (Cursor's global state.vscdb carries editor state for every
+// workspace and can reach gigabytes). Copying it would cost that much disk under the system base
+// directory for a few megabytes of events; the user's own sync reads it in place instead.
+const MaxSnapshotBytes = 512 << 20
+
+// Snapshot tuning, variables so tests can make them small or observe the copy.
+var (
+ maxSnapshotBytes int64 = MaxSnapshotBytes
+ // snapshotAttempts is how many times a copy is retried while the store keeps changing.
+ snapshotAttempts = 4
+ // betweenSnapshotCopies runs after the database is copied and before its WAL is; a test seam
+ // for a checkpoint landing between the two copies.
+ betweenSnapshotCopies = func(string) {}
+)
+
+// errSnapshotUnstable reports a store that changed during every copy attempt.
+var errSnapshotUnstable = errors.New("changed during every copy attempt")
+
+// snapshotFingerprint is what a copy of a database and its WAL must not see change.
+//
+// A WAL database copied as two files is consistent as long as the WAL was not restarted between
+// the copies: a checkpoint only writes into the database pages the WAL still holds and overrides,
+// and frames appended after the database was copied are either complete (a newer, consistent
+// state) or fail their checksum and are ignored. A restart rewrites the WAL header with new salts
+// and a new checkpoint sequence, so the 32-byte header catches it. A rollback-journal database is
+// rewritten in place on every commit, which bumps the file change counter at offset 24 of its
+// header; the size catches truncation by a checkpoint or a VACUUM.
+type snapshotFingerprint struct {
+ dbSize int64
+ dbCounter [4]byte
+ walExists bool
+ walHeader [32]byte
+}
+
+func (c *Confinement) fingerprint(db *os.File, path string) (snapshotFingerprint, error) {
+ var fp snapshotFingerprint
+ info, err := db.Stat()
+ if err != nil {
+ return fp, err
+ }
+ fp.dbSize = info.Size()
+ if _, err := db.ReadAt(fp.dbCounter[:], 24); err != nil && !errors.Is(err, io.EOF) {
+ return fp, err
+ }
+ wal, err := c.open("open", path+"-wal")
+ if err != nil {
+ return fp, nil
+ }
+ defer wal.Close()
+ fp.walExists = true
+ if _, err := wal.ReadAt(fp.walHeader[:], 0); err != nil && !errors.Is(err, io.EOF) {
+ return fp, err
+ }
+ return fp, nil
+}
+
func (c *Confinement) snapshotSQLite(path string) (string, error) {
c.mu.Lock()
cached, ok := c.snapshots[path]
@@ -356,37 +431,125 @@ func (c *Confinement) snapshotSQLite(path string) (string, error) {
if err != nil {
return "", err
}
- target, err := os.MkdirTemp(dir, "db-")
- if err != nil {
- return "", err
- }
- copyPath := filepath.Join(target, filepath.Base(path))
- if err := copyInto(copyPath, src); err != nil {
- return "", err
- }
- if wal, err := c.open("open", path+"-wal"); err == nil {
- err = copyInto(copyPath+"-wal", wal)
- _ = wal.Close()
+ for attempt := 0; attempt < snapshotAttempts; attempt++ {
+ before, err := c.fingerprint(src, path)
+ if err != nil {
+ return "", c.failed("open", path, err)
+ }
+ size := before.dbSize
+ if before.walExists {
+ if wal, err := c.root.Stat(mustRel(c, path+"-wal")); err == nil {
+ size += wal.Size()
+ }
+ }
+ if size > maxSnapshotBytes {
+ return "", c.oversize(path, size)
+ }
+ target, err := os.MkdirTemp(dir, "db-")
if err != nil {
return "", err
}
+ copyPath := filepath.Join(target, filepath.Base(path))
+ copied, err := c.copySnapshot(src, path, copyPath)
+ if errors.Is(err, errSnapshotTooLarge) {
+ _ = os.RemoveAll(target)
+ return "", c.oversize(path, copied)
+ }
+ if err != nil {
+ _ = os.RemoveAll(target)
+ return "", c.failed("open", path, err)
+ }
+ after, err := c.fingerprint(src, path)
+ if err == nil && after == before {
+ c.mu.Lock()
+ if c.snapshots == nil {
+ c.snapshots = map[string]string{}
+ }
+ c.snapshots[path] = copyPath
+ c.mu.Unlock()
+ return copyPath, nil
+ }
+ _ = os.RemoveAll(target)
}
- c.mu.Lock()
- if c.snapshots == nil {
- c.snapshots = map[string]string{}
+ return "", c.refuse("open", path, errSnapshotUnstable.Error())
+}
+
+// mustRel is rel for a path already known to be inside the home.
+func mustRel(c *Confinement, path string) string {
+ rel, _ := c.rel(path)
+ return rel
+}
+
+var errSnapshotTooLarge = errors.New("snapshot over the size limit")
+
+// copySnapshot copies the database and then its WAL, if there is one the confinement admits,
+// stopping once the two together pass maxSnapshotBytes. It reports how many bytes it copied.
+func (c *Confinement) copySnapshot(src *os.File, path, copyPath string) (int64, error) {
+ remaining := maxSnapshotBytes
+ n, err := copyInto(copyPath, io.NewSectionReader(src, 0, remaining+1))
+ if err != nil {
+ return n, err
+ }
+ if n > remaining {
+ return n, errSnapshotTooLarge
+ }
+ remaining -= n
+ betweenSnapshotCopies(path)
+ wal, err := c.open("open", path+"-wal")
+ if err != nil {
+ return n, nil
+ }
+ defer wal.Close()
+ w, err := copyInto(copyPath+"-wal", io.NewSectionReader(wal, 0, remaining+1))
+ n += w
+ if err != nil {
+ return n, err
+ }
+ if w > remaining {
+ return n, errSnapshotTooLarge
}
- c.snapshots[path] = copyPath
+ return n, nil
+}
+
+// oversize refuses a store too large to snapshot and remembers it for TakeOversized.
+func (c *Confinement) oversize(path string, size int64) error {
+ c.mu.Lock()
+ c.oversized = append(c.oversized, path)
c.mu.Unlock()
- return copyPath, nil
+ return c.refuse("open", path, fmt.Sprintf("%.1f MiB with its WAL, over the %.1f MiB a system backfill copies", float64(size)/(1<<20), float64(maxSnapshotBytes)/(1<<20)))
+}
+
+// TakeOversized returns, and forgets, the databases refused since the last call because they were
+// too large to snapshot. The backfill calls it after each runtime to name that runtime's sync
+// command, which reads the store in place as the user. Nil when unconfined.
+func TakeOversized() []string {
+ c := active.Load()
+ if c == nil {
+ return nil
+ }
+ c.mu.Lock()
+ defer c.mu.Unlock()
+ out := c.oversized
+ c.oversized = nil
+ return out
}
+// snapshotDir creates the confinement's scratch directory: a fresh 0700 directory under the
+// configured parent (Options.ScratchDir, which the system backfill puts under the root-owned system
+// base directory rather than a possibly memory-backed /tmp), or under os.TempDir() when none is set.
func (c *Confinement) snapshotDir() (string, error) {
c.mu.Lock()
defer c.mu.Unlock()
if c.scratch != "" {
return c.scratch, nil
}
- dir, err := os.MkdirTemp("", "beacon-backfill-sqlite-")
+ parent := c.scratchParent
+ if parent == "" {
+ parent = os.TempDir()
+ } else if err := os.MkdirAll(parent, 0o700); err != nil {
+ return "", fmt.Errorf("create SQLite snapshot directory: %w", err)
+ }
+ dir, err := os.MkdirTemp(parent, "beacon-backfill-sqlite-")
if err != nil {
return "", fmt.Errorf("create SQLite snapshot directory: %w", err)
}
@@ -394,14 +557,15 @@ func (c *Confinement) snapshotDir() (string, error) {
return dir, nil
}
-func copyInto(path string, src *os.File) error {
+func copyInto(path string, src io.Reader) (int64, error) {
dst, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
if err != nil {
- return err
+ return 0, err
}
- if _, err := io.Copy(dst, src); err != nil {
+ n, err := io.Copy(dst, src)
+ if err != nil {
_ = dst.Close()
- return err
+ return n, err
}
- return dst.Close()
+ return n, dst.Close()
}
diff --git a/cli/beacon/internal/sessionfs/sessionfs_unix_test.go b/cli/beacon/internal/sessionfs/sessionfs_unix_test.go
index ca36e785..3b36222f 100644
--- a/cli/beacon/internal/sessionfs/sessionfs_unix_test.go
+++ b/cli/beacon/internal/sessionfs/sessionfs_unix_test.go
@@ -44,7 +44,7 @@ func mustWrite(t *testing.T, path, data string) {
func confine(t *testing.T, home string, uid int) *Confinement {
t.Helper()
- c, err := Confine(home, uid)
+ c, err := Confine(home, uid, Options{})
if err != nil {
t.Fatalf("Confine: %v", err)
}
@@ -278,7 +278,7 @@ func TestConfinedSQLiteGoesThroughASnapshot(t *testing.T) {
t.Fatalf("snapshot survived DropSnapshots: %v", err)
}
c.Release()
- if _, err := Confine(f.home, os.Getuid()); err != nil {
+ if _, err := Confine(f.home, os.Getuid(), Options{}); err != nil {
t.Fatalf("Release left the confinement active: %v", err)
} else {
active.Load().Release()
@@ -288,7 +288,7 @@ func TestConfinedSQLiteGoesThroughASnapshot(t *testing.T) {
func TestOnlyOneConfinementAtATime(t *testing.T) {
f := newFixture(t)
confine(t, f.home, os.Getuid())
- if _, err := Confine(t.TempDir(), os.Getuid()); err == nil {
+ if _, err := Confine(t.TempDir(), os.Getuid(), Options{}); err == nil {
t.Fatal("a second confinement replaced the first")
}
}
diff --git a/cli/beacon/internal/sessionfs/snapshot_unix_test.go b/cli/beacon/internal/sessionfs/snapshot_unix_test.go
new file mode 100644
index 00000000..44aecc30
--- /dev/null
+++ b/cli/beacon/internal/sessionfs/snapshot_unix_test.go
@@ -0,0 +1,178 @@
+//go:build !windows
+
+package sessionfs
+
+import (
+ "database/sql"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ _ "modernc.org/sqlite"
+)
+
+// walStore is a WAL-mode database whose rows sit in the WAL, never checkpointed, with the writer
+// connection kept open so a test can checkpoint and write while a snapshot is being taken.
+func walStore(t *testing.T, home string) (string, *sql.DB) {
+ t.Helper()
+ path := filepath.Join(home, ".local", "share", "opencode", "opencode.db")
+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ db, err := sql.Open("sqlite", "file:"+path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { db.Close() })
+ db.SetMaxOpenConns(1)
+ exec(t, db, `PRAGMA journal_mode=WAL`, `PRAGMA wal_autocheckpoint=0`, `CREATE TABLE messages (body TEXT)`, `INSERT INTO messages VALUES ('a')`)
+ return path, db
+}
+
+func exec(t *testing.T, db *sql.DB, stmts ...string) {
+ t.Helper()
+ for _, stmt := range stmts {
+ if _, err := db.Exec(stmt); err != nil {
+ t.Fatalf("%s: %v", stmt, err)
+ }
+ }
+}
+
+// checkpointAndWrite is the race the snapshot must survive: everything moves from the WAL into the
+// database, the WAL restarts with new salts, and a new row lands in the fresh WAL. A copy of the old
+// database paired with the new WAL has neither the table nor its first row.
+func checkpointAndWrite(t *testing.T, db *sql.DB, body string) {
+ exec(t, db, `PRAGMA wal_checkpoint(TRUNCATE)`, `INSERT INTO messages VALUES ('`+body+`')`)
+}
+
+func withBetweenCopies(t *testing.T, fn func(string)) {
+ t.Helper()
+ old := betweenSnapshotCopies
+ t.Cleanup(func() { betweenSnapshotCopies = old })
+ betweenSnapshotCopies = fn
+}
+
+func readBodies(t *testing.T, path string) []string {
+ t.Helper()
+ db, err := sql.Open("sqlite", "file:"+path+"?mode=ro")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer db.Close()
+ rows, err := db.Query(`SELECT body FROM messages ORDER BY rowid`)
+ if err != nil {
+ t.Fatalf("snapshot is not a consistent database: %v", err)
+ }
+ defer rows.Close()
+ var out []string
+ for rows.Next() {
+ var body string
+ if err := rows.Scan(&body); err != nil {
+ t.Fatal(err)
+ }
+ out = append(out, body)
+ }
+ return out
+}
+
+func TestSQLiteSnapshotRetriesWhenTheWALRestartsBetweenCopies(t *testing.T) {
+ home := t.TempDir()
+ path, db := walStore(t, home)
+ calls := 0
+ withBetweenCopies(t, func(string) {
+ calls++
+ if calls == 1 {
+ checkpointAndWrite(t, db, "b")
+ }
+ })
+ confine(t, home, os.Getuid())
+
+ snap, err := SQLitePath(path)
+ if err != nil {
+ t.Fatalf("SQLitePath: %v", err)
+ }
+ if calls != 2 {
+ t.Fatalf("copied %d times, want a retry after the WAL restarted", calls)
+ }
+ if got := readBodies(t, snap); strings.Join(got, ",") != "a,b" {
+ t.Fatalf("snapshot rows = %v, want a,b", got)
+ }
+}
+
+func TestSQLiteSnapshotThatNeverSettlesIsRefused(t *testing.T) {
+ home := t.TempDir()
+ path, db := walStore(t, home)
+ calls := 0
+ withBetweenCopies(t, func(string) {
+ calls++
+ checkpointAndWrite(t, db, "busy")
+ })
+ c := confine(t, home, os.Getuid())
+
+ _, err := SQLitePath(path)
+ requireRefusedAsAbsent(t, "a store that changes during every copy", err)
+ if calls != snapshotAttempts {
+ t.Fatalf("copied %d times, want %d attempts", calls, snapshotAttempts)
+ }
+ if n, examples := c.Refused(); n != 1 || !strings.Contains(examples[0], "changed during every copy attempt") {
+ t.Fatalf("refusals = %d %v", n, examples)
+ }
+ if left, _ := filepath.Glob(filepath.Join(c.scratch, "db-*")); len(left) != 0 {
+ t.Fatalf("failed attempts left copies behind: %v", left)
+ }
+}
+
+func TestSQLiteSnapshotRefusesAStoreOverTheSizeCap(t *testing.T) {
+ old := maxSnapshotBytes
+ t.Cleanup(func() { maxSnapshotBytes = old })
+ maxSnapshotBytes = 64 << 10
+
+ home := t.TempDir()
+ big := filepath.Join(home, ".cursor", "state.vscdb")
+ mustWrite(t, big, strings.Repeat("x", 80<<10))
+ walHeavy := filepath.Join(home, ".hermes", "state.db")
+ mustWrite(t, walHeavy, strings.Repeat("x", 40<<10))
+ mustWrite(t, walHeavy+"-wal", strings.Repeat("w", 40<<10))
+ small := filepath.Join(home, ".local", "share", "opencode", "opencode.db")
+ mustWrite(t, small, "small")
+
+ scratch := filepath.Join(t.TempDir(), "state", "backfill-snapshots")
+ c, err := Confine(home, os.Getuid(), Options{ScratchDir: scratch})
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(c.Release)
+
+ for _, path := range []string{big, walHeavy} {
+ _, err := SQLitePath(path)
+ requireRefusedAsAbsent(t, path, err)
+ }
+ if got := TakeOversized(); len(got) != 2 || got[0] != big || got[1] != walHeavy {
+ t.Fatalf("TakeOversized = %v", got)
+ }
+ if got := TakeOversized(); len(got) != 0 {
+ t.Fatalf("TakeOversized did not forget: %v", got)
+ }
+ if _, examples := c.Refused(); len(examples) != 2 || !strings.Contains(examples[0], "a system backfill copies") {
+ t.Fatalf("refusal reason = %v", examples)
+ }
+
+ // A store under the cap is copied into the configured scratch directory, private to root.
+ snap, err := SQLitePath(small)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.HasPrefix(snap, scratch+string(filepath.Separator)) {
+ t.Fatalf("snapshot %s is not under the scratch directory %s", snap, scratch)
+ }
+ for _, dir := range []string{scratch, c.scratch} {
+ if info, err := os.Stat(dir); err != nil || info.Mode().Perm() != 0o700 {
+ t.Fatalf("%s: %v %v, want a 0700 directory", dir, info, err)
+ }
+ }
+ DropSnapshots()
+ if left, _ := os.ReadDir(scratch); len(left) != 0 {
+ t.Fatalf("DropSnapshots left %v", left)
+ }
+}
diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdx
index 1c9c3c38..f1833693 100644
--- a/docs/cli/endpoint-install.mdx
+++ b/docs/cli/endpoint-install.mdx
@@ -83,7 +83,9 @@ the active session on Windows). Its collector cursors stay under the system base
root is reading a home that user controls, the read is confined to that home: a link that leads out
of it, a file the user does not own (including a hard link to someone else's), and a FIFO, socket or
device are skipped rather than read, and install lists what it skipped. SQLite stores are read from
-a private copy. A manual `beacon endpoint <runtime> sync` run as the user is not confined. When
+a private copy under the system base directory, retaken if the runtime rewrites its write-ahead log
+mid-copy; a database larger than 512 MiB with its log is not copied, and install names the
+runtime's sync command to run as the user instead. A manual `beacon endpoint <runtime> sync` run as the user is not confined. When
nobody is logged in, install says the backfill was skipped and the next connect or manual sync
reads the sessions. `--dry-run` installs skip it, and `--no-backfill` or `BEACON_BACKFILL=0` turn it
off. If this install also connects to Beacon Cloud, the same history is