Skip to content

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

Record each commit link in the session's runtime timeline

Claude53aa9b59d45d
diff --git a/CLAUDE.md b/CLAUDE.md
index 8932e3c7..1b55f8dd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -66,7 +66,7 @@ Supported runtime surfaces today:
- Token usage and runtime-reported cost capture across spans, logs, and metric datapoints, normalized into `gen_ai.usage`, with attribution rollups served by the dashboard token view (`/api/tokens`) and the `beacon token-usage` report command for local and CI logs.
- 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.
-- 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.
+- 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.
- 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`.
Current non-goals unless explicitly requested:
diff --git a/cli/beacon/cmd/git.go b/cli/beacon/cmd/git.go
index 7af8d877..d05a8cb5 100644
--- a/cli/beacon/cmd/git.go
+++ b/cli/beacon/cmd/git.go
@@ -11,7 +11,9 @@ import (
"github.com/spf13/cobra"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/gitlink"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
)
type gitOptions struct {
@@ -87,6 +89,9 @@ func runGitLink(cmd *cobra.Command, args []string) error {
if err != nil {
return err
}
+ if err := recordLinkEvents(ctx, repo, result); err != nil {
+ fmt.Fprintf(cmd.ErrOrStderr(), "warning: the note was written, but the runtime log was not: %v\n", err)
+ }
out := cmd.OutOrStdout()
if gitOpts.jsonOutput {
return writeIndentedJSON(out, result)
@@ -95,6 +100,23 @@ func runGitLink(cmd *cobra.Command, args []string) error {
return nil
}
+// recordLinkEvents writes a session.commit_linked event to the runtime log for each link this run
+// added. A dry run, or a run that found every link already on the note, records nothing, so the log
+// holds one event per link however often a commit is linked.
+func recordLinkEvents(ctx context.Context, repo gitlink.Repo, result gitlink.Result) error {
+ if result.DryRun || !result.NoteUpdated || len(result.Added) == 0 {
+ return nil
+ }
+ cc := gitlink.ResolveCommitContext(ctx, repo, result.Commit)
+ logPath := gitRuntimeLogPath()
+ for _, event := range gitlink.LinkEvents(result, cc, version.GetVersion()) {
+ if _, err := writer.AppendEvent(event, writer.Options{Path: logPath, UserMode: true}); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
func printGitLinkResult(out io.Writer, result gitlink.Result) {
fmt.Fprintf(out, "commit %s %s\n", shortSHA(result.Commit.SHA), result.Commit.Subject)
fmt.Fprintf(out, "window %s .. %s\n", result.Since.Local().Format(time.DateTime), result.Until.Local().Format(time.DateTime))
diff --git a/cli/beacon/cmd/git_hooks.go b/cli/beacon/cmd/git_hooks.go
index e2ce966e..d36bebff 100644
--- a/cli/beacon/cmd/git_hooks.go
+++ b/cli/beacon/cmd/git_hooks.go
@@ -208,6 +208,9 @@ func gitPostCommit(ctx context.Context) (gitlink.Result, bool) {
if err != nil {
return gitlink.Result{}, false
}
+ // The note is the link; the event is its echo in the session's timeline. A log the hook cannot
+ // write (a system-mode log this user may not append to) costs only the echo.
+ _ = recordLinkEvents(ctx, repo, result)
return result, true
}
diff --git a/cli/beacon/cmd/git_hooks_test.go b/cli/beacon/cmd/git_hooks_test.go
index e31dfcdb..e80372e9 100644
--- a/cli/beacon/cmd/git_hooks_test.go
+++ b/cli/beacon/cmd/git_hooks_test.go
@@ -146,3 +146,78 @@ func TestGitHookPostRewriteNormalizesRewrittenNotes(t *testing.T) {
t.Fatalf("note %q", note)
}
}
+
+func linkEventsIn(t *testing.T, logPath string) []schema.Event {
+ t.Helper()
+ data, err := os.ReadFile(logPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var events []schema.Event
+ for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
+ var e schema.Event
+ if json.Unmarshal([]byte(line), &e) == nil && e.Event.Action == gitlink.LinkAction {
+ events = append(events, e)
+ }
+ }
+ return events
+}
+
+func TestGitLinkRecordsOneEventPerLink(t *testing.T) {
+ root := gitCommandRepo(t)
+ top := mustGit(t, root, "rev-parse", "--show-toplevel")
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ if err := os.WriteFile(filepath.Join(root, "x.go"), []byte("1"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ writeRuntimeEvent(t, logPath, top, "cur-1", "x.go")
+ mustGit(t, root, "add", "-A")
+ mustGit(t, root, "commit", "-q", "-m", "x")
+ mustGit(t, root, "remote", "add", "origin", "https://[email protected]/org/repo.git")
+ sha := mustGit(t, root, "rev-parse", "HEAD")
+
+ if _, err := runGit(t, "link", "--cwd", root, "--log-path", logPath, "--dry-run"); err != nil {
+ t.Fatal(err)
+ }
+ if got := linkEventsIn(t, logPath); len(got) != 0 {
+ t.Fatalf("a dry run recorded %d events", len(got))
+ }
+ for run := 0; run < 2; run++ {
+ if _, err := runGit(t, "link", "--cwd", root, "--log-path", logPath); err != nil {
+ t.Fatal(err)
+ }
+ }
+ got := linkEventsIn(t, logPath)
+ if len(got) != 1 {
+ t.Fatalf("got %d link events after two runs, want 1", len(got))
+ }
+ e := got[0]
+ if e.Session.ID != "cur-1" || e.Harness.Name != "cursor" || e.VCS.Ref.Head.Revision != sha || e.Branch != "main" || e.Event.ID == "" {
+ t.Fatalf("event %+v", e)
+ }
+ if strings.Contains(e.VCS.Repository.URL.Full, "ghp_token") {
+ t.Fatalf("remote URL kept credentials: %q", e.VCS.Repository.URL.Full)
+ }
+ data, _ := os.ReadFile(logPath)
+ if strings.Contains(string(data), "ghp_token") {
+ t.Fatal("the token reached the runtime log")
+ }
+}
+
+func TestGitHookPostCommitRecordsTheLinkEvent(t *testing.T) {
+ root := gitCommandRepo(t)
+ top := mustGit(t, root, "rev-parse", "--show-toplevel")
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ if err := os.WriteFile(filepath.Join(root, "x.go"), []byte("1"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ writeRuntimeEvent(t, logPath, top, "cur-9", "x.go")
+ mustGit(t, root, "add", "-A")
+ mustGit(t, root, "commit", "-q", "-m", "x")
+ if _, err := runGit(t, "hook", "post-commit", "--cwd", root, "--log-path", logPath); err != nil {
+ t.Fatal(err)
+ }
+ if got := linkEventsIn(t, logPath); len(got) != 1 || got[0].Session.ID != "cur-9" {
+ t.Fatalf("events %+v", got)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/schema/event.go b/cli/beacon/internal/endpoint/schema/event.go
index d3c67530..8c433b2a 100644
--- a/cli/beacon/internal/endpoint/schema/event.go
+++ b/cli/beacon/internal/endpoint/schema/event.go
@@ -91,6 +91,12 @@ type MCPResourceInfo = asymptoteobserve.MCPResourceInfo
type MCPSessionInfo = asymptoteobserve.MCPSessionInfo
type ApprovalInfo = asymptoteobserve.ApprovalInfo
type HandoffInfo = asymptoteobserve.HandoffInfo
+type VCSInfo = asymptoteobserve.VCSInfo
+type VCSRefInfo = asymptoteobserve.VCSRefInfo
+type VCSRefHeadInfo = asymptoteobserve.VCSRefHeadInfo
+type VCSRepositoryInfo = asymptoteobserve.VCSRepositoryInfo
+type VCSRepositoryURLInfo = asymptoteobserve.VCSRepositoryURLInfo
+type VCSAttributionInfo = asymptoteobserve.VCSAttributionInfo
type PolicyInfo = asymptoteobserve.PolicyInfo
type PromptInfo = asymptoteobserve.PromptInfo
type ContentInfo = asymptoteobserve.ContentInfo
diff --git a/cli/beacon/internal/gitlink/events.go b/cli/beacon/internal/gitlink/events.go
new file mode 100644
index 00000000..8d20d9b6
--- /dev/null
+++ b/cli/beacon/internal/gitlink/events.go
@@ -0,0 +1,137 @@
+package gitlink
+
+import (
+ "context"
+ "fmt"
+ "net/url"
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// LinkAction is the event action recorded in the runtime log when a commit is linked to a session.
+const LinkAction = "session.commit_linked"
+
+// AttributionFileOverlap is the only attribution method today: the session wrote files the commit
+// changes.
+const AttributionFileOverlap = "file_overlap"
+
+// CommitContext is where a commit was made: the branch it landed on and the remote that branch
+// tracks. Both are best effort and empty when git cannot say.
+type CommitContext struct {
+ Branch string
+ RemoteURL string
+}
+
+// ResolveCommitContext reads the branch and remote for commit. The branch is HEAD's, and only when
+// HEAD is the commit: linking an older commit by hand cannot know which branch it was made on.
+func ResolveCommitContext(ctx context.Context, repo Repo, commit Commit) CommitContext {
+ var cc CommitContext
+ head, err := repo.Git.Run(ctx, nil, "rev-parse", "--verify", "--quiet", "HEAD")
+ if err == nil && strings.TrimSpace(head) == commit.SHA {
+ if branch, err := repo.Git.Run(ctx, nil, "symbolic-ref", "--quiet", "--short", "HEAD"); err == nil {
+ cc.Branch = strings.TrimSpace(branch)
+ }
+ }
+ remote := "origin"
+ if cc.Branch != "" {
+ if r, err := repo.Git.Run(ctx, nil, "config", "--get", "branch."+cc.Branch+".remote"); err == nil && strings.TrimSpace(r) != "" && strings.TrimSpace(r) != "." {
+ remote = strings.TrimSpace(r)
+ }
+ }
+ if u, err := repo.Git.Run(ctx, nil, "config", "--get", "remote."+remote+".url"); err == nil {
+ cc.RemoteURL = SanitizeRemoteURL(u)
+ }
+ return cc
+}
+
+// SanitizeRemoteURL removes credentials from a remote URL. An https remote can carry a token as
+// its user info (https://x-access-token:[email protected]/org/repo), and the URL is about to be
+// written to a log that may be forwarded. The user of an scp-style remote (git@host:org/repo) is a
+// login, not a secret, but it is dropped too so every spelling of a remote reads the same.
+func SanitizeRemoteURL(raw string) string {
+ raw = strings.TrimSpace(raw)
+ if raw == "" {
+ return ""
+ }
+ if strings.Contains(raw, "://") {
+ u, err := url.Parse(raw)
+ if err != nil {
+ // Unparseable: drop anything that could be user info rather than risk keeping it.
+ if at := strings.LastIndex(raw, "@"); at >= 0 {
+ if scheme := strings.Index(raw, "://"); scheme >= 0 && scheme < at {
+ return raw[:scheme+3] + raw[at+1:]
+ }
+ }
+ return raw
+ }
+ u.User = nil
+ u.RawQuery = ""
+ u.Fragment = ""
+ return u.String()
+ }
+ // scp-like syntax: [user@]host:path. A local path has no colon before its first slash.
+ if at := strings.Index(raw, "@"); at >= 0 {
+ colon := strings.Index(raw, ":")
+ slash := strings.Index(raw, "/")
+ if colon > at && (slash < 0 || colon < slash) {
+ return raw[at+1:]
+ }
+ }
+ return raw
+}
+
+// LinkEvents returns one runtime-log event per link result added, in the session's own timeline:
+// harness and session are the linked session's, so the dashboard, traces and handoff briefs show
+// the commit alongside the work that produced it.
+//
+// The events carry no file path, command, or tool arguments. That keeps them metadata only, and it
+// keeps them from ever counting as attribution evidence themselves.
+func LinkEvents(result Result, cc CommitContext, agentVersion string) []schema.Event {
+ candidates := map[string]Candidate{}
+ for _, c := range result.Candidates {
+ candidates[c.Key()] = c
+ }
+ var events []schema.Event
+ for _, link := range result.Added {
+ c := candidates[link.Key()]
+ event := schema.NewEvent(schema.NewEventOptions{
+ Action: LinkAction,
+ Category: "session",
+ Severity: schema.SeverityInfo,
+ AgentVersion: agentVersion,
+ Harness: schema.HarnessInfo{Name: link.Harness},
+ Fidelity: asymptoteobserve.FidelityInferred,
+ Message: fmt.Sprintf("commit %s linked to this session: it wrote %d of the %d file(s) the commit changes",
+ shortRevision(result.Commit.SHA), len(c.Files), result.ChangedFiles),
+ })
+ event.Session = &schema.SessionInfo{ID: link.SessionID, WorkingDirectory: result.RepoRoot}
+ event.Repository = result.RepoRoot
+ event.Branch = cc.Branch
+ head := &schema.VCSRefHeadInfo{Revision: result.Commit.SHA, Name: cc.Branch}
+ if cc.Branch != "" {
+ head.Type = "branch"
+ }
+ event.VCS = &schema.VCSInfo{
+ Ref: &schema.VCSRefInfo{Head: head},
+ Attribution: &schema.VCSAttributionInfo{
+ Method: AttributionFileOverlap,
+ ChangedFiles: result.ChangedFiles,
+ MatchedFiles: len(c.Files),
+ },
+ }
+ if cc.RemoteURL != "" {
+ event.VCS.Repository = &schema.VCSRepositoryInfo{URL: &schema.VCSRepositoryURLInfo{Full: cc.RemoteURL}}
+ }
+ events = append(events, event)
+ }
+ return events
+}
+
+func shortRevision(sha string) string {
+ if len(sha) > 12 {
+ return sha[:12]
+ }
+ return sha
+}
diff --git a/cli/beacon/internal/gitlink/events_test.go b/cli/beacon/internal/gitlink/events_test.go
new file mode 100644
index 00000000..a2b94c8d
--- /dev/null
+++ b/cli/beacon/internal/gitlink/events_test.go
@@ -0,0 +1,143 @@
+package gitlink
+
+import (
+ "context"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+)
+
+func TestSanitizeRemoteURL(t *testing.T) {
+ for raw, want := range map[string]string{
+ "https://github.com/org/repo.git": "https://github.com/org/repo.git",
+ "https://x-access-token:[email protected]/org/repo.git": "https://github.com/org/repo.git",
+ "https://[email protected]/group/repo": "https://gitlab.example.com/group/repo",
+ "https://gitlab.example.com/group/repo.git?private_token=abc": "https://gitlab.example.com/group/repo.git",
+ "ssh://[email protected]:22/org/repo.git": "ssh://github.com:22/org/repo.git",
+ "[email protected]:org/repo.git": "github.com:org/repo.git",
+ "github.com:org/repo.git": "github.com:org/repo.git",
+ "/srv/git/repo.git": "/srv/git/repo.git",
+ "../sibling": "../sibling",
+ "file:///srv/git/repo.git": "file:///srv/git/repo.git",
+ " https://tok@host/r \n": "https://host/r",
+ "": "",
+ } {
+ if got := SanitizeRemoteURL(raw); got != want {
+ t.Errorf("SanitizeRemoteURL(%q) = %q, want %q", raw, got, want)
+ }
+ }
+ // A URL net/url rejects still loses anything that could be user info.
+ if got := SanitizeRemoteURL("https://to%ken:se cret@host/r"); strings.Contains(got, "se cret") || strings.Contains(got, "to%ken") {
+ t.Errorf("unparseable URL kept credentials: %q", got)
+ }
+}
+
+func TestLinkEventsShape(t *testing.T) {
+ result := Result{
+ Commit: Commit{SHA: "0123456789abcdef0123456789abcdef01234567"},
+ RepoRoot: "/work/repo",
+ ChangedFiles: 3,
+ Candidates: []Candidate{
+ {Link: Link{"claude_code", "s1"}, Files: []string{"a.go", "b.go"}},
+ {Link: Link{"cursor", "c1"}, Files: []string{"a.go"}, AlreadyLinked: true},
+ },
+ Added: []Link{{"claude_code", "s1"}},
+ NoteUpdated: true,
+ }
+ events := LinkEvents(result, CommitContext{Branch: "main", RemoteURL: "https://github.com/org/repo.git"}, "1.2.3")
+ if len(events) != 1 {
+ t.Fatalf("got %d events, want one per added link", len(events))
+ }
+ e := events[0]
+ if err := e.Validate(); err != nil {
+ t.Fatal(err)
+ }
+ if e.Event.Action != LinkAction || e.Event.Fidelity != "inferred" || e.Harness.Name != "claude_code" || e.Harness.CollectionMethod != "" {
+ t.Fatalf("event info %+v harness %+v", e.Event, e.Harness)
+ }
+ if e.Session == nil || e.Session.ID != "s1" || e.Session.WorkingDirectory != "/work/repo" || e.Repository != "/work/repo" || e.Branch != "main" {
+ t.Fatalf("session/repository %+v %q %q", e.Session, e.Repository, e.Branch)
+ }
+ v := e.VCS
+ if v == nil || v.Ref.Head.Revision != result.Commit.SHA || v.Ref.Head.Name != "main" || v.Ref.Head.Type != "branch" ||
+ v.Repository.URL.Full != "https://github.com/org/repo.git" ||
+ v.Attribution.Method != AttributionFileOverlap || v.Attribution.ChangedFiles != 3 || v.Attribution.MatchedFiles != 2 {
+ t.Fatalf("vcs %+v", v)
+ }
+ if e.File != nil || e.Command != nil || e.Tool != nil || e.GenAI != nil || e.Prompt != nil {
+ t.Fatal("a link event must carry no file, command, tool or content fields")
+ }
+ data, _ := json.Marshal(e)
+ for _, key := range []string{`"vcs":{"ref":{"head":{"revision":"0123456789abcdef0123456789abcdef01234567","name":"main","type":"branch"}}`, `"url":{"full":`, `"attribution":{"method":"file_overlap"`} {
+ if !strings.Contains(string(data), key) {
+ t.Errorf("serialized event lacks %s:\n%s", key, data)
+ }
+ }
+ // Detached HEAD: no branch, no ref type, no remote block.
+ detached := LinkEvents(result, CommitContext{}, "")
+ if h := detached[0].VCS.Ref.Head; h.Name != "" || h.Type != "" || detached[0].VCS.Repository != nil {
+ t.Fatalf("detached %+v", detached[0].VCS)
+ }
+ if LinkEvents(Result{}, CommitContext{}, "") != nil {
+ t.Fatal("no links, no events")
+ }
+}
+
+func TestResolveCommitContext(t *testing.T) {
+ r := newTestRepo(t)
+ ctx := context.Background()
+ r.write("a", "1")
+ first := r.commitAt("first", t0)
+ r.write("a", "2")
+ r.commitAt("second", t0.Add(time.Minute))
+ r.git("remote", "add", "origin", "https://tok:[email protected]/org/repo.git")
+ r.git("remote", "add", "fork", "[email protected]:me/repo.git")
+ repo := r.open()
+ head, _ := ResolveCommit(ctx, repo.Git, "HEAD")
+ if cc := ResolveCommitContext(ctx, repo, head); cc.Branch != "main" || cc.RemoteURL != "https://example.com/org/repo.git" {
+ t.Fatalf("HEAD context %+v", cc)
+ }
+ r.git("config", "branch.main.remote", "fork")
+ if cc := ResolveCommitContext(ctx, repo, head); cc.RemoteURL != "example.com:me/repo.git" {
+ t.Fatalf("tracked remote %+v", cc)
+ }
+ // An older commit's branch is unknown.
+ old, _ := ResolveCommit(ctx, repo.Git, first)
+ if cc := ResolveCommitContext(ctx, repo, old); cc.Branch != "" {
+ t.Fatalf("old commit branch %q", cc.Branch)
+ }
+ r.git("checkout", "-q", "--detach")
+ if cc := ResolveCommitContext(ctx, repo, head); cc.Branch != "" || cc.RemoteURL != "https://example.com/org/repo.git" {
+ t.Fatalf("detached %+v", cc)
+ }
+}
+
+func TestLinkEventsAreNeverEvidence(t *testing.T) {
+ r := newTestRepo(t)
+ ctx := context.Background()
+ repo := r.open()
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ events := LinkEvents(Result{
+ Commit: Commit{SHA: strings.Repeat("a", 40)}, RepoRoot: repo.Root, ChangedFiles: 1,
+ Candidates: []Candidate{{Link: Link{"codex_cli", "s"}, Files: []string{"x.go"}}},
+ Added: []Link{{"codex_cli", "s"}},
+ }, CommitContext{Branch: "main"}, "")
+ var b strings.Builder
+ for _, e := range events {
+ e.Timestamp = schema.FormatTimestamp(t0)
+ data, _ := json.Marshal(e)
+ b.Write(append(data, '\n'))
+ }
+ if err := os.WriteFile(logPath, []byte(b.String()), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ got, err := ReadEvidence(ctx, repo, logPath, t0.Add(-time.Hour), t0.Add(time.Hour))
+ if err != nil || len(got) != 0 {
+ t.Fatalf("link events read as evidence: %v %v", got, err)
+ }
+}
diff --git a/docs/cli/git.mdx b/docs/cli/git.mdx
index 55ea6696..29e1812c 100644
--- a/docs/cli/git.mdx
+++ b/docs/cli/git.mdx
@@ -128,6 +128,40 @@ beacon git notes origin/main --json
| `-C`, `--cwd <dir>` | Repository to operate on |
| `--json` | Print commits and their links as JSON |
+## Runtime log events
+
+Each new link is also recorded in the runtime log as a `session.commit_linked` event in the linked session's own timeline, so the dashboard, `beacon endpoint traces`, handoff briefs, rules and any forwarding destination see the commit alongside the work that produced it. `link` and the hook record an event only for a link they add: a dry run, or a commit already linked to the session, records nothing.
+
+```json title="Example event (abridged)"
+{
+ "event": { "action": "session.commit_linked", "category": "session", "fidelity": "inferred" },
+ "harness": { "name": "claude_code" },
+ "session": { "id": "sess-claude-e2e", "working_directory": "/work/my-repo" },
+ "repository": "/work/my-repo",
+ "branch": "main",
+ "vcs": {
+ "ref": { "head": { "revision": "3f6aa6c04b78…", "name": "main", "type": "branch" } },
+ "repository": { "url": { "full": "https://github.com/org/my-repo.git" } },
+ "attribution": { "method": "file_overlap", "changed_files": 3, "matched_files": 3 }
+ },
+ "message": "commit 3f6aa6c04b78 linked to this session: it wrote 3 of the 3 file(s) the commit changes"
+}
+```
+
+- `event.fidelity` is `inferred`: the link is Beacon's conclusion from file overlap, not something the runtime reported.
+- `vcs.ref.head.name` is the branch HEAD was on at commit time. It is empty for a detached HEAD, or for an older commit linked by hand, whose branch git cannot say.
+- `vcs.repository.url.full` is the URL of the remote the branch tracks, or `origin`, with any user name, token, or query string removed.
+- The event carries identifiers and counts only: no file paths, diff, or commit message.
+
+A rule can match on these fields, for example a commit to `main` that one session wrote in full:
+
+```yaml
+match: >
+ e.event.action == "session.commit_linked" &&
+ e.vcs.ref.head.name == "main" &&
+ e.vcs.attribution.matched_files == e.vcs.attribution.changed_files
+```
+
## Note format
Links live under `refs/notes/beacon`, one per line:
diff --git a/docs/telemetry-schema/fields.mdx b/docs/telemetry-schema/fields.mdx
index 3a38c3db..2e80de5e 100644
--- a/docs/telemetry-schema/fields.mdx
+++ b/docs/telemetry-schema/fields.mdx
@@ -35,6 +35,7 @@ Beacon models each event as an action plus a set of typed entities. The [`event`
| `destination` | Output or validation destination state | `type`, `mode`, `status` |
| `health` | Endpoint or component health state | `component`, `status`, `reason` |
| `user_agent` | Browser that produced a browser chat event, as the browser names itself | `name`, `version` |
+| `vcs` | On a `session.commit_linked` event, the commit a session was [linked to](/cli/git), in the OpenTelemetry VCS shape | `ref.head.revision`, `ref.head.name`, `ref.head.type`, `repository.url.full`, `attribution.method`, `attribution.changed_files`, `attribution.matched_files` |
Top-level `sequence`, `model`, `repository`, `branch`, `message`, `raw`, and `field_truncated` fields add shared context that can apply across multiple entities. For example, a command event can include both `tool` and `command`; a file edit can include `file`, `session`, `repository`, and `branch`; a CI event can include `origin` and `run`; and a GenAI tool call can include both `tool` and nested `gen_ai.tool` metadata.
@@ -80,6 +81,7 @@ Optional context fields add detail when available:
| `destination` | Output destination state, such as Wazuh localfile validation |
| `health` | Component health status |
| `user_agent` | Browser name and major version for browser extension events, such as `Microsoft Edge` or `Brave`. See [Chromium browsers](/runtimes/browser-extension-chromium#which-browser-an-event-came-from) |
+| `vcs` | Commit id, branch, and remote URL (credentials removed) of a commit linked to the session, with how many of its files the session wrote. See [`beacon git`](/cli/git#runtime-log-events) |
| `model`, `repository`, `branch`, `message`, `raw`, `field_truncated` | Additional runtime context and truncation metadata |
## Related
diff --git a/pkg/asymptoteobserve/event.go b/pkg/asymptoteobserve/event.go
index 2be21dca..0d5edec4 100644
--- a/pkg/asymptoteobserve/event.go
+++ b/pkg/asymptoteobserve/event.go
@@ -430,6 +430,48 @@ type UserAgentInfo struct {
Version string `json:"version,omitempty"`
}
+// VCSInfo is version-control context in the OpenTelemetry VCS semantic convention shape
+// (vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type, vcs.repository.url.full).
+// Attribution is Beacon's own and has no semconv equivalent: on a session.commit_linked event it
+// records how the commit was matched to the session. Everything here is metadata -- identifiers and
+// counts, never file contents or commit messages -- so it survives metadata-only retention.
+type VCSInfo struct {
+ Ref *VCSRefInfo `json:"ref,omitempty"`
+ Repository *VCSRepositoryInfo `json:"repository,omitempty"`
+ Attribution *VCSAttributionInfo `json:"attribution,omitempty"`
+}
+
+type VCSRefInfo struct {
+ Head *VCSRefHeadInfo `json:"head,omitempty"`
+}
+
+type VCSRefHeadInfo struct {
+ // Revision is the commit id.
+ Revision string `json:"revision,omitempty"`
+ // Name is the branch the commit was made on; empty on a detached HEAD.
+ Name string `json:"name,omitempty"`
+ // Type is "branch" when Name is set.
+ Type string `json:"type,omitempty"`
+}
+
+type VCSRepositoryInfo struct {
+ URL *VCSRepositoryURLInfo `json:"url,omitempty"`
+}
+
+type VCSRepositoryURLInfo struct {
+ // Full is the remote's URL with any credentials removed.
+ Full string `json:"full,omitempty"`
+}
+
+// VCSAttributionInfo records how a commit was matched to a session. Method names the rule
+// (file_overlap: the session wrote files the commit changes); ChangedFiles is how many files the
+// commit changes and MatchedFiles how many of those the session wrote.
+type VCSAttributionInfo struct {
+ Method string `json:"method,omitempty"`
+ ChangedFiles int `json:"changed_files,omitempty"`
+ MatchedFiles int `json:"matched_files,omitempty"`
+}
+
type HealthInfo struct {
Component string `json:"component,omitempty"`
Status string `json:"status,omitempty"`
@@ -484,6 +526,7 @@ type Event struct {
Destination *DestinationInfo `json:"destination,omitempty"`
Health *HealthInfo `json:"health,omitempty"`
UserAgent *UserAgentInfo `json:"user_agent,omitempty"`
+ VCS *VCSInfo `json:"vcs,omitempty"`
GenAI *GenAIInfo `json:"gen_ai,omitempty"`
Model string `json:"model,omitempty"`
Repository string `json:"repository,omitempty"`
diff --git a/spec/threat-rules/FIELDS.md b/spec/threat-rules/FIELDS.md
index 75c273ad..bc8d06a2 100644
--- a/spec/threat-rules/FIELDS.md
+++ b/spec/threat-rules/FIELDS.md
@@ -151,4 +151,11 @@ Regenerate with `beacon rules fields --markdown > spec/threat-rules/FIELDS.md`.
| `e.user.uid` | string |
| `e.user_agent.name` | string |
| `e.user_agent.version` | string |
+| `e.vcs.attribution.changed_files` | int |
+| `e.vcs.attribution.matched_files` | int |
+| `e.vcs.attribution.method` | string |
+| `e.vcs.ref.head.name` | string |
+| `e.vcs.ref.head.revision` | string |
+| `e.vcs.ref.head.type` | string |
+| `e.vcs.repository.url.full` | string |
| `e.vendor` | string |