agent update silently switches to default branch when adopted from a non-default ref

[redhat-chai-bot]

Reporter: mrizzi

Problem

When adopting a URL agent from a non-default branch (e.g. release-1.0), agent add resolves the branch to a commit SHA and stores only the SHA-pinned URL in AgentEntry.Source. The original branch name is discarded.

When agent update <name> is later called without an explicit SHA, runAgentUpdate falls back to forgeClient.GetRepo().DefaultBranch (agent.go ~403-408), silently switching the agent to track the repo's default branch instead of the originally adopted one.

The command help documents this behavior ("If no SHA is provided, the default branch HEAD is used"), but for adopters tracking a stable release branch, this is surprising and incorrect — there is no warning that the tracking branch has changed.

Reproduction

1. fullsend agent add myagent <agent-yaml-URL-on-release-1.0-branch>
2. Agent is pinned to the SHA at the tip of release-1.0 ✓
3. fullsend agent update myagent
4. Agent is now pinned to the SHA at the tip of main (or whatever the repo default branch is) ✗

Root cause

• AgentEntry (config.go) has no Ref field — only Name, Source, Enabled, Runtime, Model, Effort
• pinAgentURL (agent.go ~527-560) resolves the branch name to a SHA and overwrites info.Ref with the SHA before building the stored URL. The original branch name is lost.
• runAgentUpdate (agent.go ~403-408) has no stored ref to use, so it calls GetBranchRef(ctx, owner, repo, repo.DefaultBranch)

Proposed fix

Persist the adopted ref so agent update re-resolves that branch and re-pins to a fresh SHA+hash (integrity preserved):

1. Add a Ref field to AgentEntry (persisted in YAML)
2. agent add / pinAgentURL: store Ref: release-1.0 on the entry before overwriting info.Ref with the resolved SHA
3. runAgentUpdate: if entry.Ref is set, call GetBranchRef(ctx, owner, repo, entry.Ref) instead of falling back to DefaultBranch
4. Consider a --branch / --ref flag on agent update for one-off overrides

Related issues

• Allow sha256=* to skip integrity check for moving-ref agent sources #4040 (closed) — integrity hash opt-out for moving refs. Does not persist the adopted branch.
• Detect stale per-repo agent source overrides pinned to merged upstream branches #5012 (open) — detecting stale pins on merged branches. Different problem (stale vs. wrong branch).

[rh-hemartin]

/fs-triage

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 12:01 PM UTC · Completed 12:06 PM UTC

Commit: 133232a · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.71

[fullsend-ai-triage]

Severity: High

This is a data-correctness bug — updates silently change which branch an agent tracks with no warning. The existing custom/tsd-blocker label confirms adoption impact.

Related issues

• Detect stale per-repo agent source overrides pinned to merged upstream branches #5012 (open) — detects stale pins on merged branches; different problem (stale vs. wrong branch), but the Ref field proposed here would also benefit that issue's detection logic.

Proposed test case

// TestAgentUpdatePreservesAdoptedRef verifies that updating an agent
// adopted from a non-default branch re-resolves against the original
// branch, not the repo's default branch.
func TestAgentUpdatePreservesAdoptedRef(t *testing.T) {
    // Setup: AgentEntry with Ref: "release-1.0"
    // Act: runAgentUpdate without explicit SHA
    // Assert: resolved SHA is from release-1.0, not main
    // Assert: entry.Ref remains "release-1.0"
}

// TestAgentAddStoresRef verifies pinAgentURL persists the branch name.
func TestAgentAddStoresRef(t *testing.T) {
    // Setup: source URL with branch ref release-1.0
    // Act: pinAgentURL
    // Assert: entry.Ref == "release-1.0", Source is SHA-pinned
}

// TestAgentUpdateFallsBackWhenNoRef verifies backward compatibility.
func TestAgentUpdateFallsBackToDefaultBranchWhenNoRef(t *testing.T) {
    // Setup: AgentEntry with empty Ref
    // Act: runAgentUpdate
    // Assert: resolves against default branch
}

Implementation notes

The fix touches internal/config/config.go (add Ref field to AgentEntry) and internal/cli/agent.go (persist ref in pinAgentURL, use it in runAgentUpdate). Backward compatibility is preserved since an empty Ref falls back to existing DefaultBranch behavior.

---

Labels: Confirmed defect in agent CLI config handling (AgentEntry/harness), high priority given TSD adoption blocker status.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 12:07 PM UTC · Completed 12:22 PM UTC

Commit: 133232a · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $6.66