fix: allow @ in branch names (valid per git-check-ref-format)

[bellalMohamed]

Problem

validateBranchName in src/github/operations/branch.ts rejects branch names containing @, even though git check-ref-format permits @ and GitHub itself accepts such branches. When the action runs on a PR whose head or base branch contains an @, validation throws before any git operation and the action fails immediately:

Error: Action failed with error: Invalid branch name: "@hotfix/<ticket>-<description>".
Branch names must start with an alphanumeric character and contain only alphanumeric
characters, forward slashes, hyphens, underscores, periods, hashes (#), plus signs (+),
or commas (,).

This shows up in real workflows: ticket conventions like TICKET-123@add-feature (#998), leading-prefix conventions like @hotfix/... (we run this action org-wide for PR-comment automation on private repos, and every PR from an @-prefixed hotfix branch fails at the prepare step with the error above), and agent tooling that appends @<sessionid> (#1305). There is no workaround other than renaming the branch, which is often not under the user's control.

Fixes #998.

Root cause

The whitelist regex at src/github/operations/branch.ts:68 is:

const validPattern = /^[a-zA-Z0-9][a-zA-Z0-9/_.#+,-]*$/;

@ is not in either character class, so any ref containing one is rejected regardless of position.

The whitelist exists for injection safety, but branch names are never passed through a shell — git calls use execFileSync with an argv array — so @ carries no injection risk under that execution model. This is the same reasoning used to add # in #1167, + in #1248, and , in #1310.

Fix

Add @ to the whitelist, including the leading position: /^[a-zA-Z0-9@][a-zA-Z0-9/_.#+,@-]*$/.

• The leading-character restriction exists to prevent option injection (-x, --help); @ is not an option prefix, so allowing it first does not weaken that protection. Leading @ is what @hotfix/...-style conventions need, and git check-ref-format --branch "@hotfix/x" accepts it.
• The bare name @ is rejected with a dedicated check: per git-check-ref-format, a refname cannot be the single character @, and @ resolves to HEAD in git revision syntax, so it must never reach git as a branch argument where it could be interpreted as a revision instead.
• The @{ reflog sequence is still rejected by the existing dedicated check (untouched).
• The surrounding comment block, JSDoc, and user-facing error message are updated to match, same as the previous character additions.

Relationship to existing PRs

#999, #1022, and #1305 also propose allowing @. This PR is intended to complement them with three differences: (1) it is based on current main (#1310 landed on the same lines, so the earlier diffs now conflict); (2) it also accepts @ in the leading position, which is the failure mode for @hotfix/...-style conventions; and (3) it adds an explicit bare-@ guard with a test so HEAD shorthand cannot slip through the widened character class. Happy to close this in favor of any of those if a maintainer prefers.

Testing

• 1 new accept test (TICKET-123@add-feature, @hotfix/login-timeout, agent/task@abc123) referencing Branch name validation rejects @ character which is valid in git #998, and 1 new reject test for bare @, both following the style of the fix: allow # in branch names for PR checkout and base restore #1167/fix: allow + in branch names (generated by Claude Code EnterWorktree) #1248/fix: allow , in branch names #1310 tests
• All existing rejection cases are unaffected: @{, control characters, spaces, shell metacharacters, option injection, path traversal, .lock, and trailing/consecutive slashes are still rejected
• Verified validateBranchName standalone with node against the full accept/reject matrix from the test suite plus the new cases: 34 accept / 60 reject, 94/94 as expected (my environment cannot run bun; CI will run the real suite)

🤖 Generated with Claude Code