github / github/app

Add optional branch/worktree name param to create_session (rename_branch currently desyncs app state)

Open
#1,704 0 comments 1 reaction 0 assignees View on GitHub
Bugs
Dominant language
No language data
Stars
2.1k
Forks
153
PR merge metrics
No merged PRs in 30d

Description

## Summary

Add an optional parameter to `create_session` (the tool/RPC used to spin up a new worktree-backed session) that lets the caller specify the worktree/branch name at creation time. Today the name is always auto-generated (`--`), and the only way to change it afterwards is `rename_branch`, which only renames the git branch ref and the app's `workspaces.branch` row — it does **not** move the on-disk worktree folder or update the app's own `worktrees.branch`/`worktrees.path` row. This leaves the app's local SQLite state internally inconsistent (`worktrees` and `workspaces` disagree on the branch name for the same session), which risks breaking session resume/restore.

## Current behavior

- `create_session` accepts `project_id`, `name`, `base_branch`, `execution_location`, `coordinate_with_creator`, `notify_on_idle`, `kickoff{...}` — no branch/worktree naming param.
- The only way to get a deterministic, meaningful branch name (e.g. `copilot-`) is to call `rename_branch` from inside the freshly created session, after the fact.
- `rename_branch`'s effect is incomplete:
- Git branch ref: renamed correctly.
- `workspaces.branch` (app DB): updated correctly.
- On-disk worktree folder: **not moved** — stays at the old auto-generated path.
- `worktrees.branch` / `worktrees.path` (app DB): **not updated** — stays stale.
- Net result: two disagreeing sources of truth in the app's own local DB for the same session, confirmed via direct SQLite inspection (`~/.copilot/data.db`) before/after calling `rename_branch`.
- Verified separately that `git worktree move ` correctly relocates the folder and keeps git's own bookkeeping (`.git/worktrees//gitdir`) consistent — so this is an app-side gap, not a git limitation.

## Proposed change

Add an optional parameter to `create_session`, e.g. `branch_name` (full override, applied atomically at worktree/branch creation time), so agents/orchestrators that want deterministic naming never need to touch `rename_branch` at all:

```
create_session(project_id, name, branch_name: "copilot-dat-101", ...)
```

This sidesteps the desync bug entirely for the common case (multi-agent orchestrators fanning out one session per ticket/task, each wanting a name like `copilot-`), since the name is correct from the very first write to both `worktrees` and `workspaces`.

## Alternative / minimum fix

If a new creation-time parameter is out of scope short-term, at minimum make `rename_branch` safe to call post-creation by having it also:
- Run the equivalent of `git worktree move `, or otherwise update the folder path the app tracks.
- Update the `worktrees.branch` row (not just `workspaces.branch`) so the app's own DB doesn't disagree with itself.

## Why this matters

This is the concrete, actionable version of the branch-naming gap already being discussed elsewhere:

- #1703 — requests `branch_prefix` support in `github-app.yml` (config-as-code for the *prefix*); this issue is about the *session-creation-time* API gap for the full name/suffix, which a static prefix config can't solve for per-ticket/per-task naming.
- #1344 — reports the exact symptom of this bug: renaming gets "stuck" and the app keeps showing/using the old branch name after the first rename.
- #363 — requests configurable prefix + context-derived branch slugs; this issue proposes the concrete mechanism (a creation-time param) to deliver that without relying on the buggy post-hoc rename path.

## Repro / evidence

- Local app DB (`~/.copilot/data.db`) inspection after calling `rename_branch` in a worktree-backed session:
```
worktrees table: branch = -- stale
workspaces table: branch = -- updated
```
- Verified via a disposable test worktree that `git worktree move ` does correctly relocate the folder and keep `git worktree list` / `git status --branch` consistent, proving the desync is an app-side gap, not a git limitation.

## Environment

- GitHub Copilot CLI / desktop app version: 1.0.69-0
- OS: macOS

Contributor guide

Open the contributing guide

Research direction

Start by tracing the create_session and rename_branch tool/RPC entry points and the worktrees and workspaces records in ~/.copilot/data.db. Compare how branch and path values are written during creation and rename, then verify completion with SQLite inspection and git worktree list/status: both app tables and the on-disk worktree should consistently use the requested name.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, sqlite
Domain
backend, databases
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.