The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
fix: honor literal CODEX_HOME session stores (#855)
Rudy Mizrahi Celekli96e42b9597b1
diff --git a/cli/beacon/cmd/endpoint_codex.go b/cli/beacon/cmd/endpoint_codex.goindex bf1f477c..1466a5d6 100644--- a/cli/beacon/cmd/endpoint_codex.go+++ b/cli/beacon/cmd/endpoint_codex.go@@ -19,7 +19,8 @@ var endpointCodexCmd = &cobra.Command{Long: `Collect endpoint telemetry from Codex CLI's local rollout session files.Beacon's normal Codex integration uses local OpenTelemetry logs and traces for live-capture. This command reads Codex's committed JSONL session files under ~/.codex/sessions+capture. This command reads Codex's committed JSONL session files under $CODEX_HOME/sessions+when set, otherwise ~/.codex/sessionsso historical sessions and sessions that ran without Beacon OTLP can still be representedin the local endpoint log. Every emitted event is marked harness.collection_method=poll:Beacon sees what Codex already wrote, so nothing here can hold or deny a tool call.`,@@ -55,7 +56,7 @@ func init() {for _, c := range []*cobra.Command{endpointCodexSyncCmd, endpointCodexStatusCmd} {f := c.Flags()- f.StringVar(&endpointCodexOpts.codexDir, "codex-dir", "", "Codex directory (default ~/.codex)")+ f.StringVar(&endpointCodexOpts.codexDir, "codex-dir", "", "Codex directory (default $CODEX_HOME when nonempty, otherwise ~/.codex)")f.StringVar(&endpointCodexOpts.statePath, "state", "", "Collector cursor file (default ~/.beacon/endpoint/state/codex.json)")f.BoolVar(&endpointOpts.jsonOutput, "json", false, "Print the result as JSON")f.BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")diff --git a/cli/beacon/internal/codexsession/default_dir_test.go b/cli/beacon/internal/codexsession/default_dir_test.gonew file mode 100644index 00000000..bc2db977--- /dev/null+++ b/cli/beacon/internal/codexsession/default_dir_test.go@@ -0,0 +1,96 @@+package codexsession++import (+ "os"+ "path/filepath"+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++func TestDefaultCodexDirUsesLiteralProducerRoot(t *testing.T) {+ home := t.TempDir()+ testenv.SetHome(t, home)+ t.Chdir(home)+ for _, tc := range []struct{ name, value string }{+ {"absolute", filepath.Join(home, "profile")},+ {"relative", "relative-profile"},+ {"literal dollar", "$PROFILE"},+ {"literal tilde", "~profile"},+ {"literal spaces", " profile "},+ } {+ t.Run(tc.name, func(t *testing.T) {+ if err := os.MkdirAll(tc.value, 0700); err != nil {+ t.Fatal(err)+ }+ t.Setenv("CODEX_HOME", tc.value)+ got, err := DefaultCodexDir()+ if err != nil {+ t.Fatal(err)+ }+ canonical, err := filepath.EvalSymlinks(tc.value)+ if err != nil {+ t.Fatal(err)+ }+ want, err := filepath.Abs(canonical)+ if err != nil {+ t.Fatal(err)+ }+ if got != want {+ t.Fatalf("DefaultCodexDir()=%q, want literal root %q", got, want)+ }+ })+ }+ t.Run("canonical directory", func(t *testing.T) {+ target := filepath.Join(home, "canonical-profile")+ if err := os.MkdirAll(target, 0700); err != nil {+ t.Fatal(err)+ }+ alias := filepath.Join(home, "profile-alias")+ if err := os.Symlink(target, alias); err != nil {+ t.Skipf("owned directory symlink unavailable: %v", err)+ }+ t.Setenv("CODEX_HOME", alias)+ got, err := DefaultCodexDir()+ if err != nil {+ t.Fatal(err)+ }+ want, err := filepath.EvalSymlinks(target)+ if err != nil {+ t.Fatal(err)+ }+ want, err = filepath.Abs(want)+ if err != nil {+ t.Fatal(err)+ }+ if got != want {+ t.Fatalf("canonical root=%q, want target %q", got, want)+ }+ })+ t.Run("empty default", func(t *testing.T) {+ t.Setenv("CODEX_HOME", "")+ got, err := DefaultCodexDir()+ if err != nil {+ t.Fatal(err)+ }+ if got != filepath.Join(home, ".codex") {+ t.Fatalf("default=%q", got)+ }+ })+ t.Run("missing override", func(t *testing.T) {+ t.Setenv("CODEX_HOME", filepath.Join(home, "missing"))+ if _, err := DefaultCodexDir(); err == nil {+ t.Fatal("missing CODEX_HOME must fail rather than read another profile")+ }+ })+ t.Run("file override", func(t *testing.T) {+ path := filepath.Join(home, "file")+ if err := os.WriteFile(path, []byte("owned fixture"), 0600); err != nil {+ t.Fatal(err)+ }+ t.Setenv("CODEX_HOME", path)+ if _, err := DefaultCodexDir(); err == nil {+ t.Fatal("file CODEX_HOME must fail rather than read another profile")+ }+ })+}diff --git a/cli/beacon/internal/codexsession/store.go b/cli/beacon/internal/codexsession/store.goindex 4b9ac851..04b1c378 100644--- a/cli/beacon/internal/codexsession/store.go+++ b/cli/beacon/internal/codexsession/store.go@@ -46,7 +46,36 @@ type IndexEntry struct {UpdatedAt string `json:"updated_at,omitempty"`}+// HomeDir resolves Codex's home directory the way Codex does: a nonempty CODEX_HOME is a+// literal path (no trimming or shell expansion) that must be an existing directory and is+// canonicalized; otherwise it is <home>/.codex.+func HomeDir(home string) (string, error) {+ override := os.Getenv("CODEX_HOME")+ if override == "" {+ return filepath.Join(home, ".codex"), nil+ }+ info, err := sessionfs.Stat(override)+ if err != nil {+ return "", fmt.Errorf("read CODEX_HOME %q: %w", override, err)+ }+ if !info.IsDir() {+ return "", fmt.Errorf("CODEX_HOME %q is not a directory", override)+ }+ canonical, err := filepath.EvalSymlinks(override)+ if err != nil {+ return "", fmt.Errorf("resolve CODEX_HOME %q: %w", override, err)+ }+ absolute, err := filepath.Abs(canonical)+ if err != nil {+ return "", fmt.Errorf("resolve CODEX_HOME %q: %w", override, err)+ }+ return absolute, nil+}+func DefaultCodexDir() (string, error) {+ if os.Getenv("CODEX_HOME") != "" {+ return HomeDir("")+ }home, err := os.UserHomeDir()if err != nil {return "", fmt.Errorf("resolve home directory: %w", err)@@ -54,7 +83,7 @@ func DefaultCodexDir() (string, error) {if strings.TrimSpace(home) == "" {return "", errors.New("home directory is empty")}- return filepath.Join(home, ".codex"), nil+ return HomeDir(home)}func NewStore(dir string) (*Store, error) {diff --git a/cli/beacon/internal/mcpconnect/harness_test.go b/cli/beacon/internal/mcpconnect/harness_test.goindex 0c39642f..aa80f3ab 100644--- a/cli/beacon/internal/mcpconnect/harness_test.go+++ b/cli/beacon/internal/mcpconnect/harness_test.go@@ -776,7 +776,11 @@ func TestCodexInlineTableIsNotRewritten(t *testing.T) {func TestCodexHonorsCodexHome(t *testing.T) {home := isolate(t)+ // Codex requires CODEX_HOME to be an existing directory.codexHome := filepath.Join(home, "elsewhere")+ if err := os.MkdirAll(codexHome, 0o755); err != nil {+ t.Fatal(err)+ }t.Setenv("CODEX_HOME", codexHome)connect(t, fileOptions(home), mustTarget(t, "codex"))if !strings.Contains(readFile(t, filepath.Join(codexHome, "config.toml")), "[mcp_servers.beacon-managed]") {diff --git a/cli/beacon/internal/mcpconnect/targets.go b/cli/beacon/internal/mcpconnect/targets.goindex dfdc7057..4906454d 100644--- a/cli/beacon/internal/mcpconnect/targets.go+++ b/cli/beacon/internal/mcpconnect/targets.go@@ -7,6 +7,7 @@ import ("path/filepath""strings"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/codexsession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/harness""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks")@@ -310,12 +311,13 @@ func claudeConfigPath(home string) (string, error) {return filepath.Join(home, ".claude.json"), nil}-// codexConfigPath honors CODEX_HOME, as Codex does.+// codexConfigPath resolves CODEX_HOME exactly as Codex and Beacon's session reader do.func codexConfigPath(home string) (string, error) {- if dir := strings.TrimSpace(os.Getenv("CODEX_HOME")); dir != "" {- return filepath.Join(dir, "config.toml"), nil+ dir, err := codexsession.HomeDir(home)+ if err != nil {+ return "", err}- return filepath.Join(home, ".codex", "config.toml"), nil+ return filepath.Join(dir, "config.toml"), nil}// vscodeMCPPath is the user-profile mcp.json, next to the settings.json VS Code discovery uses.diff --git a/docs/cli/handoff.mdx b/docs/cli/handoff.mdxindex 92569423..dc7dd08d 100644--- a/docs/cli/handoff.mdx+++ b/docs/cli/handoff.mdx@@ -20,7 +20,7 @@ Sessions come from each runtime's own local session store, not from Beacon's run| Runtime | Session store | `--harness` ||---------|---------------|-------------|| Claude Code | `~/.claude/projects` | `claude` |-| Codex CLI | `~/.codex/sessions` | `codex` |+| Codex CLI | `$CODEX_HOME/sessions` when set; otherwise `~/.codex/sessions` | `codex` || OpenCode | `~/.config/opencode` (SQLite and the legacy file store) | `opencode` || Cline | `~/.cline/data` | `cline` || Pi | `~/.pi/agent/sessions` (or under `PI_CODING_AGENT_DIR`) | `pi` |diff --git a/docs/runtimes/codex-cli.mdx b/docs/runtimes/codex-cli.mdxindex 7a348649..22560bd6 100644--- a/docs/runtimes/codex-cli.mdx+++ b/docs/runtimes/codex-cli.mdx@@ -32,12 +32,14 @@ Beacon can also recover Codex CLI activity from Codex's local rollout files withbeacon endpoint codex sync```-This reads committed files under `~/.codex/sessions` and appends mapped events to the local runtime log with `harness.collection_method=poll`. It is useful for historical sessions or sessions that ran before OTLP was configured. The sync path is not part of hook execution and cannot approve, deny, or delay tool calls.+This reads committed files under `$CODEX_HOME/sessions` when `CODEX_HOME` is nonempty, otherwise `~/.codex/sessions` and appends mapped events to the local runtime log with `harness.collection_method=poll`. It is useful for historical sessions or sessions that ran before OTLP was configured. The sync path is not part of hook execution and cannot approve, deny, or delay tool calls.Use `beacon endpoint codex sync --print` to preview mapped events without writing the runtime log or advancing the cursor. Use `beacon endpoint codex status` to see which session files are present and how far Beacon has read each one.Codex rollout files can contain prompts, assistant responses, tool inputs, command output, and code. Sync is therefore explicit: Beacon does not read `~/.codex/sessions` during normal Codex hook execution, and it never reads `~/.codex/auth.json`.+Session status, sync, handoff, and `beacon mcp connect` honor Codex's literal `CODEX_HOME` directory: it must exist, and relative paths resolve from the current working directory. Unlike shell syntax, `~` and environment-variable references in the value are not expanded. Pass `--codex-dir <path>` to select a session store explicitly.+### Token usage and cost`beacon endpoint install` configures Codex's log and trace exporters in `~/.codex/config.toml`. Beacon normalizes the completed turn span into the same canonical `gen_ai.usage` fields used for Claude Code: uncached `input_tokens`, `output_tokens`, `cache_read.input_tokens`, `cache_creation.input_tokens`, and `reasoning.output_tokens`. Codex's input count includes both cache reads and cache writes, so Beacon subtracts both before recording uncached input.