Git and worktrees

Git is the recovery boundary for Tejus work. Before fixing a repository problem, identify the thread’s actual working directory and preserve every change you may need.

Start in the thread’s working directory

Open the thread’s terminal (Ctrl+J) and run:

git rev-parse --show-toplevel
git status --short --branch
git worktree list --porcelain

Confirm:

• The path matches the thread’s environment (the Work in menu shows Local or Worktree)
• The expected branch or detached base is checked out
• The repository is not in the middle of a merge, rebase, cherry-pick, or revert
• Untracked files are visible
• Another thread is not using the same checkout

Do not diagnose the primary checkout when the thread actually owns a managed worktree. Tejus-managed worktrees live under %USERPROFILE%\.tejus\worktrees\.

Large commits and pushes

Commit and push actions stream Git output and keep only a bounded preview for commit-message generation and logs. Reaching those preview limits does not shorten the committed files or stop the push. Large file selections are passed to Git through a temporary path list rather than command-line arguments, so long file lists do not hit Windows command-length limits.

Staging, committing, and pushing have no fixed Tejus time limit. A large transfer or a slow hook can take time; avoid starting a duplicate operation while one is running. Git hooks, authentication failures, and rules enforced by the remote repository can still reject an operation. Check the failed step and its error details before retrying.

Connection interrupted during a Git action

Commit, push, and pull-request actions run in the Tejus backend. If the window loses its connection to the backend while one is running, the action keeps going; when the connection returns, Tejus reattaches to the same action and shows its current step or result without running it again.

Quitting Tejus still interrupts running actions. If the backend restarted and the result is no longer available, Tejus asks you to check repository status before retrying. Completed commits and pushes are never rolled back by a disconnect.

Worktree setup failed

When a New worktree thread is created on its first message, Tejus shows each setup step (branch, worktree, copying local changes, setup script).

• “Select a base branch before sending in New worktree mode.” Choose a base branch in the branch picker next to Work in, then send again.
• The setup script failed. The script marked Run automatically on worktree creation runs in the new worktree. Fix the script or run it manually in the thread’s terminal.
• The branch is already checked out elsewhere. See Git says a branch is already checked out.

Hand off to local or worktree failed

Hand off to new worktree and Hand off to local (in Work in) move a thread and its uncommitted changes between the main checkout and a worktree using a Git stash.

• If applying the moved changes conflicts, Tejus rolls the handoff back so the thread stays where it was, and keeps the stash entry. Inspect it with git stash list and git stash show -p <entry> before applying or dropping anything.
• If moving back to local succeeds but restoring your previous local changes conflicts, the toast says so and your previous local stash entry is kept for recovery.
• “Select a base branch before handing off this thread to a worktree.” The local checkout has no current branch to base the worktree on; check out a branch first.

Detached HEAD in a managed worktree

A detached HEAD can be intentional. Tejus can create managed worktrees from a selected ref without immediately attaching a named branch.

Before changing it:

1. Inspect the commits and diff.
2. Confirm the intended delivery branch.
3. Create or attach the branch through the thread’s normal Git workflow.
4. Push the intended branch before cleanup when the work must survive.

Do not “fix” a detached HEAD by switching to main inside an active thread’s worktree.

Repository lock error

Git lock files (index.lock and similar) protect concurrent operations. First determine whether another Git process is still running.

1. Stop duplicate Git operations.
2. Wait for legitimate processes to finish.
3. Check terminals, editors, hooks, and provider processes using the repository.
4. Record the exact lock path and command.
5. Remove a lock file only after confirming no live process owns it.
6. Run git status immediately afterward.

Deleting a live lock can corrupt or interleave repository operations.

Merge or rebase is in progress

Use git status to identify the operation.

Choose deliberately:

• Continue after resolving every conflict
• Abort the operation and return to the recorded pre-operation state
• Preserve the current conflict state in a copy before experimenting

Do not mix a merge recovery with unrelated refactors or generated changes. Verify the final diff against both the intended base and objective.

Worktree path is missing

A thread can keep its metadata after its directory was removed outside Tejus.

1. Stop the affected thread.
2. Record the branch, thread, and last known worktree path.
3. Check git worktree list --porcelain.
4. Inspect whether commits or refs still preserve the work.
5. Check for uncommitted copies elsewhere before pruning metadata.
6. Recreate or recover the environment only after establishing what survived.

Uncommitted files from a manually deleted directory are not restored by Git metadata.

Project is inside WSL

Tejus recognizes projects opened through \\wsl.localhost\<distribution>\... and \\wsl$\<distribution>\... paths. Provider commands for those projects run through wsl.exe inside the named distribution, and providers receive the equivalent Linux working directory.

When a WSL-backed thread fails:

1. Confirm the path names the intended distribution.
2. Run wsl.exe --list --verbose and verify that the distribution is installed and running.
3. Open the equivalent Linux path inside that distribution and confirm the repository exists.
4. Verify the provider CLI is installed and signed in inside WSL, not only on Windows.
5. Check that a manually configured provider binary is valid in the environment where it will run.

Do not rewrite a WSL project path to a drive-letter path unless it is genuinely the same filesystem and repository.

Git says a branch is already checked out

A branch can be attached to only one worktree at a time.

Use:

git worktree list

Then either:

• Continue in the worktree (or thread) that already owns the branch
• Create a different branch for the new thread
• Remove the old worktree safely after preserving its changes

Do not force the same branch into two worktrees.

Two threads edited one checkout

Stop both threads and assign one integration owner.

Capture:

git status --short
git diff --stat
git diff
git ls-files --others --exclude-standard

Then classify each change:

• Intended by thread A
• Intended by thread B
• Shared dependency needed by both
• Unrelated or accidental
• Unknown ownership

Always preserve the combined state before separating it. Move future edits into separate worktrees.

Worktree cannot be removed

On Windows, a running terminal, dev server, file watcher, or editor holding a file open prevents removal.

Before cleanup:

1. Stop provider turns, terminal processes, and dev servers using the path (the Background tasks panel lists running commands and local servers).
2. Review uncommitted and untracked files.
3. Commit or copy wanted changes.
4. Push the branch when it must survive the machine.
5. Confirm the worktree is not the active environment of a thread you still need.
6. Remove it from Settings → Managed worktrees rather than deleting the directory by hand.

Tejus never removes the worktree of an active thread automatically, keeps the worktrees of the 15 most recently archived threads, and skips any worktree with uncommitted changes during automatic cleanup. Delete in Settings → Managed worktrees, however, removes the worktree even if it has uncommitted changes. Git commits and pushed refs remain the durable preservation mechanism.

A worktree disappeared after archiving

Automatic cleanup removes clean worktrees of deleted threads, and of archived threads beyond the 15 most recent. With Settings → General → Core defaults → Delete worktree on archive turned on, a clean worktree is also removed after Archive’s Undo period.

The branch normally survives, so you can recreate the worktree:

git branch --list "tejus/*"
git worktree add <path> <branch>

The exception is a branch that still has its temporary name (tejus/ followed by eight hex characters, used before Tejus renames it): automatic retention cleanup deletes that branch together with its worktree. Before any automatic removal, Tejus saves a recovery snapshot (including a changes.patch of the worktree’s changes) under %USERPROFILE%\worktree-snapshots\ and keeps it for 30 days. Use git reflog in the main checkout to find the branch’s last commit.

Wrong base branch

Record the current state before rebasing or moving commits:

git branch --show-current
git rev-parse HEAD
git merge-base HEAD <intended-base>
git log --oneline --decorate --graph -20

Choose whether the thread should:

• Rebase onto the intended base
• Merge the intended base
• Cherry-pick focused commits onto a clean branch
• Restart from the correct base

Do not rewrite a branch that another thread or reviewer is using without coordinating the new head.

Untracked or generated files appeared

Do not delete all untracked files automatically.

Classify them first:

• Intended source files
• Test snapshots or fixtures
• Build artifacts
• Logs and debug output
• Downloaded dependencies
• Credentials or machine-local configuration

Use repository-specific cleanup commands only after reviewing what they remove.

Repository created during a thread

A thread can start in a plain folder and initialize Git during its turn. Tejus cannot create a checkpoint baseline for the state before Git existed, so the first turn’s diff and revert options may be limited. Review the available checkpoint and diff before reverting.

Safe recovery commands

These commands observe state without changing it:

git status --short --branch
git diff --check
git diff --stat
git diff
git log --oneline --decorate -20
git worktree list --porcelain
git stash list
git reflog -20

git reflog can help locate recent commits or ref movements, but it does not restore uncommitted files from a deleted directory.

Git recovery checklist

• The thread’s actual working directory was confirmed
• Current branch, HEAD, and operation state were recorded
• Untracked files were reviewed
• No live process owns the repository lock
• Work was preserved before cleanup or history rewriting
• One integration owner controls the recovery
• The final diff will be compared with the intended base
• The final head will be tested after conflict resolution

Continue with Worktrees for normal operation or Report a problem when Tejus’s managed-worktree state disagrees with Git.