diff --git a/changelog.d/fixed-claude-bridge-legacy-dirlink.md b/changelog.d/fixed-claude-bridge-legacy-dirlink.md new file mode 100644 index 0000000000..705132817d --- /dev/null +++ b/changelog.d/fixed-claude-bridge-legacy-dirlink.md @@ -0,0 +1 @@ +- Claude credential bridge: the repair no longer acts on an agent whose whole `~/.claude` is still the legacy directory symlink to the shared `/data/home/.claude` (a paused or stopped agent that was never relaunched). Through that link the agent's credential path IS the shared login, so the watchdog renamed the shared file to `.stale-` every cycle and, when the shared file held no token, linked `.credentials.json` to itself, logging every Claude agent out. The repair and the dashboard's "credential bridge broken" signal now resolve the link's directory first and skip that layout with one warning per agent; the agent's next launch already retires the directory link (#17253). diff --git a/src/crux/agent/claude_credential_bridge.go b/src/crux/agent/claude_credential_bridge.go index 7a2c476554..4ca94d05f0 100644 --- a/src/crux/agent/claude_credential_bridge.go +++ b/src/crux/agent/claude_credential_bridge.go @@ -53,6 +53,12 @@ import ( // promoted, the shared file it replaces is preserved the same way beside the // shared credential. Both names fall outside sharedCredentialBases, so the // permissions watcher never opens them up to the group. +// +// The repair never acts on a link path that resolves to the shared credential +// itself (an agent whose whole ~/.claude is still the legacy directory symlink +// to /data/home/.claude): that "private file" is the fleet's login. Such an +// agent is skipped with one warning; its next launch retires the directory +// link (setupPerAgentCLIHome) before the repair runs. // Repair triggers, recorded in the audit detail and the log. const ( @@ -118,15 +124,73 @@ func sharedClaudeBridgeTarget() string { } // claudeCredentialBridgeBroken reports whether a regular file has replaced the -// agent's credential symlink. Read-only (one Lstat), so it is cheap enough for -// the status snapshot. +// agent's credential symlink. Read-only (one Lstat, plus two directory +// resolutions only when that Lstat finds a regular file), so it is cheap +// enough for the status snapshot. It follows the same rule as the repair: the +// legacy layout, where the link path resolves to the shared credential itself, +// is not a broken bridge and is never reported as one. func claudeCredentialBridgeBroken(agentName string, uid int, backend string) bool { - link, _, ok := claudeCredentialBridgePaths(agentName, uid, backend) + link, target, ok := claudeCredentialBridgePaths(agentName, uid, backend) if !ok { return false } info, err := os.Lstat(link) - return err == nil && info.Mode().IsRegular() + if err != nil || !info.Mode().IsRegular() { + return false + } + same, err := claudeBridgeLinkIsTarget(link, target) + return err == nil && !same +} + +// errClaudeBridgeLinkIsTarget: the agent's credential path IS the shared +// credential, so there is no private copy to move aside and no link to +// restore. On a live v6 hive this was an agent whose whole ~/.claude was still +// the legacy directory symlink to the shared /data/home/.claude (the layout +// setupPerAgentCLIHome retires at launch, never reached for an agent that is +// paused or stopped). The repair then renamed the SHARED login aside and, +// for a token-less file, linked .credentials.json to itself, logging every +// agent out. +var errClaudeBridgeLinkIsTarget = errors.New("credential link path resolves to the shared credential it would link to") + +// claudeBridgeLegacyWarned holds the credential links the legacy-layout skip +// has already been logged for, so the watchdog, which walks every managed +// agent each cycle, logs it once per agent instead of every cycle. Keyed by +// the link path, which names the agent. +var claudeBridgeLegacyWarned sync.Map + +// claudeBridgeLinkIsTarget reports whether link names the shared credential +// itself: the same path, or a file of the same name in a directory that +// resolves to the target's directory (a legacy whole-directory ~/.claude +// symlink). An error means a directory could not be resolved (absent, or not +// reachable by this process); callers treat that as nothing to repair. +func claudeBridgeLinkIsTarget(link, target string) (bool, error) { + if filepath.Clean(link) == filepath.Clean(target) { + return true, nil + } + if filepath.Base(link) != filepath.Base(target) { + return false, nil + } + linkDir, err := filepath.EvalSymlinks(filepath.Dir(link)) + if err != nil { + return false, err + } + targetDir, err := filepath.EvalSymlinks(filepath.Dir(target)) + if err != nil { + return false, err + } + if linkDir == targetDir { + return true, nil + } + // Different resolved paths can still be one directory (a bind mount). + li, err := os.Stat(linkDir) + if err != nil { + return false, err + } + ti, err := os.Stat(targetDir) + if err != nil { + return false, err + } + return os.SameFile(li, ti), nil } // preferAgentClaudeCredential decides which credential the shared file keeps. @@ -143,8 +207,10 @@ func preferAgentClaudeCredential(agent, shared *claude.OAuthTokens, now time.Tim // repairClaudeCredentialBridge re-bridges one agent's credential when a regular // file has replaced the symlink. It returns nil, nil when there is nothing to -// repair (a symlink, an absent link, or a directory, which is not this -// failure). +// repair (a symlink, an absent link, a directory, which is not this failure, +// or a link or target directory that cannot be resolved). It returns an error +// wrapping errClaudeBridgeLinkIsTarget, and touches nothing, when the link +// path resolves to the shared credential itself. func (m *Manager) repairClaudeCredentialBridge(agentName, link, target string) (*claudeBridgeRepair, error) { claudeBridgeMu.Lock() defer claudeBridgeMu.Unlock() @@ -153,6 +219,22 @@ func (m *Manager) repairClaudeCredentialBridge(agentName, link, target string) ( if err != nil || !info.Mode().IsRegular() { return nil, nil } + + // Never operate on the shared credential itself. Checked BEFORE anything + // is moved: when the link path resolves to the target, the "private file" + // below IS the shared login, moving it aside strands the fleet, and the + // symlink restored afterwards would point at its own path. + same, err := claudeBridgeLinkIsTarget(link, target) + if err != nil { + // Nothing safe to judge without both directories; never move a file + // aside on a guess. + m.logger.Debug("claude credential bridge: cannot resolve the link or shared directory; not repairing", + "agent", agentName, "link", link, "target", target, "error", err) + return nil, nil + } + if same { + return nil, fmt.Errorf("%w: %s", errClaudeBridgeLinkIsTarget, link) + } now := claudeBridgeNow() // Move the private file aside FIRST. After the rename the CLI can no @@ -292,6 +374,18 @@ func preserveClaudeCredential(path string, now time.Time) (string, error) { // sign-in hook share, so all three log and audit identically. func (m *Manager) rebridgeClaudeCredential(agentName, link, target, trigger string) *claudeBridgeRepair { rep, err := m.repairClaudeCredentialBridge(agentName, link, target) + if errors.Is(err, errClaudeBridgeLinkIsTarget) { + // The legacy layout: skipped, and said once per agent rather than on + // every watchdog cycle. Not audited (nothing changed). + if _, seen := claudeBridgeLegacyWarned.LoadOrStore(link, true); !seen { + m.logger.Warn("claude credential bridge: this agent's .claude directory resolves to the shared login directory (a legacy whole-directory symlink), so its credential path IS the shared login; not re-bridging. The agent's next launch replaces the directory link with a per-agent directory", + "agent", agentName, "trigger", trigger, "dir", filepath.Dir(link), "shared", target) + } + return nil + } + // Any other outcome clears the mark, so a legacy layout that shows up + // again later is logged again. + claudeBridgeLegacyWarned.Delete(link) if err != nil { // Logged, not audited: a repair that keeps failing (an unprivileged // hive that cannot enter the agent's 0700 home) would otherwise add an diff --git a/src/crux/agent/claude_credential_bridge_internal_test.go b/src/crux/agent/claude_credential_bridge_internal_test.go index 746940ce63..9d4d9ce5e3 100644 --- a/src/crux/agent/claude_credential_bridge_internal_test.go +++ b/src/crux/agent/claude_credential_bridge_internal_test.go @@ -1,8 +1,12 @@ package agent import ( + "bytes" + "errors" + "log/slog" "os" "path/filepath" + "strings" "syscall" "testing" "time" @@ -138,3 +142,196 @@ func TestPreferAgentClaudeCredential(t *testing.T) { } } } + +// legacyDirLinkFixture lays out the pre-#17031 layout that the launch path +// retires but the credential watchdog still walks for a paused or stopped +// agent: the agent's whole ~/.claude is a directory symlink to the shared +// .claude, so the path the bridge calls the agent's credential IS the shared +// login. The shared credential holds sharedJSON. Returns the link path exactly +// as production computes it, the target, and the shared file's FileInfo +// captured before any repair runs. +func legacyDirLinkFixture(t *testing.T, shared, agentName string, uid int, sharedJSON string) (string, string, os.FileInfo) { + t.Helper() + sharedClaude := filepath.Join(shared, ".claude") + if err := os.MkdirAll(sharedClaude, 0o755); err != nil { + t.Fatal(err) + } + target := filepath.Join(sharedClaude, ".credentials.json") + if err := os.WriteFile(target, []byte(sharedJSON), 0o660); err != nil { + t.Fatal(err) + } + home := filepath.Join(shared, "agents", agentName) + if err := os.MkdirAll(home, 0o700); err != nil { + t.Fatal(err) + } + if err := os.Symlink(sharedClaude, filepath.Join(home, ".claude")); err != nil { + t.Fatal(err) + } + link, gotTarget, ok := claudeCredentialBridgePaths(agentName, uid, "claude") + if !ok || gotTarget != target { + t.Fatalf("claudeCredentialBridgePaths = (%q, %q, %v), want target %q", link, gotTarget, ok, target) + } + before, err := os.Lstat(target) + if err != nil { + t.Fatal(err) + } + return link, target, before +} + +// assertSharedCredentialUntouched: the shared login is still the very same +// regular file (same inode, not a symlink to anything, let alone itself), +// with the same bytes, and nothing was moved aside beside it. +func assertSharedCredentialUntouched(t *testing.T, target string, before os.FileInfo, wantJSON string) { + t.Helper() + info, err := os.Lstat(target) + if err != nil { + t.Fatalf("shared credential gone: %v", err) + } + if !info.Mode().IsRegular() { + dest, _ := os.Readlink(target) + t.Fatalf("shared credential is no longer a regular file (mode %v, link -> %q)", info.Mode(), dest) + } + if !os.SameFile(before, info) { + t.Errorf("shared credential was replaced (new inode); it must not be renamed or rewritten") + } + if got := readFileString(t, target); got != wantJSON { + t.Errorf("shared credential content changed:\n got %s\nwant %s", got, wantJSON) + } + if got := staleFiles(t, filepath.Dir(target)); len(got) != 0 { + t.Errorf("shared credential was moved aside: %v", got) + } +} + +// TestRepairClaudeCredentialBridge_LegacyDirLinkUsableSharedUntouched: on the +// v6 tip the repair saw the shared file through the directory link as a +// "private copy", renamed it to .stale-, promoted the same bytes back +// (new inode) and then failed the symlink with EEXIST, every watchdog cycle. +// It must leave the shared file alone and say why. +func TestRepairClaudeCredentialBridge_LegacyDirLinkUsableSharedUntouched(t *testing.T) { + shared := withSharedAgentHome(t) + m, sink := testManagerWithSink(t) + sharedJSON := fakeClaudeCredential("fake-shared-access", time.Now().Add(8*time.Hour), "fake-shared-refresh") + link, target, before := legacyDirLinkFixture(t, shared, "reviewer", 2005, sharedJSON) + + rep, err := m.repairClaudeCredentialBridge("reviewer", link, target) + if rep != nil || !errors.Is(err, errClaudeBridgeLinkIsTarget) { + t.Fatalf("repair = (%+v, %v), want (nil, errClaudeBridgeLinkIsTarget)", rep, err) + } + if got := m.rebridgeClaudeCredential("reviewer", link, target, claudeBridgeTriggerWatchdog); got != nil { + t.Fatalf("rebridge = %+v, want nil (skipped)", got) + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) + if ev := sink.find("claude_credential_rebridged"); ev != nil { + t.Errorf("a skipped legacy layout must not be audited as a re-bridge: %+v", ev) + } +} + +// TestRepairClaudeCredentialBridge_LegacyDirLinkTokenlessSharedNotSelfLinked +// is the live incident: a logged-out (token-less) shared file is not +// promoted, so on the v6 tip the repair renamed it away and then created +// .credentials.json -> .credentials.json, a symlink to itself, logging out +// every agent. No symlink may be created and the file must stay in place. +func TestRepairClaudeCredentialBridge_LegacyDirLinkTokenlessSharedNotSelfLinked(t *testing.T) { + shared := withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + const sharedJSON = `{}` + link, target, before := legacyDirLinkFixture(t, shared, "scanner", 2003, sharedJSON) + + if _, err := m.repairClaudeCredentialBridge("scanner", link, target); !errors.Is(err, errClaudeBridgeLinkIsTarget) { + t.Fatalf("repair error = %v, want errClaudeBridgeLinkIsTarget", err) + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) +} + +// TestRepairClaudeCredentialBridges_LegacyDirLinkSurvivesWatchdogCyclesWarnsOnce: +// the watchdog walks every managed agent each cycle, paused ones included. +// Several cycles over the legacy layout leave the shared login untouched, +// re-bridge nothing, and log the skip once rather than every cycle. +func TestRepairClaudeCredentialBridges_LegacyDirLinkSurvivesWatchdogCyclesWarnsOnce(t *testing.T) { + shared := withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + var logs bytes.Buffer + m.logger = slog.New(slog.NewTextHandler(&logs, nil)) + m.mu.Lock() + m.agents["planner"] = &AgentProcess{Name: "planner", UID: 2004, Config: config.AgentConfig{Backend: "claude"}} + m.mu.Unlock() + sharedJSON := fakeClaudeCredential("fake-shared-access", time.Now().Add(8*time.Hour), "fake-shared-refresh") + _, target, before := legacyDirLinkFixture(t, shared, "planner", 2004, sharedJSON) + + for cycle := 0; cycle < 4; cycle++ { + if got := m.RepairClaudeCredentialBridges(claudeBridgeTriggerWatchdog); len(got) != 0 { + t.Fatalf("cycle %d re-bridged %v, want none", cycle, got) + } + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) + if n := strings.Count(logs.String(), "legacy whole-directory symlink"); n != 1 { + t.Errorf("legacy-layout warning logged %d times over 4 cycles, want 1:\n%s", n, logs.String()) + } + if strings.Contains(logs.String(), "repair failed") { + t.Errorf("the legacy layout must be skipped, not reported as a failed repair:\n%s", logs.String()) + } +} + +// TestRepairClaudeCredentialBridge_RefusesLinkEqualToTarget: the last line of +// defence. A link path equal to its own target is refused before anything is +// moved: nothing renamed, nothing created. +func TestRepairClaudeCredentialBridge_RefusesLinkEqualToTarget(t *testing.T) { + withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + target := sharedClaudeBridgeTarget() + if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil { + t.Fatal(err) + } + const sharedJSON = `{}` + if err := os.WriteFile(target, []byte(sharedJSON), 0o660); err != nil { + t.Fatal(err) + } + before, err := os.Lstat(target) + if err != nil { + t.Fatal(err) + } + + rep, err := m.repairClaudeCredentialBridge("coder", target, target) + if rep != nil || !errors.Is(err, errClaudeBridgeLinkIsTarget) { + t.Fatalf("repair = (%+v, %v), want (nil, errClaudeBridgeLinkIsTarget)", rep, err) + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) +} + +// TestClaudeCredentialBridgeBroken_LegacyDirLinkIsNotBroken: the dashboard's +// "bridge broken" signal follows the repair's rule. The legacy layout is not +// a broken bridge (the agent reads the shared login directly), while a real +// per-agent .claude holding a private regular file still is. +func TestClaudeCredentialBridgeBroken_LegacyDirLinkIsNotBroken(t *testing.T) { + shared := withSharedAgentHome(t) + legacyDirLinkFixture(t, shared, "architect", 2001, `{}`) + if claudeCredentialBridgeBroken("architect", 2001, "claude") { + t.Error("the legacy whole-directory layout must not report a broken credential bridge") + } + + brokenBridgeFixture(t, shared, "coder", "", + fakeClaudeCredential("fake-private-access", time.Now().Add(time.Hour), "fake-private-refresh")) + if !claudeCredentialBridgeBroken("coder", 2002, "claude") { + t.Error("a private regular file in a real per-agent .claude must still report a broken bridge") + } +} + +// TestSetupInteractiveHome_LegacyDirLinkLaunchRetiresBeforeRebridge pins the +// launch ordering: setupPerAgentCLIHome retires the directory link and makes +// a real per-agent .claude BEFORE it runs the credential repair, so a launch +// never sees the shared file through the old link. The shared login stays the +// same file and the agent ends up bridged to it. +func TestSetupInteractiveHome_LegacyDirLinkLaunchRetiresBeforeRebridge(t *testing.T) { + shared := withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + sharedJSON := fakeClaudeCredential("fake-shared-access", time.Now().Add(8*time.Hour), "fake-shared-refresh") + link, target, before := legacyDirLinkFixture(t, shared, "coder", 2002, sharedJSON) + + m.setupInteractiveHome(&AgentProcess{Name: "coder", UID: 2002, Config: config.AgentConfig{Backend: "claude"}}, "claude") + + assertSharedCredentialUntouched(t, target, before, sharedJSON) + if info, err := os.Lstat(filepath.Dir(link)); err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() { + t.Fatalf("legacy .claude directory link not retired: info=%v err=%v", info, err) + } + assertBridgeRestored(t, link, target) +} diff --git a/src/crux/claude/oauth_test.go b/src/crux/claude/oauth_test.go index bdbcfbd99d..9a93e6e86d 100644 --- a/src/crux/claude/oauth_test.go +++ b/src/crux/claude/oauth_test.go @@ -352,6 +352,48 @@ func TestWriteCredentialsIsAtomic(t *testing.T) { } } +// A sign-in is how an operator recovers a fleet whose shared credential path +// was turned into a symlink to itself (an older credential-bridge repair did +// this on a live v6 hive) or to a file that no longer exists. WriteCredentials +// renames its temp file over the path, which replaces the symlink itself, so +// the path ends up a regular file holding the new tokens. +func TestWriteCredentialsReplacesSelfAndDanglingSymlinks(t *testing.T) { + cases := []struct { + name string + linkTo func(path string) string + }{ + {"self-referencing", func(path string) string { return path }}, + {"dangling", func(path string) string { return filepath.Join(filepath.Dir(path), "gone", ".credentials.json") }}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + path := filepath.Join(t.TempDir(), ".credentials.json") + if err := os.Symlink(c.linkTo(path), path); err != nil { + t.Fatal(err) + } + tokens := &OAuthTokens{ + AccessToken: "fake-recovered-access", + RefreshToken: "fake-recovered-refresh", + ExpiresAt: time.Now().Add(time.Hour).UnixMilli(), + } + if err := WriteCredentials(tokens, path); err != nil { + t.Fatalf("WriteCredentials over a %s symlink: %v", c.name, err) + } + info, err := os.Lstat(path) + if err != nil { + t.Fatal(err) + } + if !info.Mode().IsRegular() { + t.Fatalf("credentials path is still not a regular file (mode %v)", info.Mode()) + } + got := LoadTokens(path) + if got == nil || got.AccessToken != "fake-recovered-access" || got.RefreshToken != "fake-recovered-refresh" { + t.Fatalf("credentials file does not hold the written tokens: %+v", got) + } + }) + } +} + // An expired token must read as absent: handing an expired token to an agent // produces confusing 401s instead of a clean re-auth prompt. func TestReadAccessTokenRejectsExpiredToken(t *testing.T) { diff --git a/src/docs/agent-configuration.md b/src/docs/agent-configuration.md index d9acd1392a..af61e9df89 100644 --- a/src/docs/agent-configuration.md +++ b/src/docs/agent-configuration.md @@ -703,6 +703,8 @@ The repair never deletes a token: Each repair writes a `claude_credential_rebridged` Audit Log entry naming the agent, the trigger (`launch`, `watchdog` or `sign-in`), which credential was kept (`shared` or `agent`) and where the moved-aside file went. It never records token material. Until the repair runs, the agent card shows **credential bridge broken (private stale file)** instead of a generic "needs login". Moved-aside files are not cleaned up automatically; remove them by hand once you no longer need them. +The repair skips an agent whose whole `~/.claude` is still the old directory symlink to `/data/home/.claude`. That happens to an agent that has been paused or stopped since before the per-agent split, because only a launch replaces the directory link. Through that link the agent's `.credentials.json` is the shared login itself, so there is nothing private to move aside. The hive log says so once per agent (`claude credential bridge: this agent's .claude directory resolves to the shared login directory`), the card does not show a broken bridge, and the agent's next launch replaces the directory link with its own `~/.claude`. + ### CLI auto-memory (`agents.cli_memory`) Subscription CLIs keep their own long-lived "memory" next to the transcripts: Claude Code's auto-memory (`~/.claude/projects/-data-agents-/memory/MEMORY.md`), Codex memories (`$CODEX_HOME/memories/`), Copilot CLI's `memory` setting, and Gemini's `~/.gemini/GEMINI.md`. Hive agents already get their durable context from beads, the knowledge store, and the kick prompt, so a hidden per-CLI notebook mostly accumulates stale one-off inferences ([#17032](https://github.com/hivecommons/hive/issues/17032)). The `agents.cli_memory` block controls it fleet-wide, and each agent may override it with its own `cli_memory:` block: