Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-claude-bridge-legacy-dirlink.md
Original file line number Diff line number Diff line change
@@ -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-<UTC>` 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).
106 changes: 100 additions & 6 deletions src/crux/agent/claude_credential_bridge.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down Expand Up @@ -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.
Expand All @@ -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()
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
197 changes: 197 additions & 0 deletions src/crux/agent/claude_credential_bridge_internal_test.go
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
package agent

import (
"bytes"
"errors"
"log/slog"
"os"
"path/filepath"
"strings"
"syscall"
"testing"
"time"
Expand Down Expand Up @@ -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-<UTC>, 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)
}
Loading
Loading