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

[jorgevista]

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 (<prefix>-<adjective>-<noun>), 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-<ticket-key>) 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 <old> <new> correctly relocates the folder and keeps git's own bookkeeping (.git/worktrees/<id>/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-<ticket-key>), 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 <path> <new-path>, 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:

• Support branch_prefix in github-app.yml, mirroring the Project Settings override #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.
• [Requests and ideas] the possibility to rename the branch after the inital renaming of the branch. #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.
• [Requests and ideas] Use context-derived branch names with configurable prefix for worktree sessions #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 = <original auto-generated name>   -- stale
  workspaces table: branch = <new name>                       -- updated
  

• Verified via a disposable test worktree that git worktree move <path> <new-path> 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