@senad-d/branchme 0.1.7 → 0.1.8

package/docs/SMOKE_TEST.md

@@ -1,16 +1,21 @@
 # BranchMe Smoke Test Notes
 
-Date: 2026-07-15
+Date: 2026-08-23
 
 Validated from the repository checkout with no discovered extensions enabled.
 
 ## Commands
 
 ```bash
-npm run validate
+npm run typecheck
+npm run format:check
+npm run test
 npm run smoke:pi
-npm run smoke:pi:packed
 npm run check:pack
+npm run smoke:worktree-handoff
+npm run validate
+npm run smoke:pi:packed
+npm run release:check
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 pi --no-extensions -e .
 ```
@@ -18,24 +23,29 @@ pi --no-extensions -e .
 ## Automated smoke behavior
 
 - `npm run smoke:pi` first runs isolated checkout Pi processes from a temporary non-Git working directory: one with `pi --no-extensions -e <package> -e <temporary verifier>` and `/branchmeverify verify`, then one with `pi --no-extensions -e <package>` and `/branchme help`.
-- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms `branch_status`, `change_branch`, `fetch_branch`, `pull_branch`, `rebase_branch`, `create_branch`, `push_branch`, and `pull_request` are active runtime tools with strict schemas, prompt guidelines, descriptions, and extension source metadata.
+- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms `branch_status`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, and `remove_worktree` are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata.
 - A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback.
+- The Pi runtime smoke validates worktree tool registration, strict schemas, and prompt contracts only; it never creates or removes a worktree. Real-Git `list_worktrees`/`create_worktree`/`remove_worktree` lifecycle coverage runs under `npm run test` in temporary local repositories with sibling destinations under the same temporary root and no remotes.
+- `npm run smoke:worktree-handoff` loads only BranchMe into a deterministic extension host backed by real local Git, creates a new-branch linked worktree through the registered `create_worktree` tool, and launches a separate Node verification process with the returned absolute `handoff.cwd`. That process verifies its cwd, branch, full `HEAD`, and lack of remotes. The smoke then calls the registered `remove_worktree` tool, verifies the directory is absent, and verifies the retained local branch remains at the original commit.
+- The handoff smoke uses only a freshly created temporary source repository and sibling worktree, an empty Git config, a minimal credential-free environment, no remotes, offline Pi flags, and a fetch guard that fails on any network request. Cleanup recursively removes the isolated temporary root even on failure.
+- `npm run validate` includes the isolated handoff smoke after package-content checks.
 - The checkout command smoke accepts either `/branchme help` text or the read-only BranchMe status fallback as equivalent non-mutating command output.
 - `npm run smoke:pi:packed` creates an npm tarball under a temporary directory, installs that tarball into a separate temporary package with `npm install --omit=dev`, and runs pi against the installed package instead of the source checkout.
-- `npm run smoke:pi:packed` is the release gate for packaged runtime imports and required packaged files; `npm run release:check` and `node scripts/publish-npm.mjs` run it before publish, while everyday `npm run validate` keeps the faster checkout smoke.
-- Both smoke runs disable discovered extensions, skills, prompt templates, themes, context files, persistent sessions, telemetry, startup network checks, and GitHub token environment variables.
-- Both smoke runs are credential-free, allow documented credential variable names in help text, reject credential value patterns, do not call BranchMe mutation tools, and do not contact GitHub.
-- Pi's documented `getAllTools()` metadata currently exposes parameter schemas and prompt guidelines, but not `promptSnippet`. The deterministic local smoke model exercises `branch_status` through Pi's normal model tool-call loop without provider or GitHub network access.
+- `npm run release:check` is the canonical release gate: it runs `npm run validate` and then `npm run smoke:pi:packed`. Both `node scripts/publish-npm.mjs` and the GitHub `Publish to npm` workflow run it before npm publication; a packed install/load failure stops publication and the workflow's Git tag step. Everyday `npm run validate` keeps the faster checkout smoke.
+- Both Pi smoke runs disable discovered extensions, skills, prompt templates, themes, context files, persistent sessions, telemetry, startup network checks, and GitHub token environment variables.
+- Both Pi smoke runs are credential-free, allow documented credential variable names in help text, reject credential value patterns, do not call BranchMe mutation or remote tools, and do not contact GitHub.
+- Pi's documented `getAllTools()` metadata exposes parameter schemas, descriptions, prompt guidelines, and source metadata, while command context exposes active `promptSnippet` values through `getSystemPromptOptions().toolSnippets`; the runtime verifier checks both surfaces. The deterministic local smoke model exercises `branch_status` through Pi's normal model tool-call loop without provider or GitHub network access.
 - Set `BRANCHME_SKIP_PI_SMOKE=1` to skip intentionally, or `BRANCHME_PI_BIN=/path/to/pi` to test a specific Pi binary for the checkout smoke.
 - If no Pi binary is available, the checkout smoke script prints an explicit skip message; default CI installs the Pi dev dependency, so `npm run validate` exercises the real Pi loading path.
 
 ## Result
 
-- `npm run validate` passed.
-- `npm run smoke:pi` loaded BranchMe through Pi, verified all eight BranchMe tools through the real `pi.getAllTools()` runtime surface, and confirmed non-mutating BranchMe command output.
+- `npm run typecheck`, `npm run format:check`, `npm run test`, `npm run smoke:pi`, `npm run check:pack`, `npm run validate`, and `npm run smoke:pi:packed` passed.
+- `npm run smoke:worktree-handoff` returned `ok: true`, an absolute ready cwd, the expected `feature/isolated-handoff-smoke` branch and full commit ID from a separate process, `branchRetained: true` after force-free removal, zero network requests, and an isolated empty credential source.
+- `npm run smoke:pi` loaded BranchMe through Pi, verified the complete BranchMe tool set and prompt metadata through real Pi runtime APIs, and confirmed non-mutating BranchMe command output.
 - The isolated Git-context prompt smoke observed the `before_agent_start` snapshot, answered branch and dirty-tree state without a tool call, refreshed a verifier-created local change through one real `branch_status` call, returned safe unavailable context without credentials or outside Git, and attempted no network request.
 - `npm run smoke:pi:packed` packed BranchMe outside the repository, installed the artifact in a temporary production workspace, loaded the installed package through Pi, and confirmed non-mutating BranchMe command output.
-- `npm run check:pack` confirmed the package contents are limited to public docs, images, source, license, package metadata, `.env.example`, and `tsconfig.json`.
+- `npm run check:pack` confirmed the package contents are limited to public docs (including worktree behavior and security boundaries), images, source, license, package metadata, `.env.example`, and `tsconfig.json`; private planning specs and generated files remain excluded.
 - The isolated Pi smoke command loaded BranchMe and displayed BranchMe help or status output instead of template behavior.
 - The bare `pi --no-extensions -e .` smoke command exited cleanly in this non-interactive validation environment.
 - No template command or template tool output was observed.

package/docs/STRUCTURE.md

@@ -1,6 +1,6 @@
 # BranchMe Structure Guide
 
-BranchMe is a TypeScript Pi extension package for current-repository git branch fetch/update/rebase, push, and GitHub pull request workflows.
+BranchMe is a TypeScript Pi extension package for current-repository Git branch, verified linked-worktree, push, and GitHub pull request workflows.
 
 ## Source layout
 
@@ -13,8 +13,8 @@ src/
 ├── commands/
 │   └── branchme-command.ts       # /branchme status/help command; informational only
 ├── tools/
-│   └── branchme-tools.ts         # registration for eight branch/GitHub workflow tools
-├── git.ts                        # argv-style git helpers and per-repo workflow queue
+│   └── branchme-tools.ts         # registration for eleven branch/worktree/GitHub workflow tools
+├── git.ts                        # argv-style branch/worktree helpers and per-repo workflow queue
 ├── github.ts                     # GitHub repo resolution, env/.env tokens, branch preflight, REST calls, redaction
 └── ui/
     └── branchme-panel.ts         # compact /branchme status panel renderer
@@ -22,11 +22,11 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, eight tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, eleven tools, and one `before_agent_start` context hook.
 2. `src/git-context.ts` owns the shared read-only collector, escaped/bounded formatter, automatic system-prompt append, and the current-state output used by `branch_status`.
 3. `src/commands/branchme-command.ts` parses `/branchme`, `/branchme help`, `--help`, and `-h`; it never performs git or GitHub mutations and avoids raw stdout in JSON mode.
-4. `src/tools/branchme-tools.ts` owns TypeBox schemas, prompt metadata, tool content, and safe structured details. `branch_status` delegates to the shared context collector for an explicit refresh.
-5. `src/git.ts` owns current-repository git behavior: root detection, branch/upstream/ahead-behind inspection, working-tree parsing, recent-commit collection, PR base/commit-subject inference, branch validation, branch creation, existing-local-branch switching, configured-upstream fetch, clean-worktree preflight, fast-forward-only current-branch pull, current-branch rebase with automatic abort on failure, current-branch push/publish, and the per-repository workflow queue.
+4. `src/tools/branchme-tools.ts` owns strict TypeBox schemas, prompt metadata, bounded tool content, and safe structured details. `branch_status` delegates to the shared context collector; `list_worktrees`, `create_worktree`, and `remove_worktree` expose explicit repository inventory and verified handoff operations.
+5. `src/git.ts` owns current-repository Git behavior: root and common-Git-directory detection, branch/upstream/ahead-behind inspection, working-tree parsing, recent-commit collection, PR base/commit-subject inference, branch validation and branch workflows, NUL-delimited worktree parsing/inventory, canonical worktree path validation, verified create/remove postconditions, and the per-repository workflow queue.
 6. `src/github.ts` owns GitHub `owner/repo` parsing, repository boundary checks, `GITHUB_TOKEN`/`GH_TOKEN` and `BRANCHME_PR_AUTOFILL` process-env/hardened git-root `.env` resolution, authenticated related-open-PR lookup, PR branch-name syntax validation, GitHub branch visibility/commit preflight, PR REST calls, bounded response validation, and redacted errors.
 7. `src/redaction.ts` owns shared credential redaction for Git, GitHub, and prompt-bound metadata.
 8. `src/types.ts` keeps serializable details shared by helpers, context, and tools.
@@ -36,11 +36,12 @@ src/
 
 - No long-lived processes, watchers, timers, sockets, or background jobs start in the extension factory.
 - A single `before_agent_start` handler synchronously collects a fresh snapshot for each agent run and appends it to the existing system prompt; failures degrade to bounded unavailable context rather than blocking startup.
-- Slash commands are informational; tools perform branch fetch/update/rebase, push, and PR actions. There is no context command.
-- Every tool uses a strict TypeBox object schema with `additionalProperties: false`.
+- Slash commands are informational; tools perform branch, worktree, push, and PR actions. Commands never create/remove worktrees, change cwd, or start Pi sessions. There is no context command.
+- Every tool uses a strict TypeBox object schema with `additionalProperties: false`; worktree creation requires exactly `worktreePath`, `branchName`, and `branchMode`, while listing is empty and removal accepts only `worktreePath`.
 - Every tool defines a description, `promptSnippet`, and tool-specific `promptGuidelines` that explicitly name the tool.
-- Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root and same-repository mutation/PR windows are serialized per repository.
-- Tool details avoid token values and unbounded raw command/API output.
+- Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from verified locations and same-repository mutation/PR windows are serialized per repository.
+- Worktree results expose serializable requested and verified before/after state. Create returns `handoff: { cwd: <absolute>, branch, head, ready: true, summary }`; remove returns the retained branch/HEAD with `cwd: null` and `ready: false`.
+- Tool details avoid token values, abort signals, runtime objects, and unbounded raw command/API output.
 - Automatic and explicit context include branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged/untracked entries, related open PR state, and up to 5 recent commits. Metadata values default to 512 characters and rendered context to 4,000 characters.
 - Pi core packages, including `@earendil-works/pi-tui` for key/width utilities, remain in `peerDependencies` with `"*"`.
 
@@ -55,10 +56,13 @@ src/
 - `pull_branch` requires a clean worktree and configured upstream, then updates only the current branch with an explicit `git pull --ff-only --no-rebase --no-autostash <remote> <remote-ref>` command; divergence fails without a rebase or merge commit.
 - `rebase_branch` requires a clean worktree and configured upstream, then rebases only the current branch with `git rebase --no-autostash --no-update-refs <upstream>`; it rewrites local commits and automatically attempts `git rebase --abort` on failure.
 - `create_branch` mutates local branch/HEAD only with `git switch -c`.
+- `list_worktrees` reads a bounded `git worktree list --porcelain -z` inventory and remains explicit rather than expanding automatic active-worktree context.
+- `create_worktree` requires an explicitly approved absolute destination, canonicalizes its existing parent, rejects existing or nested/common-Git-directory destinations, and creates only from current `HEAD` or an unoccupied existing local branch. It verifies canonical path, branch, `HEAD`, and cleanliness before returning a ready handoff.
+- `remove_worktree` resolves an exact fresh current-repository inventory match, rejects main/current/dirty/ignored-entry-containing/detached/locked/prunable/missing/bare entries, runs a bounded removal-specific ignored-entry scan, performs force-free removal with the verified path, and confirms that the local branch remains at the same commit.
 - `push_branch` mutates remote refs only for the current branch and uses an explicit upstream remote/refspec instead of bare `git push` when an upstream exists.
 - `pull_request` requires resolved `headBranch` and `baseBranch` values to be distinct and exist locally, requires `headBranch` to match the GitHub-visible branch commit, queues behind already-started same-repository git mutation windows, makes GitHub REST API calls for the resolved current repository only, and rejects owner-prefixed or unsafe branch refs before the request. Omitted fields require configured autofill.
 - `pull_request` reads `GITHUB_TOKEN` or `GH_TOKEN` from process environment first; only when neither process token is set does it read those token keys from a small regular `.env` file in the verified git root as a fallback. `BRANCHME_PR_AUTOFILL` uses the same process-first, `.env`-fallback precedence and defaults off.
-- BranchMe does not force checkout, stash, stage, create user-authored commits, reset, force-push, create merge commits, directly edit files, read unsupported `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry. Rebase-driven commit rewriting occurs only through explicit `rebase_branch` calls.
+- BranchMe does not force checkout/removal, move/prune/repair/lock/unlock worktrees, create detached/orphan worktrees, infer remote worktree branches, copy ignored/untracked files such as `.env`, remove linked worktrees that contain ignored entries, delete retained worktree branches, change Pi's cwd, or start Pi sessions. It also does not stash, stage, create user-authored commits, reset, force-push, create merge commits, directly edit files, read unsupported `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry. Git documents submodule worktree support as incomplete; BranchMe adds no force-based submodule cleanup.
 
 ## Documentation
 
@@ -73,11 +77,12 @@ src/
 test/
 ├── command.test.mjs      # /branchme parsing, help, fallback, panel width
 ├── git-context.test.mjs  # collection, prompt hook, formatting, safety, and output bounds
-├── git.test.mjs          # git helper command construction and failures
-├── git-integration.test.mjs # isolated real-git context and branch helper coverage
+├── git.test.mjs          # branch/worktree parsing, validation, command construction, postconditions, failures
+├── git-integration.test.mjs # isolated real-Git context, branch, and worktree lifecycle coverage
 ├── github.test.mjs       # GitHub parsing, token resolution, related-PR lookup, redaction
 ├── preparation.test.mjs  # package/docs/source metadata checks
-├── tools.test.mjs        # extension registration, schemas, shared refresh, tool behavior
+├── schema-validation.test.mjs # strict TypeBox schema validation, including worktree fields/modes
+├── tools.test.mjs        # extension registration, prompt metadata, shared refresh, tool behavior
 └── tui-capture.test.mjs  # generated text capture for TUI/help visual baselines
 ```
 

package/docs/TUI_CAPTURE.md

@@ -16,7 +16,7 @@ UPDATE_TUI_CAPTURE=1 node --test test/tui-capture.test.mjs
 ```text
 # BranchMe
 
-Current-repository branch workflow tools for Pi.
+Current-repository Git workflow tools for Pi.
 
 Commands only show info; BranchMe tools perform actions.
 
@@ -31,6 +31,14 @@ Commands only show info; BranchMe tools perform actions.
 7. `push_branch` — push the current branch.
 8. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.
 
+## Worktree handoff
+
+- `list_worktrees` — inspect the main and linked worktrees in the current repository.
+- `create_worktree` — create a linked worktree and return a ready handoff with an absolute `handoff.cwd`.
+- A separate orchestrator starts the next Pi session or subagent in `handoff.cwd`.
+- `remove_worktree` — remove a verified clean linked worktree while retaining its local branch.
+- BranchMe does not change cwd, start Pi, copy `.env`, or remove branches automatically.
+
 ## Requirements
 
 - Run inside a Git repo with `git` available.
@@ -72,7 +80,7 @@ Width: 40
 │                                      │
 │                                      │
 ├──────────────────────────────────────┤
-│ 1/2 • status • current repository on…│
+│ 1/3 • status • current repository on…│
 ╰──────────────────────────────────────╯
 ```
 
@@ -86,7 +94,7 @@ Width: 80
 ├─────────────────────┬────────────────────────────────────────────────────────┤
 │▶  Status            │ STATUS                                                 │
 │   Workflow          │  Current branch:    feature/current                    │
-│                     │  GitHub repository: senad-d/branchme                   │
+│   Worktrees         │  GitHub repository: senad-d/branchme                   │
 │                     │  GitHub token:      present                            │
 │                     │                                                        │
 │                     │                                                        │
@@ -94,7 +102,7 @@ Width: 80
 │                     │                                                        │
 │                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 1/2 • status • current repository only • tools perform actions               │
+│ 1/3 • status • current repository only • tools perform actions               │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -107,16 +115,38 @@ Width: 80
 │ ↑↓ section • q quit • /branchme help                                         │
 ├─────────────────────┬────────────────────────────────────────────────────────┤
 │   Status            │ WORKFLOW                                               │
-│▶  Workflow          │  branch_status  -> inspect                             │
-│                     │  change_branch  -> existing local                      │
-│                     │  fetch_branch   -> upstream remote                     │
-│                     │  pull_branch    -> fast-forward                        │
-│                     │  rebase_branch  -> onto upstream                       │
-│                     │  create_branch  -> from HEAD                           │
-│                     │  push_branch    -> current branch                      │
-│                     │  pull_request   -> after push                          │
+│▶  Workflow          │  branch_status   -> inspect                            │
+│   Worktrees         │  change_branch   -> existing local                     │
+│                     │  fetch_branch    -> upstream remote                    │
+│                     │  pull_branch     -> fast-forward                       │
+│                     │  rebase_branch   -> onto upstream                      │
+│                     │  create_branch   -> from HEAD                          │
+│                     │  push_branch     -> current branch                     │
+│                     │  pull_request    -> after push                         │
+├─────────────────────┴────────────────────────────────────────────────────────┤
+│ 2/3 • workflow • inspect → change → fetch/pull/rebase → create → push → PR   │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Panel: Wide mode: Worktrees selected
+
+Width: 80
+
+```text
+╭ BranchMe ───────────────────────────────────────────────────────── Worktrees ╮
+│ ↑↓ section • q quit • /branchme help                                         │
+├─────────────────────┬────────────────────────────────────────────────────────┤
+│   Status            │ WORKTREES                                              │
+│   Workflow          │  list_worktrees  -> inspect inventory                  │
+│▶  Worktrees         │  create_worktree -> ready handoff.cwd                  │
+│                     │  remove_worktree -> clean linked; branch retained      │
+│                     │                                                        │
+│                     │                                                        │
+│                     │                                                        │
+│                     │                                                        │
+│                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 2/2 • workflow • inspect → change → fetch/pull/rebase → create → push → PR   │
+│ 3/3 • worktrees • create → handoff cwd → next session • remove retains branch│
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -130,7 +160,7 @@ Width: 112
 ├──────────────────────┬───────────────────────────────────────────────────────────────────────┤
 │▶  Status             │ STATUS                                                                │
 │   Workflow           │  Current branch:    main                                              │
-│                      │  GitHub repository: senad-d/BranchMe                                  │
+│   Worktrees          │  GitHub repository: senad-d/BranchMe                                  │
 │                      │  GitHub token:      not set                                           │
 │                      │                                                                       │
 │                      │                                                                       │
@@ -138,7 +168,7 @@ Width: 112
 │                      │                                                                       │
 │                      │                                                                       │
 ├──────────────────────┴───────────────────────────────────────────────────────────────────────┤
-│ 1/2 • status • current repository only • tools perform actions                               │
+│ 1/3 • status • current repository only • tools perform actions                               │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -161,7 +191,7 @@ Width: 50
 │                                                │
 │                                                │
 ├────────────────────────────────────────────────┤
-│ 1/2 • warning • Unable to resolve a GitHub rep…│
+│ 1/3 • warning • Unable to resolve a GitHub rep…│
 ╰────────────────────────────────────────────────╯
 ```
 
@@ -175,7 +205,7 @@ Width: 80
 ├─────────────────────┬────────────────────────────────────────────────────────┤
 │▶  Status            │ STATUS                                                 │
 │   Workflow          │  Current branch:    main                               │
-│                     │  GitHub repository: warning: Repository boundary misma…│
+│   Worktrees         │  GitHub repository: warning: Repository boundary misma…│
 │                     │  GitHub token:      present                            │
 │                     │                                                        │
 │                     │                                                        │
@@ -183,7 +213,7 @@ Width: 80
 │                     │                                                        │
 │                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 1/2 • warning • Repository boundary mismatch: local origin resolves to senad…│
+│ 1/3 • warning • Repository boundary mismatch: local origin resolves to senad…│
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -197,7 +227,7 @@ Width: 72
 ├───────────────────┬──────────────────────────────────────────────────┤
 │▶  Status          │ STATUS                                           │
 │   Workflow        │  Current branch:    main                         │
-│                   │  GitHub repository: senad-d/branchme             │
+│   Worktrees       │  GitHub repository: senad-d/branchme             │
 │                   │  GitHub token:      warning: Unable to read .env…│
 │                   │                                                  │
 │                   │                                                  │
@@ -205,7 +235,7 @@ Width: 72
 │                   │                                                  │
 │                   │                                                  │
 ├───────────────────┴──────────────────────────────────────────────────┤
-│ 1/2 • warning • Unable to read .env file for GitHub token fallback: …│
+│ 1/3 • warning • Unable to read .env file for GitHub token fallback: …│
 ╰──────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -219,7 +249,7 @@ Width: 72
 ├───────────────────┬──────────────────────────────────────────────────┤
 │▶  Status          │ STATUS                                           │
 │   Workflow        │  Current branch:    feature/super-long-branch-na…│
-│                   │  GitHub repository: very-long-owner-name/very-lo…│
+│   Worktrees       │  GitHub repository: very-long-owner-name/very-lo…│
 │                   │  GitHub token:      present                      │
 │                   │                                                  │
 │                   │                                                  │
@@ -227,6 +257,6 @@ Width: 72
 │                   │                                                  │
 │                   │                                                  │
 ├───────────────────┴──────────────────────────────────────────────────┤
-│ 1/2 • warning • This deliberately long status note is captured to de…│
+│ 1/3 • warning • This deliberately long status note is captured to de…│
 ╰──────────────────────────────────────────────────────────────────────╯
 ```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
-  "description": "Minimal Pi extension for current-repository git branch, push, and pull request workflows.",
+  "description": "Pi extension for verified current-repository Git branch, worktree, push, and pull request workflows.",
   "license": "MIT",
   "author": "Senad Dizdarević <112484166+senad-d@users.noreply.github.com>",
   "repository": {
@@ -21,6 +21,7 @@
     "branchme",
     "git",
     "git-branch",
+    "git-worktree",
     "git-workflow",
     "github",
     "github-pr",
@@ -52,10 +53,11 @@
     "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info test/*.test.mjs",
     "smoke:pi": "node scripts/smoke-pi-runtime.mjs && node scripts/smoke-pi-git-context.mjs",
     "smoke:pi:packed": "node scripts/smoke-pi-installed-package.mjs",
-    "check": "node --check scripts/check-format.mjs && node --check scripts/check-package-contents.mjs && node --check scripts/publish-npm.mjs && node --check scripts/smoke-pi-git-context.mjs && node --check scripts/smoke-pi-installed-package.mjs && node --check scripts/smoke-pi-runtime.mjs",
+    "smoke:worktree-handoff": "node scripts/smoke-worktree-handoff.mjs",
+    "check": "node --check scripts/check-format.mjs && node --check scripts/check-package-contents.mjs && node --check scripts/publish-npm.mjs && node --check scripts/smoke-pi-git-context.mjs && node --check scripts/smoke-pi-installed-package.mjs && node --check scripts/smoke-pi-runtime.mjs && node --check scripts/smoke-worktree-handoff.mjs",
     "pack:dry-run": "npm pack --dry-run --json",
     "check:pack": "node scripts/check-package-contents.mjs",
-    "validate": "npm run typecheck && npm run format:check && npm run test && npm run smoke:pi && npm run check && npm run check:pack",
+    "validate": "npm run typecheck && npm run format:check && npm run test && npm run smoke:pi && npm run check && npm run check:pack && npm run smoke:worktree-handoff",
     "release:check": "npm run validate && npm run smoke:pi:packed"
   },
   "pi": {
@@ -65,13 +67,15 @@
     "image": "https://raw.githubusercontent.com/senad-d/BranchMe/main/img/demo.gif"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.80.2",
+    "@earendil-works/pi-tui": "^0.84.1",
     "@types/node": "^26.0.1",
     "typebox": "^1.2.18",
     "typescript": "^7.0.2"

package/src/commands/branchme-command.ts

@@ -25,7 +25,7 @@ export function getBranchMeHelpText(): string {
   return [
     "# BranchMe",
     "",
-    "Current-repository branch workflow tools for Pi.",
+    "Current-repository Git workflow tools for Pi.",
     "",
     "Commands only show info; BranchMe tools perform actions.",
     "",
@@ -40,6 +40,14 @@ export function getBranchMeHelpText(): string {
     "7. `push_branch` — push the current branch.",
     "8. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.",
     "",
+    "## Worktree handoff",
+    "",
+    "- `list_worktrees` — inspect the main and linked worktrees in the current repository.",
+    "- `create_worktree` — create a linked worktree and return a ready handoff with an absolute `handoff.cwd`.",
+    "- A separate orchestrator starts the next Pi session or subagent in `handoff.cwd`.",
+    "- `remove_worktree` — remove a verified clean linked worktree while retaining its local branch.",
+    "- BranchMe does not change cwd, start Pi, copy `.env`, or remove branches automatically.",
+    "",
     "## Requirements",
     "",
     "- Run inside a Git repo with `git` available.",

package/src/constants.ts

@@ -9,6 +9,9 @@ export const PULL_BRANCH_TOOL_NAME = "pull_branch";
 export const REBASE_BRANCH_TOOL_NAME = "rebase_branch";
 export const PUSH_BRANCH_TOOL_NAME = "push_branch";
 export const PULL_REQUEST_TOOL_NAME = "pull_request";
+export const LIST_WORKTREES_TOOL_NAME = "list_worktrees";
+export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
+export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
 export const PULL_REQUEST_AUTOFILL_ENV_NAME = "BRANCHME_PR_AUTOFILL";
 
 export const BRANCHME_TOOL_NAMES = [
@@ -20,6 +23,9 @@ export const BRANCHME_TOOL_NAMES = [
   REBASE_BRANCH_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
+  LIST_WORKTREES_TOOL_NAME,
+  CREATE_WORKTREE_TOOL_NAME,
+  REMOVE_WORKTREE_TOOL_NAME,
 ] as const;
 
 export const GIT_STATUS_TIMEOUT_MS = 5_000;
@@ -28,6 +34,7 @@ export const GIT_FETCH_TIMEOUT_MS = 120_000;
 export const GIT_PULL_TIMEOUT_MS = 120_000;
 export const GIT_REBASE_TIMEOUT_MS = 120_000;
 export const GIT_PUSH_TIMEOUT_MS = 120_000;
+export const GIT_WORKTREE_MUTATION_TIMEOUT_MS = 120_000;
 export const GITHUB_RELATED_PR_TIMEOUT_MS = 4_000;
 
 export const GIT_CONTEXT_RECENT_COMMIT_LIMIT = 5;
@@ -36,6 +43,11 @@ export const GIT_CONTEXT_VALUE_LIMIT_CHARS = 512;
 export const GIT_CONTEXT_SUMMARY_LIMIT_CHARS = 4_000;
 export const PULL_REQUEST_AUTOFILL_COMMIT_LIMIT = 20;
 export const PULL_REQUEST_AUTOFILL_SUBJECT_LIMIT_CHARS = 256;
+export const GIT_WORKTREE_RAW_OUTPUT_LIMIT_BYTES = 128 * 1024;
+export const GIT_WORKTREE_ENTRY_LIMIT = 100;
+export const GIT_WORKTREE_PATH_LIMIT_CHARS = 4_096;
+export const GIT_WORKTREE_REASON_LIMIT_CHARS = 512;
+export const GIT_WORKTREE_SUMMARY_LIMIT_CHARS = 4_000;
 
 export const GITHUB_API_BASE_URL = "https://api.github.com";
 export const GITHUB_API_VERSION = "2022-11-28";