@senad-d/branchme 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -3,8 +3,8 @@
 ## 0.1.0 - Unreleased
 
 - Implemented the `branchme` informational slash command with help aliases.
-- Added strict BranchMe tools: `branch_status`, `change_branch`, `pull_branch`, `create_branch`, `push_branch`, and `pull_request`.
-- Added argv-style git helpers for repository status, branch validation/creation/switching, clean-worktree preflight, upstream detection, fast-forward-only current-branch pull, and current-branch push/publish.
+- Added strict BranchMe tools: `branch_status`, `change_branch`, `fetch_branch`, `pull_branch`, `rebase_branch`, `create_branch`, `push_branch`, and `pull_request`.
+- Added argv-style git helpers for repository status, branch validation/creation/switching, clean-worktree preflight, upstream detection, configured-upstream fetch, fast-forward-only current-branch pull, current-branch rebase with automatic abort on failure, and current-branch push/publish.
 - Added GitHub repository resolution, environment-token and local `.env` token fallback handling, REST pull request creation, response validation, and token redaction.
 - Added bounded automatic Git context before each agent run with branch/upstream state, working-tree counts and unstaged paths, authenticated related-open-PR lookup, and recent commits.
 - Expanded `branch_status` into a shared, explicit, read-only context refresh for state that may change during a run.

package/README.md

@@ -11,12 +11,12 @@
 
 <p align="center">
   Current-repository branch and pull request tools for <a href="https://pi.dev">pi</a>.
-  <br />Inspect branch state, switch/create/update branches, push, and open GitHub PRs from pi prompts.
+  <br />Inspect branch state, fetch, switch/create/pull/rebase branches, push, and open GitHub PRs from pi prompts.
 </p>
 
 ---
 
-BranchMe is a Pi extension for safe branch workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and six agent-callable tools that explicitly refresh state, switch to an existing local branch, fast-forward the clean current branch from its upstream, create a branch from the current `HEAD`, push the current branch, and create a GitHub pull request.
+BranchMe is a Pi extension for safe branch workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and eight agent-callable tools that explicitly refresh state, switch to an existing local branch, fetch its configured upstream remote, fast-forward or rebase the clean current branch onto its upstream, create a branch from the current `HEAD`, push the current branch, and create a GitHub pull request.
 
 <table align="center">
   <tr>
@@ -30,12 +30,13 @@ BranchMe is a Pi extension for safe branch workflow automation. Before each agen
 </table>
 
 - **Context-aware:** every agent run starts with bounded branch, working-tree, related-PR, and recent-commit metadata; repository metadata is untrusted data, not instructions.
-- **Current-repository only:** Git and GitHub operations are scoped to the checkout where pi is running; `pull_branch` updates only the clean current branch from its configured upstream.
-- **Commit-safe:** context collection is read-only, and BranchMe never stages files, creates commits, generates commit messages, rebases, creates merge commits, resets, or edits files directly.
+- **Current-repository only:** Git and GitHub operations are scoped to the checkout where pi is running; fetch, pull, and rebase resolve the current branch's configured upstream.
+- **Explicit history rewrites:** `rebase_branch` runs only when explicitly requested, requires a clean current branch with an upstream, disables autostash and multi-ref updates, and automatically attempts to abort on failure.
+- **Commit-safe:** context collection is read-only, and BranchMe never stages files, creates user-authored commits, generates commit messages, force-pushes, creates merge commits, resets, or edits files directly.
 - **Strict tools:** tool schemas reject extra properties such as `force`, `stash`, `discard`, `owner`, `repo`, `path`, or `baseRef`.
 - **PR-ready:** create GitHub pull requests from existing local branches after verifying the `headBranch` matches GitHub and the base is visible, with explicit PR fields and `GITHUB_TOKEN` or `GH_TOKEN` from the process environment or a local `.env` fallback.
 
-> **Security:** pi packages run with your full system permissions. BranchMe runs local `git` commands, may make an automatic authenticated GitHub request to find a related open pull request, can switch/create branches and push the current branch, and can create GitHub pull requests. Read [`SECURITY.md`](SECURITY.md).
+> **Security:** pi packages run with your full system permissions. BranchMe runs local `git` commands, may make an automatic authenticated GitHub request to find a related open pull request, can fetch remotes, switch/create/pull/rebase branches, push the current branch, and create GitHub pull requests. Read [`SECURITY.md`](SECURITY.md).
 
 ## Table of Contents
 
@@ -88,7 +89,9 @@ A typical BranchMe flow is:
 7. Push the current branch with `push_branch`.
 8. After `push_branch` completes and GitHub can see the branches, create a pull request with `pull_request`.
 
-BranchMe is tool-based. The slash command is informational only and never changes or updates branches, pushes, commits, stages, edits files, or opens pull requests.
+To refresh the current branch's configured remote-tracking ref without changing the local branch or working tree, use `fetch_branch`. To reconcile the clean current branch by rewriting its local commits, run `fetch_branch`, wait for it to complete, and then run `rebase_branch`. Both tools require a configured upstream; `rebase_branch` automatically attempts `git rebase --abort` if rebasing fails.
+
+BranchMe is tool-based. The slash command is informational only and never changes or updates branches, fetches, rebases, pushes, commits, stages, edits files, or opens pull requests.
 
 ---
 
@@ -158,7 +161,7 @@ $EDITOR .env
 pi
 ```
 
-`pull_branch` and `push_branch` use your normal Git remote credentials. BranchMe does not inject `GITHUB_TOKEN` into `git pull` or `git push`.
+`fetch_branch`, `pull_branch`, and `push_branch` use your normal Git remote credentials. BranchMe does not inject `GITHUB_TOKEN` into `git fetch`, `git pull`, or `git push`. `rebase_branch` operates on the locally available configured upstream ref and makes no network request itself.
 When the current branch already has an upstream, BranchMe pushes an explicit `HEAD:<upstream-branch-ref>` refspec to the configured upstream remote instead of relying on a bare `git push`.
 Run `pull_request` only after `push_branch` has completed; `pull_request` preflights the GitHub `headBranch` and `baseBranch` before creating the PR and fails with retry guidance if a branch is not visible yet or the GitHub `headBranch` commit does not match the local branch.
 
@@ -199,12 +202,14 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | --- | --- | --- |
 | `branch_status` | `{}` | Explicitly refreshes the same bounded context used at agent start: repo root in structured details, branch/detached state, upstream and ahead/behind counts, working-tree counts and unstaged/untracked paths, related open PR, and recent commits. It is read-only. |
 | `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects dirty worktrees, and runs `git switch <branchName>`. |
+| `fetch_branch` | `{}` | Requires a current branch with a configured upstream and runs `git fetch --no-tags --no-recurse-submodules <upstream-remote> <upstream-branch-ref>:<remote-tracking-ref>`; only that tracking ref is refreshed without changing local branches or working-tree files. |
 | `pull_branch` | `{}` | Requires a clean current branch with a configured upstream and runs `git pull --ff-only --no-rebase --no-autostash <upstream-remote> <upstream-branch-ref>`; divergence fails without rebasing or creating a merge commit. |
+| `rebase_branch` | `{}` | Requires a clean current branch with a configured upstream and runs `git rebase --no-autostash --no-update-refs <upstream>`; it rewrites local commits and automatically attempts `git rebase --abort` on failure. |
 | `create_branch` | `{ "branchName": string }` | Validates `branchName`, rejects existing local branches, and runs `git switch -c <branchName>` from current `HEAD`. |
 | `push_branch` | `{}` | Pushes the current branch to its configured upstream remote with an explicit `HEAD:<upstream-branch-ref>` refspec, or publishes it with `git push --set-upstream origin <currentBranch>` when no upstream exists. |
 | `pull_request` | `{ "headBranch": string, "baseBranch": string, "title": string, "body": string, "draft": boolean }` | Preflights GitHub branch visibility and verifies the GitHub `headBranch` commit matches the local branch, then creates a pull request in the resolved current repository via `POST /repos/{owner}/{repo}/pulls`; branch refs must exist locally and cannot use `owner:branch`. |
 
-All schemas reject additional properties. `change_branch` never accepts `baseRef`, `force`, `stash`, `discard`, `create`, `owner`, `repo`, or path inputs. `pull_branch` has a strict empty schema and never accepts a branch, remote, force, or rebase option. `pull_request` never accepts `owner`, `repo`, or owner-prefixed branch refs; BranchMe resolves the repository from local `origin` and/or matching `GITHUB_REPOSITORY`.
+All schemas reject additional properties. `change_branch` never accepts `baseRef`, `force`, `stash`, `discard`, `create`, `owner`, `repo`, or path inputs. `fetch_branch`, `pull_branch`, and `rebase_branch` have strict empty schemas and never accept a branch, remote, refspec, force, autostash, or arbitrary rebase target. `pull_request` never accepts `owner`, `repo`, or owner-prefixed branch refs; BranchMe resolves the repository from local `origin` and/or matching `GITHUB_REPOSITORY`.
 
 ---
 
@@ -222,7 +227,7 @@ Before each agent run, BranchMe appends an **Automatic Git Context** snapshot to
 
 Collection defaults are a 5-second timeout per local Git command, a 4-second related-PR lookup timeout, at most 512 characters per metadata value, and at most 4,000 characters for the rendered snapshot. GitHub response bodies are limited to 64 KiB. The formatter can further shorten values or omit entries to stay within the total limit.
 
-The snapshot is fresh at agent start but is not live. A branch switch, pull, commit, file change, push, or other mutation later in the same run can make it stale. `branch_status` performs an explicit current-state refresh through the same shared collector and remains read-only; it does not mutate files, Git state, or GitHub state.
+The snapshot is fresh at agent start but is not live. A fetch, branch switch, pull, rebase, commit, file change, push, or other mutation later in the same run can make it stale. `branch_status` performs an explicit current-state refresh through the same shared collector and remains read-only; it does not mutate files, Git state, or GitHub state.
 
 Related-PR metadata does not come from Git alone. When repository, branch, and credentials resolve, automatic collection and explicit `branch_status` may make an authenticated `GET /repos/{owner}/{repo}/pulls?state=open&head={owner}:{branch}&per_page=1` request. Without a token there is no unauthenticated fallback or GitHub request; the PR field is reported as unavailable while local Git context remains usable.
 
@@ -233,6 +238,7 @@ Use BranchMe from pi prompts or automation that drives pi with explicit tool cal
 ```text
 Use branch_status.
 Switch to the base branch with change_branch, then use pull_branch after the switch completes.
+Fetch the current branch upstream with fetch_branch, wait for it to complete, then rebase with rebase_branch.
 Create branch feature/docs-refresh from the updated current HEAD with create_branch.
 Push the current branch with push_branch.
 After push_branch completes, create a draft pull request from feature/docs-refresh to main titled "Refresh docs" with this body: "...".
@@ -243,13 +249,15 @@ BranchMe operates only on the repository where pi is running:
 - Automatic collection and `branch_status` run bounded, read-only Git commands from the verified git root.
 - Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root.
 - `change_branch` switches only to existing local branches and has no `force`, `stash`, `discard`, remote, or path input.
+- `fetch_branch` requires a configured upstream, uses an explicit source-to-remote-tracking refspec with tags and submodule recursion disabled, and does not change local branches or working-tree files.
 - `pull_branch` requires a clean worktree and configured upstream, updates only the current branch with `git pull --ff-only --no-rebase --no-autostash`, and has no branch, remote, force, or rebase input.
+- `rebase_branch` requires a clean worktree and configured upstream, rewrites only the current branch onto the locally available upstream with autostash and multi-ref updates disabled, and automatically attempts to abort on failure.
 - `create_branch` creates from the current `HEAD` only and has no `baseRef` input.
 - `push_branch` pushes only the current branch, uses no bare upstream `git push`, and has no `branchName` input.
 - `pull_request` creates PRs only for the resolved current GitHub repository, requires `headBranch` and `baseBranch` to exist locally, requires the GitHub `headBranch` commit to match the local branch, queues behind in-flight same-repository git mutation windows when possible, and rejects `owner:branch` head refs.
 - If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
 
-BranchMe intentionally does **not** stage files, create commits, force checkout, stash changes, discard changes, edit files directly, or generate commit messages.
+BranchMe intentionally does **not** stage files, create user-authored commits, force checkout, stash changes, discard changes, force-push, create merge commits, edit files directly, or generate commit messages. Rebase-driven commit rewriting occurs only through explicit `rebase_branch` calls.
 
 ---
 
@@ -292,12 +300,13 @@ Ensure the token and Git credentials have permission for the branch and pull req
 | Problem | Try |
 | --- | --- |
 | Not a git repository | Start pi from inside a git checkout. |
-| Detached `HEAD` | Use `change_branch` to switch to an existing local branch, or checkout a branch before `pull_branch`, `create_branch`, or `push_branch`. |
+| Detached `HEAD` | Use `change_branch` to switch to an existing local branch, or checkout a branch before `fetch_branch`, `pull_branch`, `rebase_branch`, `create_branch`, or `push_branch`. |
 | Branch already exists | Choose a new local branch name for `create_branch`, or use `change_branch` to switch to it. |
 | Branch does not exist locally | Create a local branch first; `change_branch` does not checkout remote branches. |
-| Dirty worktree before branch switch or pull | Commit, stash, or discard changes outside BranchMe before using `change_branch` or `pull_branch`. |
-| Pull has no upstream | Configure the current branch upstream outside BranchMe, then retry `pull_branch`. |
-| Pull is not a fast-forward | Reconcile the divergent branch outside BranchMe; `pull_branch` never rebases, force-updates, or creates a merge commit. |
+| Dirty worktree before branch switch, pull, or rebase | Commit, stash, or discard changes outside BranchMe before using `change_branch`, `pull_branch`, or `rebase_branch`. |
+| Fetch, pull, or rebase has no upstream | Configure the current branch upstream outside BranchMe, then retry the tool. |
+| Pull is not a fast-forward | Run `fetch_branch`, wait for it to complete, then explicitly run `rebase_branch` if rewriting local commits is intended; otherwise reconcile outside BranchMe. |
+| Rebase fails or conflicts | `rebase_branch` automatically attempts `git rebase --abort`. Inspect repository state before continuing if automatic cleanup also fails. |
 | Push fails | Confirm the current branch is correct and your normal Git remote credentials can push. |
 | Related PR is unavailable | Set `GITHUB_TOKEN` or `GH_TOKEN` before starting pi if related-PR context is wanted. Without a token, BranchMe keeps local context and intentionally makes no unauthenticated GitHub request. |
 | PR auth fails | Set `GITHUB_TOKEN` or `GH_TOKEN` before starting pi, or copy `.env.example` to `.env` and fill in one token. |
@@ -319,7 +328,7 @@ npm run check:pack
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 ```
 
-Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, unit tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all six BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
+Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, unit tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all eight BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
 
 Refresh TUI captures intentionally with:
 

package/SECURITY.md

@@ -17,16 +17,18 @@ Implemented git mutations are limited to:
 
 - `change_branch`: `git switch <branchName>` after branch-name validation, local `refs/heads/<branchName>` verification, and clean-worktree preflight.
 - `create_branch`: `git switch -c <branchName>` from current `HEAD` after branch-name validation and existing-branch checks.
+- `fetch_branch`: `git fetch --no-tags --no-recurse-submodules <upstreamRemote> <upstreamBranchRef>:<remoteTrackingRef>` after validating the current branch's configured upstream target. The explicit destination is limited to that upstream's remote-tracking ref, so local branches and working-tree files are not changed.
 - `pull_branch`: `git pull --ff-only --no-rebase --no-autostash <upstreamRemote> <upstreamBranchRef>` for the clean current branch after validating its configured upstream target.
+- `rebase_branch`: `git rebase --no-autostash --no-update-refs <upstream>` for the clean current branch after validating its configured upstream target. It rewrites local commits and automatically attempts `git rebase --abort` without the cancelled caller signal if the rebase fails or is killed.
 - `push_branch`: `git push <upstreamRemote> HEAD:<upstreamBranchRef>` for the current branch when an upstream exists, or `git push --set-upstream origin <currentBranch>` when no upstream exists.
 
-Before each agent run, BranchMe also runs bounded, read-only Git commands to collect branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged or untracked path entries, and up to 5 recent commits. The same collector runs when `branch_status` explicitly refreshes context. Collection does not run `switch`, `push`, `add`, `commit`, or any other mutation, and it never reads diffs or file contents.
+Before each agent run, BranchMe also runs bounded, read-only Git commands to collect branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged or untracked path entries, and up to 5 recent commits. The same collector runs when `branch_status` explicitly refreshes context. Collection does not run `fetch`, `switch`, `pull`, `rebase`, `push`, `add`, `commit`, or any other mutation, and it never reads diffs or file contents.
 
-Branch switching and fast-forward pulls can update working-tree files as normal Git behavior. Mutating branch operations for the same repository are serialized to avoid same-turn branch races. `pull_request` also uses the same repository queue around PR preflight and creation so it can wait behind an already-started same-repository mutation. BranchMe rejects dirty worktrees before `change_branch` and `pull_branch`. It does not force checkout, stash, stage files, create commits, reset, rebase, create merge commits, or edit files directly.
+Branch switching, fast-forward pulls, and successful rebases can update working-tree files as normal Git behavior; fetch updates one validated remote-tracking ref without changing local branches or the working tree. Mutating branch operations for the same repository are serialized to avoid same-turn branch races. `pull_request` also uses the same repository queue around PR preflight and creation so it can wait behind an already-started same-repository mutation. BranchMe rejects dirty worktrees before `change_branch`, `pull_branch`, and `rebase_branch`. It does not force checkout, stash, stage files, create user-authored commits, reset, force-push, create merge commits, or edit files directly. Rebase-driven commit rewriting occurs only through an explicit `rebase_branch` call.
 
 ## Network behavior
 
-`pull_branch` and `push_branch` contact the configured Git remote through the user's normal Git transport and credentials. They do not use or inject `GITHUB_TOKEN` or `GH_TOKEN`.
+`fetch_branch`, `pull_branch`, and `push_branch` contact the configured Git remote through the user's normal Git transport and credentials. They do not use or inject `GITHUB_TOKEN` or `GH_TOKEN`. `rebase_branch` uses the locally available upstream ref and makes no network request.
 
 BranchMe's GitHub helpers use these REST API requests:
 
@@ -48,14 +50,16 @@ BranchMe operates on the current repository only.
 - The GitHub repository is inferred from local `origin` and/or `GITHUB_REPOSITORY`.
 - Tool inputs never accept filesystem paths, `owner`, `repo`, or owner-prefixed `owner:branch` PR refs.
 - `change_branch` accepts only `branchName` and never creates branches, checks out remote branches, forces, stashes, or discards changes.
+- `fetch_branch` accepts no parameters, resolves the current branch's configured upstream remote and branch, constructs a source-to-remote-tracking refspec internally, disables tag fetching and submodule recursion, and does not prune or accept arbitrary refspecs.
 - `pull_branch` accepts no parameters, updates only the clean current branch from its configured upstream, and uses fast-forward-only semantics.
+- `rebase_branch` accepts no parameters, rebases only the clean current branch onto its configured upstream, disables autostash and multi-ref updates, never pushes, and attempts to abort on failure.
 - If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, PR creation and related-PR lookup fail closed.
 - PR branch inputs are validated as existing local branch-name refs; missing local branches and cross-repository `head` values are rejected before token lookup or any GitHub request.
 - PR branch inputs must also be visible on GitHub before the PR is created, and `headBranch` must match the local branch commit; unpublished or stale `headBranch` values fail with guidance to run `push_branch`, wait for it to complete, and retry `pull_request`.
 
 ## Credentials
 
-Git pull and push authentication is handled by the user's configured Git credential and transport setup. BranchMe never passes GitHub API tokens to Git commands.
+Git fetch, pull, and push authentication is handled by the user's configured Git credential and transport setup. BranchMe never passes GitHub API tokens to Git commands.
 
 `pull_request` and related-PR lookup check `process.env.GITHUB_TOKEN`, then `process.env.GH_TOKEN`. If neither process token is set, BranchMe reads a local `.env` file from the verified git root and checks:
 

package/docs/SMOKE_TEST.md

@@ -18,7 +18,7 @@ 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`, `pull_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`, `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.
 - 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 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.
@@ -32,7 +32,7 @@ pi --no-extensions -e .
 ## Result
 
 - `npm run validate` passed.
-- `npm run smoke:pi` loaded BranchMe through Pi, verified all six BranchMe tools through the real `pi.getAllTools()` runtime surface, and confirmed non-mutating BranchMe command output.
+- `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.
 - 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`.

package/docs/STRUCTURE.md

@@ -1,6 +1,6 @@
 # BranchMe Structure Guide
 
-BranchMe is a TypeScript Pi extension package for current-repository git branch update, push, and GitHub pull request workflows.
+BranchMe is a TypeScript Pi extension package for current-repository git branch fetch/update/rebase, push, and GitHub pull request workflows.
 
 ## Source layout
 
@@ -13,7 +13,7 @@ src/
 ├── commands/
 │   └── branchme-command.ts       # /branchme status/help command; informational only
 ├── tools/
-│   └── branchme-tools.ts         # branch_status/change_branch/pull_branch/create_branch/push_branch/pull_request registration
+│   └── branchme-tools.ts         # registration for eight branch/GitHub workflow tools
 ├── git.ts                        # argv-style git helpers and per-repo workflow queue
 ├── github.ts                     # GitHub repo resolution, env/.env tokens, branch preflight, REST calls, redaction
 └── ui/
@@ -22,11 +22,11 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, six tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, eight 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, branch validation, branch creation, existing-local-branch switching, clean-worktree preflight, fast-forward-only current-branch pull, current-branch push/publish, and the per-repository workflow queue.
+5. `src/git.ts` owns current-repository git behavior: root detection, branch/upstream/ahead-behind inspection, working-tree parsing, recent-commit collection, 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.
 6. `src/github.ts` owns GitHub `owner/repo` parsing, repository boundary checks, `GITHUB_TOKEN`/`GH_TOKEN` process-env and hardened git-root `.env` fallback 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,7 +36,7 @@ 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 update, push, and PR actions. There is no context command or seventh tool.
+- 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`.
 - 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.
@@ -51,12 +51,14 @@ src/
 - Related-PR lookup may issue an authenticated `GET /pulls` before every agent run and on explicit refresh. It has a 4-second timeout and 64 KiB response limit, and makes no unauthenticated fallback request.
 - The start-of-run snapshot may be stale after a mutation in that same run; `branch_status` is the explicit read-only refresh.
 - `change_branch` mutates local HEAD and working-tree files only through `git switch <branchName>` for existing local branches after a clean-worktree preflight.
+- `fetch_branch` requires a configured upstream and runs `git fetch --no-tags --no-recurse-submodules <remote> <remote-ref>:<remote-tracking-ref>`; its explicit refspec updates only that tracking ref without changing local branches or working-tree files.
 - `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`.
 - `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 `headBranch` and `baseBranch` to 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 missing, owner-prefixed, or unsafe branch refs before token lookup or the request.
 - `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 does not force checkout, stash, stage, commit, rebase, create merge commits, directly edit files, read non-token `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry.
+- BranchMe does not force checkout, stash, stage, create user-authored commits, reset, force-push, create merge commits, directly edit files, read non-token `.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.
 
 ## Documentation
 

package/docs/TUI_CAPTURE.md

@@ -23,19 +23,22 @@ Commands only show info; BranchMe tools perform actions.
 ## Workflow
 
 1. `branch_status` — inspect repo and branch state.
-2. `change_branch` — switch to the clean local base branch.
-3. `pull_branch` — fast-forward the current branch from its configured upstream.
-4. `create_branch` — create a new branch from the updated `HEAD`.
-5. Commit outside BranchMe.
-6. `push_branch` — push the current branch.
-7. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.
+2. `change_branch` — switch to a clean existing local branch.
+3. `fetch_branch` — fetch its configured upstream remote without changing local files.
+4. `pull_branch` — fast-forward from upstream, or `rebase_branch` — rebase local commits onto upstream.
+5. `create_branch` — create a new branch from the updated `HEAD`.
+6. Commit outside BranchMe.
+7. `push_branch` — push the current branch.
+8. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.
 
 ## Requirements
 
 - Run inside a Git repo with `git` available.
 - For PRs: GitHub `origin` and `GITHUB_TOKEN` or `GH_TOKEN` (environment or `.env`).
-- `pull_branch` requires a clean working tree and configured upstream.
-- BranchMe never stages, commits, rebases, or creates merge commits.
+- `fetch_branch`, `pull_branch`, and `rebase_branch` require a configured upstream.
+- `pull_branch` and `rebase_branch` require a clean working tree.
+- `rebase_branch` rewrites local commits only when explicitly requested and auto-aborts on failure.
+- BranchMe never stages, creates user-authored commits, force-pushes, or creates merge commits.
 ```
 
 ## Panel: Tiny mode: clean branch with token
@@ -65,6 +68,8 @@ Width: 40
 │                                      │
 │                                      │
 │                                      │
+│                                      │
+│                                      │
 ├──────────────────────────────────────┤
 │ 1/2 • status • current repository on…│
 ╰──────────────────────────────────────╯
@@ -85,6 +90,8 @@ Width: 80
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
+│                     │                                                        │
+│                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
 │ 1/2 • status • current repository only • tools perform actions               │
 ╰──────────────────────────────────────────────────────────────────────────────╯
@@ -101,12 +108,14 @@ Width: 80
 │   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                          │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 2/2 • workflow • inspect → change → pull → create → push → PR                │
+│ 2/2 • workflow • inspect → change → fetch/pull/rebase → create → push → PR   │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -125,6 +134,8 @@ Width: 112
 │                      │                                                                       │
 │                      │                                                                       │
 │                      │                                                                       │
+│                      │                                                                       │
+│                      │                                                                       │
 ├──────────────────────┴───────────────────────────────────────────────────────────────────────┤
 │ 1/2 • status • current repository only • tools perform actions                               │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────╯
@@ -146,6 +157,8 @@ Width: 50
 │                                                │
 │                                                │
 │                                                │
+│                                                │
+│                                                │
 ├────────────────────────────────────────────────┤
 │ 1/2 • warning • Unable to resolve a GitHub rep…│
 ╰────────────────────────────────────────────────╯
@@ -166,6 +179,8 @@ Width: 80
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
+│                     │                                                        │
+│                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
 │ 1/2 • warning • Repository boundary mismatch: local origin resolves to senad…│
 ╰──────────────────────────────────────────────────────────────────────────────╯
@@ -186,6 +201,8 @@ Width: 72
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
+│                   │                                                  │
+│                   │                                                  │
 ├───────────────────┴──────────────────────────────────────────────────┤
 │ 1/2 • warning • Unable to read .env file for GitHub token fallback: …│
 ╰──────────────────────────────────────────────────────────────────────╯
@@ -206,6 +223,8 @@ Width: 72
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
+│                   │                                                  │
+│                   │                                                  │
 ├───────────────────┴──────────────────────────────────────────────────┤
 │ 1/2 • warning • This deliberately long status note is captured to de…│
 ╰──────────────────────────────────────────────────────────────────────╯

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "description": "Minimal Pi extension for current-repository git branch, push, and pull request workflows.",
   "license": "MIT",

package/src/commands/branchme-command.ts

@@ -32,19 +32,22 @@ export function getBranchMeHelpText(): string {
     "## Workflow",
     "",
     "1. `branch_status` — inspect repo and branch state.",
-    "2. `change_branch` — switch to the clean local base branch.",
-    "3. `pull_branch` — fast-forward the current branch from its configured upstream.",
-    "4. `create_branch` — create a new branch from the updated `HEAD`.",
-    "5. Commit outside BranchMe.",
-    "6. `push_branch` — push the current branch.",
-    "7. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.",
+    "2. `change_branch` — switch to a clean existing local branch.",
+    "3. `fetch_branch` — fetch its configured upstream remote without changing local files.",
+    "4. `pull_branch` — fast-forward from upstream, or `rebase_branch` — rebase local commits onto upstream.",
+    "5. `create_branch` — create a new branch from the updated `HEAD`.",
+    "6. Commit outside BranchMe.",
+    "7. `push_branch` — push the current branch.",
+    "8. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.",
     "",
     "## Requirements",
     "",
     "- Run inside a Git repo with `git` available.",
     "- For PRs: GitHub `origin` and `GITHUB_TOKEN` or `GH_TOKEN` (environment or `.env`).",
-    "- `pull_branch` requires a clean working tree and configured upstream.",
-    "- BranchMe never stages, commits, rebases, or creates merge commits.",
+    "- `fetch_branch`, `pull_branch`, and `rebase_branch` require a configured upstream.",
+    "- `pull_branch` and `rebase_branch` require a clean working tree.",
+    "- `rebase_branch` rewrites local commits only when explicitly requested and auto-aborts on failure.",
+    "- BranchMe never stages, creates user-authored commits, force-pushes, or creates merge commits.",
   ].join("\n");
 }
 

package/src/constants.ts

@@ -4,7 +4,9 @@ export const BRANCHME_COMMAND_NAME = "branchme";
 export const BRANCH_STATUS_TOOL_NAME = "branch_status";
 export const CREATE_BRANCH_TOOL_NAME = "create_branch";
 export const CHANGE_BRANCH_TOOL_NAME = "change_branch";
+export const FETCH_BRANCH_TOOL_NAME = "fetch_branch";
 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";
 
@@ -12,14 +14,18 @@ export const BRANCHME_TOOL_NAMES = [
   BRANCH_STATUS_TOOL_NAME,
   CREATE_BRANCH_TOOL_NAME,
   CHANGE_BRANCH_TOOL_NAME,
+  FETCH_BRANCH_TOOL_NAME,
   PULL_BRANCH_TOOL_NAME,
+  REBASE_BRANCH_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
 ] as const;
 
 export const GIT_STATUS_TIMEOUT_MS = 5_000;
 export const GIT_MUTATION_TIMEOUT_MS = 30_000;
+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 GITHUB_RELATED_PR_TIMEOUT_MS = 4_000;
 

package/src/git.ts

@@ -3,9 +3,11 @@ import {
   GIT_CONTEXT_CHANGE_LIMIT,
   GIT_CONTEXT_RECENT_COMMIT_LIMIT,
   GIT_CONTEXT_VALUE_LIMIT_CHARS,
+  GIT_FETCH_TIMEOUT_MS,
   GIT_MUTATION_TIMEOUT_MS,
   GIT_PULL_TIMEOUT_MS,
   GIT_PUSH_TIMEOUT_MS,
+  GIT_REBASE_TIMEOUT_MS,
   GIT_STATUS_TIMEOUT_MS,
   MAX_SUMMARY_OUTPUT_CHARS,
 } from "./constants.ts";
@@ -16,11 +18,13 @@ import type {
   ChangeBranchDetails,
   CreateBranchDetails,
   CurrentBranchInfo,
+  FetchBranchDetails,
   GitExecResult,
   GitFileChange,
   GitFileChangeSummary,
   PullBranchDetails,
   PushBranchDetails,
+  RebaseBranchDetails,
   RecentCommit,
   WorkingTreeDetails,
 } from "./types.ts";
@@ -199,7 +203,7 @@ interface PushTarget {
   args: string[];
 }
 
-type UpstreamOperation = "pull" | "push";
+type UpstreamOperation = "fetch" | "pull" | "push" | "rebase";
 
 function validateRemoteName(remote: string, operation: UpstreamOperation): void {
   if (!remote) throw new Error(`Unable to ${operation} current branch: upstream remote is missing.`);
@@ -241,6 +245,17 @@ async function getBranchConfigValue(
   return value || null;
 }
 
+function remoteTrackingRef(upstream: string, remote: string): string {
+  const prefix = `${remote}/`;
+  if (!upstream.startsWith(prefix)) {
+    throw new Error("Unable to fetch current branch: configured upstream does not match its remote.");
+  }
+
+  const trackingBranch = upstream.slice(prefix.length);
+  validateBranchNameInput(trackingBranch, "Upstream branch name");
+  return `refs/remotes/${upstream}`;
+}
+
 async function resolveConfiguredUpstreamTarget(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -700,6 +715,46 @@ export async function changeExistingLocalBranch(
   });
 }
 
+export async function fetchCurrentBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<FetchBranchDetails> {
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const rootCtx = { cwd: repoRoot };
+
+  return withRepositoryMutationQueue(repoRoot, async () => {
+    const currentBranch = await requireCurrentBranch(pi, rootCtx, signal);
+    const target = await resolveConfiguredUpstreamTarget(pi, rootCtx, currentBranch, "fetch", signal);
+    if (!target) {
+      throw new Error(`Unable to fetch current branch '${safeDetail(currentBranch)}': no upstream is configured.`);
+    }
+
+    const trackingRef = remoteTrackingRef(target.upstream, target.remote);
+    const refspec = `${target.remoteRef}:${trackingRef}`;
+    const result = await runGit(
+      pi,
+      rootCtx,
+      ["fetch", "--no-tags", "--no-recurse-submodules", target.remote, refspec],
+      {
+        signal,
+        timeout: GIT_FETCH_TIMEOUT_MS,
+      },
+    );
+
+    return {
+      repoRoot,
+      currentBranch: safeDetail(currentBranch),
+      upstream: safeDetail(target.upstream),
+      remote: safeDetail(target.remote),
+      remoteRef: safeDetail(target.remoteRef),
+      remoteTrackingRef: safeDetail(trackingRef),
+      refspec: safeDetail(refspec),
+      output: safeOutput(result.stdout || result.stderr),
+    };
+  });
+}
+
 export async function pullCurrentBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -735,6 +790,78 @@ export async function pullCurrentBranch(
   });
 }
 
+async function abortFailedRebase(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  failureMessage: string,
+): Promise<never> {
+  const abortArgs = ["rebase", "--abort"];
+  let abortResult: GitExecResult;
+  try {
+    abortResult = await runGit(pi, ctx, abortArgs, {
+      timeout: GIT_MUTATION_TIMEOUT_MS,
+      allowFailure: true,
+    });
+  } catch (error) {
+    const reason = safeOutput(error instanceof Error ? error.message : String(error)) || "git rebase --abort failed";
+    throw new Error(`${failureMessage}. Automatic rebase cleanup failed: ${reason}. Inspect the repository before continuing.`);
+  }
+
+  if (abortResult.code === 0) {
+    throw new Error(`${failureMessage}. Rebase was aborted and the current branch was restored.`);
+  }
+
+  const reason = safeOutput(abortResult.stderr || abortResult.stdout) || `exit code ${abortResult.code}`;
+  throw new Error(`${failureMessage}. Automatic git rebase --abort did not complete: ${reason}. Inspect the repository before continuing.`);
+}
+
+export async function rebaseCurrentBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<RebaseBranchDetails> {
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const rootCtx = { cwd: repoRoot };
+
+  return withRepositoryMutationQueue(repoRoot, async () => {
+    const currentBranch = await requireCurrentBranch(pi, rootCtx, signal);
+    if (await hasWorkingTreeChanges(pi, rootCtx, signal)) {
+      throw new Error("Working tree has uncommitted changes; clean it before rebasing the current branch.");
+    }
+
+    const target = await resolveConfiguredUpstreamTarget(pi, rootCtx, currentBranch, "rebase", signal);
+    if (!target) {
+      throw new Error(`Unable to rebase current branch '${safeDetail(currentBranch)}': no upstream is configured.`);
+    }
+
+    const args = ["rebase", "--no-autostash", "--no-update-refs", target.upstream];
+    let result: GitExecResult;
+    try {
+      result = await runGit(pi, rootCtx, args, {
+        signal,
+        timeout: GIT_REBASE_TIMEOUT_MS,
+        allowFailure: true,
+      });
+    } catch (error) {
+      const failureMessage = safeOutput(error instanceof Error ? error.message : String(error)) || "git rebase failed";
+      return abortFailedRebase(pi, rootCtx, failureMessage);
+    }
+
+    if (result.code !== 0) {
+      return abortFailedRebase(pi, rootCtx, formatGitFailure(args, result));
+    }
+
+    return {
+      repoRoot,
+      currentBranch: safeDetail(currentBranch),
+      upstream: safeDetail(target.upstream),
+      remote: safeDetail(target.remote),
+      remoteRef: safeDetail(target.remoteRef),
+      output: safeOutput(result.stdout || result.stderr),
+    };
+  });
+}
+
 export async function pushCurrentBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,

package/src/tools/branchme-tools.ts

@@ -4,18 +4,22 @@ import {
   BRANCH_STATUS_TOOL_NAME,
   CHANGE_BRANCH_TOOL_NAME,
   CREATE_BRANCH_TOOL_NAME,
+  FETCH_BRANCH_TOOL_NAME,
   PULL_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
+  REBASE_BRANCH_TOOL_NAME,
 } from "../constants.ts";
 import {
   changeExistingLocalBranch,
   createLocalBranch,
+  fetchCurrentBranch,
   getGitRoot,
   getLocalBranchCommit,
   localBranchExists,
   pullCurrentBranch,
   pushCurrentBranch,
+  rebaseCurrentBranch,
   validateBranchName,
   withRepositoryMutationQueue,
 } from "../git.ts";
@@ -199,6 +203,26 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  pi.registerTool({
+    name: FETCH_BRANCH_TOOL_NAME,
+    label: "Fetch Branch",
+    description: "fetch_branch fetches the current branch's configured upstream branch into its remote-tracking ref with an explicit git fetch --no-tags --no-recurse-submodules refspec. fetch_branch does not change local branches or working-tree files and never prunes, rebases, merges, stashes, stages, commits, or pushes.",
+    promptSnippet: "fetch_branch: fetch the current branch's configured upstream into its remote-tracking ref without changing local branches or files",
+    promptGuidelines: [
+      "Use fetch_branch only when the user explicitly wants to fetch the configured upstream branch for the current branch.",
+      "Use fetch_branch only on a current branch with an upstream; fetch_branch has no branchName, remote, tags, prune, force, or refspec parameters.",
+      "Call fetch_branch and wait for it to complete before rebase_branch when the user wants the latest upstream state; do not batch fetch_branch with rebase_branch.",
+    ],
+    parameters: EmptyParametersSchema,
+    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+      const details = await fetchCurrentBranch(pi, ctx, signal);
+      return {
+        content: [{ type: "text", text: `Fetched configured upstream remote ${details.remote} for current branch ${details.currentBranch}.` }],
+        details,
+      };
+    },
+  });
+
   pi.registerTool({
     name: PULL_BRANCH_TOOL_NAME,
     label: "Pull Branch",
@@ -219,6 +243,27 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  pi.registerTool({
+    name: REBASE_BRANCH_TOOL_NAME,
+    label: "Rebase Branch",
+    description: "rebase_branch rebases the clean current branch onto its configured upstream with git rebase --no-autostash --no-update-refs. rebase_branch rewrites local commits, never pushes or force-pushes, and automatically attempts git rebase --abort if the rebase fails.",
+    promptSnippet: "rebase_branch: rebase the clean current branch onto its configured upstream with automatic abort on failure",
+    promptGuidelines: [
+      "Use rebase_branch only when the user explicitly requests rebasing and accepts that rebase_branch rewrites local commit history.",
+      "Use rebase_branch only on a clean current branch with an upstream; rebase_branch has no branchName, base, remote, force, autostash, continue, or abort parameters.",
+      "Call fetch_branch and wait for it to complete before rebase_branch when the latest upstream state is required; do not batch rebase_branch with fetch_branch, change_branch, pull_branch, create_branch, push_branch, or pull_request.",
+      "If rebase_branch fails or conflicts, rebase_branch automatically attempts git rebase --abort and never leaves conflict resolution to another parallel tool call.",
+    ],
+    parameters: EmptyParametersSchema,
+    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+      const details = await rebaseCurrentBranch(pi, ctx, signal);
+      return {
+        content: [{ type: "text", text: `Rebased current branch ${details.currentBranch} onto ${details.upstream}.` }],
+        details,
+      };
+    },
+  });
+
   pi.registerTool({
     name: PUSH_BRANCH_TOOL_NAME,
     label: "Push Branch",

package/src/types.ts

@@ -87,6 +87,17 @@ export interface ChangeBranchDetails {
   hasChangesBeforeSwitch: false;
 }
 
+export interface FetchBranchDetails {
+  repoRoot: string;
+  currentBranch: string;
+  upstream: string;
+  remote: string;
+  remoteRef: string;
+  remoteTrackingRef: string;
+  refspec: string;
+  output: string;
+}
+
 export interface PullBranchDetails {
   repoRoot: string;
   currentBranch: string;
@@ -96,6 +107,15 @@ export interface PullBranchDetails {
   output: string;
 }
 
+export interface RebaseBranchDetails {
+  repoRoot: string;
+  currentBranch: string;
+  upstream: string;
+  remote: string;
+  remoteRef: string;
+  output: string;
+}
+
 export interface PushBranchDetails {
   repoRoot: string;
   currentBranch: string;

package/src/ui/branchme-panel.ts

@@ -29,8 +29,8 @@ export type BranchMePanelSection = "status" | "workflow";
 const NARROW_MIN_WIDTH = 24;
 const WIDE_MIN_WIDTH = 72;
 const MAX_PANEL_WIDTH = 96;
-const MAX_PANEL_HEIGHT = 14;
-const BODY_HEIGHT = 7;
+const MAX_PANEL_HEIGHT = 16;
+const BODY_HEIGHT = 9;
 const PANEL_SECTIONS: BranchMePanelSection[] = ["status", "workflow"];
 const ANSI_RESET = "\u001b[0m";
 
@@ -177,7 +177,7 @@ function sectionFooter(section: BranchMePanelSection, data: BranchMePanelData):
     case "status":
       return "status • current repository only • tools perform actions";
     case "workflow":
-      return "workflow • inspect → change → pull → create → push → PR";
+      return "workflow • inspect → change → fetch/pull/rebase → create → push → PR";
   }
 }
 
@@ -197,7 +197,9 @@ function sectionRows(section: BranchMePanelSection, data: BranchMePanelData): Pa
         heading("WORKFLOW"),
         workflowDetailRow("branch_status", "inspect"),
         workflowDetailRow("change_branch", "existing local"),
+        workflowDetailRow("fetch_branch", "upstream remote"),
         workflowDetailRow("pull_branch", "fast-forward"),
+        workflowDetailRow("rebase_branch", "onto upstream"),
         workflowDetailRow("create_branch", "from HEAD"),
         workflowDetailRow("push_branch", "current branch"),
         workflowDetailRow("pull_request", "after push"),