Skip to content

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

fix(writer): decide the retention guard from where its files are now

Clauded71d4a0489a4
diff --git a/cli/beacon/cmd/endpoint_claude.go b/cli/beacon/cmd/endpoint_claude.go
index 0fa4d596..0c858796 100644
--- a/cli/beacon/cmd/endpoint_claude.go
+++ b/cli/beacon/cmd/endpoint_claude.go
@@ -33,7 +33,7 @@ var endpointClaudeSyncCmd = &cobra.Command{
The runtime log keeps the live file plus five archives, 10 MiB each by default, and every
rotation deletes the oldest. A sweep never rotates out its own output: when writing more would
-delete the file holding the sweep's first event, it stops, reports how many sessions are still
+delete a log file holding the sweep's output, it stops, reports how many sessions are still
pending, and leaves their cursors where they were, so the next sweep picks them up. Between
sweeps, ship or copy the log files if you need to keep every event, or backfill a large history
in one sweep with a larger --rotate-bytes.`,
diff --git a/cli/beacon/internal/endpoint/writer/retention.go b/cli/beacon/internal/endpoint/writer/retention.go
index 8b81cfa9..e83808a7 100644
--- a/cli/beacon/internal/endpoint/writer/retention.go
+++ b/cli/beacon/internal/endpoint/writer/retention.go
@@ -8,8 +8,8 @@ import (
"os"
)
-// ErrRetentionWindowFull is returned by a guarded append whose rotation would discard the file
-// holding the guard's first event. Nothing is written or rotated when it is returned.
+// ErrRetentionWindowFull is returned by a guarded append whose rotation would delete a file holding
+// the guard's output. Nothing is written or rotated when it is returned.
var ErrRetentionWindowFull = errors.New("the runtime log's rotation window is full of this run's own output")
// RetentionGuard keeps one run of appends -- a session backfill sweep, say -- from rotating its
@@ -18,13 +18,15 @@ var ErrRetentionWindowFull = errors.New("the runtime log's rotation window is fu
// The log keeps the live file plus a fixed number of archives, and every rotation deletes the
// oldest archive. A run that writes more than that window used to rotate its own first events away
// before it finished, so a backfill of 595,640 events kept 27,550 and still reported success
-// (#619). With a guard, the append whose rotation would delete the file holding the run's first
-// event fails with ErrRetentionWindowFull instead, and the caller can stop where it is and leave
+// (#619). With a guard, the append whose rotation would delete a file holding the run's output
+// fails with ErrRetentionWindowFull instead, and the caller can stop where it is and leave
// the rest for the next run.
//
-// The guard counts the distinct files its appends landed in. That sees rotations by other writers
-// too (the hooks and the collector share the log), but only after the fact: another process can
-// still rotate the window over during the run, which is what Retained reports.
+// The decision is made under the log's lock from where the guard's files actually are, not from how
+// many it has written: the hooks and the collector share the log and can rotate it several times
+// between two guarded appends. A guarded rotation is refused when the archive it would delete holds
+// any of the guard's output. Output another writer has already rotated out cannot be protected;
+// Retained reports it.
//
// The zero value is ready to use. A guard is not safe for concurrent use; give each run its own.
type RetentionGuard struct {
@@ -83,7 +85,7 @@ func (g *RetentionGuard) Retained() int {
continue
}
for i, info := range kept {
- if os.SameFile(s.file, info) && s.firstLineAt(keptPaths[i]) {
+ if s.isFile(keptPaths[i], info) {
n += s.events
break
}
@@ -92,6 +94,11 @@ func (g *RetentionGuard) Retained() int {
return n
}
+// isFile reports whether the file at path, stat'd as info, is the one this segment was written to.
+func (s retentionSegment) isFile(path string, info os.FileInfo) bool {
+ return s.file != nil && os.SameFile(s.file, info) && s.firstLineAt(path)
+}
+
// firstLineAt reports whether path still holds the segment's first line where it was written.
func (s retentionSegment) firstLineAt(path string) bool {
f, err := os.Open(path)
@@ -107,15 +114,31 @@ func (s retentionSegment) firstLineAt(path string) bool {
return bytes.Equal(digest[:], s.digest[:])
}
-// rotationWouldDiscardOwnOutput reports whether a rotation now would delete the file holding the
-// guard's first event. The guard's files are, oldest first, at .N ... .1 and the live path, and a
-// rotation deletes .archives, so once the guard has written into archives+1 files the oldest of
-// them is at .archives. Before the guard's first write there is nothing of its own to lose.
-func (g *RetentionGuard) rotationWouldDiscardOwnOutput(archives int) bool {
+// rotationWouldDiscardOwnOutput reports whether rotating path now would delete a file holding the
+// guard's output. Rotation deletes the archive at .archives (and anything numbered past it, which
+// no reader looks at), so that is the one file to check. Called under the log's lock, so the answer
+// holds for the rotation that follows it.
+func (g *RetentionGuard) rotationWouldDiscardOwnOutput(path string, archives int) (bool, error) {
+ if len(g.segments) == 0 {
+ return false, nil
+ }
if archives < 1 {
archives = DefaultRotateArchives
}
- return len(g.segments) >= archives+1
+ victim := fmt.Sprintf("%s.%d", path, archives)
+ info, err := os.Stat(victim)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return false, nil
+ }
+ return false, err
+ }
+ for _, s := range g.segments {
+ if s.isFile(victim, info) {
+ return true, nil
+ }
+ }
+ return false, nil
}
// record notes one written line. info is the file it was appended to, stat'd after the write under
diff --git a/cli/beacon/internal/endpoint/writer/retention_test.go b/cli/beacon/internal/endpoint/writer/retention_test.go
index ac8d0897..9581dc92 100644
--- a/cli/beacon/internal/endpoint/writer/retention_test.go
+++ b/cli/beacon/internal/endpoint/writer/retention_test.go
@@ -172,3 +172,71 @@ func TestRetentionGuardWithNoWritesRetainsNothing(t *testing.T) {
t.Fatalf("Written()=%d Retained()=%d, want 0 and 0", w, r)
}
}
+
+// Other writers take the log's lock between guarded appends and can rotate several times while a
+// sweep reads its next session. The guard must decide from where its first file actually is now,
+// not from how many files it has written into: here it has written one file, which another writer
+// has already pushed to the last retained slot, so the guarded rotation would delete it.
+func TestRetentionGuardRefusesWhenAnotherWriterMovedItsFirstFileToTheLastSlot(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ guard := &RetentionGuard{}
+ guarded := Options{Path: path, RotateSize: 1, RotateArchives: 2, Guard: guard}
+ other := Options{Path: path, RotateSize: 1, RotateArchives: 2}
+
+ if _, err := AppendEvent(retentionEvent(0), guarded); err != nil {
+ t.Fatal(err)
+ }
+ for i := 100; i < 102; i++ {
+ if _, err := AppendEvent(retentionEvent(i), other); err != nil {
+ t.Fatal(err)
+ }
+ }
+ if data, err := os.ReadFile(path + ".2"); err != nil || !strings.Contains(string(data), "retention event 0\"") {
+ t.Fatalf("fixture: guarded event is not at .2 (err=%v): %q", err, data)
+ }
+
+ if _, err := AppendEvent(retentionEvent(1), guarded); !errors.Is(err, ErrRetentionWindowFull) {
+ t.Fatalf("guarded AppendEvent err = %v, want ErrRetentionWindowFull", err)
+ }
+ if !strings.Contains(retainedText(t, path, 2), "retention event 0\"") {
+ t.Fatal("the guarded append rotated out the guard's own first event")
+ }
+ if got := guard.Retained(); got != 1 {
+ t.Errorf("Retained() = %d, want 1", got)
+ }
+}
+
+// Once another writer has rotated the guard's first file out entirely, there is nothing left of it
+// to protect: the guard keeps writing, reports the loss, and protects what it wrote afterwards.
+func TestRetentionGuardProtectsWhatSurvivesAfterAnotherWriterRotatedItsFirstFileOut(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ guard := &RetentionGuard{}
+ guarded := Options{Path: path, RotateSize: 1, RotateArchives: 2, Guard: guard}
+ other := Options{Path: path, RotateSize: 1, RotateArchives: 2}
+
+ if _, err := AppendEvent(retentionEvent(0), guarded); err != nil {
+ t.Fatal(err)
+ }
+ for i := 100; i < 103; i++ {
+ if _, err := AppendEvent(retentionEvent(i), other); err != nil {
+ t.Fatal(err)
+ }
+ }
+ if _, err := AppendEvent(retentionEvent(1), guarded); err != nil {
+ t.Fatalf("guarded append after the first file was already gone: %v", err)
+ }
+ if w, r := guard.Written(), guard.Retained(); w != 2 || r != 1 {
+ t.Fatalf("Written()=%d Retained()=%d, want 2 and 1", w, r)
+ }
+ for i := 103; i < 105; i++ {
+ if _, err := AppendEvent(retentionEvent(i), other); err != nil {
+ t.Fatal(err)
+ }
+ }
+ if _, err := AppendEvent(retentionEvent(2), guarded); !errors.Is(err, ErrRetentionWindowFull) {
+ t.Fatalf("guarded AppendEvent err = %v, want ErrRetentionWindowFull (event 1 is at .2)", err)
+ }
+ if !strings.Contains(retainedText(t, path, 2), "retention event 1\"") {
+ t.Fatal("the guarded append rotated out the guard's surviving event")
+ }
+}
diff --git a/cli/beacon/internal/endpoint/writer/writer.go b/cli/beacon/internal/endpoint/writer/writer.go
index 55503015..767ac2cd 100644
--- a/cli/beacon/internal/endpoint/writer/writer.go
+++ b/cli/beacon/internal/endpoint/writer/writer.go
@@ -212,8 +212,14 @@ func appendJSONL(path string, line []byte, rotateBytes int64, rotateArchives int
if err != nil {
return err
}
- if rotate && guard.rotationWouldDiscardOwnOutput(rotateArchives) {
- return ErrRetentionWindowFull
+ if rotate {
+ discard, err := guard.rotationWouldDiscardOwnOutput(path, rotateArchives)
+ if err != nil {
+ return err
+ }
+ if discard {
+ return ErrRetentionWindowFull
+ }
}
}
if err := rotateIfNeeded(path, rotateBytes, rotateArchives, int64(len(line))); err != nil {
diff --git a/docs/runtimes/claude-code.mdx b/docs/runtimes/claude-code.mdx
index 42f7e6ce..9bc041fa 100644
--- a/docs/runtimes/claude-code.mdx
+++ b/docs/runtimes/claude-code.mdx
@@ -126,7 +126,7 @@ Run `beacon endpoint claude sync --watch`, or schedule one-shot sweeps, if you w
### Large backfills and log rotation
-The runtime log keeps the live file plus five archives, 10 MiB each, and every rotation deletes the oldest archive. A first sync over a long Claude Code history can produce far more than that window. A sweep never rotates out its own output. When writing the next event would delete the file that holds the sweep's first event, the sweep stops. It leaves the cursors of the remaining sessions (including the one it stopped inside) where they were and exits non-zero:
+The runtime log keeps the live file plus five archives, 10 MiB each, and every rotation deletes the oldest archive. A first sync over a long Claude Code history can produce far more than that window. A sweep never rotates out its own output. When writing the next event would delete a log file that holds the sweep's output, the sweep stops. It decides from where its files are at that moment, so it holds even when the hooks or the collector rotate the log during the sweep. It leaves the cursors of the remaining sessions (including the one it stopped inside) where they were and exits non-zero:
```text
claude sync: 3496 sessions, 168 changed, 33689 events (33689 retained), 0 errors