hqt/docs/superpowers/specs/2026-06-10-worktree-sessions-design.md

# Worktree-Isolated Sessions — Design

Date: 2026-06-10
Status: Approved

## Goal

Allow a new session to run in a git worktree of its project so the harness
operates on an isolated checkout, on its own branch, without trampling the
main checkout or other sessions.

## Decisions (from brainstorming)

- **Lifecycle:** Feature-branch work. hqt creates worktrees but never
  auto-deletes work. Cleanup is explicit and guarded.
- **Branching:** The user names the branch in the new-session dialog; hqt
  creates it with `git worktree add -b <branch>` based off the project's
  current HEAD. No existing-branch checkout, no auto-generated names.
- **Location:** `<project>/.worktrees/<branch>`. hqt ensures `.worktrees/` is
  listed in the repo's `.git/info/exclude` (idempotent append; resolved via
  `git rev-parse --git-common-dir` so it works when the project itself is a
  worktree).
- **Deletion:** Deleting a worktree session prompts with an "Also remove
  worktree" option and a safety check. Dirty trees or branches with commits
  unreachable from other refs require explicit opt-in (maps to
  `git worktree remove --force`). Branches are only deleted with safe
  `git branch -d`, so unmerged branches always survive.
- **Dialog UX:** Checkbox "Isolate in worktree" + branch input (prefilled from
  the slugified nickname). Disabled with a hint when the project is not a git
  repo.
- **Setup:** None. Fresh worktrees have no deps/env files; the agent in the
  session handles its own setup.
- **Base ref:** Current HEAD of the main checkout.

## Architecture (Approach A)

### Data model

`Session` gains two nullable columns; both NULL means a normal session (no
boolean flag):

- `worktree_path: str | None` — absolute path of the worktree
- `worktree_branch: str | None` — branch name

Migration version 2 in `hqt/db/migrations.py` `MIGRATIONS` with two
`ALTER TABLE sessions ADD COLUMN` statements.

### Git layer: `src/hqt/git/worktree.py`

Async subprocess wrappers around git, mirroring `tmux/runner.py`. Failures
raise `ServiceError` carrying git's stderr.

- `slugify(text) -> str` — lowercase, keep alphanumerics, collapse runs of
  other chars to `-`, strip leading/trailing `-`.
- `is_git_repo(path) -> bool` — `git rev-parse --is-inside-work-tree`.
- `create_worktree(repo, branch) -> Path` — validate branch name
  (`git check-ref-format --branch`), ensure `.worktrees/` in
  `.git/info/exclude`, run `git worktree add -b <branch> .worktrees/<branch>`.
  Returns absolute worktree path.
- `worktree_state(repo, path, branch) -> WorktreeState` — dataclass:
  `exists: bool`, `dirty: bool` (`git status --porcelain` in the worktree),
  `unique_commits: int` (commits on `branch` not reachable from any other
  ref).
- `remove_worktree(repo, path, branch, force) -> None` —
  `git worktree remove` (`--force` only when the user confirmed past the
  warning), then best-effort `git branch -d` (keep branch if unmerged), then
  `git worktree prune`.
- `add_worktree_for_branch(repo, branch) -> Path` — `git worktree add <path>
  <branch>` (no `-b`); used to recreate a vanished worktree on attach.

### SessionService changes

- `create_session(..., worktree_branch: str | None = None)`. When set:
  resolve project path → `create_worktree` (failure raises ServiceError
  before any row exists) → create Session row with `worktree_path` /
  `worktree_branch` → spawn with `cwd=worktree_path`.
- `_session_path(db, sess) -> Path` returns
  `Path(sess.worktree_path) or project.path` and replaces `_project_path` at
  every harness-facing call site: `build_spawn_config`,
  `build_resume_config`, and `capture_session_id` (Claude keys session files
  by cwd, which is now the worktree).
- Attach rung 0: if `worktree_path` is set but missing on disk and the
  branch still exists, recreate via `add_worktree_for_branch` and continue
  the normal resume ladder. If the branch is gone too, raise
  `ServiceError("Worktree and branch are gone; delete the session")`.
- `delete_session(session_id, remove_worktree: bool = False, force: bool =
  False)`. When removal is requested and fails, neither the worktree nor the
  DB row is deleted (no half-deleted state); the error surfaces as a
  notification.

### TUI changes

- `NewSessionScreen`: constructor gains `is_git_repo: bool`. Adds a
  "Isolate in worktree" checkbox (disabled + "(not a git repo)" hint when
  false) and a branch `Input`, hidden until checked, prefilled with the
  slugified nickname (editable). Result tuple extends with
  `worktree_branch: str | None`.
- New `ConfirmDeleteScreen` modal, used only for worktree sessions
  (non-worktree `d` keeps today's instant behavior): shows session name,
  "Also remove worktree" checkbox. The app fetches `worktree_state` before
  pushing it; if dirty or `unique_commits > 0`, show a warning line ("N
  uncommitted files, M unmerged commits — work will be lost") and start the
  checkbox unchecked; checked-through-warning maps to `force=True`.
- Session list rows and tmux window labels mark worktree sessions with
  `⎇ <branch>`; nickname defaults to the branch name when left empty.

## Corner cases

- Branch exists / invalid name / leftover `.worktrees/<branch>` dir → git
  fails, ServiceError notification, no session row.
- Non-git project → checkbox disabled; service raises if called anyway.
- Project path deleted with live worktree sessions → same as today (capture
  skipped, attach errors).
- Submodules are not initialized in fresh worktrees — documented limitation.
- `git worktree remove` fails (e.g. process cwd inside) → notification,
  session row kept.

## Testing

- `tests/test_worktree.py`: git module against real temp git repos (init,
  commit; create/remove/state; exclude idempotence; invalid names).
- Service tests: monkeypatch worktree functions; verify ordering (worktree
  before row, no row on failure), spawn/resume/capture cwd, attach rung 0,
  guarded delete.
- TUI tests: dialog return values, checkbox-disabled path, confirm modal
  wiring.