@senad-d/branchme 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,12 +1,16 @@
 # Changelog
 
-## 0.2.2 - Unreleased
+## 0.3.0 - Unreleased
+
+- Added `land_branch` for deterministic post-host-merge cleanup in one queued call: explicit cwd-independent Git routing from the primary repository root, targeted remote fetch and captured ancestry proof, force-free linked-worktree removal including ignored residue, expected-HEAD-leased local source deletion against the fetched remote target, and independent final target sync (`fetch-refspec`, `pull-ff`, `skipped-dirty`, or `noop`).
+- Landing refuses an unmerged source or a cwd inside the removal target, never switches branches or prunes, preserves dirty checkouts and remote branches, and supports absent-branch/worktree retries. Structured per-step receipts report redacted diagnostics, deleted ignored top-level paths, actual before/after refs, and ahead/behind counts; failed or unattempted sync is never reported as a fast-forward.
+- Added bare-origin real-Git landing regression tests for the parked-main/dirty-primary incident, clean and dirty target checkouts, unmerged and dirty-worktree refusals, cwd safety, idempotence, lease races, false-success command reporting, divergence, configuration-driven pruning, and redaction.
 
 - Allowed `branch_status` ancestry endpoints to be remote-tracking refs such as `origin/main` in addition to exact local branches; local branches take precedence and remote-tracking refs stay read-only comparison targets.
 - Added optional `remote`/`branch` parameters to `fetch_branch` for a targeted fetch of one exact remote branch into its remote-tracking ref (default remote `origin`; `remote` requires `branch`) without touching local branches, the working tree, or the current branch's upstream configuration; the no-argument behavior is unchanged.
 - Added an optional read-only `baseRef` parameter to `create_worktree` for `branchMode: "new"`, starting the new branch from an exact local branch, remote-tracking ref, or full commit regardless of the current checkout's branch, dirt, or staleness; the default from-`HEAD` behavior is unchanged.
 - Implemented the `branchme` informational slash command with help aliases.
-- Added thirteen strict BranchMe tools: `branch_status`, `change_branch`, `fetch_branch`, `pull_branch`, `rebase_branch`, `integrate_branch`, `retire_branch`, `create_branch`, `push_branch`, `pull_request`, `list_worktrees`, `create_worktree`, and `remove_worktree`; merge-continuation tools are intentionally absent.
+- Added fourteen strict BranchMe tools: `branch_status`, `change_branch`, `fetch_branch`, `pull_branch`, `rebase_branch`, `integrate_branch`, `retire_branch`, `land_branch`, `create_branch`, `push_branch`, `pull_request`, `list_worktrees`, `create_worktree`, and `remove_worktree`; merge-continuation tools are intentionally absent.
 - 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, verified local branch integration, current-branch push/publish, and bounded NUL-delimited worktree discovery.
 - Added `integrate_branch` for exact local source-to-target integration from a clean already-current target control worktree. It rejects branch-specific target merge options that could alter the fixed policy and supports already-integrated, fast-forward, verified normal merge-commit, and automatically aborted/restored conflict outcomes with before/after ref and ancestry proofs, while exposing no fetch, push, reset, merge-message, or continuation controls.
 - Added `retire_branch` for explicit deletion of one exact unoccupied local branch ref after full expected-`HEAD` matching and captured target-ancestry verification. It uses `git update-ref --no-deref -d` with an expected-old-value lease, requires explicit force authorization for unmerged history, leaves branch configuration and remote/remote-tracking refs untouched, and reports uncertain postconditions for manual inspection without reset rollback.

package/README.md

@@ -16,7 +16,7 @@
 
 ---
 
-BranchMe is a Pi extension for safe branch and worktree 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 thirteen agent-callable tools that refresh state, manage, integrate, and retire local branches, inspect/create/remove linked worktrees, push the current branch, and create GitHub pull requests.
+BranchMe is a Pi extension for safe branch and worktree 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 fourteen agent-callable tools that refresh state, manage, integrate, and retire local branches, inspect/create/remove linked worktrees, push the current branch, and create GitHub pull requests.
 
 <table align="center">
   <tr>
@@ -99,7 +99,9 @@ For isolated work, a specialized Git subagent can use the explicit worktree work
 5. After that session finishes, remove or preserve any staged, unstaged, untracked, unmerged, or ignored local files, then explicitly call `remove_worktree` if removal was requested. Removal retains the local branch.
 6. If the user separately asks to retire that retained branch, obtain its fresh exact `HEAD`, verify it against an exact local target, and call `retire_branch` only after worktree removal has completed.
 
-BranchMe does not change the active Pi process's cwd, start Pi or other processes, create sessions, copy `.env` or other ignored/untracked files, or automatically retire a branch when removing its worktree. For credentials needed by agents in linked worktrees, prefer process-level environment variables rather than copying repository-root secrets.
+After a pull request merges on the host, use [`land_branch`](#post-merge-cleanup-in-one-call) from the repository root instead of composing fetch/removal/retirement/sync calls. This explicitly authorized combined workflow deletes ignored worktree residue and retires the source branch; standalone `remove_worktree` continues to retain the branch and refuse ignored residue.
+
+BranchMe does not change the active Pi process's cwd, start Pi or other processes, create sessions, or copy `.env` or other ignored/untracked files. For credentials needed by agents in linked worktrees, prefer process-level environment variables rather than copying repository-root secrets.
 
 To refresh the current branch's configured remote-tracking ref without changing the local branch or working tree, use `fetch_branch` with no arguments. To refresh another remote-tracking ref — for example `origin/main` after a pull request merged on GitHub — call `fetch_branch` with `branch` (and optional `remote`, default `origin`); the targeted fetch never touches local branches, the working tree, or the current branch's upstream configuration. To reconcile the clean current branch by rewriting its local commits, run `fetch_branch`, wait for it to complete, and then run `rebase_branch`. The no-argument `fetch_branch` and `rebase_branch` require a configured upstream; `rebase_branch` automatically attempts `git rebase --abort` if rebasing fails.
 
@@ -229,6 +231,7 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | `create_worktree` | `{ "worktreePath": string, "branchName": string, "branchMode": "new" \| "existing", "baseRef"?: string }` | Creates and verifies a linked worktree at an explicitly approved absolute path. `new` creates a local branch from current `HEAD`, or from the optional read-only `baseRef` (an exact local branch, remote-tracking ref such as `origin/main`, or full commit) regardless of the current checkout's branch, dirt, or staleness; `existing` requires an existing local branch not checked out elsewhere and rejects `baseRef`. It returns a ready handoff with the exact canonical absolute cwd and local branch identity. |
 | `remove_worktree` | `{ "worktreePath": string }` | Force-free removal of an explicitly selected, verified clean linked worktree. It rejects the main/current, detached, locked, prunable/missing, dirty, ignored-file-containing, or foreign worktree and verifies that the local branch remains at the same commit. |
 | `retire_branch` | `{ "branchName": string, "expectedHead": string, "targetBranch": string, "force": boolean }` | Deletes only the exact unoccupied local branch ref when its direct ref matches the supplied full commit ID and its relationship to the exact local target has been verified. Unmerged retirement requires explicit `force: true`; remote and remote-tracking refs are untouched. |
+| `land_branch` | `{ "sourceBranch": string, "targetBranch": string, "remote"?: string, "worktreePath"?: string }` | Post-merge fetch, ancestry proof, linked-worktree removal including ignored residue, leased local source deletion, and independent fast-forward target sync. Default remote `origin`; omitted path finds the source's linked worktree. Returns per-step receipts. |
 | `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects dirty worktrees, and runs `git switch <branchName>`. |
 | `fetch_branch` | `{ "remote"?: string, "branch"?: string }` | With no arguments it 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>`. With `branch` (and optional `remote`, default `origin`; `remote` requires `branch`) it fetches that exact remote branch into `refs/remotes/<remote>/<branch>` instead. Either way only that tracking ref is refreshed without changing local branches, working-tree files, or upstream configuration. |
 | `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. |
@@ -344,6 +347,37 @@ The full details also distinguish requested input from verified before/after sta
 
 Ignored and untracked files—including a repository-root `.env`—are not copied into a new linked worktree. Prefer credentials inherited through the new agent process environment. Git documents support for multiple worktrees of a superproject containing submodules as incomplete; BranchMe adds no force-based submodule cleanup. There is no force, move, prune, repair, lock, unlock, detached, orphan, or remote-inference worktree behavior.
 
+### Post-merge cleanup in one call
+
+After the pull request **merged on the host**, run from the repository root:
+
+```json
+{
+  "sourceBranch": "docs/74-add-canonical-glossary-context",
+  "targetBranch": "main",
+  "remote": "origin",
+  "worktreePath": "/absolute/path/to/issue-74-worktree"
+}
+```
+
+`remote` defaults to `origin`. Omit `worktreePath` to find the linked worktree holding `sourceBranch`, if any. An explicit path can also select a worktree incorrectly parked on `targetBranch`; unrelated branches, primary/root checkouts, detached, locked, dirty, or foreign worktrees are not removed. Invocation from inside the removal directory (including a nested or symlinked cwd) is refused: **run from the repository root**. Other caller directories in the same repository are supported; every Git command has an explicit `-C` directory, and cleanup runs through the primary checkout without switching any branches.
+
+The tool fetches the exact remote target and requires the captured source tip to be its ancestor before cleanup. Squash/rebase merges that do not preserve ancestry are refused; there is no force escape hatch. Tracked/staged changes and non-ignored untracked files block removal. **Ignored `.env`, `.pi/`, `node_modules/`, `dist/`, and other ignored residue are deleted with the worktree**; preserve anything needed first. Only their top-level path entries, never contents, appear in `deletedIgnoredPaths`. Source retirement uses the captured expected-HEAD lease and the **remote-tracking target**, not local `HEAD` or a stale local target.
+
+Target sync is last, even when worktree removal or branch retirement is refused:
+
+| Mode | Behavior |
+| --- | --- |
+| `fetch-refspec` | Target is not checked out anywhere: non-forced `fetch <remote> refs/heads/<target>:refs/heads/<target>`. Git enforces fast-forward-only updates. |
+| `pull-ff` | Target is checked out clean: explicit `pull --ff-only --no-rebase --no-autostash <remote> refs/heads/<target>` in that worktree. |
+| `skipped-dirty` | Target checkout is dirty: leave it untouched and report its path and ahead/behind counts against the captured remote target. |
+| `noop` | Local target already equals the captured remote head; no sync mutation. |
+| `not-run` / `failed` | Initial safety/ancestry refusal or sync failure; a successful fast-forward is never inferred from Git's prose. |
+
+The structured result contains `repositoryRoot`, `remote`, `targetBranch`, `remoteTargetHead`, `sourceBranch`, `sourceHead`, `ancestry.isAncestor`, `worktree`, `branch`, `targetSync`, and ordered `steps`, plus a one-line summary. Worktree outcomes are `removed`/`absent`/`refused`; branch outcomes are `deleted`/`absent`/`refused`. Full target `before`/`after` IDs are read from the exact local ref in this call. Unknown/not-applicable identities and ancestry are `null`, not invented proofs. A second successful call reports absent cleanup and `noop` sync. An already-missing directory is reported absent without pruning a remaining registration; such occupancy can still block branch deletion.
+
+`land_branch` never stashes, resets, checks out/switches branches, force-updates, pushes, prunes, or deletes remote/tracking refs. It holds one process-local primary-root mutation queue; it cannot lock other Pi/external Git processes. Inspect each receipt outcome before declaring landing complete. Standalone `remove_worktree` and `retire_branch` retain their original contracts.
+
 ### Verified local branch retirement
 
 `retire_branch` is a separate, explicit lifecycle step after integration and any linked-worktree removal. It accepts exactly:
@@ -391,7 +425,7 @@ BranchMe operates only on the repository where pi is running:
 - `pull_request` creates PRs only for the resolved current GitHub repository, requires resolved `headBranch` and `baseBranch` values to be distinct and 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. Missing PR fields fail unless `BRANCHME_PR_AUTOFILL=true`.
 - If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
 
-BranchMe intentionally does **not** stage files, create user-authored commits, accept or generate commit messages, force checkout, stash changes, discard changes, force-push, reset, edit files directly, copy ignored/untracked files between worktrees, or delete branches during worktree removal. Rebase-driven rewriting occurs only through explicit `rebase_branch`; a Git-generated standard merge commit is possible only through explicit `integrate_branch` for divergent histories; one exact local ref can be deleted only through explicit `retire_branch` under the leased boundary above.
+BranchMe intentionally does **not** stage files, create user-authored commits, accept or generate commit messages, force checkout, stash changes, discard changes, force-push, reset, edit files directly, copy ignored/untracked files between worktrees, or delete branches during standalone `remove_worktree`. Rebase-driven rewriting occurs only through explicit `rebase_branch`; a Git-generated standard merge commit is possible only through explicit `integrate_branch` for divergent histories; one exact local ref can be deleted only through explicit `retire_branch` or merged-only `land_branch` under the leased boundaries above.
 
 ---
 
@@ -476,7 +510,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, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle 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 thirteen BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, and targeted `branch_status.ancestry`, with no merge-continuation tool. Runtime smoke inspects retirement registration and schema but never executes branch retirement. 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, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle 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 fourteen BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, and targeted `branch_status.ancestry`, with no merge-continuation tool. Runtime smoke inspects retirement and landing registration/schema but never executes either cleanup tool. 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

@@ -24,19 +24,20 @@ Implemented git mutations are limited to:
 - `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.
 - `create_worktree`: `git worktree add -b <branchName> <canonicalPath> HEAD` for a new local branch, or `git worktree add <canonicalPath> <existingLocalBranch>` for an existing unoccupied local branch, after destination and repository-boundary validation.
 - `remove_worktree`: `git worktree remove <verifiedCanonicalPath>` without force, only after fresh repository-membership, safety-state, path, tracked/untracked status, and ignored-entry checks. The local branch is retained and verified at the same commit.
+- `land_branch`: explicit post-host-merge targeted fetch, linked-worktree removal including ignored residue, leased source-local-ref deletion against the fetched remote target, and independent final target sync. Every Git command uses an explicit `-C` directory; unoccupied targets use a non-forced fetch refspec, clean occupied targets use an explicit ff-only pull, and dirty targets are left untouched. No remote mutation, prune, stash, reset, or branch switching is attempted.
 - `retire_branch`: `git update-ref --no-deref -d refs/heads/<branchName> <capturedRetiringHead>` only for one exact unoccupied direct local ref whose commit matches the required full `expectedHead`. The exact local target commit and ancestry are captured first; unmerged retirement requires explicit `force: true` authorization.
 
 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. An explicit optional `branch_status.ancestry` query captures exact local source/target commit IDs and uses `git merge-base --is-ancestor` against those commits; automatic Git context never runs this query and remains unchanged. Collection does not run `fetch`, `switch`, `pull`, `rebase`, `merge`, `push`, `add`, `commit`, or any other mutation, and it never reads diffs or file contents.
 
 Branch switching, worktree creation/removal, fast-forward pulls, successful rebases, and branch integration can update or remove filesystem content as normal Git behavior; fetch updates one validated remote-tracking ref without changing local branches or the working tree, and retirement deletes one verified local branch ref. Mutating operations for the same repository are serialized to avoid same-turn races. `integrate_branch` holds one queue window across preflight, merge, cleanup, and final verification; `retire_branch` holds one active-worktree-keyed window across preflight, immediate reinspection, leased deletion, and postcondition verification; `pull_request` uses the queue around PR preflight and creation. This in-memory queue is process-local: it coordinates BranchMe calls using the same active checkout but does not lock a different active worktree, another Pi process, or an external Git process. Integration refs are captured and re-verified. Retirement additionally uses an expected-old-value ref lease and rechecks its captured target and complete worktree occupancy. Unexpected or inconclusive movement produces a bounded uncertain error with manual inspection guidance and no reset-based rollback.
 
-BranchMe rejects a dirty control worktree before `change_branch`, `pull_branch`, `rebase_branch`, and `integrate_branch`, and rejects any staged, unstaged, untracked, unmerged, or ignored entry in a linked worktree before removal. Retirement does not require an unrelated active worktree to be clean, but every registered worktree record is inspected and any occupancy of the retiring branch blocks deletion. Integration also rejects an existing merge, rebase, cherry-pick, revert, or sequencer state and any non-empty target-branch `mergeOptions` setting that could alter the fixed command policy. After merge or retirement mutation begins, cleanup/postcondition inspection ignores caller cancellation and uses bounded timeouts. A `conflict` result is returned only after exact repository-relative conflict paths are captured, `git merge --abort` succeeds, source and target refs are restored, repository/control-worktree identity is preserved, operation state is cleared, and the control worktree is clean. Failed non-conflict merges remain errors; inconclusive cleanup or verification is never reported as success. After retirement is attempted, contradictory or inconclusive repository, target-ref, retiring-ref, or occupancy state is an uncertain error stating that retirement may have completed and requiring manual inspection before retry.
+BranchMe rejects a dirty control worktree before `change_branch`, `pull_branch`, `rebase_branch`, and `integrate_branch`, and rejects any staged, unstaged, untracked, unmerged, or ignored entry in a linked worktree before standalone `remove_worktree`. `land_branch` allows ignored residue to be deleted, but still refuses tracked/staged or non-ignored untracked changes. Retirement does not require an unrelated active worktree to be clean, but every registered worktree record is inspected and any occupancy of the retiring branch blocks deletion. Integration also rejects an existing merge, rebase, cherry-pick, revert, or sequencer state and any non-empty target-branch `mergeOptions` setting that could alter the fixed command policy. After merge or retirement mutation begins, cleanup/postcondition inspection ignores caller cancellation and uses bounded timeouts. A `conflict` result is returned only after exact repository-relative conflict paths are captured, `git merge --abort` succeeds, source and target refs are restored, repository/control-worktree identity is preserved, operation state is cleared, and the control worktree is clean. Failed non-conflict merges remain errors; inconclusive cleanup or verification is never reported as success. After retirement is attempted, contradictory or inconclusive repository, target-ref, retiring-ref, or occupancy state is an uncertain error stating that retirement may have completed and requiring manual inspection before retry.
 
-BranchMe does not force checkout/removal, stash, stage files, create user-authored commits, accept commit messages, reset, force-push, or edit files directly. Rebase-driven rewriting occurs only through explicit `rebase_branch`. Explicit `integrate_branch` may let Git create its standard merge commit for divergent histories, but BranchMe exposes no strategy, squash, unrelated-history, signing, force, commit, `continue_merge`, or `abort_merge` control. Explicit `retire_branch` is the only local branch-deletion surface; it has no bulk, pattern, inferred-target, remote-delete, remote-tracking-delete, automatic worktree-removal, or rollback-ref control.
+BranchMe does not force checkout/removal, stash, stage files, create user-authored commits, accept commit messages, reset, force-push, or edit files directly. Rebase-driven rewriting occurs only through explicit `rebase_branch`. Explicit `integrate_branch` may let Git create its standard merge commit for divergent histories, but BranchMe exposes no strategy, squash, unrelated-history, signing, force, commit, `continue_merge`, or `abort_merge` control. Explicit `retire_branch` and merged-only `land_branch` are the local branch-deletion surfaces. Standalone retirement has no bulk, pattern, inferred-target, remote-delete, remote-tracking-delete, automatic worktree-removal, or rollback-ref control.
 
 ## Network behavior
 
-`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`, `integrate_branch`, and `retire_branch` use locally available refs; BranchMe's direct retirement argv never fetches, pulls, pushes, or names a remote or remote-tracking ref for deletion.
+`fetch_branch`, `pull_branch`, `land_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`, `integrate_branch`, and `retire_branch` use locally available refs; BranchMe's direct retirement argv never fetches, pulls, pushes, or names a remote or remote-tracking ref for deletion.
 
 Git extension points are a separate trust boundary. `integrate_branch` preserves repository-configured hooks, custom merge drivers, clean/smudge filters, and signature policy; it does not pass `--no-verify`. Retirement's `git update-ref` can invoke repository-configured `reference-transaction` hooks. Those configurations may execute arbitrary local commands, mutate other state, or contact networks under the user's identity. BranchMe's fixed argv, direct no-network contract, and direct no-remote-delete guarantees cannot constrain hook behavior.
 
@@ -58,7 +59,7 @@ The branch preflight requests have no body. BranchMe uses the resolved `headBran
 BranchMe operates on the current repository only.
 
 - The GitHub repository is inferred from local `origin` and/or `GITHUB_REPOSITORY`.
-- Branch and PR tools never accept filesystem paths, `owner`, `repo`, or owner-prefixed `owner:branch` PR refs. Worktree mutations accept only an explicitly approved absolute `worktreePath`, with `branchName` and `branchMode` additionally required for creation.
+- Except for `land_branch`'s optional absolute cleanup path, branch and PR tools never accept filesystem paths. They reject `owner`, `repo`, and owner-prefixed `owner:branch` PR refs. Worktree mutations accept only an explicitly approved absolute `worktreePath`, with `branchName` and `branchMode` additionally required for creation.
 - `list_worktrees` is read-only and returns a bounded inventory collected from `git worktree list --porcelain -z`; automatic Git context remains focused on the active worktree.
 - `create_worktree` accepts exactly `worktreePath`, `branchName`, and `branchMode` (`new` or `existing`). New mode uses current `HEAD` only; existing mode requires an existing local branch not checked out elsewhere and does not infer remote branches.
 - `remove_worktree` accepts exactly `worktreePath`, requires an exact canonical match in a fresh current-repository inventory, removes no branch, and does not accept force.
@@ -81,7 +82,15 @@ Linked worktree management expands the mutation boundary beyond the active check
 
 Paths, branch names, lock/prune reasons, and Git output are untrusted metadata. Informational inventory, prose, summaries, and non-identity details are escaped, redacted, and bounded. Successful machine-readable `handoff.cwd` and handoff branch fields instead contain exact verified identities, so BranchMe rejects any identity that would require display transformation before mutation. This also applies to the retained branch returned after removal. Creation failures do not trigger automatic deletion of a possibly created directory or branch; the caller is told to inspect the repository and destination. No force, move, prune, repair, lock, unlock, detached, orphan, or remote-inference worktree operation is implemented.
 
-BranchMe does not copy ignored or untracked files, including repository-root `.env` files, into linked worktrees. If a caller creates ignored local files in a linked checkout, those files block removal until they are removed or preserved outside the checkout. Git documents support for multiple worktrees of a superproject containing submodules as incomplete; BranchMe does not add force-based submodule cleanup.
+BranchMe does not copy ignored or untracked files, including repository-root `.env` files, into linked worktrees. If a caller creates ignored local files in a linked checkout, those files block standalone `remove_worktree` until they are removed or preserved outside the checkout. In contrast, an explicit `land_branch` call authorizes deletion of ignored residue with that worktree. Git documents support for multiple worktrees of a superproject containing submodules as incomplete; BranchMe does not add force-based submodule cleanup.
+
+## Post-merge landing boundary
+
+`land_branch` is execution-only and accepts required exact local `sourceBranch`/`targetBranch`, optional configured `remote` (default `origin`), and optional absolute `worktreePath`. It resolves the primary checkout from the caller's repository and holds its process-local mutation queue for the entire operation. This is not an external-process or cross-worktree lock. Both the actual process cwd and tool-context cwd are checked against the canonical removal path; if either is inside it, landing refuses before fetching and says to run from the repository root.
+
+The captured source tip must be an ancestor of the freshly fetched remote-tracking target before any deletion. The primary checkout is never removed. The selected linked checkout must be on the source or target branch, clean of tracked/staged/non-ignored untracked changes, unlocked, attached, and part of the same repository. Its HEAD must also be contained in the captured target. Ignored files and directories, including `.env` and `.pi/`, are intentionally deleted by force-free `git worktree remove`; preserve needed files first. The receipt lists redacted top-level ignored paths, never file contents. The source branch is then retired with the same atomic expected-old-value lease and full occupancy checks as standalone retirement, but ancestry is against the fetched remote-tracking ref. No remote or remote-tracking ref is deleted.
+
+Target sync always follows attempted cleanup, including cleanup refusals, unless initial cwd/fetch/ancestry checks refuse the whole operation. No branch switching, stash, reset, force update, or prune occurs. Explicit fetch mappings and prune-disabling flags/config prevent Git's configured extra fetch mappings and pruning from expanding the landing scope. Actual local target refs are read before/after sync; errors, dirty skips, and unattempted steps are reported, not described as successful fast-forwards. After possible sync mutation, final ref verification ignores cancellation. Missing branches/worktrees are idempotent; a leftover missing-worktree registration is not pruned and can still block retirement. Repository hooks and external concurrent mutations remain within the existing trust/uncertainty boundary.
 
 ## Local branch-retirement boundary
 

package/docs/PROJECT_DEFINITION_BRIEF.md

@@ -1,6 +1,6 @@
 # Project Definition Brief
 
-Originally approved on 2026-06-30. Updated to describe the implemented `0.2.0` package.
+Originally approved on 2026-06-30. Updated to describe the implemented `0.3.0` package.
 
 ## 1. Bootstrap history
 
@@ -15,7 +15,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.2.0` p
 - Exported extension function: `branchMeExtension`
 - Repository URL: `https://github.com/senad-d/branchme`
 - One-sentence pitch: Verified current-repository Pi tools for branch, integration, retirement, linked-worktree, push, and GitHub pull request workflows.
-- Tool count: thirteen strict agent-callable tools.
+- Tool count: fourteen strict agent-callable tools.
 
 ## 3. Users and use cases
 
@@ -27,6 +27,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.2.0` p
   - Create and verify a linked worktree for a new branch from current `HEAD` or an unoccupied existing local branch.
   - Return an exact, absolute, machine-readable worktree handoff for a caller-managed separate Pi session or subagent.
   - Remove an exact verified linked worktree only when it is clean and contains no ignored entries, while retaining its local branch.
+  - Land a host-merged feature in one cwd-independent call: fetch/prove remote ancestry, remove a clean linked checkout including ignored residue, lease-delete the source branch, and sync the target independently without touching a dirty checkout.
   - Retire one exact unoccupied local branch ref only when it matches a full expected `HEAD` and its relationship to one exact local target has been verified; unmerged retirement requires explicit force authorization.
   - Switch to an existing local branch after a clean-worktree preflight or create a new branch from current `HEAD`.
   - Fetch a configured upstream tracking ref, fast-forward the current branch, or explicitly rebase it.
@@ -51,6 +52,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.2.0` p
 | Tool | `create_worktree` | Create and verify a linked worktree | Exact absolute handoff cwd; new/existing local branch modes only |
 | Tool | `remove_worktree` | Remove an exact verified clean linked worktree | Force-free; ignored entries block removal; branch retained |
 | Tool | `retire_branch` | Delete one exact verified local branch ref | Expected-`HEAD` lease; exact target ancestry; explicit force for unmerged history; local-only |
+| Tool | `land_branch` | Post-host-merge cleanup and final target sync in one call | Remote ancestry gate, ignored-residue deletion, leased local source deletion, per-step receipts; run from repository root |
 | Tool | `change_branch` | Switch to an existing local branch | Rejects dirty worktrees |
 | Tool | `fetch_branch` | Refresh the current branch's configured tracking ref | Explicit fetch refspec; no checkout change |
 | Tool | `pull_branch` | Fast-forward the clean current branch | No rebase, merge commit, or autostash |
@@ -75,10 +77,11 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.2.0` p
   - `src/git.ts`
   - `src/git-integration.ts`
   - `src/git-retirement.ts`
+  - `src/git-landing.ts`
   - `src/github.ts`
   - `src/ui/branchme-panel.ts`
 - Module boundaries:
-  - The extension entry point registers the informational command, thirteen tools, and automatic context hook.
+  - The extension entry point registers the informational command, fourteen tools, and automatic context hook.
   - The context module owns bounded read-only collection, prompt formatting, targeted ancestry rendering, and the `before_agent_start` hook; automatic context never runs ancestry queries.
   - The command and UI modules own mode-safe informational help/status behavior and never invoke mutations.
   - The tools module owns strict TypeBox schemas, descriptions, prompt metadata, bounded display content, and serializable result details.
@@ -102,6 +105,8 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.2.0` p
 - Linked-worktree mutations: `create_worktree` can create a checkout directory outside the active checkout after canonical destination and repository-boundary validation. `remove_worktree` can recursively remove only an exact verified linked-worktree directory after clean and ignored-entry preflights.
 - BranchMe does not directly edit project files, stage content, create user-authored commits, accept commit messages, copy local-only files into new worktrees, delete the retained branch during removal, or mutate worktrees through slash commands. `integrate_branch` may cause Git to create a standard merge commit under the verified boundary below; `retire_branch` may delete one exact local branch ref only under the separate leased boundary below.
 
+The standalone worktree-removal/retirement contracts below remain unchanged. `land_branch` is an explicit combined post-merge alternative: it authorizes deletion of ignored residue, uses the fetched remote-tracking target for leased retirement, reports each outcome, and syncs the local target last. See [README landing contract](../README.md#post-merge-cleanup-in-one-call) and [security boundary](../SECURITY.md#post-merge-landing-boundary).
+
 ## 7. Worktree handoff contract
 
 - `list_worktrees` reads bounded NUL-delimited porcelain inventory and keeps worktree discovery out of automatic active-worktree context.

package/docs/SMOKE_TEST.md

@@ -23,9 +23,9 @@ 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 exactly thirteen tools—`branch_status`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, `remove_worktree`, and `retire_branch`—are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata. It also proves `continue_merge` and `abort_merge` are absent.
+- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms exactly fourteen tools—`branch_status`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_branch`, `land_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, `remove_worktree`, and `retire_branch`—are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata. It also proves `continue_merge` and `abort_merge` are absent.
 - Runtime schema inspection verifies that `integrate_branch` has exactly the required `sourceBranch` and `targetBranch` fields and that `retire_branch` has exactly the required `branchName`, `expectedHead`, `targetBranch`, and `force` fields with `additionalProperties: false`. It also verifies that `branch_status` has only an optional top-level `ancestry` object whose required nested `sourceBranch` and `targetBranch` fields reject additional nested or top-level properties.
-- 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. It expects all thirteen tools but forbids `retire_branch`, `integrate_branch`, and every remote or worktree mutation tool from executing.
+- 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. It expects all fourteen tools but forbids `land_branch`, `retire_branch`, `integrate_branch`, and every remote or worktree mutation tool from executing.
 - The Pi runtime smoke validates worktree, integration, and retirement tool registration, strict schemas, and prompt contracts only; it never creates or removes a worktree, runs a merge, or retires a branch. Real-Git lifecycle coverage runs under `npm run test` in isolated temporary local repositories with no remote contact.
 - Isolated real-Git integration tests cover `already_integrated`, `fast_forward`, exact two-parent `merge_commit`, and conflict-path capture followed by verified automatic abort/restoration. They also cover target mismatch, dirty control state, rejection of branch-specific target merge options, unrelated histories, ignored-file overwrite protection, preserved repository hooks, and a committed source ref checked out in another dirty linked worktree. The recorded merge argv proves autostash and rerere are disabled, ignored-file protection is enabled, and `--no-verify` is absent.
 - Isolated real-Git retirement tests cover merged and explicitly forced-unmerged local-ref deletion, stale expected-`HEAD` rejection, current and linked-worktree occupancy, dirty unrelated worktrees, non-current targets, and preservation of target refs, remote-tracking refs, worktrees, working-tree files, and `branch.<name>.*` configuration without contacting a remote. Recorded argv proves retirement uses `update-ref --no-deref -d` with the captured expected commit and never uses `git branch -d/-D`, fetch, push, or a remote ref target.
@@ -45,7 +45,7 @@ pi --no-extensions -e .
 
 - `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, `retireBranchInvoked: false`, zero network requests, and an isolated empty credential source.
-- `npm run smoke:pi` loaded BranchMe through Pi, verified exactly thirteen BranchMe tools (including strict `integrate_branch`, `retire_branch`, and nested `branch_status.ancestry` schemas), proved merge-continuation tools absent, and confirmed non-mutating BranchMe command output.
+- `npm run smoke:pi` loaded BranchMe through Pi, verified exactly fourteen BranchMe tools (including strict `land_branch`, `integrate_branch`, `retire_branch`, and nested `branch_status.ancestry` schemas), proved merge-continuation tools absent, 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 (including worktree, local integration, leased local branch-retirement, and security boundaries), images, source, license, package metadata, `.env.example`, and `tsconfig.json`; private planning specs and generated files remain excluded.

package/docs/STRUCTURE.md

@@ -13,10 +13,11 @@ src/
 ├── commands/
 │   └── branchme-command.ts       # /branchme status/help command; informational only
 ├── tools/
-│   └── branchme-tools.ts         # registration for thirteen branch/integration/retirement/worktree/GitHub tools
+│   └── branchme-tools.ts         # registration for fourteen branch/integration/retirement/landing/worktree/GitHub tools
 ├── git.ts                        # shared argv-style Git primitives and per-repo mutation queue
 ├── git-integration.ts            # integration preflight, merge, cleanup, and verification state machine
 ├── git-retirement.ts             # leased local-ref retirement and postcondition state machine
+├── git-landing.ts                # queued post-merge cleanup, explicit cwd routing, per-step receipts
 ├── github.ts                     # GitHub repo resolution, env/.env tokens, branch preflight, REST calls, redaction
 └── ui/
     └── branchme-panel.ts         # compact /branchme status panel renderer
@@ -24,7 +25,7 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, thirteen tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, fourteen 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 strict TypeBox schemas, prompt metadata, bounded tool content, and safe structured details. `branch_status` delegates to the shared context collector and optional ancestry verifier; `integrate_branch` and `retire_branch` delegate to focused mutation state machines; worktree tools expose explicit inventory and verified handoff operations.
@@ -35,6 +36,7 @@ src/
 9. `src/redaction.ts` owns shared credential redaction for Git, GitHub, and prompt-bound metadata.
 10. `src/types.ts` keeps serializable details shared by helpers, context, and tools.
 11. `src/ui/branchme-panel.ts` renders a compact status panel and clips lines to terminal width.
+12. `src/git-landing.ts` owns execution-only `land_branch` orchestration and receipt types. It resolves the primary checkout, routes every Git call with `-C`, and reuses queue-free targeted fetch/removal/retirement helpers under one primary-root mutation window. Remote ancestry gates cleanup; final target sync independently reports exact ref observations. No startup work or persistent landing state is added.
 
 ## Pi extension conventions
 
@@ -69,10 +71,11 @@ src/
 - `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 from current `HEAD`, from an explicit read-only `baseRef` (exact local branch, remote-tracking ref, or full commit resolved to a commit before mutation and never checked out or reset), or from 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.
+- `land_branch` fetches the exact remote target, refuses unmerged history or a cwd inside the removal target, removes only a safe linked source/target checkout (including ignored residue), and lease-deletes only the source local ref against the fetched remote-tracking target. Target sync is last and uses a non-forced fetch refspec, a clean-worktree ff-only pull, dirty-skip, or no-op. Failed/unattempted sync is explicit; receipts include actual before/after refs and top-level deleted ignored paths. Standalone removal/retirement defaults are unchanged.
 - `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/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 during removal, change Pi's cwd, or start Pi sessions. It also does not stash, stage, create user-authored commits, accept commit messages, reset, force-push, directly edit files, read unsupported `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry. Only explicit `integrate_branch` may let Git create a standard merge commit for divergent histories; only explicit leased `retire_branch` may delete one exact local branch ref. Retirement has no bulk, inferred-target, remote, remote-tracking, rollback, or automatic worktree deletion. Git documents submodule worktree support as incomplete; BranchMe adds no force-based submodule cleanup.
+- 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 ignored-entry-containing worktrees through standalone `remove_worktree`, delete retained worktree branches during standalone removal, change Pi's cwd, or start Pi sessions. It also does not stash, stage, create user-authored commits, accept commit messages, reset, force-push, directly edit files, read unsupported `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry. Only explicit `integrate_branch` may let Git create a standard merge commit for divergent histories; only explicit leased `retire_branch` or merged-only `land_branch` may delete one exact local branch ref. Retirement has no bulk, inferred-target, remote, remote-tracking, rollback, or automatic worktree deletion. Git documents submodule worktree support as incomplete; BranchMe adds no force-based submodule cleanup.
 
 ## Documentation
 
@@ -91,6 +94,7 @@ test/
 ├── git-integration.test.mjs # isolated real-Git context, branch integration, and worktree lifecycle coverage
 ├── git-retirement.test.mjs # mocked retirement preflight, lease, postconditions, and failures
 ├── git-retirement-integration.test.mjs # isolated real-Git local-ref retirement lifecycle coverage
+├── land-branch.test.mjs  # bare-origin post-merge cleanup, cwd safety, idempotence, and receipt regressions
 ├── github.test.mjs       # GitHub parsing, token resolution, related-PR lookup, redaction
 ├── preparation.test.mjs  # package/docs/source metadata checks
 ├── schema-validation.test.mjs # strict TypeBox schema validation, including worktree and retirement fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Pi extension for verified current-repository Git branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/constants.ts

@@ -14,6 +14,7 @@ export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
 export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
 export const INTEGRATE_BRANCH_TOOL_NAME = "integrate_branch";
 export const RETIRE_BRANCH_TOOL_NAME = "retire_branch";
+export const LAND_BRANCH_TOOL_NAME = "land_branch";
 export const PULL_REQUEST_AUTOFILL_ENV_NAME = "BRANCHME_PR_AUTOFILL";
 
 export const BRANCHME_TOOL_NAMES = [
@@ -25,6 +26,7 @@ export const BRANCHME_TOOL_NAMES = [
   REBASE_BRANCH_TOOL_NAME,
   INTEGRATE_BRANCH_TOOL_NAME,
   RETIRE_BRANCH_TOOL_NAME,
+  LAND_BRANCH_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,

package/src/git-landing.ts

@@ -0,0 +1,449 @@
+import { lstat, realpath } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { GIT_FETCH_TIMEOUT_MS, GIT_PULL_TIMEOUT_MS, MAX_SUMMARY_OUTPUT_CHARS } from "./constants.ts";
+import {
+  canonicalizePathAllowMissing,
+  collectWorktreeInventory,
+  fetchRemoteBranchWithinQueue,
+  formatGitFailure,
+  getAheadBehindCount,
+  getCanonicalCommonGitDirectory,
+  getCanonicalGitWorktreeRoot,
+  getCurrentBranch,
+  getGitOperationState,
+  getLocalBranchCommit,
+  getRemoteTrackingRefCommit,
+  getWorkingTreeStatus,
+  inspectDirectLocalBranchRef,
+  inspectDirectRemoteTrackingRef,
+  isCommitAncestor,
+  pathIsInsideOrEqual,
+  removeWorktreeWithinQueue,
+  requireLosslessWorktreeIdentity,
+  runGit,
+  validateBranchName,
+  validateBranchNameInput,
+  validateWorktreePathInput,
+  validateWorktreeRemovalPath,
+  withRepositoryMutationQueue,
+  type GitCommandContext,
+} from "./git.ts";
+import { retireBranchWithinQueue } from "./git-retirement.ts";
+import { redactSecrets } from "./redaction.ts";
+import type { AheadBehindCount } from "./types.ts";
+
+type GitAPI = Pick<ExtensionAPI, "exec">;
+type Inventory = Awaited<ReturnType<typeof collectWorktreeInventory>>;
+
+export interface LandBranchInput {
+  sourceBranch: string;
+  targetBranch: string;
+  remote?: string;
+  worktreePath?: string;
+}
+
+export interface LandBranchReceipt {
+  repositoryRoot: string;
+  remote: string;
+  targetBranch: string;
+  remoteTargetHead: string | null;
+  sourceBranch: string;
+  sourceHead: string | null;
+  ancestry: { isAncestor: boolean | null };
+  worktree: {
+    path: string | null;
+    outcome: "removed" | "absent" | "refused";
+    reason: string | null;
+    deletedIgnoredPaths: string[];
+  };
+  branch: {
+    outcome: "deleted" | "absent" | "refused";
+    reason: string | null;
+    expectedHead: string | null;
+  };
+  targetSync: {
+    mode: "fetch-refspec" | "pull-ff" | "skipped-dirty" | "noop" | "not-run" | "failed";
+    worktreePath: string | null;
+    before: string | null;
+    after: string | null;
+    aheadBehind: AheadBehindCount | null;
+    reason: string | null;
+  };
+  steps: {
+    step: "repository" | "cwd" | "fetch" | "ancestry" | "worktree" | "branch" | "targetSync";
+    outcome: string;
+    reason: string | null;
+  }[];
+}
+
+function landingError(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error);
+  return redactSecrets(text).replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ").slice(0, MAX_SUMMARY_OUTPUT_CHARS);
+}
+
+function validateLandingInput(input: LandBranchInput): void {
+  for (const key of Object.keys(input)) {
+    if (!["sourceBranch", "targetBranch", "remote", "worktreePath"].includes(key)) {
+      throw new Error("land_branch accepts only sourceBranch, targetBranch, remote, and worktreePath.");
+    }
+  }
+  for (const branch of [input.sourceBranch, input.targetBranch]) {
+    validateBranchNameInput(branch);
+    requireLosslessWorktreeIdentity(branch, "branch");
+    if (branch.startsWith("refs/") || branch.includes("@{")) {
+      throw new Error("land_branch requires exact local branch names, not full refs or revision expressions.");
+    }
+  }
+  if (input.sourceBranch === input.targetBranch) throw new Error("Source and target branches must be distinct.");
+  if (input.remote !== undefined) {
+    validateBranchNameInput(input.remote, "Remote");
+    requireLosslessWorktreeIdentity(input.remote, "branch");
+  }
+  if (input.worktreePath !== undefined) validateWorktreePathInput(input.worktreePath);
+}
+
+// Reused Git helpers all receive explicit -C routing. Disable config-driven pruning,
+// extra fetch mappings and submodule recursion as well as command-line force options.
+async function executeLandingGit(
+  pi: GitAPI,
+  remote: string,
+  command: string,
+  args: string[],
+  options: Parameters<GitAPI["exec"]>[2],
+) {
+  if (!options?.cwd) throw new Error("Landing Git commands require an explicit working directory.");
+  let routedArgs = args;
+  if (args[0] === "fetch") {
+    routedArgs = ["fetch", "--no-prune", "--no-prune-tags", "--refmap=", ...args.slice(1)];
+  } else if (args[0] === "pull") {
+    routedArgs = [
+      "-c", "fetch.prune=false", "-c", "fetch.pruneTags=false",
+      "-c", `remote.${remote}.prune=false`, "-c", `remote.${remote}.pruneTags=false`,
+      "pull", "--no-tags", "--no-prune", "--refmap=", "--no-recurse-submodules", ...args.slice(1),
+    ];
+  }
+  return pi.exec(command, ["-C", options.cwd, ...routedArgs], options);
+}
+
+function newLandingReceipt(root: string, input: LandBranchInput): LandBranchReceipt {
+  return {
+    repositoryRoot: root,
+    remote: input.remote ?? "origin",
+    targetBranch: input.targetBranch,
+    remoteTargetHead: null,
+    sourceBranch: input.sourceBranch,
+    sourceHead: null,
+    ancestry: { isAncestor: null },
+    worktree: { path: null, outcome: "refused", reason: "Not attempted.", deletedIgnoredPaths: [] },
+    branch: { outcome: "refused", reason: "Not attempted.", expectedHead: null },
+    targetSync: { mode: "not-run", worktreePath: null, before: null, after: null, aheadBehind: null, reason: "Not attempted." },
+    steps: [{ step: "repository", outcome: "resolved", reason: null }],
+  };
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function registeredBranchEntries(inventory: Inventory, branch: string) {
+  return inventory.entries.filter((entry) => entry.record.branch === branch);
+}
+
+async function resolveLandingWorktree(
+  inventory: Inventory,
+  input: LandBranchInput,
+): Promise<string | null> {
+  if (input.worktreePath !== undefined) {
+    const path = await canonicalizePathAllowMissing(validateWorktreePathInput(input.worktreePath));
+    if (!path) throw new Error("worktreePath could not be resolved.");
+    return requireLosslessWorktreeIdentity(path, "cwd");
+  }
+  const entries = registeredBranchEntries(inventory, input.sourceBranch).filter((entry) => entry.index !== 0);
+  if (entries.length > 1) throw new Error("Source branch occupies multiple worktrees; provide an exact worktreePath.");
+  if (entries.length === 0) return null;
+  const path = entries[0].canonicalPath;
+  if (!path) throw new Error("Source worktree path could not be resolved.");
+  return requireLosslessWorktreeIdentity(path, "cwd");
+}
+
+async function requireSafeLandingCwd(cwd: string, worktreePath: string | null): Promise<void> {
+  if (worktreePath === null) return;
+  const callerCwd = await realpath(cwd);
+  const processCwd = await realpath(process.cwd());
+  if (pathIsInsideOrEqual(callerCwd, worktreePath) || pathIsInsideOrEqual(processCwd, worktreePath)) {
+    throw new Error("The running cwd is inside worktreePath; run from the repository root.");
+  }
+}
+
+async function captureLocalHead(pi: GitAPI, ctx: GitCommandContext, branch: string, signal?: AbortSignal) {
+  const ref = await inspectDirectLocalBranchRef(pi, ctx, branch, signal);
+  if (ref.status === "absent") return null;
+  const head = await getLocalBranchCommit(pi, ctx, branch, signal);
+  if (ref.objectId !== head) throw new Error("Local branch is not a direct ref to its captured commit.");
+  return head;
+}
+
+async function requireIdleWorktree(pi: GitAPI, ctx: GitCommandContext, signal?: AbortSignal): Promise<void> {
+  const state = await getGitOperationState(pi, ctx, signal);
+  if (state.active.length > 0) throw new Error("Worktree has an in-progress Git operation; it will not be touched.");
+}
+
+async function removeLandingWorktree(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  const worktree = receipt.worktree;
+  const ctx = { cwd: receipt.repositoryRoot };
+  const inventory = await collectWorktreeInventory(pi, ctx, signal);
+  if (worktree.path === null) {
+    if (registeredBranchEntries(inventory, receipt.sourceBranch).some((entry) => entry.index !== 0)) {
+      throw new Error("Source branch became occupied after preflight.");
+    }
+    worktree.outcome = "absent";
+    worktree.reason = null;
+    return;
+  }
+  const matches = inventory.entries.filter((entry) => entry.canonicalPath === worktree.path);
+  if (matches.some((entry) => entry.index === 0) || worktree.path === receipt.repositoryRoot) {
+    throw new Error("The primary checkout / repository root can never be removed.");
+  }
+  if (!(await pathExists(worktree.path))) {
+    worktree.outcome = "absent";
+    worktree.reason = matches.length > 0 ? "Directory absent; registration retained (no prune)." : null;
+    return;
+  }
+  const validated = await validateWorktreeRemovalPath(pi, ctx, worktree.path, signal);
+  if (![receipt.sourceBranch, receipt.targetBranch].includes(validated.worktree.branch ?? "")) {
+    throw new Error("The selected worktree must hold the source or target branch, not an unrelated branch.");
+  }
+  if (receipt.sourceHead === null) throw new Error("Source branch is absent; cannot prove this existing worktree is merged.");
+  const sourceHead = await captureLocalHead(pi, ctx, receipt.sourceBranch, signal);
+  if (sourceHead !== receipt.sourceHead) throw new Error("Source branch moved after the ancestry proof; no worktree removed.");
+  const worktreeHead = validated.worktree.head;
+  if (!worktreeHead || !receipt.remoteTargetHead ||
+      !(await isCommitAncestor(pi, ctx, worktreeHead, receipt.remoteTargetHead, signal))) {
+    throw new Error("Selected worktree HEAD is not merged into the fetched target.");
+  }
+  await requireIdleWorktree(pi, { cwd: worktree.path }, signal);
+  const removed = await removeWorktreeWithinQueue(pi, ctx, worktree.path, signal, true, {
+    branch: validated.worktree.branch!, head: worktreeHead,
+  });
+  if (await pathExists(worktree.path)) throw new Error("Git unregistered the worktree but its directory is still present.");
+  worktree.outcome = "removed";
+  worktree.reason = null;
+  worktree.deletedIgnoredPaths = removed.deletedIgnoredPaths;
+}
+
+async function retireLandingBranch(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  const ctx = { cwd: receipt.repositoryRoot };
+  const head = await captureLocalHead(pi, ctx, receipt.sourceBranch, signal);
+  if (head === null) {
+    receipt.branch.outcome = "absent";
+    receipt.branch.reason = null;
+    return;
+  }
+  if (receipt.worktree.outcome === "refused") throw new Error("Worktree removal was refused; source branch retained.");
+  if (head !== receipt.sourceHead || receipt.remoteTargetHead === null) {
+    throw new Error("Source branch moved after the captured expected-HEAD lease; branch retained.");
+  }
+  await retireBranchWithinQueue(pi, ctx, {
+    branchName: receipt.sourceBranch,
+    expectedHead: head,
+    targetBranch: `${receipt.remote}/${receipt.targetBranch}`,
+    force: false,
+  }, ctx.cwd, signal, "remote-tracking", receipt.remoteTargetHead);
+  receipt.branch.outcome = "deleted";
+  receipt.branch.reason = null;
+}
+
+async function requireLandingPullPolicy(pi: GitAPI, ctx: GitCommandContext, branch: string, signal?: AbortSignal): Promise<void> {
+  const args = ["config", "--get-all", `branch.${branch}.mergeOptions`];
+  const result = await runGit(pi, ctx, args, { signal, allowFailure: true });
+  if (result.code === 1) return;
+  if (result.code !== 0) throw new Error(formatGitFailure(args, result));
+  if (result.stdout.trim()) {
+    throw new Error("Target has branch-specific mergeOptions; sync refused to preserve the fixed fast-forward policy.");
+  }
+}
+
+async function syncLandingTarget(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  const ctx = { cwd: receipt.repositoryRoot };
+  const sync = receipt.targetSync;
+  sync.before = await captureLocalHead(pi, ctx, receipt.targetBranch, signal);
+  if (sync.before === null) throw new Error("Local target branch is absent; landing will not create it.");
+  const inventory = await collectWorktreeInventory(pi, ctx, signal);
+  const entries = registeredBranchEntries(inventory, receipt.targetBranch);
+  if (entries.length > 1) throw new Error("Target branch is checked out in multiple worktrees; sync refused.");
+  if (entries.length === 1) {
+    sync.worktreePath = entries[0].canonicalPath;
+    if (!sync.worktreePath) throw new Error("Target worktree path could not be resolved.");
+    requireLosslessWorktreeIdentity(sync.worktreePath, "cwd");
+  }
+  if (sync.before === receipt.remoteTargetHead) {
+    sync.mode = "noop";
+    sync.reason = null;
+    return;
+  }
+  if (sync.worktreePath !== null) {
+    const targetCtx = { cwd: sync.worktreePath };
+    const root = await getCanonicalGitWorktreeRoot(pi, targetCtx, signal);
+    if (root !== sync.worktreePath ||
+        await getCanonicalCommonGitDirectory(pi, targetCtx, signal) !== await getCanonicalCommonGitDirectory(pi, ctx, signal) ||
+        (await getCurrentBranch(pi, targetCtx, signal)).currentBranch !== receipt.targetBranch) {
+      throw new Error("Target checkout identity changed; sync refused.");
+    }
+    const status = await getWorkingTreeStatus(pi, targetCtx, signal);
+    if (status.workingTree.state !== "clean") {
+      sync.mode = "skipped-dirty";
+      sync.reason = "Target checkout is dirty; no pull attempted.";
+      return;
+    }
+    await requireIdleWorktree(pi, targetCtx, signal);
+    await requireLandingPullPolicy(pi, targetCtx, receipt.targetBranch, signal);
+    await runGit(pi, targetCtx, ["pull", "--ff-only", "--no-rebase", "--no-autostash", receipt.remote, `refs/heads/${receipt.targetBranch}`], {
+      signal, timeout: GIT_PULL_TIMEOUT_MS,
+    });
+    sync.mode = "pull-ff";
+  } else {
+    await runGit(pi, ctx, ["fetch", "--no-tags", "--no-recurse-submodules", receipt.remote, `refs/heads/${receipt.targetBranch}:refs/heads/${receipt.targetBranch}`], {
+      signal, timeout: GIT_FETCH_TIMEOUT_MS,
+    });
+    sync.mode = "fetch-refspec";
+  }
+  sync.reason = null;
+}
+
+async function recordTargetAfter(pi: GitAPI, receipt: LandBranchReceipt): Promise<void> {
+  const ctx = { cwd: receipt.repositoryRoot };
+  const sync = receipt.targetSync;
+  sync.after = await captureLocalHead(pi, ctx, receipt.targetBranch);
+  if (sync.after !== null && receipt.remoteTargetHead !== null) {
+    sync.aheadBehind = await getAheadBehindCount(pi, ctx, undefined, `${sync.after}...${receipt.remoteTargetHead}`);
+  }
+  if (["fetch-refspec", "pull-ff"].includes(sync.mode)) {
+    if (sync.before === null || sync.after === null ||
+        !(await isCommitAncestor(pi, ctx, sync.before, sync.after)) ||
+        receipt.remoteTargetHead === null || !(await isCommitAncestor(pi, ctx, receipt.remoteTargetHead, sync.after)) ||
+        (sync.after === sync.before && sync.before !== receipt.remoteTargetHead)) {
+      throw new Error("Git did not produce a verified target fast-forward; inspect the recorded before/after refs.");
+    }
+  } else if (["noop", "skipped-dirty"].includes(sync.mode) && sync.before !== sync.after) {
+    throw new Error("Target ref moved concurrently during a read-only sync decision.");
+  }
+}
+
+async function finishLandingSync(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  try {
+    await syncLandingTarget(pi, receipt, signal);
+  } catch (error) {
+    receipt.targetSync.mode = "failed";
+    receipt.targetSync.reason = landingError(error);
+  }
+  try {
+    // Verification is deliberately uncancelled after a possible mutation.
+    await recordTargetAfter(pi, receipt);
+  } catch (error) {
+    receipt.targetSync.mode = "failed";
+    receipt.targetSync.reason = landingError(error);
+  }
+  receipt.steps.push({ step: "targetSync", outcome: receipt.targetSync.mode, reason: receipt.targetSync.reason });
+}
+
+async function refuseLanding(pi: GitAPI, receipt: LandBranchReceipt, error: unknown): Promise<LandBranchReceipt> {
+  const reason = landingError(error);
+  receipt.worktree.reason = reason;
+  receipt.branch.reason = reason;
+  receipt.targetSync.reason = reason;
+  try {
+    receipt.targetSync.before ??= await captureLocalHead(pi, { cwd: receipt.repositoryRoot }, receipt.targetBranch);
+    await recordTargetAfter(pi, receipt);
+  } catch (verificationError) {
+    receipt.targetSync.reason = `${reason} Verification: ${landingError(verificationError)}`;
+  }
+  const recorded = new Set(receipt.steps.map((step) => step.step));
+  for (const step of ["cwd", "fetch", "ancestry", "worktree", "branch", "targetSync"] as const) {
+    if (!recorded.has(step)) receipt.steps.push({ step, outcome: "not-run", reason });
+  }
+  return receipt;
+}
+
+async function landBranchWithinQueue(
+  pi: GitAPI,
+  cwd: string,
+  root: string,
+  input: LandBranchInput,
+  signal?: AbortSignal,
+): Promise<LandBranchReceipt> {
+  const ctx = { cwd: root };
+  const receipt = newLandingReceipt(root, input);
+  let step: "cwd" | "fetch" | "ancestry" = "cwd";
+  try {
+    const inventory = await collectWorktreeInventory(pi, ctx, signal);
+    receipt.worktree.path = await resolveLandingWorktree(inventory, input);
+    await requireSafeLandingCwd(cwd, receipt.worktree.path);
+    receipt.steps.push({ step: "cwd", outcome: "safe", reason: null });
+    step = "fetch";
+    await validateBranchName(pi, ctx, input.sourceBranch, signal);
+    await validateBranchName(pi, ctx, input.targetBranch, signal);
+    receipt.sourceHead = await captureLocalHead(pi, ctx, input.sourceBranch, signal);
+    receipt.branch.expectedHead = receipt.sourceHead;
+    receipt.targetSync.before = await captureLocalHead(pi, ctx, input.targetBranch, signal);
+    if (receipt.targetSync.before === null) throw new Error("Local target branch does not exist.");
+    await fetchRemoteBranchWithinQueue(pi, ctx, receipt.remote, receipt.targetBranch, signal);
+    const tracking = `${receipt.remote}/${receipt.targetBranch}`;
+    const ref = await inspectDirectRemoteTrackingRef(pi, ctx, tracking, signal);
+    receipt.remoteTargetHead = await getRemoteTrackingRefCommit(pi, ctx, tracking, signal);
+    if (ref.status !== "present" || ref.objectId !== receipt.remoteTargetHead) {
+      throw new Error("Fetched target is not a direct ref to its captured commit.");
+    }
+    receipt.steps.push({ step: "fetch", outcome: "fetched", reason: null });
+    step = "ancestry";
+    if (receipt.sourceHead !== null) {
+      receipt.ancestry.isAncestor = await isCommitAncestor(pi, ctx, receipt.sourceHead, receipt.remoteTargetHead, signal);
+      if (!receipt.ancestry.isAncestor) throw new Error("Source branch is not merged into the fetched remote target; landing refused.");
+    }
+    receipt.steps.push({ step: "ancestry", outcome: receipt.sourceHead === null ? "absent" : "verified", reason: null });
+  } catch (error) {
+    receipt.steps.push({ step, outcome: "refused", reason: landingError(error) });
+    return refuseLanding(pi, receipt, error);
+  }
+  try {
+    await removeLandingWorktree(pi, receipt, signal);
+  } catch (error) {
+    receipt.worktree.reason = landingError(error);
+  }
+  receipt.steps.push({ step: "worktree", outcome: receipt.worktree.outcome, reason: receipt.worktree.reason });
+  try {
+    await retireLandingBranch(pi, receipt, signal);
+  } catch (error) {
+    receipt.branch.reason = landingError(error);
+  }
+  receipt.steps.push({ step: "branch", outcome: receipt.branch.outcome, reason: receipt.branch.reason });
+  await finishLandingSync(pi, receipt, signal);
+  return receipt;
+}
+
+export async function landBranch(pi: GitAPI, ctx: GitCommandContext, input: LandBranchInput, signal?: AbortSignal): Promise<LandBranchReceipt> {
+  validateLandingInput(input);
+  const routedPi: GitAPI = { exec: executeLandingGit.bind(undefined, pi, input.remote ?? "origin") };
+  const callerRoot = await getCanonicalGitWorktreeRoot(routedPi, ctx, signal);
+  const inventory = await collectWorktreeInventory(routedPi, { cwd: callerRoot }, signal);
+  const primary = inventory.entries[0];
+  if (!primary?.canonicalPath || primary.record.bare) throw new Error("Landing requires a primary non-bare checkout.");
+  const root = await getCanonicalGitWorktreeRoot(routedPi, { cwd: primary.canonicalPath }, signal);
+  requireLosslessWorktreeIdentity(root, "cwd");
+  if (root !== primary.canonicalPath ||
+      await getCanonicalCommonGitDirectory(routedPi, { cwd: root }, signal) !== await getCanonicalCommonGitDirectory(routedPi, { cwd: callerRoot }, signal)) {
+    throw new Error("Primary checkout repository identity could not be verified.");
+  }
+  return withRepositoryMutationQueue(root, landBranchWithinQueue.bind(undefined, routedPi, ctx.cwd, root, input, signal));
+}
+
+export function formatLandBranch(receipt: LandBranchReceipt): string {
+  const summary = `land_branch: worktree ${receipt.worktree.outcome}; branch ${receipt.branch.outcome}; target sync ${receipt.targetSync.mode}.`;
+  const reason = receipt.worktree.reason ?? receipt.branch.reason ?? receipt.targetSync.reason;
+  return reason ? `${summary} ${landingError(reason)}` : summary;
+}

package/src/git-retirement.ts

@@ -10,7 +10,9 @@ import {
   getCanonicalCommonGitDirectory,
   getCanonicalGitWorktreeRoot,
   getLocalBranchCommit,
+  getRemoteTrackingRefCommit,
   inspectDirectLocalBranchRef,
+  inspectDirectRemoteTrackingRef,
   inspectLocalBranchWorktreeOccupancy,
   isCommitAncestor,
   isLosslessGitMetadata,
@@ -36,6 +38,8 @@ import type {
 const FULL_OBJECT_ID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu;
 const RETIREMENT_REQUEST_FIELDS = new Set(["branchName", "expectedHead", "targetBranch", "force"]);
 
+type RetirementTargetScope = "local" | "remote-tracking";
+
 export interface PreparedBranchRetirement {
   worktreeRoot: string;
   canonicalCommonGitDirectory: string;
@@ -62,7 +66,7 @@ function normalizeExpectedHead(value: unknown): string {
   return value.toLowerCase();
 }
 
-function validateRetirementRequest(request: unknown): RetireBranchToolInput {
+function validateRetirementRequest(request: unknown, targetScope: RetirementTargetScope = "local"): RetireBranchToolInput {
   if (typeof request !== "object" || request === null || Array.isArray(request)) {
     throw new TypeError("Branch retirement request must be an object.");
   }
@@ -78,7 +82,7 @@ function validateRetirementRequest(request: unknown): RetireBranchToolInput {
 
   validateRetirementBranchName(values.branchName, "Retiring branch");
   validateRetirementBranchName(values.targetBranch, "Target branch");
-  if (values.branchName === values.targetBranch) {
+  if (targetScope === "local" && values.branchName === values.targetBranch) {
     throw new Error("Retiring branch and target branch must be distinct local branches.");
   }
   const expectedHead = normalizeExpectedHead(values.expectedHead);
@@ -164,13 +168,26 @@ function retirementRefIdentity(
   };
 }
 
+function retirementTargetScope(prepared: PreparedBranchRetirement): RetirementTargetScope {
+  return prepared.target.fullRef.startsWith("refs/remotes/") ? "remote-tracking" : "local";
+}
+
+function targetRefInspector(scope: RetirementTargetScope) {
+  return scope === "local" ? inspectDirectLocalBranchRef : inspectDirectRemoteTrackingRef;
+}
+
+function targetCommitResolver(scope: RetirementTargetScope) {
+  return scope === "local" ? getLocalBranchCommit : getRemoteTrackingRefCommit;
+}
+
 export async function prepareBranchRetirement(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   requestValue: unknown,
   signal?: AbortSignal,
+  targetScope: RetirementTargetScope = "local",
 ): Promise<PreparedBranchRetirement> {
-  const request = validateRetirementRequest(requestValue);
+  const request = validateRetirementRequest(requestValue, targetScope);
   const worktreeRoot = await getCanonicalGitWorktreeRoot(pi, ctx, signal);
   const rootCtx = { cwd: worktreeRoot };
   const canonicalCommonGitDirectory = await getCanonicalCommonGitDirectory(pi, rootCtx, signal);
@@ -182,11 +199,11 @@ export async function prepareBranchRetirement(
     "Retiring",
   );
   const targetRef = requirePresentDirectRef(
-    await inspectDirectLocalBranchRef(pi, rootCtx, request.targetBranch, signal),
+    await targetRefInspector(targetScope)(pi, rootCtx, request.targetBranch, signal),
     "Target",
   );
   const retiringHead = await getLocalBranchCommit(pi, rootCtx, request.branchName, signal);
-  const targetHead = await getLocalBranchCommit(pi, rootCtx, request.targetBranch, signal);
+  const targetHead = await targetCommitResolver(targetScope)(pi, rootCtx, request.targetBranch, signal);
   requireDirectRefCommitIdentity(retiringRef, retiringHead, "Retiring");
   requireDirectRefCommitIdentity(targetRef, targetHead, "Target");
   if (!sameObjectIdentity(retiringHead, request.expectedHead)) {
@@ -328,7 +345,7 @@ async function inspectImmediateRetirementState(
     "Retiring",
   );
   const targetRef = requirePresentDirectRef(
-    await inspectDirectLocalBranchRef(pi, rootCtx, prepared.request.targetBranch, signal),
+    await targetRefInspector(retirementTargetScope(prepared))(pi, rootCtx, prepared.request.targetBranch, signal),
     "Target",
   );
   const retiringHead = await getLocalBranchCommit(
@@ -337,7 +354,7 @@ async function inspectImmediateRetirementState(
     prepared.request.branchName,
     signal,
   );
-  const targetHead = await getLocalBranchCommit(
+  const targetHead = await targetCommitResolver(retirementTargetScope(prepared))(
     pi,
     rootCtx,
     prepared.request.targetBranch,
@@ -445,7 +462,7 @@ async function inspectPostRetirementState(
     rootCtx,
     prepared.request.branchName,
   );
-  const targetRef = await inspectDirectLocalBranchRef(
+  const targetRef = await targetRefInspector(retirementTargetScope(prepared))(
     pi,
     rootCtx,
     prepared.request.targetBranch,
@@ -458,7 +475,7 @@ async function inspectPostRetirementState(
   }
   let targetHead: string | null = null;
   if (targetRef.status === "present") {
-    targetHead = await getLocalBranchCommit(pi, rootCtx, prepared.request.targetBranch);
+    targetHead = await targetCommitResolver(retirementTargetScope(prepared))(pi, rootCtx, prepared.request.targetBranch);
     requireDirectRefCommitIdentity(targetRef, targetHead, "Target");
     targetHead = targetHead.toLowerCase();
   }
@@ -610,14 +627,20 @@ function classifyRetirementOutcome(
   );
 }
 
-async function retireBranchWithinQueue(
+// Caller must hold the repository mutation queue; remote targets are used only by land_branch.
+export async function retireBranchWithinQueue(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   request: RetireBranchToolInput,
   queuedWorktreeRoot: string,
   signal?: AbortSignal,
+  targetScope: RetirementTargetScope = "local",
+  expectedTargetHead?: string,
 ): Promise<RetireBranchDetails> {
-  const prepared = await prepareBranchRetirement(pi, ctx, request, signal);
+  const prepared = await prepareBranchRetirement(pi, ctx, request, signal, targetScope);
+  if (expectedTargetHead !== undefined && prepared.target.head !== expectedTargetHead) {
+    throw new Error("The fetched retirement target moved after the landing ancestry proof.");
+  }
   if (prepared.worktreeRoot !== queuedWorktreeRoot) {
     throw new Error("The active worktree changed while preparing branch retirement.");
   }

package/src/git.ts

@@ -741,7 +741,7 @@ export function validateWorktreePathInput(worktreePath: unknown): string {
   return normalizedPath;
 }
 
-async function canonicalizePathAllowMissing(path: string): Promise<string | null> {
+export async function canonicalizePathAllowMissing(path: string): Promise<string | null> {
   let candidate = normalize(path);
   const suffix: string[] = [];
 
@@ -759,7 +759,7 @@ async function canonicalizePathAllowMissing(path: string): Promise<string | null
   }
 }
 
-async function collectWorktreeInventory(
+export async function collectWorktreeInventory(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   signal?: AbortSignal,
@@ -783,7 +783,7 @@ async function collectWorktreeInventory(
   return { repoRoot, canonicalCurrentPath, entries };
 }
 
-function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string): boolean {
+export function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string): boolean {
   const relation = relative(boundaryPath, candidatePath);
   return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
@@ -1399,7 +1399,11 @@ async function requirePresentWorktreeDirectory(canonicalPath: string): Promise<v
 
 interface WorktreeRemovalStatus {
   workingTree: WorkingTreeDetails;
-  hasIgnoredEntries: boolean;
+  ignoredPaths: string[];
+}
+
+function compareIgnoredPaths(left: string, right: string): number {
+  return left.localeCompare(right);
 }
 
 function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
@@ -1408,7 +1412,7 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
   }
 
   const records = output.split(NUL_SEPARATOR);
-  let hasIgnoredEntries = false;
+  const ignoredPaths = new Set<string>();
   let skipNextRecord = false;
   for (const [index, record] of records.entries()) {
     if (skipNextRecord) {
@@ -1419,12 +1423,12 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
 
     const parsed = parsePorcelainChange(records, index);
     skipNextRecord = parsed.nextIndex > index;
-    if (parsed.status === "!!") hasIgnoredEntries = true;
+    if (parsed.status === "!!") ignoredPaths.add(parsed.path.split("/")[0]);
   }
 
   return {
     workingTree: parseWorkingTreeStatus(output).workingTree,
-    hasIgnoredEntries,
+    ignoredPaths: [...ignoredPaths].sort(compareIgnoredPaths),
   };
 }
 
@@ -1432,7 +1436,8 @@ async function inspectRemovableWorktree(
   pi: Pick<ExtensionAPI, "exec">,
   canonicalPath: string,
   signal?: AbortSignal,
-): Promise<WorkingTreeDetails> {
+  allowIgnored = false,
+): Promise<WorktreeRemovalStatus> {
   const workingTree = await inspectWorktreeState(pi, canonicalPath, signal);
   if (workingTree.state !== "clean") {
     throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
@@ -1446,12 +1451,12 @@ async function inspectRemovableWorktree(
   if (removalStatus.workingTree.state !== "clean") {
     throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
   }
-  if (removalStatus.hasIgnoredEntries) {
+  if (!allowIgnored && removalStatus.ignoredPaths.length > 0) {
     throw new Error(
       "The target worktree contains ignored files or directories; remove or preserve them outside the checkout before removal.",
     );
   }
-  return workingTree;
+  return removalStatus;
 }
 
 function assertWorktreeRemoved(
@@ -1487,7 +1492,22 @@ export async function removeWorktree(
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
 
-  return withRepositoryMutationQueue(repoRoot, async () => {
+  return withRepositoryMutationQueue(
+    repoRoot,
+    removeWorktreeWithinQueue.bind(undefined, pi, rootCtx, requestedWorktreePath, signal),
+  );
+}
+
+// Caller must hold the repository mutation queue. Standalone removal still refuses ignored residue.
+export async function removeWorktreeWithinQueue(
+  pi: Pick<ExtensionAPI, "exec">,
+  rootCtx: GitCommandContext,
+  requestedWorktreePath: string,
+  signal?: AbortSignal,
+  allowIgnored = false,
+  expectedIdentity?: { branch: string; head: string },
+): Promise<RemoveWorktreeDetails & { deletedIgnoredPaths: string[] }> {
+    const repoRoot = rootCtx.cwd;
     const resolved = await resolveWorktreeRemovalTarget(
       pi,
       rootCtx,
@@ -1499,6 +1519,9 @@ export async function removeWorktree(
     }
 
     const worktree = requireRemovableWorktreeEntry(resolved);
+    if (expectedIdentity && (worktree.branch !== expectedIdentity.branch || worktree.head !== expectedIdentity.head)) {
+      throw new Error("The selected worktree branch or HEAD moved after the landing ancestry proof.");
+    }
     const branchName = resolved.entry.record.branch;
     const head = resolved.entry.record.head;
     if (branchName === null || head === null) {
@@ -1507,7 +1530,7 @@ export async function removeWorktree(
     const verifiedCanonicalPath = requireLosslessWorktreeIdentity(resolved.canonicalPath, "cwd");
     const retainedBranch = requireLosslessWorktreeIdentity(branchName, "branch");
     await requirePresentWorktreeDirectory(verifiedCanonicalPath);
-    const workingTree = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal);
+    const { workingTree, ignoredPaths } = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal, allowIgnored);
     const branchHeadBefore = await getLocalBranchCommit(pi, rootCtx, retainedBranch, signal);
     if (branchHeadBefore.toLowerCase() !== head.toLowerCase()) {
       throw new Error("The target local branch did not match the worktree HEAD before removal.");
@@ -1540,6 +1563,7 @@ export async function removeWorktree(
       );
       return {
         action: "remove_worktree",
+        deletedIgnoredPaths: ignoredPaths.map((path) => redactSecrets(path)),
         repoRoot: safeWorktreeValue(repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
         request: {
           worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
@@ -1567,7 +1591,6 @@ export async function removeWorktree(
     } catch (error) {
       throw worktreeRemovalFailure(error, resolved.canonicalPath, branchName);
     }
-  });
 }
 
 function isRenameOrCopyStatus(status: string): boolean {
@@ -1880,8 +1903,9 @@ export async function getAheadBehindCount(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   signal?: AbortSignal,
+  comparison = "HEAD...@{u}",
 ): Promise<AheadBehindCount> {
-  const result = await runGit(pi, ctx, ["rev-list", "--left-right", "--count", "HEAD...@{u}"], {
+  const result = await runGit(pi, ctx, ["rev-list", "--left-right", "--count", comparison], {
     signal,
     timeout: GIT_STATUS_TIMEOUT_MS,
   });
@@ -1934,9 +1958,9 @@ export async function localBranchExists(
   return result.code === 0;
 }
 
-function requireLosslessLocalRef(branchName: string): string {
+function requireLosslessLocalRef(branchName: string, prefix = "refs/heads/"): string {
   requireLosslessWorktreeIdentity(branchName, "branch");
-  const fullRef = `refs/heads/${branchName}`;
+  const fullRef = `${prefix}${branchName}`;
   if (!isLosslessGitMetadata(fullRef, GIT_CONTEXT_VALUE_LIMIT_CHARS)) {
     throw new Error(
       "The full local branch ref cannot be returned safely and losslessly. " +
@@ -2014,9 +2038,28 @@ export async function inspectDirectLocalBranchRef(
   ctx: GitCommandContext,
   branchName: string,
   signal?: AbortSignal,
+): Promise<DirectLocalBranchRefInspection> {
+  return inspectDirectBranchRef(pi, ctx, branchName, "refs/heads/", signal);
+}
+
+export async function inspectDirectRemoteTrackingRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  signal?: AbortSignal,
+): Promise<DirectLocalBranchRefInspection> {
+  return inspectDirectBranchRef(pi, ctx, refName, "refs/remotes/", signal);
+}
+
+async function inspectDirectBranchRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  prefix: string,
+  signal?: AbortSignal,
 ): Promise<DirectLocalBranchRefInspection> {
   validateBranchNameInput(branchName);
-  const fullRef = requireLosslessLocalRef(branchName);
+  const fullRef = requireLosslessLocalRef(branchName, prefix);
   const listArgs = [
     "for-each-ref",
     "--count=1",
@@ -2317,7 +2360,22 @@ export async function fetchRemoteBranch(
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
 
-  return withRepositoryMutationQueue(repoRoot, async () => {
+  return withRepositoryMutationQueue(
+    repoRoot,
+    fetchRemoteBranchWithinQueue.bind(undefined, pi, rootCtx, remote, branch, signal),
+  );
+}
+
+// Caller must hold the repository mutation queue.
+export async function fetchRemoteBranchWithinQueue(
+  pi: Pick<ExtensionAPI, "exec">,
+  rootCtx: GitCommandContext,
+  remote: string,
+  branch: string,
+  signal?: AbortSignal,
+): Promise<FetchRemoteBranchDetails> {
+    const repoRoot = rootCtx.cwd;
+    validateRequestedRemoteName(remote);
     await validateBranchName(pi, rootCtx, branch, signal);
     await requireConfiguredRemote(pi, rootCtx, remote, signal);
 
@@ -2343,7 +2401,6 @@ export async function fetchRemoteBranch(
       refspec: safeDetail(refspec),
       output: safeOutput(result.stdout || result.stderr),
     };
-  });
 }
 
 export async function pullCurrentBranch(

package/src/tools/branchme-tools.ts

@@ -11,6 +11,7 @@ import {
   GIT_RETIREMENT_SUMMARY_LIMIT_CHARS,
   GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
   INTEGRATE_BRANCH_TOOL_NAME,
+  LAND_BRANCH_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
   PULL_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
@@ -42,6 +43,7 @@ import {
 import { collectGitContext, formatGitContext } from "../git-context.ts";
 import { integrateBranch } from "../git-integration.ts";
 import { retireBranch } from "../git-retirement.ts";
+import { formatLandBranch, landBranch } from "../git-landing.ts";
 import {
   createGitHubPullRequest,
   ensureGitHubBranchExists,
@@ -106,6 +108,16 @@ const RetireBranchParametersSchema = Type.Object(
   { additionalProperties: false },
 );
 
+const LandBranchParametersSchema = Type.Object(
+  {
+    sourceBranch: Type.String({ minLength: 1, description: "Merged local feature branch to delete, or its name on an idempotent retry." }),
+    targetBranch: Type.String({ minLength: 1, description: "Local default branch to fast-forward after cleanup." }),
+    remote: Type.Optional(Type.String({ minLength: 1, description: "Configured remote name; defaults to origin." })),
+    worktreePath: Type.Optional(Type.String({ minLength: 1, description: "Absolute linked-worktree path to remove, including one parked on targetBranch. Omit to find the source branch's worktree." })),
+  },
+  { additionalProperties: false },
+);
+
 const CreateBranchParametersSchema = Type.Object(
   {
     branchName: Type.String({ minLength: 1, description: "Name of the new branch to create from current HEAD." }),
@@ -703,6 +715,28 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  pi.registerTool({
+    name: LAND_BRANCH_TOOL_NAME,
+    label: "Land Branch",
+    description: "land_branch performs deterministic post-merge cleanup: fetch the remote target, prove source ancestry, remove its clean linked worktree (including ignored residue), lease-delete the local source branch, then fast-forward the local target without switching branches. Returns a structured per-step receipt and one-line summary. No remote mutation, force, stash, reset, checkout, or prune; retries are idempotent. Diagnostics are redacted and bounded to 4000 characters each.",
+    promptSnippet: "land_branch: post-merge linked-worktree cleanup, leased source retirement, and independent fast-forward target sync with verified receipts",
+    promptGuidelines: [
+      "Use land_branch after the pull request merged on the host; the source tip must be an ancestor of the fetched remote target (squash/rebase merges may not satisfy this).",
+      "land_branch is cwd-independent; run from the repository root, never inside the worktree being removed.",
+      "land_branch deletes ignored files such as .env, .pi/, node_modules/, and dist/ with the worktree and lists their top-level entries in deletedIgnoredPaths; preserve anything needed beforehand.",
+      "land_branch target sync never touches a dirty checkout; skipped-dirty reports its path and ahead/behind counts, independently of cleanup outcomes.",
+      "Call land_branch by itself and inspect each receipt outcome; do not batch it with other Git mutations. It never switches branches or mutates remote branches.",
+    ],
+    parameters: LandBranchParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await landBranch(pi, ctx, params, signal);
+      return {
+        content: [{ type: "text", text: formatLandBranch(details) }],
+        details,
+      };
+    },
+  });
+
   pi.registerTool({
     name: PUSH_BRANCH_TOOL_NAME,
     label: "Push Branch",