Skip to content

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

Stop --follow at an end the runtime log records; report read failures

Claudec1219e42b492
diff --git a/cli/beacon/cmd/share_follow.go b/cli/beacon/cmd/share_follow.go
index 2151c5fe..35777d00 100644
--- a/cli/beacon/cmd/share_follow.go
+++ b/cli/beacon/cmd/share_follow.go
@@ -16,6 +16,7 @@ import (
"github.com/spf13/cobra"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/account"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/handoff"
)
// `beacon share --follow` keeps a shared trace current while its session runs: it re-reads the
@@ -30,6 +31,9 @@ const (
// shareFollowFinalRetries bounds how many more times --follow tries to upload a session's last
// messages after the session ended, one interval apart, before it gives up with an error.
shareFollowFinalRetries = 3
+ // shareFollowMaxReadFailures is how many polls in a row may fail to read the session, after
+ // the first upload, before --follow gives up with an error.
+ shareFollowMaxReadFailures = 5
)
var (
@@ -78,17 +82,43 @@ func runShareFollow(cmd *cobra.Command, client *account.ShareClient, subject sha
finalFailures int
finalErr error
)
+ var (
+ readFailures int
+ lastReadWarn string
+ )
for {
+ var readErr error
if subject.fromLog {
// A session read from the runtime log is re-read each time; one from a store is read
// fresh by buildSharePayload anyway.
if fresh, err := resolveShareLog(subject.session); err == nil {
fresh.selectedBy = subject.selectedBy
subject = fresh
+ } else {
+ readErr = err
}
}
fingerprint, end, err := shareFollowState(subject)
ended = end
+ if readErr == nil && err != nil && !errors.Is(err, errShareNothingYet) {
+ readErr = err
+ }
+ if uploads > 0 {
+ // After the first upload a read failure is not fatal at once (a store or log being
+ // rewritten under us), but it is never silent, and it is not retried forever.
+ if readErr != nil {
+ readFailures++
+ if readFailures >= shareFollowMaxReadFailures {
+ return fmt.Errorf("stopped following: the session could not be read %d times in a row (%s holds %d messages): %w", readFailures, last.SharedURL, last.MessageCount, readErr)
+ }
+ if msg := readErr.Error(); msg != lastReadWarn {
+ fmt.Fprintf(errOut, "warning: could not read the session, retrying in %s: %v\n", interval, readErr)
+ lastReadWarn = msg
+ }
+ } else {
+ readFailures, lastReadWarn = 0, ""
+ }
+ }
if err == nil && fingerprint != lastPrint {
// Every upload that sends messages records a session.shared refresh, so a session
// being followed never looks out of date locally; it is at most one per interval.
@@ -176,6 +206,9 @@ func shareFollowState(subject shareSubject) (string, bool, error) {
ended = true
}
}
+ if !ended && !subject.fromLog {
+ ended = shareLogRecordsEnd(subject.session)
+ }
payload, err := buildSharePayload(subject)
if err != nil {
return "", ended, err
@@ -205,3 +238,19 @@ func printShareFollow(out, errOut io.Writer, result shareResult, first, final, e
}
return nil
}
+
+// shareLogRecordsEnd reports whether the runtime log records the end of session, which most store
+// mappers do not emit: the runtime's hooks write session.ended to the log, not to its own store.
+// A log that cannot be read says nothing.
+func shareLogRecordsEnd(session handoff.Session) bool {
+ found, events, ok, err := handoff.LogSession(shareLogPath(), session.ID, session.Harness)
+ if err != nil || !ok || found.ID != session.ID || found.Harness != session.Harness {
+ return false
+ }
+ for _, e := range events {
+ if e.Event.Action == "session.ended" {
+ return true
+ }
+ }
+ return false
+}
diff --git a/cli/beacon/cmd/share_follow_test.go b/cli/beacon/cmd/share_follow_test.go
index 3dfef142..726da40c 100644
--- a/cli/beacon/cmd/share_follow_test.go
+++ b/cli/beacon/cmd/share_follow_test.go
@@ -22,6 +22,8 @@ type growingSource struct {
mu sync.Mutex
session handoff.Session
events []schema.Event
+ // fail, when set, is what reading the session's events returns.
+ fail error
}
func (g *growingSource) Harness() string { return handoff.HarnessClaude }
@@ -31,6 +33,9 @@ func (g *growingSource) List() ([]handoff.Session, error) {
func (g *growingSource) Events(handoff.Session) ([]schema.Event, error) {
g.mu.Lock()
defer g.mu.Unlock()
+ if g.fail != nil {
+ return nil, g.fail
+ }
return append([]schema.Event(nil), g.events...), nil
}
func (g *growingSource) add(e schema.Event) {
@@ -342,3 +347,95 @@ func TestShareFollowKeepsTitleAndAppliesExplicitVisibility(t *testing.T) {
t.Fatalf("visibility = %q, want the explicit --visibility", srv.trace.Visibility)
}
}
+
+// Most store mappers never emit session.ended; the runtime's hooks write it to the runtime log.
+// --follow on a store-backed session stops when the log records the end.
+func TestShareFollowStopsWhenTheRuntimeLogRecordsTheEnd(t *testing.T) {
+ env := newShareEnv(t)
+ src := &growingSource{
+ session: handoff.Session{Harness: handoff.HarnessClaude, ID: shareTestSession, Directory: env.projectDir, UpdatedAt: time.Now()},
+ events: shareFixtureEvents(env.projectDir),
+ }
+ stubHandoffSources(t, src)
+ srv := newFakeShareServer(t)
+ srv.signIn(account.ScopeTracesWrite)
+ polls := 0
+ prevWait := shareFollowWait
+ shareFollowWait = func(ctx context.Context, d time.Duration) error {
+ polls++
+ switch polls {
+ case 1:
+ // Another session's end must not stop this one.
+ other := followEvent(env.projectDir, "2026-10-01T10:02:00.000000000Z", "session.ended")
+ other.Session.ID = "someone-else"
+ appendLogEvent(t, env.logPath, other)
+ case 2:
+ appendLogEvent(t, env.logPath, followEvent(env.projectDir, "2026-10-01T10:03:00.000000000Z", "session.ended"))
+ case 10:
+ return errors.New("the loop did not stop at the end the runtime log recorded")
+ }
+ return nil
+ }
+ t.Cleanup(func() { shareFollowWait = prevWait })
+ _, stderr, err := runShareCommand(t, "--follow", "--cwd", env.projectDir, "--log-path", env.logPath)
+ if err != nil {
+ t.Fatalf("follow: %v\n%s", err, stderr)
+ }
+ if polls != 2 || !strings.Contains(stderr, "The session ended;") {
+ t.Fatalf("polls = %d, stderr:\n%s", polls, stderr)
+ }
+}
+
+// After the first upload, a session that cannot be read is reported (once per distinct error,
+// not every poll), and --follow gives up after shareFollowMaxReadFailures polls in a row.
+func TestShareFollowReportsReadFailuresAndGivesUp(t *testing.T) {
+ env := newShareEnv(t)
+ src := &growingSource{
+ session: handoff.Session{Harness: handoff.HarnessClaude, ID: shareTestSession, Directory: env.projectDir, UpdatedAt: time.Now()},
+ events: shareFixtureEvents(env.projectDir),
+ }
+ stubHandoffSources(t, src)
+ srv := newFakeShareServer(t)
+ srv.signIn(account.ScopeTracesWrite)
+ polls := 0
+ prevWait := shareFollowWait
+ shareFollowWait = func(ctx context.Context, d time.Duration) error {
+ polls++
+ if polls == 1 {
+ src.mu.Lock()
+ src.fail = errors.New("store is being rewritten")
+ src.mu.Unlock()
+ }
+ if polls > 20 {
+ return errors.New("the loop did not give up")
+ }
+ return nil
+ }
+ t.Cleanup(func() { shareFollowWait = prevWait })
+ _, stderr, err := runShareCommand(t, "--follow", "--cwd", env.projectDir, "--log-path", env.logPath)
+ if err == nil || !strings.Contains(err.Error(), "could not be read") || !strings.Contains(err.Error(), "store is being rewritten") {
+ t.Fatalf("follow err = %v\n%s", err, stderr)
+ }
+ if polls != shareFollowMaxReadFailures {
+ t.Fatalf("waits = %d, want %d", polls, shareFollowMaxReadFailures)
+ }
+ if n := strings.Count(stderr, "warning: could not read the session"); n != 1 {
+ t.Fatalf("read warnings = %d, want one for the repeated error\n%s", n, stderr)
+ }
+}
+
+func appendLogEvent(t *testing.T, path string, e schema.Event) {
+ t.Helper()
+ data, err := json.Marshal(e)
+ if err != nil {
+ t.Fatal(err)
+ }
+ f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer f.Close()
+ if _, err := f.Write(append(data, '\n')); err != nil {
+ t.Fatal(err)
+ }
+}
diff --git a/docs/cli/share.mdx b/docs/cli/share.mdx
index 726f6be3..a4d02702 100644
--- a/docs/cli/share.mdx
+++ b/docs/cli/share.mdx
@@ -120,7 +120,7 @@ beacon share refresh # this session, found like --current
## Follow a running session
-`--follow` keeps the trace current while the session runs. It shares the session, then checks it again every `--interval` (default `10s`, at least `1s`) and uploads what changed, until the session records its end (`session.ended`) or you press Ctrl+C. A check is a local read; a request is made only when the session's messages changed, and it sends only what beacon.sh lacks, the same way `refresh` does. A failed upload after the first is reported and retried on the next check. When the session has ended and its last messages cannot be uploaded, `--follow` retries three more times, one interval apart, and then exits non-zero naming what the trace holds. If the runtime log cannot be written after an upload, `--follow` warns and keeps going.
+`--follow` keeps the trace current while the session runs. It shares the session, then checks it again every `--interval` (default `10s`, at least `1s`) and uploads what changed, until the session records its end (`session.ended`, in the runtime's store or in the runtime log, where the hooks write it) or you press Ctrl+C. A check is a local read; a request is made only when the session's messages changed, and it sends only what beacon.sh lacks, the same way `refresh` does. A failed upload after the first is reported and retried on the next check. When the session has ended and its last messages cannot be uploaded, `--follow` retries three more times, one interval apart, and then exits non-zero naming what the trace holds. If the runtime log cannot be written after an upload, `--follow` warns and keeps going. A check that cannot read the session is reported once per distinct error, and after five failed checks in a row `--follow` exits non-zero.
```bash
beacon share --follow # this session, until it ends