fix(audit): make JSONL sidecar opt-in (#4688)

Routine issue history already lands in the database events tables. Stop creating or appending the interactions JSONL sidecar by default, add audit.enabled for explicit sidecar use, and expose database events via bd history --events.

Fixes gastownhall/beads#4687

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
This commit is contained in:
matt wilkie 2026-07-11 00:09:17 -07:00 • committed by GitHub
commit 64a136d56e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 181 additions and 29 deletions

View file

@ -29,9 +29,14 @@ var (
var auditCmd = &cobra.Command{
Use: "audit",
Short: "Record and label agent interactions (append-only JSONL)",
Long: `Audit log entries are appended to .beads/interactions.jsonl.
Long: `Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
Each line is one event. This file is intended to be versioned in git and used for:
This optional JSONL sidecar is disabled by default. Enable it with:
bd config set audit.enabled true
Issue history is always recorded in the database and is visible with
bd history <id> --events. The JSONL sidecar is for explicit interaction capture:
- auditing ("why did the agent do that?")
- dataset generation (SFT/RL fine-tuning)
@ -95,7 +100,7 @@ var auditRecordCmd = &cobra.Command{
}
}
id, err := audit.Append(&e)
id, err := audit.AppendIfEnabled(&e)
if err != nil {
return HandleError("%v", err)
}
@ -138,7 +143,7 @@ var auditLabelCmd = &cobra.Command{
Reason: auditLabelReason,
}
id, err := audit.Append(&e)
id, err := audit.AppendIfEnabled(&e)
if err != nil {
return HandleError("%v", err)
}

View file

@ -1,15 +1,18 @@
package main
import (
"context"
"fmt"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
)
var (
historyLimit int
historyLimit int
historyEvents bool
)
var historyCmd = &cobra.Command{
@ -21,7 +24,8 @@ where the issue was modified.
Examples:
bd history bd-123 # Show all history for issue bd-123
bd history bd-123 --limit 5 # Show last 5 changes`,
bd history bd-123 --limit 5 # Show last 5 changes
bd history bd-123 --events # Show database audit events`,
Args: cobra.ExactArgs(1),
SilenceUsage: true,
SilenceErrors: true,
@ -36,6 +40,18 @@ Examples:
ctx := rootCtx
issueID := args[0]
if historyEvents {
events, err := collectHistoryEvents(ctx, issueID, historyLimit)
if err != nil {
return HandleErrorRespectJSON("failed to get history events: %v", err)
}
if jsonOutput {
return outputJSON(events)
}
printHistoryEvents(issueID, events)
return nil
}
history, err := store.History(ctx, issueID)
if err != nil {
return HandleErrorRespectJSON("failed to get history: %v", err)
@ -87,6 +103,56 @@ Examples:
func init() {
historyCmd.Flags().IntVar(&historyLimit, "limit", 0, "Limit number of history entries (0 = all)")
historyCmd.Flags().BoolVar(&historyEvents, "events", false, "Show database audit events instead of commit snapshots")
historyCmd.ValidArgsFunction = issueIDCompletion
rootCmd.AddCommand(historyCmd)
}
func collectHistoryEvents(ctx context.Context, issueID string, limit int) ([]types.Event, error) {
iter, err := store.IterEvents(ctx, issueID, limit)
if err != nil {
return nil, err
}
defer func() { _ = iter.Close() }()
var events []types.Event
for iter.Next(ctx) {
event := iter.Value()
if event != nil {
events = append(events, *event)
}
}
if err := iter.Err(); err != nil {
return nil, err
}
return events, nil
}
func printHistoryEvents(issueID string, events []types.Event) {
if len(events) == 0 {
fmt.Printf("No history events found for issue %s\n", issueID)
return
}
fmt.Printf("\n%s History events for %s (%d entries)\n\n",
ui.RenderAccent("📜"), issueID, len(events))
for i, event := range events {
fmt.Printf("%s %s by %s\n",
ui.RenderMuted(event.CreatedAt.Format("2006-01-02 15:04:05")),
event.EventType,
event.Actor)
if event.OldValue != nil && *event.OldValue != "" {
fmt.Printf(" Old: %s\n", *event.OldValue)
}
if event.NewValue != nil && *event.NewValue != "" {
fmt.Printf(" New: %s\n", *event.NewValue)
}
if event.Comment != nil && *event.Comment != "" {
fmt.Printf(" Comment: %s\n", *event.Comment)
}
if i < len(events)-1 {
fmt.Println()
}
}
fmt.Println()
}

View file

@ -121,6 +121,22 @@ func TestEmbeddedHistory(t *testing.T) {
}
})
t.Run("events_json_output", func(t *testing.T) {
events := bdHistoryJSON(t, bd, dir, issue.ID, "--events")
if len(events) == 0 {
t.Fatal("expected non-empty history events")
}
var sawStatus bool
for _, event := range events {
if event["event_type"] == "status_changed" {
sawStatus = true
}
}
if !sawStatus {
t.Fatalf("expected status_changed event in history events, got %#v", events)
}
})
// ===== --json output =====
t.Run("json_output_structure", func(t *testing.T) {

View file

@ -685,8 +685,8 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
}
// Always create local .beads/ when using default location (CWD/.beads).
// The local directory is needed for metadata.json, config.yaml, .gitignore,
// interactions.jsonl, and hooks — regardless of where dolt data lives.
// The local directory is needed for metadata.json, config.yaml,
// .gitignore, and hooks — regardless of where dolt data lives.
// Only skip when BEADS_DIR explicitly points outside the project.
//
// Previous logic only created .beads/ when the dolt data dir was a
@ -775,15 +775,6 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
}
}
// Ensure interactions.jsonl exists (append-only agent audit log)
interactionsPath := filepath.Join(beadsDir, "interactions.jsonl")
if _, err := os.Stat(interactionsPath); os.IsNotExist(err) {
// nolint:gosec // G306: JSONL file needs to be readable by other tools
if err := os.WriteFile(interactionsPath, []byte{}, 0644); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to create interactions.jsonl: %v\n", err)
// Non-fatal - continue anyway
}
}
}
// Ensure git is initialized — bd requires git for role config, sync branches,

View file

@ -1463,7 +1463,9 @@ func TestEmbeddedInit(t *testing.T) {
t.Run("files_created", func(t *testing.T) {
dir, beadsDir, _ := bdInit(t, bd, "--prefix", "fc", "--skip-hooks")
requireFile(t, filepath.Join(beadsDir, "config.yaml"))
requireFile(t, filepath.Join(beadsDir, "interactions.jsonl"))
if _, err := os.Stat(filepath.Join(beadsDir, "interactions.jsonl")); !os.IsNotExist(err) {
t.Fatalf("interactions.jsonl should be created only when audit.enabled is true, got stat err %v", err)
}
requireFile(t, filepath.Join(dir, "AGENTS.md"))
requireFile(t, filepath.Join(dir, ".agents", "skills", "beads", "SKILL.md"))
requireFile(t, filepath.Join(dir, ".agents", "skills", "beads", "agents", "openai.yaml"))

View file

@ -60,6 +60,12 @@ func renderInitConfigYAML(prefix string, noDbMode bool) []byte {
# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
# actor: ""
# Optional JSONL sidecar for explicit agent/tool interaction audit records.
# Issue history is always recorded in the database and is visible with
# bd history <id> --events; this only controls .beads/interactions.jsonl.
# audit:
# enabled: false
# Export events (audit trail) to .beads/events.jsonl on each flush/sync
# When enabled, new events are appended incrementally using a high-water mark.
# Use 'bd export --events' to trigger manually regardless of this setting.

View file

@ -1713,6 +1713,7 @@ where the issue was modified.
Examples:
bd history bd-123 # Show all history for issue bd-123
bd history bd-123 --limit 5 # Show last 5 changes
bd history bd-123 --events # Show database audit events
```
bd history <id> [flags]
@ -1721,6 +1722,7 @@ bd history <id> [flags]
**Flags:**
```
--events Show database audit events instead of commit snapshots
--limit int Limit number of history entries (0 = all)
```
@ -5470,9 +5472,14 @@ bd ado sync [flags]
### bd audit
Audit log entries are appended to .beads/interactions.jsonl.
Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
Each line is one event. This file is intended to be versioned in git and used for:
This optional JSONL sidecar is disabled by default. Enable it with:
bd config set audit.enabled true
Issue history is always recorded in the database and is visible with
bd history &lt;id&gt; --events. The JSONL sidecar is for explicit interaction capture:
- auditing ("why did the agent do that?")
- dataset generation (SFT/RL fine-tuning)

View file

@ -9,9 +9,11 @@ import (
"fmt"
"os"
"path/filepath"
"strings"
"time"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/config"
)
const (
@ -59,6 +61,25 @@ func Path() (string, error) {
return filepath.Join(beadsDir, FileName), nil
}
// Enabled reports whether the optional JSONL interaction sidecar is enabled.
// First-class issue history is always recorded in the database events tables;
// this gate only controls .beads/interactions.jsonl.
func Enabled() bool {
if raw, ok := os.LookupEnv("BD_AUDIT_ENABLED"); ok {
return truthy(raw)
}
return config.GetBool("audit.enabled")
}
func truthy(raw string) bool {
switch strings.ToLower(strings.TrimSpace(raw)) {
case "1", "t", "true", "y", "yes", "on":
return true
default:
return false
}
}
// EnsureFile creates .beads/interactions.jsonl if it does not exist.
func EnsureFile() (string, error) {
p, err := Path()
@ -133,9 +154,18 @@ func Append(e *Entry) (string, error) {
return e.ID, nil
}
// AppendIfEnabled appends only when the optional JSONL sidecar is enabled.
func AppendIfEnabled(e *Entry) (string, error) {
if !Enabled() {
return "", fmt.Errorf("audit JSONL sidecar is disabled; set audit.enabled=true or BD_AUDIT_ENABLED=1 to write %s", FileName)
}
return Append(e)
}
// LogFieldChange logs a field change (status, assignee, priority, etc.) to the
// audit log. This survives Dolt GC flatten, which destroys commit history.
// Best-effort: errors are silently ignored so audit logging never blocks operations.
// optional JSONL sidecar when it is enabled. First-class issue history is
// recorded separately in the database events tables. Best-effort: errors are
// silently ignored so sidecar logging never blocks operations.
// Optional reason is included when non-empty (e.g., close reason, cleanup rule).
func LogFieldChange(issueID, field, oldValue, newValue, actor, reason string) {
if oldValue == newValue {
@ -149,7 +179,7 @@ func LogFieldChange(issueID, field, oldValue, newValue, actor, reason string) {
if reason != "" {
extra["reason"] = reason
}
_, _ = Append(&Entry{
_, _ = AppendIfEnabled(&Entry{
Kind: "field_change",
IssueID: issueID,
Actor: actor,

View file

@ -22,6 +22,7 @@ func TestAppend_CreatesFileAndWritesJSONL(t *testing.T) {
t.Fatalf("write metadata.json: %v", err)
}
t.Setenv("BEADS_DIR", beadsDir)
t.Setenv("BD_AUDIT_ENABLED", "1")
id1, err := Append(&Entry{Kind: "llm_call", Model: "test-model", Prompt: "p", Response: "r"})
if err != nil {
@ -55,6 +56,28 @@ func TestAppend_CreatesFileAndWritesJSONL(t *testing.T) {
}
}
func TestAppendIfEnabled_DisabledDoesNotCreateFile(t *testing.T) {
tmp := t.TempDir()
beadsDir := filepath.Join(tmp, ".beads")
if err := os.MkdirAll(beadsDir, 0750); err != nil {
t.Fatalf("mkdir: %v", err)
}
metadataPath := filepath.Join(beadsDir, "metadata.json")
if err := os.WriteFile(metadataPath, []byte(`{"backend":"dolt"}`), 0644); err != nil {
t.Fatalf("write metadata.json: %v", err)
}
t.Setenv("BEADS_DIR", beadsDir)
t.Setenv("BD_AUDIT_ENABLED", "")
if _, err := AppendIfEnabled(&Entry{Kind: "llm_call", Model: "test-model"}); err == nil {
t.Fatalf("expected disabled append to fail")
}
if _, err := os.Stat(filepath.Join(beadsDir, FileName)); !os.IsNotExist(err) {
t.Fatalf("disabled append created %s: %v", FileName, err)
}
}
func TestEnsureFile_DoesNotTruncateWhenConcurrentCreatorWins(t *testing.T) {
tmp := t.TempDir()
beadsDir := filepath.Join(tmp, ".beads")

View file

@ -42,6 +42,7 @@ func TestAppend_ConcurrentWritersUniqueIDs(t *testing.T) {
t.Fatalf("write metadata.json: %v", err)
}
t.Setenv("BEADS_DIR", beadsDir)
t.Setenv("BD_AUDIT_ENABLED", "1")
const (
writers = 8

View file

@ -171,6 +171,7 @@ func Initialize() error {
// Set defaults for all flags
v.SetDefault("json", false)
v.SetDefault("events-export", false)
v.SetDefault("audit.enabled", false)
v.SetDefault("no-db", false)
v.SetDefault("no-hooks", false)
v.SetDefault("db", "")

View file

@ -101,7 +101,7 @@ func IsYamlOnlyKey(key string) bool {
}
// Check prefix matches for nested keys
prefixes := []string{"routing.", "sync.", "git.", "directory.", "repos.", "external_projects.", "validation.", "hierarchy.", "ai.", "backup.", "export.", "dolt.", "federation.", "metrics.", "list."}
prefixes := []string{"routing.", "sync.", "git.", "directory.", "repos.", "external_projects.", "validation.", "hierarchy.", "ai.", "backup.", "export.", "dolt.", "federation.", "metrics.", "list.", "audit."}
for _, prefix := range prefixes {
if strings.HasPrefix(key, prefix) {
return true

View file

@ -186,9 +186,6 @@ func (u *beadsDirFSUseCaseImpl) InitializeBeadsDir(ctx context.Context, params I
return InitializeBeadsDirResult{}, err
}
}
if err := u.fsRepo.WriteInteractionsLog(ctx); err != nil {
return InitializeBeadsDirResult{}, err
}
if err := u.fsRepo.WriteReadme(ctx); err != nil {
return InitializeBeadsDirResult{}, err
}

View file

@ -10,9 +10,14 @@ Generated from `bd help --doc audit`
## bd audit
Audit log entries are appended to .beads/interactions.jsonl.
Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
Each line is one event. This file is intended to be versioned in git and used for:
This optional JSONL sidecar is disabled by default. Enable it with:
bd config set audit.enabled true
Issue history is always recorded in the database and is visible with
bd history &lt;id&gt; --events. The JSONL sidecar is for explicit interaction capture:
- auditing ("why did the agent do that?")
- dataset generation (SFT/RL fine-tuning)

View file

@ -16,6 +16,7 @@ where the issue was modified.
Examples:
bd history bd-123 # Show all history for issue bd-123
bd history bd-123 --limit 5 # Show last 5 changes
bd history bd-123 --events # Show database audit events
```
bd history <id> [flags]
@ -24,5 +25,6 @@ bd history <id> [flags]
**Flags:**
```
--events Show database audit events instead of commit snapshots
--limit int Limit number of history entries (0 = all)
```