fix(push): honor explicit branches and protect dirty team clones

[dvd233]

Summary

Fixes #663.

• Add teamai push --branch <name> for new resource and team-config pushes.
• Keep the recorded branch when updating an existing open PR; when one invocation updates an existing PR and creates a new group, route the pending teamai.yaml change to the explicit new branch.
• Inspect the team-repo clone before reset --hard / clean -fd; abort with sorted unsafe paths when user changes are present while preserving only restorable TeamAI-owned changes.
• Treat deleted, mode-only, and content-plus-mode teamai.yaml changes as unsafe; content-only changes are restorable only after their content is captured.
• Keep the generic-host PR failure path non-zero with manual-PR guidance.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature causing existing behavior to change)
• Documentation only
• Refactor / internal cleanup

Test Plan

• npm run typecheck
• npm run build
• Added/updated unit tests for the dirty-path guard and explicit branch behavior
• Real CLI E2E verification after build

Targeted unit verification:

• npx vitest run src/__tests__/push-role.test.ts src/__tests__/push-pending-pr.test.ts --reporter=dot — 108 passed

Real CLI E2E verification:

• npx vitest run --config vitest.e2e.config.ts src/__tests__/push-role-skill-e2e.test.ts --reporter=verbose — 20 passed
• Covers Claude, Codex, CodeBuddy, and OpenCode across generic Git, GitLab, and GitHub provider flows.
• Covers explicit --branch resource pushes, config-only pushes, existing open-PR branch reuse, mixed existing-PR plus explicit-new-branch routing, and dirty-clone protection for mode-only and content-plus-mode teamai.yaml changes.

The earlier full npm test run on the Windows host recorded 4,401 passed, 106 failed, 8 skipped. The failures are concentrated in platform-sensitive tests covering symlink privileges, POSIX-only path expectations, Unix file modes, and npm PATH resolution; the focused push unit tests and the real CLI E2E suite above pass after this follow-up patch. The full suite was not re-run for this follow-up because the failures are environment-limited.

Related Issues

Fixes #663

Notes for Reviewers

The explicit branch applies to newly created push groups; an existing open PR's recorded branch remains authoritative. If both kinds of group are present, the pending config change follows the new explicit branch; if there is no new group, it remains with the existing PR. TeamAI-owned config changes remain supported when their content is captured and its mode is unchanged, while deleted, mode-only, content-plus-mode, or unrelated dirty-clone paths must be committed or stashed before pushing. The branch was merged with the current upstream/main in the previous closeout commit to resolve the PR conflicts.

[github-actions]

Findings

• [P1 blocking] src/push.ts:500 — The unconditional teamai.yaml exemption can still destroy user work. If the file is deleted, or only its mode changes, pendingTeamConfig remains null; the path is nevertheless considered safe, and resetToCleanMaster() silently restores/discards the change. Exempt teamai.yaml only when its content was successfully captured as pendingTeamConfig; otherwise report it as unsafe.
• [P1 blocking] PR description — The test record does not satisfy the required real-CLI coverage. It only records help output and one dirty-clone fixture; it does not exercise an actual --branch resource/config push, existing-PR behavior, or the required Claude/Codex/CodeBuddy/OpenCode and git/gitlab/github coverage. Add the completed end-to-end verification record before merge.

[CarlosWonMore]

A real incident for the teamai.yaml exemption (P1 at src/push.ts:500)

Windows 11, teamai 0.24.0 — but this is about the guard's shape rather than the version, and the shape is what this PR introduces:

const TEAMAI_OWNED_DIRTY_PATHS = new Set(['teamai.yaml', '.teamai/.sync-lock']);
function isTeamaiOwnedDirtyPath(filePath: string): boolean {
  return TEAMAI_OWNED_DIRTY_PATHS.has(filePath.replaceAll('\\', '/'));
}
…
const unsafeDirtyPaths = dirtyPaths.filter((f) => !isTeamaiOwnedDirtyPath(f));
if (unsafeDirtyPaths.length > 0) { … return; }
await resetToCleanMaster(git, repoPath);
await pullRepo(repoPath);
if (pendingTeamConfig !== null) { … }

The exemption is decided by path name, while the thing that actually makes teamai.yaml safe is that its content was captured into pendingTeamConfig a few lines earlier. Whenever those two disagree, the path is waved through even though nothing will restore it afterwards. Two cheap ways for a real user to hit that:

• The file is deleted — a user cleaning up a stale config, or an interrupted teamai source remove. There is no working-tree content to capture, so pendingTeamConfig stays null, yet teamai.yaml is still in the exempt set; the deletion passes the dirty check and reset --hard brings the file back.
• Only the mode changes — content is identical, so again there is nothing to capture, the path is exempt, and the permission change is discarded.

Suggestion: derive "safe" from what was captured (pendingTeamConfig !== null for that path) rather than from the name, and classify anything modified-but-uncapturable as unsafe, listed alongside the other paths.

Why we care beyond the theory. On 2026-09-21 our own team repo held two local commits that had not been pushed yet — a git rm --cached of a tracked file plus a .gitignore edit, i.e. exactly the kind of deliberate, user-authored change #663 is about. pullRepo() opens with git pull --ff-only; with the local branch ahead that fails, and because isDedicatedRepoRoot() is true for that path the error path falls through to git reset --hard origin/master — one warning line, commits gone. We happened to be watching; an ordinary run is indistinguishable from success. The PR's dirty-tree inspection is the right fix for it, which is precisely why we would like the exemption to be conservative about anything it did not positively capture, rather than about a fixed list of recognised names.

If a Windows real-CLI record of the dirty-clone path helps with the other open P1 (the test record), say the word and we will produce one — including the reconvergence case where teamai.yaml is deleted while an unrelated file is also modified.

[jeff-r2026]

Please resolve the conflicts and P1 findings.

[jeff-r2026]

Hi @dvd233 — still on this? Conflicts + the two P1s are the only blockers left. Happy to take it over if you're busy.

[dvd233]

Hi @jeff-r2026 — I picked this back up and pushed the closeout as 1ef8ee0.

Resolved:

• Merged the current upstream/main and resolved the PR conflicts.
• Fixed the teamai.yaml exemption: it is only treated as safe when its content was captured for restoration; deleted and mode-only changes now block before reset.
• Added real CLI E2E coverage for --branch, config-only pushes, existing open-PR branch reuse, and dirty-clone protection.
• Covered Claude, Codex, CodeBuddy, and OpenCode across generic Git, GitLab, and GitHub provider flows.

Verification:

• Targeted unit tests: 108 passed.
• Real CLI E2E suite: 18 passed.
• Typecheck and build: passed.
• The PR description now contains the full test record, including the Windows full-suite platform limitations.

[github-actions]

Findings

• [P1 blocking] src/push.ts:327 — A teamai.yaml change that modifies both content and file mode is exempted because pendingTeamConfig is non-null, but restoration only writes the content. reset --hard silently discards the mode change. Only exempt the path after verifying that content is its sole change, or preserve all changed metadata.
• [P1 blocking] src/push.ts:1502 — With an edited teamai.yaml, an existing-PR group, and a new group using --branch, configRider attaches the config to the first group—which is always the existing PR—so the explicit branch does not receive the config and an unrelated existing review is modified. Route config to the new group when --branch is supplied, or reject the ambiguous combination.
• [P1 blocking] PR description — The required real-CLI verification record is still missing. The recorded focused test command excludes the added branch/config e2e suite, and the only manual fixture covers clean/dirty clone handling. There is no successful recorded verification of resource/config --branch, existing-PR behavior, or the required Claude/Codex/CodeBuddy/OpenCode × git/gitlab/github coverage.
• [P2 non-blocking] src/push.ts:1478 — The new multiple-new-group guard is unreachable: planPushGroups() combines every unclaimed item into a single non-reuse group, so newGroupCount cannot exceed one. Remove this speculative branch or implement and test the grouping behavior it claims to protect.

Resolved

• The earlier deletion/mode-only teamai.yaml finding is fixed: those cases now remain unsafe when no content was captured.

[dvd233]

Hi @jeff-r2026 — thanks for the follow-up. I pushed commit 9e16043 and updated the PR description.

The remaining findings are addressed:

• teamai.yaml content + mode (P1): the dirty-clone guard now checks both worktree and index diff summaries. A config edit is restorable only when its content was captured and no mode change is present; deleted, mode-only, and content-plus-mode changes stop before reset.
• Existing PR + explicit --branch (P1): when a run updates an existing PR and creates a new group, the pending config is attached to the explicit new branch rather than the existing review. The existing PR's recorded branch remains authoritative.
• Verification record (P1): the PR description now records the complete real-CLI suite: 20 passed, including Claude/Codex/CodeBuddy/OpenCode across generic Git, GitLab, and GitHub, plus resource/config --branch, existing-PR reuse, mixed routing, and dirty-clone cases.
• Unreachable guard (P2): removed the speculative multiple-new-group check because planPushGroups() currently produces at most one new group.

Local verification for this follow-up:

• npm run typecheck — passed
• npm run build — passed
• Focused unit tests — 108 passed
• Real CLI E2E — 20 passed

The remote checks should rerun against 9e16043 now.

[dvd233]

Update for accuracy: #690 was merged as 9d3a91c before follow-up commit 9e16043 could be included. I have prepared a separate follow-up PR based on the latest upstream/main for issue #800: #820

The previous statement that checks would rerun against 9e16043 was incorrect because #690 was already merged. The follow-up patch has been revalidated locally: typecheck passed, build passed, focused unit tests 108 passed, and the real CLI E2E suite 20 passed.