# Worktree-Isolated Sessions — Implementation Plan

Spec: docs/superpowers/specs/2026-06-10-worktree-sessions-design.md
Branch: worktree-sessions

Quality gates after every task (must pass before commit):

```
uv run ruff format src tests
uv run ruff check src tests
uv run ty check
uv run pytest -q
```

Do NOT stage `src/hqt/tmux/runner.py` — it carries an unrelated uncommitted
user change. Stage only files you created/modified for your task.

## Task 1 — Git worktree module

Create `src/hqt/git/__init__.py` and `src/hqt/git/worktree.py`, plus
`tests/test_worktree.py`.

Module contents (async functions use `asyncio.create_subprocess_exec`, in the
style of `src/hqt/tmux/runner.py`; failures raise `hqt.errors.ServiceError`
with git's stderr included):

- `slugify(text: str) -> str` — lowercase; keep `[a-z0-9]`; collapse runs of
  anything else into single `-`; strip leading/trailing `-`. Pure function.
- `async is_git_repo(path: Path) -> bool` — `git rev-parse
  --is-inside-work-tree` in `path`; False on any failure (including missing
  directory).
- `WorktreeState` dataclass: `exists: bool`, `dirty: bool`,
  `unique_commits: int`.
- `async create_worktree(repo: Path, branch: str) -> Path`:
  1. Validate with `git check-ref-format --branch <branch>` → ServiceError
     "Invalid branch name: ..." on failure.
  2. Resolve git common dir (`git rev-parse --git-common-dir`, relative
     results resolved against `repo`); append line `.worktrees/` to
     `<common-dir>/info/exclude` if not already present (create file if
     missing).
  3. `git worktree add -b <branch> <repo>/.worktrees/<branch>` (cwd=repo).
     ServiceError with stderr on failure (branch exists, dir exists, etc.).
  4. Return the absolute worktree path.
- `async add_worktree_for_branch(repo: Path, branch: str) -> Path` —
  `git worktree add <repo>/.worktrees/<branch> <branch>` (no `-b`), same
  exclude handling, for recreating a vanished worktree.
- `async worktree_state(repo: Path, path: Path, branch: str) ->
  WorktreeState` — `exists` = path exists on disk; `dirty` = non-empty
  `git status --porcelain` run in the worktree (False if not exists);
  `unique_commits` = line count of `git rev-list <branch> --not --all
  --count`-style query. Use `git rev-list --count <branch> --not
  --exclude=refs/heads/<branch> --all`... simplest correct form:
  `git for-each-ref --format='%(refname)' refs/heads refs/remotes`, drop the
  branch's own ref, then `git rev-list --count <branch> --not <others...>`
  (0 when no other refs exist is acceptable only if branch tip is reachable
  from them; with no other refs, count commits on branch). Implement and test
  against a real repo; exact plumbing is the implementer's choice as long as
  the tests below pass.
- `async remove_worktree(repo: Path, path: Path, branch: str, force: bool)
  -> None` — `git worktree remove [--force] <path>` (ServiceError on
  failure), then best-effort `git branch -d <branch>` (ignore failure), then
  `git worktree prune`.

Tests (real git in `tmp_path` repos; configure user.name/email; create an
initial commit):

- slugify: mixed case, spaces, punctuation, leading/trailing junk, empty.
- is_git_repo: repo → True; plain dir → False; missing dir → False.
- create_worktree: creates `.worktrees/<branch>` with branch checked out;
  `.git/info/exclude` contains `.worktrees/`; calling again with same branch
  raises ServiceError; invalid branch name (`foo..bar`) raises ServiceError;
  exclude not duplicated after two different worktrees.
- worktree_state: fresh worktree → exists, not dirty, 0 unique commits;
  touch a file → dirty; commit on the branch → unique_commits == 1; after
  removing dir manually → exists False.
- remove_worktree: clean worktree removed, branch (merged/no unique commits)
  deleted; dirty worktree without force → ServiceError and dir remains; with
  force → removed; unmerged branch survives removal (`git branch -d` fails
  silently, branch still listed).

Commit message: `feat: git worktree module`.

## Task 2 — Session columns + migration

Modify `src/hqt/db/models.py` and `src/hqt/db/migrations.py`; extend
`tests/test_db.py`.

- `Session` gains `worktree_path: Mapped[str | None] =
  mapped_column(default=None)` and `worktree_branch: Mapped[str | None] =
  mapped_column(default=None)`.
- Add migration entry `(2, ...)` to `MIGRATIONS` executing two
  `ALTER TABLE sessions ADD COLUMN` statements (worktree_path TEXT,
  worktree_branch TEXT). `LATEST_VERSION` derives automatically.
- Tests: fresh DB has the columns and user_version 2; a DB created at
  baseline (simulate: create tables via models without the new columns is
  impractical — instead create a v1 DB by issuing the old CREATE TABLE
  through exec_driver_sql or by building metadata then dropping the two
  columns is messy; acceptable approach: stamp an existing schema to
  user_version 1 after removing the columns via SQLite `ALTER TABLE ... DROP
  COLUMN`, then run `migrate()` and assert columns exist and version == 2).
  Follow the existing migration-test patterns in `tests/test_db.py` if any.

Commit message: `feat: worktree columns on sessions + migration v2`.

## Task 3 — SessionService worktree support

Modify `src/hqt/sessions/service.py`; extend `tests/test_sessions.py` /
`tests/test_services.py` (match where SessionService is currently tested).

- Import the worktree module as a module (`from hqt.git import worktree`)
  so tests can monkeypatch `worktree.create_worktree` etc.
- `create_session(self, project_id, harness_name, nickname=None, model=None,
  worktree_branch=None)`:
  - When `worktree_branch` is falsy → behavior identical to today.
  - When set: after resolving `project_path`, `await
    worktree.create_worktree(project_path, worktree_branch)` BEFORE adding
    the Session row; on ServiceError let it propagate (no row, no spawn).
    Store `worktree_path=str(path)` and `worktree_branch` on the row. Spawn
    config must be built with the worktree path, and the capture-retry loop
    must also use the worktree path.
  - Default nickname: if `worktree_branch` set and nickname blank, nickname
    becomes the branch name.
- Add `_session_path(self, db, sess) -> Path`: `Path(sess.worktree_path)`
  when set, else `self._project_path(db, sess.project_id)`. Use it in
  `_respawn_with_fallback`, `_get_resume_config`, and
  `_maybe_capture_missing_session_id` (replace direct project-path lookups
  for harness-facing paths; `_maybe_capture_missing_session_id` keeps its
  "project deleted → skip" behavior for non-worktree sessions, and for
  worktree sessions uses the worktree path without needing the project row).
- `attach_session` rung 0: before the alive check... no — keep order: if
  session has `worktree_path` and the path does not exist on disk:
  - branch exists (`git rev-parse --verify refs/heads/<branch>` helper in
    worktree module is NOT needed; use `worktree.add_worktree_for_branch`
    and catch ServiceError) → recreate, then continue normal flow.
  - recreate fails → raise ServiceError("Worktree and branch are gone;
    delete the session").
- `delete_session(self, session_id, remove_worktree=False, force=False)`:
  - Kill tmux window as today.
  - If `remove_worktree` and session has worktree: `await
    worktree.remove_worktree(project_path, Path(sess.worktree_path),
    sess.worktree_branch, force)`. On ServiceError: do NOT delete the DB row;
    re-raise (the TUI shows the notification; the tmux window being already
    killed is acceptable).
  - Then delete row + commit.
- Expose `async worktree_state_for(self, session_id) -> WorktreeState | None`
  returning None for non-worktree sessions; the TUI uses it to build the
  confirm dialog.

Tests (fake tmux pattern as existing tests; monkeypatch worktree functions
with AsyncMock/recording fakes):

- create_session with worktree_branch: create_worktree called with project
  path and branch; spawn cwd == worktree path; capture uses worktree path;
  row has worktree fields; nickname defaults to branch.
- create_worktree raising → ServiceError propagates, no Session row exists,
  no spawn attempted.
- attach with worktree_path missing on disk → add_worktree_for_branch
  called; on its failure → ServiceError with the delete-hint message.
- resume config for a worktree session uses worktree path.
- delete_session remove_worktree=True calls worktree.remove_worktree and
  deletes row; worktree.remove_worktree raising → row still present.
- worktree_state_for: None for plain sessions; delegates for worktree ones.

Commit message: `feat: worktree-aware session lifecycle in SessionService`.

## Task 4 — TUI wiring + docs

Modify `src/hqt/tui/screens/new_session.py`, add
`src/hqt/tui/screens/confirm_delete.py`, modify `src/hqt/tui/app.py`,
`src/hqt/tui/widgets/session_list.py`, `src/hqt/status.py` callers if
needed, `README.md`; extend `tests/test_tui.py`.

- `NewSessionScreen(harness_names, is_git_repo)`:
  - Result type becomes `tuple[str, str, str | None, str | None] | None`
    (harness, nickname, model, worktree_branch).
  - Add `Checkbox("Isolate in worktree", id="worktree-checkbox")` (textual
    `Checkbox`); when `is_git_repo` is False, `disabled=True` and label
    "Isolate in worktree (not a git repo)".
  - Branch `Input(id="branch-input")` hidden (`display = False`) until the
    checkbox is checked; when first revealed, prefill with
    `slugify(nickname)` if the field is empty; user edits freely afterwards.
  - On submit with checkbox checked: empty branch → block submit and focus
    the branch field (or fall back to slugified nickname if non-empty;
    if both empty, keep dialog open). Unchecked → worktree_branch None.
- `ConfirmDeleteScreen(ModalScreen[tuple[bool, bool] | None])` in new file:
  constructor takes `session_label: str`, `warning: str | None`. Shows
  "Delete session <label>?", optional warning line, `Checkbox("Also remove
  worktree", value=warning is None)`, Delete/Cancel buttons. Returns
  `(confirmed, remove_worktree)`; `remove_worktree and warning is not None`
  means force.
- `app.py`:
  - `action_new_session`: compute `is_git_repo` via
    `await worktree.is_git_repo(Path(project.path))` (inside the worker or
    pre-fetched; ProjectService has the path — follow existing access
    patterns), pass to screen; pass `worktree_branch` to `create_session`.
  - `action_delete_session`: fetch session; if it has no worktree, keep
    today's immediate delete. Otherwise call
    `sessions.worktree_state_for(sid)`, build warning string when dirty or
    unique_commits > 0 ("N uncommitted file(s), M unmerged commit(s) — work
    will be lost"), push ConfirmDeleteScreen; on (True, remove) call
    `delete_session(sid, remove_worktree=remove, force=remove and warned)`.
    ServiceError already surfaces via `_run_service_worker`.
- Session list: rows for worktree sessions append ` ⎇ <branch>`; check
  `src/hqt/tui/widgets/session_list.py` for the row-label construction.
- tmux window label: in `sync_window_labels`, the name passed to
  `window_label` for worktree sessions is `nickname or branch` (nickname
  already defaults to branch at creation, so no change may be needed —
  verify and leave a test).
- README: document the worktree checkbox under Key Bindings/feature notes,
  and the `.worktrees/` location + submodule limitation.
- Tests: NewSessionScreen returns worktree_branch when checked, None when
  unchecked, disabled checkbox when not a repo; ConfirmDeleteScreen returns
  the right tuples; app delete path for non-worktree sessions unchanged
  (no modal).

Commit message: `feat: worktree session UI (dialog checkbox, confirm delete, list marker)`.