Skip to content

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

Show sharing state, staleness and the refresh command in local views

Claude4c7994e95bf5
diff --git a/CLAUDE.md b/CLAUDE.md
index dcce2146..90f48433 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -70,7 +70,7 @@ Supported runtime surfaces today:
- Local threat detection via `beacon scan`, which runs the open Threat Rules format (`spec/threat-rules`; CEL match conditions over the endpoint event schema, with embedded conformance fixtures) over the runtime JSONL. The engine (`pkg/asymptoteobserve/threatrules`) ships in the binary; the rule corpus is external data loaded from a local store (`~/.beacon/endpoint/rules`) managed by `beacon rules`, so the corpus can grow without enlarging the binary. `scan` is read-only and offline; only the explicit, user-initiated `beacon rules pull <url>` reaches the network. A small frozen baseline is embedded so `scan` works before any rules are installed.
- Session handoff via `beacon handoff list|export|resume` (`cli/beacon/internal/handoff`, `cli/beacon/cmd/handoff*.go`; docs in `docs/cli/handoff.mdx` and `docs/concepts/session-handoff.mdx`). Every runtime is one entry in the registry in `cli/beacon/internal/handoff/runtimes.go`: its session source, the names it answers to, and the commands that reopen it or start it from a brief; `TestRegistryIsConsistent` checks the entries. Handoff reads the session stores of Claude Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent, Factory Droid, GitHub Copilot CLI, Hermes Agent, DeepSeek Harness, fx, Grok Build, OpenClaw Gateway and Cursor read-only and never touches the network. Oh My Pi, Gemini CLI, Qwen Code, Kiro, Antigravity CLI, Devin CLI, Muse Code, OpenHands and goose have no store Beacon reads: their sessions come from the runtime log, and they take a brief as the target of `--agent`. `resume` reopens a session natively with its runtime's own command when it can, and otherwise writes a brief to `~/.beacon/endpoint/handoffs` (0700/0600) and starts a new session pointed at it. DeepSeek Harness cannot be started, and Hermes Agent and fx only reopen their own sessions, so their sessions continue in another runtime. fx, Grok Build and Cursor find a session by the directory they run in, so they are reopened natively only in the session's own directory. The brief is passed by absolute path, never inlined on a command line. Every launch keeps the runtime's approvals on: Beacon never passes a flag that turns them off, names the approval mode that asks where a CLI takes one (Cline always gets `--auto-approve false`, because Cline defaults to approving every tool call), and removes or overrides environment switches that would approve everything (`COPILOT_ALLOW_ALL`, `COPILOT_PLAN_THEN_AUTOPILOT`, `HERMES_YOLO_MODE`, `GOOSE_MODE`); `--print` shows them under `env`. Briefs run every event through `SanitizeEvent`, and quoted content goes in fences longer than any backtick run it contains, with inline fields reduced to one line, so quoted content cannot forge brief structure. A new session's first prompt ends with the `[beacon-handoff from=<harness> session=<id>]` marker (`pkg/asymptoteobserve/handoff.go`). The hook and plugin prompt paths and the session-store mappers record a `session.handoff` event with `handoff.{source_harness,source_session_id}` when they see it; that is an observed claim, not a verified identity.
- Session sharing via `beacon share` and `beacon share refresh` (`cli/beacon/cmd/share.go`; docs in `docs/cli/share.mdx`). It publishes one session the person names (or the most recent in a directory) to beacon.sh as a shared trace under the `beacon.share.v1` contract: the types, `ShareExternalID` (`<harness>:<session-id>`, or a sha256 form) and the event-to-message projection `BuildShareMessages` live in `pkg/asymptoteobserve/share.go`, and the client in `cli/beacon/internal/account/share.go`. Sessions resolve through the handoff registry (store first, then the runtime log). Every event goes through `SanitizeEvent` and session-directory/home paths are rewritten before projection; a tool invocation and its completion become a `tool_call` and a `tool_result` message sharing one callId, and a call reported twice is written once. `--print` shows the exact payload with no network, `public` needs confirmation (refused without a terminal unless `--yes`), and a re-share upserts by stable message id. After an upload it writes one `session.shared` event (`event.fidelity=inferred`, no collection method) carrying `shared_url`, `visibility`, `shared_at`/`last_refreshed_at` in raw, which the trace list reads as the sharing state; the projection skips that event. It never runs from hooks or in the background. With no selector (or `--current`) it shares the session it runs inside: `BEACON_SESSION_ID`/`BEACON_HARNESS` (the Claude Code SessionStart hook appends both as `export` lines to `$CLAUDE_ENV_FILE`, plain identifiers only), then the active-session record, then the directory's most recent session. The record is `pkg/asymptoteobserve/activesession` (`~/.beacon/endpoint/active-sessions.json`, 0600 under 0700, atomic and locked, at most 256 entries, 14-day prune, an unchanged entry rewritten at most once a minute), written by the hook logger after every endpoint event with a session id, working directory and harness; it holds identifiers and paths only, never content, and hooks write it silently and never touch the network for it. Hook tests point `BEACON_ACTIVE_SESSIONS_FILE` at a temp file in `TestMain`. Auto-share (`beacon share auto enable|disable|status`, `cli/beacon/cmd/share_auto.go`, settings in `pkg/asymptoteobserve/shareauto`) is server-side publishing: when it applies to a session's working directory, the hook logger writes ONE local `session.share_requested` event per session (`event.fidelity=inferred`, `share.visibility`; deduplicated under the active-session record's lock) and Beacon Cloud forwarding ships it; beacon.sh builds and refreshes the trace with the same `ShareExternalID`. Hooks never upload. The user file `~/.beacon/endpoint/share.json` (0600, CLI-written) holds the user-wide switch and per-project choices by path; a project marker `<repo>/.beacon/share.json` may disable on its own but enables only when the user's file trusts that project, with the user's visibility, so a cloned repository can never publish someone's sessions. `ForHook` costs one failed read when nothing is enabled. Hook tests point `BEACON_SHARE_SETTINGS_FILE` at a temp file. The share projection and `handoff.LogSessions` recency skip `session.share_requested`.
-- Commit-to-session links via `beacon git setup|status|remove|link|notes` (`cli/beacon/internal/gitlink`, `cli/beacon/cmd/git*.go`; docs in `docs/cli/git.mdx`). A link is a `beacon:<harness>/<session-id>` line in a git note under `refs/notes/beacon`; it carries identifiers only, never content, because notes can be pushed. Which sessions to link is inferred from the local runtime log: a session is linked when, between the parent commit and the commit (at least two hours, at most 24), it wrote a file the commit changes (for a merge, only files that differ from every parent, so a clean merge or pull links nothing). Evidence is file write events, write-type `file.operation`s, plainly readable shell targets, and `apply_patch` envelopes; reads never count. Note updates are a compare-and-swap on the notes ref through a private `refs/notes/beacon-tx/` working ref, and every existing note line, a teammate's or a person's, is kept verbatim. `setup` installs post-commit (links HEAD in the foreground with a 3 s budget, silent, never fails the commit, skips rebase/cherry-pick/revert) and post-rewrite (normalizes the note git concatenates on amend) as standalone `beacon-<hook>` scripts called from a marked block inserted after the shebang of the repository's own hook; only shell hooks are edited, `core.hooksPath` is refused without `--hooks-path`, and `notes.rewriteRef` carries links through amend and rebase. `BEACON_GIT_HOOKS=0` disables the hooks for one command. Every link a run adds is also written to the runtime log as one `session.commit_linked` event in the linked session's timeline (`event.fidelity=inferred`, no collection method), with commit id, branch and credential-stripped remote in the OTel-shaped `vcs` block and overlap counts in `vcs.attribution`; the event deliberately carries no file, command or tool fields so it can never become attribution evidence. Sharing is opt-in (`setup --share-notes`, off by default): a non-destructive fetch refspec `+refs/notes/beacon:refs/notes/beacon-remotes/<remote>` so git's own fetch brings teammates' links into a read-only tracking ref that `beacon git notes` unions with the local one (never force-fetch into `refs/notes/beacon`: it would destroy unpushed links), and a pre-push hook that fetches, merges with `cat_sort_uniq` through the same CAS, and pushes only the notes ref with `--no-verify`, within a 10 s budget and never failing the push. That pre-push hook is the only Beacon git hook that touches the network, and only during a push the person started; `beacon git notes push|fetch` do the same by hand. A note line may carry the session's share URL as its first trailing field (`beacon:<harness>/<id> <url>`; an identifier, not content): `gitlink.ValidShareURL` admits only https URLs on beacon.sh or the configured Beacon host (`AllowShareHost`, fed by `gitAllowShareHosts`), on write and on read, and `MergeNote`/`ParseNote` prefer the line with the URL over the bare one. Post-commit and `link` take URLs only from local `session.shared` events (`localShareURLs`). `setup --share-sessions [--share-visibility]` (implies `--share-notes`; stored as `beacon.shareSessions`/`beacon.shareVisibility` in local git config; public needs confirmation or `--yes`) makes the pre-push hook, which now receives git's stdin, share sessions linked to pushed commits that have no URL (at most 100 commits/10 sessions, inside the 10 s budget less 3 s kept for the notes push, silent without credentials, never failing the push) through `shareUpload` (`cmd/share_upload.go`: `alignShareSource` + `messagesAfter`), then write the URLs into the notes before pushing them. `beacon share --follow [--interval]` (`cmd/share_follow.go`) polls the session locally, uploads through `shareUpload` only when the projected messages' fingerprint changed, stops at `session.ended` or Ctrl+C (`shareFollowWait`/`shareFollowSignals` are the test seams), and records `session.shared` once at the start and once at the end; `docs/cli/share.mdx` carries the API-key CI walkthrough with GitHub Actions and GitLab CI examples.
+- Commit-to-session links via `beacon git setup|status|remove|link|notes` (`cli/beacon/internal/gitlink`, `cli/beacon/cmd/git*.go`; docs in `docs/cli/git.mdx`). A link is a `beacon:<harness>/<session-id>` line in a git note under `refs/notes/beacon`; it carries identifiers only, never content, because notes can be pushed. Which sessions to link is inferred from the local runtime log: a session is linked when, between the parent commit and the commit (at least two hours, at most 24), it wrote a file the commit changes (for a merge, only files that differ from every parent, so a clean merge or pull links nothing). Evidence is file write events, write-type `file.operation`s, plainly readable shell targets, and `apply_patch` envelopes; reads never count. Note updates are a compare-and-swap on the notes ref through a private `refs/notes/beacon-tx/` working ref, and every existing note line, a teammate's or a person's, is kept verbatim. `setup` installs post-commit (links HEAD in the foreground with a 3 s budget, silent, never fails the commit, skips rebase/cherry-pick/revert) and post-rewrite (normalizes the note git concatenates on amend) as standalone `beacon-<hook>` scripts called from a marked block inserted after the shebang of the repository's own hook; only shell hooks are edited, `core.hooksPath` is refused without `--hooks-path`, and `notes.rewriteRef` carries links through amend and rebase. `BEACON_GIT_HOOKS=0` disables the hooks for one command. Every link a run adds is also written to the runtime log as one `session.commit_linked` event in the linked session's timeline (`event.fidelity=inferred`, no collection method), with commit id, branch and credential-stripped remote in the OTel-shaped `vcs` block and overlap counts in `vcs.attribution`; the event deliberately carries no file, command or tool fields so it can never become attribution evidence. Sharing is opt-in (`setup --share-notes`, off by default): a non-destructive fetch refspec `+refs/notes/beacon:refs/notes/beacon-remotes/<remote>` so git's own fetch brings teammates' links into a read-only tracking ref that `beacon git notes` unions with the local one (never force-fetch into `refs/notes/beacon`: it would destroy unpushed links), and a pre-push hook that fetches, merges with `cat_sort_uniq` through the same CAS, and pushes only the notes ref with `--no-verify`, within a 10 s budget and never failing the push. That pre-push hook is the only Beacon git hook that touches the network, and only during a push the person started; `beacon git notes push|fetch` do the same by hand. A note line may carry the session's share URL as its first trailing field (`beacon:<harness>/<id> <url>`; an identifier, not content): `gitlink.ValidShareURL` admits only https URLs on beacon.sh or the configured Beacon host (`AllowShareHost`, fed by `gitAllowShareHosts`), on write and on read, and `MergeNote`/`ParseNote` prefer the line with the URL over the bare one. Post-commit and `link` take URLs only from local `session.shared` events (`localShareURLs`). `setup --share-sessions [--share-visibility]` (implies `--share-notes`; stored as `beacon.shareSessions`/`beacon.shareVisibility` in local git config; public needs confirmation or `--yes`) makes the pre-push hook, which now receives git's stdin, share sessions linked to pushed commits that have no URL (at most 100 commits/10 sessions, inside the 10 s budget less 3 s kept for the notes push, silent without credentials, never failing the push) through `shareUpload` (`cmd/share_upload.go`: `alignShareSource` + `messagesAfter`), then write the URLs into the notes before pushing them. `beacon share --follow [--interval]` (`cmd/share_follow.go`) polls the session locally, uploads through `shareUpload` only when the projected messages' fingerprint changed, stops at `session.ended` or Ctrl+C (`shareFollowWait`/`shareFollowSignals` are the test seams), and records `session.shared` once at the start and once at the end; `docs/cli/share.mdx` carries the API-key CI walkthrough with GitHub Actions and GitLab CI examples. Local views show sharing read-only: the trace summary (`traceAggregate`, and the history through `traceAggregateState`, derivation version 5) and the dashboard's `SessionRecord.Sharing` mark a shared session `stale` when an event other than Beacon's bookkeeping (`session.shared`, `session.share_requested`, `session.commit_linked`) is newer than its last `session.shared` record, and carry `asymptoteobserve.ShareRefreshCommand` for the reader to copy; the session list/page, `beacon traces` TUI and plain list display them, and nothing in them shares.
- Beacon Cloud MCP registration via `beacon mcp connect|disconnect|status` (`cli/beacon/internal/mcpconnect`, `cli/beacon/cmd/mcp_connect.go`; docs in `docs/cli/mcp-connect.mdx`). It registers the Beacon Cloud MCP server as `beacon-managed`, a different name from the local stdio server `beacon`, in the user-level config of Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI and OpenCode. It prints manual steps for runtimes without confirmed MCP OAuth support. OAuth is the default and writes only the URL; `--token-env` writes a reference to an environment variable in each harness's own syntax, never a value. `connect` never reads or copies the account token and never writes a token; minting one is the separate, explicit `beacon mcp token create`. It is explicit and interactive: never run by an unattended install; the onboarding wizard runs it only after the person chose Beacon Cloud and left "Beacon Cloud MCP" selected (that screen is the confirmation), and otherwise the install only suggests it. It is refused as root, and refused in CI or without a terminal unless `--yes` is given. Its one network request is the RFC 9728 resource-metadata check of the URL, which `--dry-run` skips. Configs are edited like the Kimi Code writer: never re-serialized, spliced as text, parsed back and compared before an atomic replace, backed up first. What was written is recorded in `~/.beacon/mcp/connections.json`, and `disconnect` removes only entries recorded there that still point at the recorded URL. `cmd/mcp_connect_e2e_test.go` runs the real harness CLIs when they are installed; re-run it when a harness changes its MCP config format.
- An optional, off-by-default policy seam in the hook path (`cli/beacon-hooks/internal/policy`) governed by the stable contract in `pkg/asymptoteobserve/policycontract`. When `BEACON_POLICY_PROVIDER` names an executable, the `pre-tool` and `permission-request` hooks send it a JSON request describing the imminent tool call and honor an allow/deny response, returning the runtime's native deny shape and `policy.enforcement=enforce` telemetry on a deny. The seam is inert when unset and fail-open on any error (timeout, non-zero exit, malformed output), so the open build ships no enforcement of its own; all audit/enforce decision logic lives in the external provider. `rules/agent-control/agent-permission-bypass-spawn.rule.yaml` is the open detect twin that flags the same pattern in `beacon scan`.
diff --git a/cli/beacon/cmd/endpoint_traces.go b/cli/beacon/cmd/endpoint_traces.go
index 5c47b41a..53c565e7 100644
--- a/cli/beacon/cmd/endpoint_traces.go
+++ b/cli/beacon/cmd/endpoint_traces.go
@@ -59,13 +59,26 @@ func runTopLevelTraces(cmd *cobra.Command, args []string) error {
func printPlainTraceList(out io.Writer, result dashboard.TraceListResultV1) {
for _, trace := range result.Traces {
title := strings.Join(strings.Fields(trace.Title), " ")
- fmt.Fprintf(out, "%s\t%s\t%s\t%s\n", trace.ID, trace.Harness.Name, trace.UpdatedAt, title)
+ fmt.Fprintf(out, "%s\t%s\t%s\t%s%s\n", trace.ID, trace.Harness.Name, trace.UpdatedAt, title, plainSharing(trace))
}
if result.Truncated {
fmt.Fprintf(out, "Showing %d of %d traces; use `beacon endpoint traces list --page` to continue.\n", result.Returned, result.TotalMatched)
}
}
+// plainSharing is a shared trace's extra column: its state and link, and for a stale trace the
+// command that refreshes it.
+func plainSharing(trace dashboard.TraceSummaryV1) string {
+ if trace.Sharing.URL == "" {
+ return ""
+ }
+ column := "\t" + trace.Sharing.State + " " + trace.Sharing.URL
+ if trace.Sharing.State == "stale" && trace.Sharing.RefreshCommand != "" {
+ column += " (" + trace.Sharing.RefreshCommand + ")"
+ }
+ return column
+}
+
var endpointTracesStatusCmd = &cobra.Command{
Use: "status",
Short: "Show the local trace history's status",
diff --git a/cli/beacon/cmd/endpoint_traces_tui_test.go b/cli/beacon/cmd/endpoint_traces_tui_test.go
index aea6c8ae..94212251 100644
--- a/cli/beacon/cmd/endpoint_traces_tui_test.go
+++ b/cli/beacon/cmd/endpoint_traces_tui_test.go
@@ -42,3 +42,15 @@ func TestPrintPlainTraceList(t *testing.T) {
}
}
}
+
+func TestPlainTraceListShowsSharing(t *testing.T) {
+ var out bytes.Buffer
+ printPlainTraceList(&out, dashboard.TraceListResultV1{Traces: []dashboard.TraceSummaryV1{
+ {ID: "session:claude_code:s7", Title: "a", Harness: dashboard.TraceHarnessV1{Name: "claude_code"}, Sharing: dashboard.TraceSharingV1{State: "stale", URL: "https://beacon.sh/s/x", RefreshCommand: "beacon share refresh claude_code:s7"}},
+ {ID: "session:claude_code:s8", Title: "b", Harness: dashboard.TraceHarnessV1{Name: "claude_code"}, Sharing: dashboard.TraceSharingV1{State: "local_only"}},
+ }})
+ lines := strings.Split(strings.TrimSpace(out.String()), "\n")
+ if !strings.HasSuffix(lines[0], "\tstale https://beacon.sh/s/x (beacon share refresh claude_code:s7)") || strings.Count(lines[1], "\t") != 3 {
+ t.Fatalf("output:\n%s", out.String())
+ }
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/history_ingest.go b/cli/beacon/internal/endpoint/dashboard/history_ingest.go
index 2e692da3..484fa86e 100644
--- a/cli/beacon/internal/endpoint/dashboard/history_ingest.go
+++ b/cli/beacon/internal/endpoint/dashboard/history_ingest.go
@@ -799,18 +799,22 @@ func (f *traceFolder) finish(previous historyTraceState) error {
// and the sets finish() reads. finish() runs on a copy each time a summary is read, so it never
// feeds back into the running state.
type traceAggregateState struct {
- Summary TraceSummaryV1 `json:"summary"`
- Models []string `json:"models,omitempty"`
- Methods []string `json:"methods,omitempty"`
- TitlePriority int `json:"title_priority"`
+ Summary TraceSummaryV1 `json:"summary"`
+ Models []string `json:"models,omitempty"`
+ Methods []string `json:"methods,omitempty"`
+ TitlePriority int `json:"title_priority"`
+ LastActivity string `json:"last_activity,omitempty"`
+ LastShareRecord string `json:"last_share_record,omitempty"`
}
func (a *traceAggregate) state() traceAggregateState {
return traceAggregateState{
- Summary: a.summary,
- Models: sortedKeys(a.models),
- Methods: sortedKeys(a.methods),
- TitlePriority: a.titlePriority,
+ Summary: a.summary,
+ Models: sortedKeys(a.models),
+ Methods: sortedKeys(a.methods),
+ TitlePriority: a.titlePriority,
+ LastActivity: a.lastActivity,
+ LastShareRecord: a.lastShareRecord,
}
}
@@ -820,11 +824,13 @@ func decodeTraceAggregate(raw string) (*traceAggregate, error) {
return nil, err
}
agg := &traceAggregate{
- summary: state.Summary,
- spans: map[string]*TraceSpanV1{},
- models: map[string]bool{},
- methods: map[string]bool{},
- titlePriority: state.TitlePriority,
+ summary: state.Summary,
+ spans: map[string]*TraceSpanV1{},
+ models: map[string]bool{},
+ methods: map[string]bool{},
+ titlePriority: state.TitlePriority,
+ lastActivity: state.LastActivity,
+ lastShareRecord: state.LastShareRecord,
}
for _, model := range state.Models {
agg.models[model] = true
diff --git a/cli/beacon/internal/endpoint/dashboard/history_store.go b/cli/beacon/internal/endpoint/dashboard/history_store.go
index d94cb5b2..ee2609b9 100644
--- a/cli/beacon/internal/endpoint/dashboard/history_store.go
+++ b/cli/beacon/internal/endpoint/dashboard/history_store.go
@@ -41,7 +41,7 @@ const (
// historyDerivationVersion covers everything computed from a stored line: trace keys, event
// numbers, types, summaries and search text. Bump it when that projection changes; the next
// catch-up recomputes it from the stored lines, so history survives the change.
- historyDerivationVersion = 4 // 2: trace events carry the event's policy block; 3: and its error; 4: usage carries the 1h cache-write split
+ historyDerivationVersion = 5 // 2: trace events carry the event's policy block; 3: and its error; 4: usage carries the 1h cache-write split; 5: sharing goes stale on newer activity and carries a refresh command
defaultHistoryRetentionDays = 90
// maxHistoryRetentionDays is 100 years: a retention this long or longer means nothing expires.
diff --git a/cli/beacon/internal/endpoint/dashboard/history_test.go b/cli/beacon/internal/endpoint/dashboard/history_test.go
index bb26e9f2..7b18c695 100644
--- a/cli/beacon/internal/endpoint/dashboard/history_test.go
+++ b/cli/beacon/internal/endpoint/dashboard/history_test.go
@@ -125,7 +125,7 @@ func traceAnswers(t *testing.T, path string, showIDs []string) map[string]string
}
out[fmt.Sprintf("search q=%q typed", q)] = mustJSON(t, typed)
}
- for _, state := range []string{"local_only", "LOCAL_ONLY", "shared"} {
+ for _, state := range []string{"local_only", "LOCAL_ONLY", "shared", "stale"} {
list, err := ReadTraceList(path, TraceQuery{State: state, Limit: 50})
if err != nil {
t.Fatalf("ReadTraceList state=%s: %v", state, err)
@@ -200,6 +200,14 @@ func parityFixture() [][]byte {
`{"timestamp":"2026-06-11T14:00:00Z","event":{"id":"q0","action":"prompt.submitted","category":"prompt"},"harness":{"name":"codex_cli"},"session":{"id":"s6"},"prompt":{"text":"unsequenced goes first"}}`,
`{"timestamp":"2026-06-11T13:59:00Z","event":{"id":"q-early","action":"session.started","category":"session"},"harness":{"name":"codex_cli","version":"1.0"},"session":{"id":"s6"}}`,
`{"timestamp":"2026-06-11T13:00:05Z","event":{"id":"s5b","action":"command.executed","category":"command"},"harness":{"name":"opencode"},"session":{"id":"s5"},"command":{"command":"ls a-b"}}`,
+ // Shared with beacon share, then active again: the trace is stale. s8 was shared after
+ // its last activity, and the commit link after that does not make it stale.
+ `{"timestamp":"2026-06-11T15:00:00Z","event":{"id":"h1","action":"prompt.submitted","category":"prompt"},"harness":{"name":"claude_code","collection_method":"hook"},"session":{"id":"s7"},"prompt":{"text":"share me"}}`,
+ `{"timestamp":"2026-06-11T15:01:00Z","event":{"id":"h2","action":"session.shared","category":"session","fidelity":"inferred"},"harness":{"name":"claude_code"},"session":{"id":"s7"},"raw":{"shared_url":"https://beacon.sh/s/s7trace","visibility":"direct","shared_at":"2026-06-11T15:01:00Z","last_refreshed_at":"2026-06-11T15:01:00Z"}}`,
+ `{"timestamp":"2026-06-11T15:02:00Z","event":{"id":"h3","action":"agent.message","category":"agent"},"harness":{"name":"claude_code","collection_method":"hook"},"session":{"id":"s7"},"message":"later work"}`,
+ `{"timestamp":"2026-06-11T16:00:00Z","event":{"id":"k1","action":"prompt.submitted","category":"prompt"},"harness":{"name":"claude_code","collection_method":"hook"},"session":{"id":"s8"},"prompt":{"text":"shared and current"}}`,
+ `{"timestamp":"2026-06-11T16:01:00Z","event":{"id":"k2","action":"session.shared","category":"session","fidelity":"inferred"},"harness":{"name":"claude_code"},"session":{"id":"s8"},"raw":{"shared_url":"https://beacon.sh/s/s8trace","visibility":"private","shared_at":"2026-06-11T16:01:00Z","last_refreshed_at":"2026-06-11T16:01:00Z"}}`,
+ `{"timestamp":"2026-06-11T16:02:00Z","event":{"id":"k3","action":"session.commit_linked","category":"session","fidelity":"inferred"},"harness":{"name":"claude_code"},"session":{"id":"s8"},"message":"commit linked"}`,
}
out := make([][]byte, len(lines))
for i, line := range lines {
@@ -210,7 +218,7 @@ func parityFixture() [][]byte {
var parityShowIDs = []string{
"session:cursor:s1", "trace:t-abc", "session:codex_cli:s3", "session:opencode:s4", "session:opencode:s5",
- "session:codex_cli:s6", "event:m1", "missing",
+ "session:codex_cli:s6", "session:claude_code:s7", "session:claude_code:s8", "event:m1", "missing",
}
// The core promise: for the same log, the history answers every list, search and show exactly
diff --git a/cli/beacon/internal/endpoint/dashboard/sessions.go b/cli/beacon/internal/endpoint/dashboard/sessions.go
index e23a3a60..42ccc6f0 100644
--- a/cli/beacon/internal/endpoint/dashboard/sessions.go
+++ b/cli/beacon/internal/endpoint/dashboard/sessions.go
@@ -6,6 +6,7 @@ import (
"time"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
type SessionRecord struct {
@@ -32,6 +33,20 @@ type SessionRecord struct {
ToolCount int `json:"tool_count"`
IsRecurring bool `json:"is_recurring"`
RecurrenceCount int `json:"recurrence_count"`
+ // Sharing is set once the session was shared with `beacon share` (its session.shared record).
+ Sharing *SessionSharing `json:"sharing,omitempty"`
+}
+
+// SessionSharing is a shared session's state as the local log knows it. State is "shared", or
+// "stale" when the session has activity newer than its last share or refresh; RefreshCommand is
+// the command that would upload it. The dashboard shows both and runs neither.
+type SessionSharing struct {
+ URL string `json:"url"`
+ Visibility string `json:"visibility,omitempty"`
+ State string `json:"state"`
+ SharedAt string `json:"shared_at,omitempty"`
+ LastRefreshedAt string `json:"last_refreshed_at,omitempty"`
+ RefreshCommand string `json:"refresh_command,omitempty"`
}
type SessionResult struct {
@@ -97,6 +112,7 @@ func ReadSessions(path string, query EventQuery) (SessionResult, error) {
}
sessions := make([]SessionRecord, 0, len(byID))
for id, acc := range byID {
+ acc.finish()
if classification := classifications[id]; classification.state == "recurring" {
acc.record.IsRecurring = true
acc.record.RecurrenceCount = classification.recurrenceCount
@@ -156,6 +172,7 @@ func ReadSessionDetail(path, id string) (SessionDetail, bool, error) {
WazuhLevel: record.WazuhLevel,
})
}
+ acc.finish()
return SessionDetail{Session: acc.record, Events: events}, true, nil
}
@@ -163,10 +180,59 @@ type sessionAccumulator struct {
record SessionRecord
first time.Time
last time.Time
+ // lastActivity and lastShared drive SessionSharing.State: see traceAggregate.
+ lastActivity time.Time
+ lastShared time.Time
+}
+
+// noteSharing reads a session.shared record, and otherwise notes when the session last did
+// something of its own.
+func (acc *sessionAccumulator) noteSharing(record EventRecord) {
+ event := record.Event
+ if event.Event.Action == "session.shared" {
+ url := rawString(event.Raw, "shared_url")
+ if url == "" {
+ return
+ }
+ if acc.record.Sharing == nil {
+ acc.record.Sharing = &SessionSharing{}
+ }
+ s := acc.record.Sharing
+ s.URL = url
+ if v := rawString(event.Raw, "visibility"); v != "" {
+ s.Visibility = v
+ }
+ if v := rawString(event.Raw, "shared_at"); v != "" && s.SharedAt == "" {
+ s.SharedAt = v
+ }
+ if v := rawString(event.Raw, "last_refreshed_at"); v != "" {
+ s.LastRefreshedAt = v
+ }
+ if record.Parsed.After(acc.lastShared) {
+ acc.lastShared = record.Parsed
+ }
+ return
+ }
+ if !shareBookkeeping(event.Event.Action) && record.Parsed.After(acc.lastActivity) {
+ acc.lastActivity = record.Parsed
+ }
+}
+
+func (acc *sessionAccumulator) finish() {
+ s := acc.record.Sharing
+ if s == nil {
+ return
+ }
+ s.State = "shared"
+ if !acc.lastShared.IsZero() && acc.lastActivity.After(acc.lastShared) {
+ s.State = "stale"
+ }
+ s.RefreshCommand = asymptoteobserve.ShareRefreshCommand(acc.record.Harness, acc.record.ID)
}
func (acc *sessionAccumulator) add(record EventRecord) {
event := record.Event
+ acc.noteSharing(record)
acc.record.EventCount++
if isNeedsReview(record) {
acc.record.ReviewCount++
diff --git a/cli/beacon/internal/endpoint/dashboard/sharing_view_test.go b/cli/beacon/internal/endpoint/dashboard/sharing_view_test.go
new file mode 100644
index 00000000..307bf452
--- /dev/null
+++ b/cli/beacon/internal/endpoint/dashboard/sharing_view_test.go
@@ -0,0 +1,65 @@
+package dashboard
+
+import (
+ "testing"
+)
+
+func TestTraceSharingStateAndRefreshCommand(t *testing.T) {
+ path := newTestLog(t, parityFixture())
+ withoutHistory(t)
+ list, err := ReadTraceList(path, TraceQuery{Limit: 50})
+ if err != nil {
+ t.Fatal(err)
+ }
+ byID := map[string]TraceSummaryV1{}
+ for _, trace := range list.Traces {
+ byID[trace.ID] = trace
+ }
+ stale := byID["session:claude_code:s7"].Sharing
+ if stale.State != "stale" || stale.URL != "https://beacon.sh/s/s7trace" || stale.RefreshCommand != "beacon share refresh claude_code:s7" {
+ t.Fatalf("s7 sharing = %+v", stale)
+ }
+ current := byID["session:claude_code:s8"].Sharing
+ if current.State != "shared" || current.Visibility != "private" || current.RefreshCommand == "" {
+ t.Fatalf("s8 sharing = %+v (a commit link must not make it stale)", current)
+ }
+ if local := byID["session:opencode:s5"].Sharing; local.State != "local_only" || local.RefreshCommand != "" {
+ t.Fatalf("s5 sharing = %+v", local)
+ }
+ staleOnly, err := ReadTraceList(path, TraceQuery{State: "stale", Limit: 50})
+ if err != nil {
+ t.Fatal(err)
+ }
+ found := false
+ for _, trace := range staleOnly.Traces {
+ found = found || trace.ID == "session:claude_code:s7"
+ }
+ if !found {
+ t.Fatalf("--state stale missed s7: %+v", staleOnly.Traces)
+ }
+}
+
+func TestSessionsCarrySharingState(t *testing.T) {
+ path := newTestLog(t, parityFixture())
+ result, err := ReadSessions(path, EventQuery{Limit: 50})
+ if err != nil {
+ t.Fatal(err)
+ }
+ got := map[string]*SessionSharing{}
+ for _, s := range result.Sessions {
+ got[s.ID] = s.Sharing
+ }
+ if s := got["s7"]; s == nil || s.State != "stale" || s.RefreshCommand != "beacon share refresh claude_code:s7" {
+ t.Fatalf("s7 = %+v", s)
+ }
+ if s := got["s8"]; s == nil || s.State != "shared" || s.Visibility != "private" {
+ t.Fatalf("s8 = %+v", s)
+ }
+ if got["s5"] != nil {
+ t.Fatalf("s5 = %+v, want no sharing", got["s5"])
+ }
+ detail, ok, err := ReadSessionDetail(path, "s7")
+ if err != nil || !ok || detail.Session.Sharing == nil || detail.Session.Sharing.State != "stale" {
+ t.Fatalf("detail = %+v %v %v", detail.Session.Sharing, ok, err)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/static/app.js b/cli/beacon/internal/endpoint/dashboard/static/app.js
index 55975651..044fc0b2 100644
--- a/cli/beacon/internal/endpoint/dashboard/static/app.js
+++ b/cli/beacon/internal/endpoint/dashboard/static/app.js
@@ -1598,6 +1598,7 @@ function sessionRowHTML(session) {
<span class="session-list-prompt">
${models.length ? `<strong class="session-list-prompt-model">${models.map(escapeHTML).join(" · ")}</strong>` : ""}
${session.is_recurring ? `<strong class="session-recurring-indicator">Recurring ×${escapeHTML(session.recurrence_count)}</strong>` : ""}
+ ${sessionSharingIndicator(session.sharing)}
<span>${prompt}</span>
</span>
</td>
@@ -1610,6 +1611,47 @@ function sessionRowHTML(session) {
`;
}
+// Sharing state comes from the session.shared record `beacon share` writes. The dashboard is
+// read-only: it links to the shared trace and shows the refresh command to copy, and never shares.
+function sessionSharingIndicator(sharing) {
+ if (!sharing || !sharing.url) return "";
+ const stale = sharing.state === "stale";
+ return `<strong class="session-share-indicator${stale ? " session-share-stale" : ""}" title="${escapeHTML(stale ? "Shared; the session has newer activity than the shared trace" : "Shared on beacon.sh")}">${stale ? "Shared · stale" : "Shared"}</strong>`;
+}
+
+function safeShareURL(url) {
+ return typeof url === "string" && /^https:\/\/[^\s"'<>]+$/.test(url) ? url : "";
+}
+
+function sessionSharingRowHTML(sharing) {
+ if (!sharing || !sharing.url) return "";
+ const url = safeShareURL(sharing.url);
+ const stale = sharing.state === "stale";
+ const link = url
+ ? `<a href="${escapeHTML(url)}" target="_blank" rel="noopener noreferrer">${escapeHTML(url)}</a>`
+ : escapeHTML(sharing.url);
+ const detail = [sharing.visibility, stale ? "stale: newer local activity" : "up to date"].filter(Boolean).join(" · ");
+ const hint = sharing.refresh_command
+ ? `<span class="session-share-hint"><code>${escapeHTML(sharing.refresh_command)}</code> <button type="button" class="copy-share-refresh" data-command="${escapeHTML(sharing.refresh_command)}">Copy</button></span>`
+ : "";
+ return `${link}<small>${escapeHTML(detail)}</small>${hint}`;
+}
+
+function bindShareRefreshCopy(scope = document) {
+ scope.querySelectorAll(".copy-share-refresh").forEach((button) => {
+ button.onclick = async (event) => {
+ event.stopPropagation();
+ try {
+ await navigator.clipboard.writeText(button.dataset.command || "");
+ button.textContent = "Copied";
+ } catch (_) {
+ button.textContent = "Copy failed";
+ }
+ window.setTimeout(() => { button.textContent = "Copy"; }, 1400);
+ };
+ });
+}
+
function bindSessionRows(scope = document) {
const rows = scope.matches?.("tr[data-session-id]") ? [scope] : Array.from(scope.querySelectorAll("tr[data-session-id]"));
rows.forEach((row) => {
@@ -1960,6 +2002,11 @@ function renderSessionOverview(detail) {
: `<span class="session-badge session-badge-ok">No high risk events</span>`,
`<span class="session-badge session-badge-info">${escapeHTML(session.event_count || records.length)} events captured</span>`,
];
+ if (session.sharing && session.sharing.url) {
+ badges.push(session.sharing.state === "stale"
+ ? `<span class="session-badge session-badge-risk">Shared · stale</span>`
+ : `<span class="session-badge session-badge-ok">Shared</span>`);
+ }
$("#session-badges").innerHTML = badges.join("");
renderSessionMetadata(session, events);
@@ -1994,12 +2041,16 @@ function renderSessionMetadata(session, events) {
{ label: "Repository", value: session.repository ? escapeHTML(repositoryOptionLabel(session.repository)) : `<span class="muted">-</span>`, className: "mono" },
{ label: "Branch", value: session.branch ? escapeHTML(session.branch) : `<span class="muted">-</span>`, className: "mono" },
];
+ if (session.sharing && session.sharing.url) {
+ rows.push({ label: "Shared", value: sessionSharingRowHTML(session.sharing), className: "session-meta-sharing" });
+ }
$("#session-metadata").innerHTML = rows.map((row) => `
<div class="session-meta-item ${row.className || ""}">
<span>${escapeHTML(row.label)}</span>
<strong>${row.value}</strong>
</div>
`).join("");
+ bindShareRefreshCopy($("#session-metadata"));
}
function renderSessionActivity(session, records) {
diff --git a/cli/beacon/internal/endpoint/dashboard/static/styles.css b/cli/beacon/internal/endpoint/dashboard/static/styles.css
index dd3b0b80..370f1841 100644
--- a/cli/beacon/internal/endpoint/dashboard/static/styles.css
+++ b/cli/beacon/internal/endpoint/dashboard/static/styles.css
@@ -3611,3 +3611,29 @@ pre {
background: transparent;
}
+
+/* Sharing state from `beacon share`; read-only: a link and a command to copy. */
+.session-share-indicator {
+ color: var(--ok, #2f7d4f);
+ font-size: 0.75rem;
+ margin-right: 0.4rem;
+}
+.session-share-indicator.session-share-stale {
+ color: var(--warn, #a15c00);
+}
+.session-meta-sharing a {
+ word-break: break-all;
+}
+.session-meta-sharing small,
+.session-share-hint {
+ display: block;
+ margin-top: 0.2rem;
+}
+.session-share-hint code {
+ font-size: 0.75rem;
+ word-break: break-all;
+}
+.copy-share-refresh {
+ font-size: 0.7rem;
+ margin-left: 0.3rem;
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/traces.go b/cli/beacon/internal/endpoint/dashboard/traces.go
index e40a9e95..2dbd9798 100644
--- a/cli/beacon/internal/endpoint/dashboard/traces.go
+++ b/cli/beacon/internal/endpoint/dashboard/traces.go
@@ -66,6 +66,35 @@ type traceAggregate struct {
models map[string]bool
methods map[string]bool
titlePriority int
+ // lastActivity is the newest timestamp of an event the session itself produced, and
+ // lastShareRecord the newest session.shared record's; a shared trace whose session has
+ // activity after its last share or refresh is stale.
+ lastActivity string
+ lastShareRecord string
+}
+
+// shareBookkeeping is an event Beacon writes into a session's timeline about the session, rather
+// than activity of the session: it never makes a shared trace stale.
+func shareBookkeeping(action string) bool {
+ return action == "session.shared" || action == "session.share_requested" || action == "session.commit_linked"
+}
+
+func laterTimestamp(a, b string) string {
+ if b == "" {
+ return a
+ }
+ if a == "" {
+ return b
+ }
+ ta, errA := schema.ParseTimestamp(a)
+ tb, errB := schema.ParseTimestamp(b)
+ if errA != nil {
+ return b
+ }
+ if errB != nil || !tb.After(ta) {
+ return a
+ }
+ return b
}
// The local history, once the user has opted in to it, answers the same
@@ -357,6 +386,12 @@ func (a *traceAggregate) update(event schema.Event, traceEvent TraceEventV1) {
}
updateContentSummary(&a.summary.Content, event.Content)
a.updateRawMetadata(event.Raw)
+ switch {
+ case event.Event.Action == "session.shared":
+ a.lastShareRecord = laterTimestamp(a.lastShareRecord, event.Timestamp)
+ case !shareBookkeeping(event.Event.Action):
+ a.lastActivity = laterTimestamp(a.lastActivity, event.Timestamp)
+ }
}
func (a *traceAggregate) updateRawMetadata(raw map[string]interface{}) {
@@ -436,6 +471,14 @@ func (a *traceAggregate) finish() {
if a.summary.RemoteEventCount > 0 && a.summary.RemoteEventCount != a.summary.LocalEventCount {
a.summary.Sharing.State = "stale"
}
+ if a.summary.Sharing.URL != "" {
+ if a.lastShareRecord != "" && a.lastActivity != "" && laterTimestamp(a.lastShareRecord, a.lastActivity) != a.lastShareRecord {
+ a.summary.Sharing.State = "stale"
+ }
+ if a.summary.Session != nil {
+ a.summary.Sharing.RefreshCommand = asymptoteobserve.ShareRefreshCommand(a.summary.Harness.Name, a.summary.Session.ID)
+ }
+ }
}
func traceEventFromRecord(record EventRecord, number int) TraceEventV1 {
diff --git a/cli/beacon/internal/endpoint/traceview/traceview.go b/cli/beacon/internal/endpoint/traceview/traceview.go
index 6e950e8e..c31e4226 100644
--- a/cli/beacon/internal/endpoint/traceview/traceview.go
+++ b/cli/beacon/internal/endpoint/traceview/traceview.go
@@ -456,7 +456,7 @@ func (m Model) listView() string {
}
titleWidth := max(12, m.width-35)
line := fmt.Sprintf("%-8s %-*s %s", clock, titleWidth, truncate(trace.Title, titleWidth), trace.Harness.Name)
- meta := fmt.Sprintf(" %s · %d events · %s", tracePath(trace), trace.EventCount, contentLabel(trace))
+ meta := fmt.Sprintf(" %s · %d events · %s%s", tracePath(trace), trace.EventCount, contentLabel(trace), sharingLabel(trace))
if i == m.selected {
b.WriteString(selectedStyle.Render(fit(" ❯ "+line, m.width)) + "\n")
b.WriteString(selectedStyle.Render(fit(" "+meta, m.width)) + "\n")
@@ -483,6 +483,9 @@ func (m Model) detailView() string {
b.WriteString(" " + accentStyle.Render(truncate(title, max(20, m.width-4))) + "\n")
b.WriteString(" " + dimStyle.Render(fmt.Sprintf("%s · %s · %s%s · filter: %s",
trace.Harness.Name, tracePath(trace), trace.UpdatedAt, traceUsageLabel(trace), m.filterLabel)) + "\n")
+ for _, line := range sharingLines(trace) {
+ b.WriteString(" " + dimStyle.Render(truncate(line, max(20, m.width-4))) + "\n")
+ }
b.WriteString(" " + ruleStyle.Render(strings.Repeat("─", max(1, m.width-4))) + "\n")
if m.loading {
b.WriteString("\n Loading events…\n")
@@ -617,6 +620,36 @@ func tracePath(trace dashboard.TraceSummaryV1) string {
return "local"
}
+// sharingLabel marks a shared trace in the list: shared, or stale when the session has activity
+// newer than its last share or refresh.
+func sharingLabel(trace dashboard.TraceSummaryV1) string {
+ switch {
+ case trace.Sharing.URL == "":
+ return ""
+ case trace.Sharing.State == "stale":
+ return " · shared (stale)"
+ default:
+ return " · shared"
+ }
+}
+
+// sharingLines are the detail view's sharing lines: the link, and for a stale trace the command
+// that refreshes it, to copy. The view never shares or refreshes anything itself.
+func sharingLines(trace dashboard.TraceSummaryV1) []string {
+ if trace.Sharing.URL == "" {
+ return nil
+ }
+ state := "shared"
+ if trace.Sharing.State == "stale" {
+ state = "stale: newer local activity"
+ }
+ lines := []string{fmt.Sprintf("Shared (%s, %s): %s", firstNonEmpty(trace.Sharing.Visibility, "direct"), state, trace.Sharing.URL)}
+ if trace.Sharing.State == "stale" && trace.Sharing.RefreshCommand != "" {
+ lines = append(lines, "Refresh with: "+trace.Sharing.RefreshCommand)
+ }
+ return lines
+}
+
func contentLabel(trace dashboard.TraceSummaryV1) string {
label := trace.Content.Retention
if label == "" {
diff --git a/cli/beacon/internal/endpoint/traceview/traceview_test.go b/cli/beacon/internal/endpoint/traceview/traceview_test.go
index a56209d3..04a615eb 100644
--- a/cli/beacon/internal/endpoint/traceview/traceview_test.go
+++ b/cli/beacon/internal/endpoint/traceview/traceview_test.go
@@ -334,3 +334,24 @@ func TestEventDetailsIncludesStructuredData(t *testing.T) {
}
}
}
+
+func TestSharingLabelsAndRefreshHint(t *testing.T) {
+ local := dashboard.TraceSummaryV1{Sharing: dashboard.TraceSharingV1{State: "local_only"}}
+ if sharingLabel(local) != "" || sharingLines(local) != nil {
+ t.Fatal("a local trace shows sharing")
+ }
+ shared := dashboard.TraceSummaryV1{Sharing: dashboard.TraceSharingV1{State: "shared", Visibility: "direct", URL: "https://beacon.sh/s/x", RefreshCommand: "beacon share refresh claude_code:s"}}
+ if got := sharingLabel(shared); got != " · shared" {
+ t.Fatalf("label = %q", got)
+ }
+ if lines := sharingLines(shared); len(lines) != 1 || !strings.Contains(lines[0], "https://beacon.sh/s/x") {
+ t.Fatalf("lines = %q", lines)
+ }
+ shared.Sharing.State = "stale"
+ if got := sharingLabel(shared); got != " · shared (stale)" {
+ t.Fatalf("label = %q", got)
+ }
+ if lines := sharingLines(shared); len(lines) != 2 || lines[1] != "Refresh with: beacon share refresh claude_code:s" {
+ t.Fatalf("lines = %q", lines)
+ }
+}
diff --git a/docs/cli/dashboard.mdx b/docs/cli/dashboard.mdx
index 492c3185..b2b0f458 100644
--- a/docs/cli/dashboard.mdx
+++ b/docs/cli/dashboard.mdx
@@ -33,6 +33,11 @@ poll, and OTLP collection paths.
contains only lifecycle, metric, or internal events.
- **Session detail:** open a session timeline with metadata, activity and severity
summaries, event filters, raw JSON, and value inspectors.
+- **Sharing state:** a session shared with [`beacon share`](/cli/share) is marked
+ **Shared** in the session list and on its page, which links to the trace on
+ beacon.sh. It is marked **stale** when the session has activity newer than its
+ last share or refresh, and the page shows the `beacon share refresh …` command
+ to copy. The dashboard never shares or refreshes anything itself.
- **Lenses:** add tabs to a session's page that show it from one angle: files
changed with diffs, an itemized token bill, a security review, approvals, or a
[lens you wrote](/concepts/lenses). Each lens runs in a sandboxed frame with no
diff --git a/docs/cli/endpoint-traces.mdx b/docs/cli/endpoint-traces.mdx
index 9f6782a4..489f140f 100644
--- a/docs/cli/endpoint-traces.mdx
+++ b/docs/cli/endpoint-traces.mdx
@@ -15,6 +15,8 @@ beacon traces
Use the arrow keys or `j`/`k` to move, `enter` to open a trace, `/` to search, and `1`–`4` to filter an open trace by event type. Page Up and Page Down scroll long event details. The browser reads only local Beacon state and does not contact the network.
+A trace shared with [`beacon share`](/cli/share) is marked `shared` in the list, or `shared (stale)` when the session has activity newer than its last share or refresh (Beacon's own records, such as a commit link, do not count). An open trace shows its link and, when it is stale, the `beacon share refresh …` command to run. The plain list adds a last column for shared traces with the state, the link and, when stale, that command. In `--json` output, `sharing.refresh_command` carries the command for any shared trace.
+
When stdout or stdin is redirected, `beacon traces` falls back to a bounded tab-separated trace list instead of emitting terminal control sequences. The `beacon endpoint traces` commands below remain the stable JSON and scripting interface.
```bash title="Command syntax"
@@ -84,7 +86,7 @@ All commands accept:
|------|-------------|
| `--query <text>`, `-q <text>` | Filter traces by text |
| `--page <n>` | Page number for trace listing. Defaults to `1` |
-| `--state <state>` | Filter by sharing state: `local_only`, or `shared` for sessions published with [`beacon share`](/cli/share) |
+| `--state <state>` | Filter by sharing state: `local_only`, `shared` for sessions published with [`beacon share`](/cli/share), or `stale` for shared sessions with newer local activity |
| `--visibility <visibility>` | Filter by sharing visibility: `private` for local-only traces, or the `public`, `direct` or `private` a shared trace was given |
`search` also accepts:
diff --git a/pkg/asymptoteobserve/share.go b/pkg/asymptoteobserve/share.go
index e48a8d15..69a0264f 100644
--- a/pkg/asymptoteobserve/share.go
+++ b/pkg/asymptoteobserve/share.go
@@ -29,6 +29,22 @@ type ShareInfo struct {
Visibility string `json:"visibility,omitempty"`
}
+// ShareRefreshCommand is the command that refreshes harness's shared session: by external id when
+// that names the session plainly, and otherwise by session id and runtime.
+func ShareRefreshCommand(harness, sessionID string) string {
+ harness, sessionID = strings.TrimSpace(harness), strings.TrimSpace(sessionID)
+ if harness == "" || sessionID == "" {
+ return ""
+ }
+ if id := ShareExternalID(harness, sessionID); !strings.Contains(id, ":sha256-") {
+ return "beacon share refresh " + id
+ }
+ if strings.ContainsAny(sessionID, " \t\n'\"$`\\;&|<>()") {
+ return ""
+ }
+ return "beacon share refresh --harness " + NormalizeHarnessName(harness) + " " + sessionID
+}
+
// ShareSchemaVersion names the wire contract.
const ShareSchemaVersion = "beacon.share.v1"
diff --git a/pkg/asymptoteobserve/trace.go b/pkg/asymptoteobserve/trace.go
index 8e6d1f4d..e49cfa55 100644
--- a/pkg/asymptoteobserve/trace.go
+++ b/pkg/asymptoteobserve/trace.go
@@ -90,6 +90,9 @@ type TraceSharingV1 struct {
SharedAt string `json:"shared_at,omitempty"`
LastRefreshedAt string `json:"last_refreshed_at,omitempty"`
CreatedBy *TraceActorV1 `json:"created_by,omitempty"`
+ // RefreshCommand is the `beacon share refresh` command that uploads what a shared session
+ // gained since, for a reader to copy. Local views show it; they never run it.
+ RefreshCommand string `json:"refresh_command,omitempty"`
}
type TraceActorV1 struct {