Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

teamai-reports checkout conflict between user scope and project scope of the same single-repo (kind: self) team repo (variant not covered by #808)

Closed
  • Is something wrong?
#1,443 5 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@Walternater is already working on this.

Since Oct 27, 2026.

  • #1465 by @Walternater — open

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
git, gitlab, node.js, typescript
Domain
backend, cli

Research direction

Read the worktree path and eviction logic named in the report: getWorktreeDir, getDataHome, removeOldCheckoutsInDotTeamai, and ensureWorktree/openWorktree; compare how they handle user and project scopes. Reproduce the conflict with the listed steps, then check both teamai-reports and teamai-learnings from each scope. Done means the two scopes can use the repository’s side branches without leaving report data stranded; pull request #1465 is already open for this issue.

Written by the indexing model from the issue text.

Description

bug help wanted

Title

teamai-reports checkout conflict between user scope and project scope of the same single-repo (kind: self) team repo (variant not covered by #808)

Body

Summary

On one machine, a single-repo (kind: self) team repo is installed at user scope, and running any teamai command inside that repo also auto-bootstraps a project scope partition for it. Both scopes publish teamai-reports / teamai-learnings, but they compute different side-branch worktree paths:

  • user scope: ~/.teamai/reports-wt
  • project scope: ~/.teamai/projects/<workspace-slug>/reports-wt

Git allows a branch to be checked out in one worktree only, and the eviction logic is one-directional, so the project scope permanently locks the user scope out. Report pushes then fail non-blocking, so usage events accumulate locally without any visible error (unless debug.log is inspected) and never reach the reports branch.

This looks like a variant of #808 that #808 does not cover: #808 fixed per-checkout installs that each kept side-branch checkouts in their own .teamai/; here the two conflicting checkouts are the user-scope install and the project-scope partition of the same repo.

Environment

  • teamai-cli: 0.27.0 (observed), and 0.28.0 (source compared; see below)
  • Node.js: v22.23.3, macOS arm64
  • Provider: self-hosted GitLab (gitlab provider), team repo in mode: self with usageReport: true
  • Config:
    • user scope: scope: user, repo.kind: self, repo.localPath: <business-repo>/.teamai, repo.businessRepoRoot: <business-repo>
    • project scope (auto-created): scope: project, projectRoot: <business-repo>, data home ~/.teamai/projects/<workspace-slug>/

Steps to reproduce

  1. Install the single-repo team at user scope and teamai pull from outside the repo. ~/.teamai/reports-wt is created and holds teamai-reports.
  2. Run teamai pull (or let the host's session-start hook run it) inside the repo. A project partition is bootstrapped and its pull refreshes its own checkout. Log: 
    [reports] removed the old checkout at /Users/<user>/.teamai/reports-wt
    The project-scope checkout at ~/.teamai/projects/<slug>/reports-wt now holds teamai-reports.
  3. Generate a usage event (invoke any skill), then teamai pull from outside the repo again.

Actual behavior

The user-scope report fails non-blocking and keeps the data local:

[reports] update failed (non-blocking): Preparing worktree (checking out 'teamai-reports')
fatal: 'teamai-reports' is already used by worktree at
'/Users/<user>/.teamai/projects/<slug>/reports-wt'
Auto-report push was not confirmed; keeping local report data

~/.teamai/user-usage.jsonl keeps growing; nothing reaches teamai-reports. The state lasts until the project-scope checkout is removed manually. The same conflict class applies to teamai-learnings.

Expected behavior

One shared side-branch checkout per repository (as CheckoutRefusedError itself promises: "teamai now keeps that checkout at ${wt}, shared by every checkout of this repo"), or at least symmetric eviction so the next pull can take ownership.

Root cause

  • getWorktreeDir(localConfig, dirname) → getDataHome(localConfig) + dirname; getDataHome → config.dataHome ?? getTeamaiHome(scope).
  • Project configs get dataHome = partitionHome from anchorProjectConfig; user-scope configs keep ~/.teamai (loadLocalConfig does not redirect a kind: self user config to the partition).
  • removeOldCheckoutsInDotTeamai (self mode) removes only checkouts whose resolved path ends with /.teamai/<worktreeDirname>. That matches the user-scope path (~/.teamai/reports-wt) but not the project partition path (~/.teamai/projects/<slug>/reports-wt). Hence:
    • project-scope pull can evict the user-scope checkout and take the branch;
    • user-scope pull can never evict the project-scope checkout, because git worktree add fails first.

Not fixed in 0.28.0

I compared 0.27.0 and 0.28.0 dist code for the paths involved: getWorktreeDir, getDataHome, usesBranchWorktree, ensureWorktree/openWorktree, removeOldCheckoutsInDotTeamai, loadLocalConfig. The relevant logic is unchanged, so #808's "they now live in the project partition that every checkout shares" appears to cover only the per-checkout .teamai/ variant, not user scope vs project scope.

Suggested fixes

  1. For kind: self configs, resolve the side-branch worktree dir from the shared project partition (resolveProjectDataHome(businessRepoRoot)) regardless of config scope (mirrors #808).
  2. Or make the eviction symmetric: consider any checkout of the same repository's worktree dirname, not only paths under /.teamai/.
  3. Or, when git worktree add reports the branch is checked out in another worktree of the same repository, adopt that checkout instead of failing (as openWorktree already does for valid existing checkouts).
  4. At minimum, surface the retained-report state in teamai status so members notice.

Workaround used

Symlink the project-scope paths to the user-scope checkouts so openWorktree accepts the existing checkout:

ln -s ~/.teamai/reports-wt   ~/.teamai/projects/<slug>/reports-wt
ln -s ~/.teamai/learnings-wt ~/.teamai/projects/<slug>/learnings-wt

plus a periodic script that removes the project-scope checkouts and runs teamai pull from outside the repo. Fragile and not upstream-able.

Dominant language
TypeScript
Stars
5.6k
Forks
471
Avg merge
20h 16m
Merged PRs (30d)
399

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Tencent/teamai-cli

All issues in Tencent/teamai-cli

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.