wendkeep 0.76.9 → 0.77.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.77.0] — 2026-08-22
+
+### Added
+
+- **Fechamento comprovado de worktrees.** `worktree finish <slug> --pr <ref>` valida no GitHub que o
+  PR foi merged, cruza branch e merge commit com a base local, executa preflight de checkout,
+  sessões, delivery, outbox e handoff, e fecha somente o active context da worktree alvo.
+- **Cleanup auditável e retomável.** Reservas sob lock, remoção do ref local por CAS e receipts JSONL
+  append-only tornam o fechamento idempotente e retomável depois de crash; `doctor` diagnostica
+  estado interrompido, failed ou receipt inconsistente com recovery objetivo.
+- **Comandos destrutivos explícitos.** `worktree cleanup --merged` e `worktree prune` são dry-run por
+  padrão e exigem `--apply`; `worktree remove --reason` preserva branch não merged. Exclusão remota
+  continua proibida sem `--delete-remote` e falha fechado quando a branch diverge.
+- **Paridade operacional.** README e guia de worktrees PT-BR/EN documentam flags, blockers,
+  PowerShell/POSIX e recovery; a task local do VS Code oferece `WendKeep: Finish merged worktree`.
+
 ## [0.76.9] — 2026-08-22
 
 ### Fixed

package/README.en.md

@@ -147,7 +147,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-companions` | Pin no companions. |
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
-| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening worktrees; never overwrites an existing file. Also accepted by `sync`. |
+| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing worktrees; never overwrites an existing file. Also accepted by `sync`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -239,7 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | Group | Use it for | Detailed guide |
 |---|---|---|
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
-| **Managed worktrees** | `worktree create/list/status/open`, Vault binding, and recovery | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
+| **Managed worktrees** | `worktree create/list/status/open/finish/cleanup/remove/prune`, merge proof, preflight, and receipts | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
 | **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |

package/README.md

@@ -147,7 +147,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-companions` | Pin no companions. |
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
-| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening worktrees; never overwrites an existing file. Also accepted by `sync`. |
+| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing worktrees; never overwrites an existing file. Also accepted by `sync`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -239,7 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | Group | Use it for | Detailed guide |
 |---|---|---|
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
-| **Managed worktrees** | `worktree create/list/status/open`, Vault binding, and recovery | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
+| **Managed worktrees** | `worktree create/list/status/open/finish/cleanup/remove/prune`, merge proof, preflight, and receipts | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
 | **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |

package/docs/en/commands/worktrees.md

@@ -4,23 +4,24 @@
 
 ## Purpose
 
-Create isolated linked worktrees that remain bound to the same project and canonical Vault,
-without copying private state into versioned files.
+Create and finish isolated linked worktrees that remain bound to the same project and canonical
+Vault, without copying private state into versioned files or discarding local work.
 
 ## When to use
 
-Use it to start isolated implementation work, list managed checkouts, diagnose a partial create,
-or open an already-ready worktree in VS Code.
+Use it to start isolated implementation work, list managed checkouts, diagnose a partial operation,
+open a worktree in VS Code, or clean it up after a provably merged PR.
 
 ## When not to use
 
-Do not use it to remove, merge, or self-merge worktrees. Those operations remain outside this
-capability.
+Do not use it to merge the PR, discard a dirty/untracked checkout, or delete a remote branch without
+explicit authorization. `finish` consumes an existing merge; it does not self-merge.
 
 ## Prerequisites
 
 - A Git repository whose project is already bound to its Vault through `.wendkeep.json`.
-- Git on `PATH`; opening also requires the VS Code `code` command.
+- Git on `PATH`; `finish` also requires authenticated `gh` access to query GitHub.
+- Opening also requires the VS Code `code` command.
 
 ## Syntax
 
@@ -29,48 +30,88 @@ npx --no-install wendkeep worktree create <slug> [--base <ref>] [--branch <name>
 npx --no-install wendkeep worktree list [--json]
 npx --no-install wendkeep worktree status [<slug>] [--json]
 npx --no-install wendkeep worktree open <slug> [--editor vscode] [--json]
+npx --no-install wendkeep worktree finish <slug> [--pr <number|url>] [--delete-remote] [--open-main] [--json]
+npx --no-install wendkeep worktree cleanup --merged [--dry-run|--apply] [--json]
+npx --no-install wendkeep worktree remove <slug> --reason <text> [--json]
+npx --no-install wendkeep worktree prune [--dry-run|--apply] [--json]
 ```
 
 All commands accept `--project <root>`. By default, create uses `.worktrees/<slug>`, the detected
-base, and branch `wk/<slug>`. When configured, `worktrees.root` must be a
-non-empty relative path. Git validates slugs and branches; paths escaping the root or crossing a
-symlink/junction are rejected before mutation.
+base, and branch `wk/<slug>`. When configured, `worktrees.root` must be a non-empty relative path.
+Git validates slugs and branches; paths escaping the root or crossing a symlink/junction are rejected
+before mutation.
+
+## Safe finish
+
+When `origin` exists, `finish` runs `git fetch --prune`, queries the PR through the GitHub adapter,
+and requires `MERGED`, a matching branch, and a merge commit reachable from the local base. The
+number/URL is associated with the registry. Before removal, preflight fails closed on dirty or
+untracked files, an active session, active delivery, memory outbox, or pending handoff.
+
+After reserving under lock, the command removes the linked worktree, closes only its active
+contexts, prunes, deletes the local ref with CAS, and appends a JSONL receipt in the Git common-dir.
+This accepts merge commits, squash, and rebase without `git branch -D`. Re-running the same proof is
+idempotent; when the directory vanished between steps, the interrupted reservation resumes.
+`doctor` reports interrupted/failed cleanup with an objective recovery command.
+
+`--delete-remote` is the only authorization to delete the remote branch. The branch must remain at
+the proven head; divergence or an unavailable network blocks the operation. An already-absent branch
+is idempotent success. `--open-main` opens the main worktree only after completion.
+
+## Cleanup, remove, and prune
+
+`cleanup --merged` and `prune` are dry-run by default. `--dry-run` makes that intent explicit; only
+`--apply` permits mutation. Plans are slug-sorted and do not change Git, registry, contexts, or
+receipts. `cleanup --merged` acts only on entries with an associated PR whose merge is revalidated.
+`remove --reason` is the auditable escape hatch for explicit abandonment: it waives merge proof but
+keeps every preflight and preserves both local and remote branches.
 
 ## Options and exit codes
 
 The registry lives in the Git common-dir at `wendkeep/worktrees-v1.json`, protected by a
-multi-process lock. It stores repository/worktree identity and the canonical binding;
-`.wendkeep.json` stays unchanged. `.worktrees/` is added to both the versioned ignore and the
-repository-private exclude. JSON `list`/`status` output exposes neither Vault paths nor contents.
-For each worktree, human output shows its slug, identity, checkout path, branch, HEAD, state, and
-binding health.
+multi-process lock. It stores repository/worktree identity, canonical binding, PR, and transient
+cleanup state; `.wendkeep.json` stays unchanged. Receipts live at
+`wendkeep/worktree-cleanup-receipts-v1.jsonl`. `.worktrees/` is added to both the versioned ignore
+and the repository-private exclude. JSON `list`/`status` output exposes neither Vault paths nor
+contents.
 
 `create` is idempotent when slug, path, and branch already match. Collisions fail closed. Failures
-after reservation remain `failed`; run `worktree status <slug>` and follow the `recovery` field.
-`doctor` also reports this debt under `[worktrees]` without repairing it.
+after reservation remain `failed`; run `worktree status <slug>` and follow `recovery`. `doctor`
+also reports create or cleanup debt under `[worktrees]` without repairing it.
 
-## VS Code and exit codes
+## VS Code
 
-`--open vscode` and `worktree open` validate `code --version`, then open a new window with
-`code -n`. Use `init --vscode-worktree-tasks` or `sync --vscode-worktree-tasks` to create local
-tasks; an existing or tracked `.vscode/tasks.json`, even when deleted in the checkout, is never
-overwritten.
+`--open vscode` and `worktree open` validate `code --version`, then open a new window with `code -n`.
+Use `init --vscode-worktree-tasks` or `sync --vscode-worktree-tasks` to create local tasks, including
+**WendKeep: Finish merged worktree**; an existing or tracked `.vscode/tasks.json`, even when deleted
+in the checkout, is never overwritten.
 
-Exit `0` means success. Usage, binding, safety, Git, or editor failures return `2` with a stable
-`WENDKEEP_WORKTREE_*` code. The command never removes or merges a worktree.
+Exit `0` means success. Usage, binding, safety, proof, Git, or editor failures return `2` with a
+stable `WENDKEEP_WORKTREE_*` code. No command merges or uses force to discard a checkout.
 
 ## Examples
 
-```bash
+PowerShell:
+
+```powershell
 npx --no-install wendkeep worktree create auth --open vscode
-npx --no-install wendkeep worktree status auth --json
-npx --no-install wendkeep worktree list
+npx --no-install wendkeep worktree finish auth --pr 72 --open-main
+npx --no-install wendkeep worktree cleanup --merged --dry-run --json
+```
+
+POSIX:
+
+```bash
+npx --no-install wendkeep worktree cleanup --merged --apply
+npx --no-install wendkeep worktree remove spike --reason "PR cancelled"
+npx --no-install wendkeep worktree prune --dry-run
 ```
 
 ## Expected result
 
-`create auth` produces `.worktrees/auth` on branch `wk/auth`; the main and linked worktrees resolve
-the same `projectId` and Vault, while the main checkout remains clean.
+`create auth` produces `.worktrees/auth` on branch `wk/auth`. After a proven merge, `finish` removes
+the checkout and local ref, closes only its active context, and preserves the Vault, sessions,
+evidence, and receipt.
 
 ## Common errors and diagnosis
 
@@ -79,13 +120,20 @@ the same `projectId` and Vault, while the main checkout remains clean.
 - `WENDKEEP_WORKTREE_PATH_OUTSIDE_ROOT` or `WENDKEEP_WORKTREE_PATH_SYMLINK_ESCAPE`: use a relative
   root contained in the main worktree, without an intermediate symlink/junction.
 - `WENDKEEP_WORKTREE_COLLISION`: the slug, path, or branch represents different state; run `status`.
-- `WENDKEEP_WORKTREE_GIT_FAILED` or `WENDKEEP_WORKTREE_BASE_UNRESOLVED`: repair the Git state and
-  retry the command shown in `recovery`.
+- `WENDKEEP_WORKTREE_PR_INVALID`, `WENDKEEP_WORKTREE_PR_NOT_MERGED`,
+  `WENDKEEP_WORKTREE_PR_MISMATCH`, or `WENDKEEP_WORKTREE_PR_MERGE_UNREACHABLE`: correct/associate
+  the PR, update the local base, and retry without manually removing the worktree.
+- `WENDKEEP_WORKTREE_DIRTY`, `WENDKEEP_WORKTREE_ACTIVE_SESSION`,
+  `WENDKEEP_WORKTREE_ACTIVE_DELIVERY`, `WENDKEEP_WORKTREE_OUTBOX_PENDING`, or
+  `WENDKEEP_WORKTREE_HANDOFF_PENDING`: complete the recovery named by the blocker.
+- `WENDKEEP_WORKTREE_CLEANUP_BUSY`: another operation owns the reservation; if the directory is
+  already gone, retry the same command/proof to resume. Use `doctor` for failed/incomplete state.
+- `WENDKEEP_WORKTREE_REMOTE_UNAVAILABLE` or `WENDKEEP_WORKTREE_REMOTE_DIVERGED`: the local branch is
+  preserved; recover the network or review the divergence before authorizing again.
 - `WENDKEEP_WORKTREE_REGISTRY_*`, `WENDKEEP_WORKTREE_*_MISMATCH`, or `WENDKEEP_VAULT_*` errors:
   preserve the artifacts and use `doctor` to diagnose the registry/binding.
 - `WENDKEEP_WORKTREE_EDITOR_NOT_FOUND` or `WENDKEEP_WORKTREE_EDITOR_OPEN_FAILED`: make `code`
   available on PATH or use `--open none`.
-- `failed`/`missing` state: read `recovery` from `status --json` and doctor's `[worktrees]` section.
 
 ## Next steps
 

package/docs/pt-BR/commands/worktrees.md

@@ -4,23 +4,24 @@
 
 ## Objetivo
 
-Criar linked worktrees isoladas que continuam vinculadas ao mesmo projeto e Vault canônico,
-sem copiar estado privado para arquivos versionados.
+Criar e encerrar linked worktrees isoladas que continuam vinculadas ao mesmo projeto e Vault
+canônico, sem copiar estado privado para arquivos versionados nem descartar trabalho local.
 
 ## Quando usar
 
-Use ao iniciar uma implementação isolada, listar checkouts gerenciados, diagnosticar uma criação
-parcial ou abrir uma worktree já pronta no VS Code.
+Use ao iniciar uma implementação isolada, listar checkouts gerenciados, diagnosticar uma operação
+parcial, abrir uma worktree no VS Code ou limpá-la depois de um PR comprovadamente merged.
 
 ## Quando não usar
 
-Não use para remover, mesclar ou fazer self-merge de worktrees. Essas operações permanecem fora
-desta capability.
+Não use para fazer merge do PR, descartar checkout dirty/untracked nem remover branch remota sem
+autorização explícita. `finish` consome um merge já concluído; não faz self-merge.
 
 ## Pré-requisitos
 
 - Repositório Git com o projeto já vinculado ao Vault por `.wendkeep.json`.
-- Git disponível no `PATH`; para abertura, o comando `code` do VS Code também deve existir.
+- Git disponível no `PATH`; `finish` também requer `gh` autenticado para consultar o GitHub.
+- Para abertura, o comando `code` do VS Code deve existir.
 
 ## Sintaxe
 
@@ -29,46 +30,87 @@ npx --no-install wendkeep worktree create <slug> [--base <ref>] [--branch <nome>
 npx --no-install wendkeep worktree list [--json]
 npx --no-install wendkeep worktree status [<slug>] [--json]
 npx --no-install wendkeep worktree open <slug> [--editor vscode] [--json]
+npx --no-install wendkeep worktree finish <slug> [--pr <número|url>] [--delete-remote] [--open-main] [--json]
+npx --no-install wendkeep worktree cleanup --merged [--dry-run|--apply] [--json]
+npx --no-install wendkeep worktree remove <slug> --reason <texto> [--json]
+npx --no-install wendkeep worktree prune [--dry-run|--apply] [--json]
 ```
 
 Todas aceitam `--project <raiz>`. O padrão cria `.worktrees/<slug>` a partir da base detectada e
-usa a branch `wk/<slug>`. `worktrees.root`, quando configurado, deve ser um
-path relativo não vazio. Slug e branch são validados pelo Git; paths que escapam da raiz ou
-atravessam symlink/junction são rejeitados antes da mutação.
+usa a branch `wk/<slug>`. `worktrees.root`, quando configurado, deve ser um path relativo não vazio.
+Slug e branch são validados pelo Git; paths que escapam da raiz ou atravessam symlink/junction são
+rejeitados antes da mutação.
+
+## Fechamento seguro
+
+`finish` executa `git fetch --prune` quando existe `origin`, consulta o PR por adapter GitHub e
+exige estado `MERGED`, branch coerente e merge commit alcançável pela base local. O número/URL fica
+associado ao registry. Antes da remoção, o preflight falha fechado diante de checkout dirty ou
+untracked, sessão ativa, delivery ativa, memory outbox ou handoff pendente.
+
+Depois da reserva sob lock, o comando remove a linked worktree, fecha somente seus active contexts,
+faz prune, apaga o ref local por CAS e grava receipt JSONL append-only no Git common-dir. Isso aceita
+merge commit, squash e rebase sem usar `git branch -D`. Reexecução com a mesma prova é idempotente;
+se a pasta sumiu entre etapas, a reserva interrompida é retomada. `doctor` mostra cleanup
+interrompido/failed e uma recuperação objetiva.
+
+`--delete-remote` é a única autorização para excluir a branch remota. A branch deve continuar no
+head comprovado; divergência ou rede indisponível bloqueia. Branch já ausente é sucesso idempotente.
+`--open-main` abre a worktree principal somente depois da conclusão.
+
+## Cleanup, remove e prune
+
+`cleanup --merged` e `prune` são dry-run por padrão. `--dry-run` apenas torna essa intenção
+explícita; somente `--apply` permite mutação. O plano é ordenado por slug e não altera Git,
+registry, contexts ou receipts. `cleanup --merged` atua apenas em entries com PR associado e merge
+revalidado. `remove --reason` é a saída auditável para abandono explícito: dispensa prova de merge,
+mas mantém todo o preflight e preserva as branches local e remota.
 
 ## Opções e códigos de saída
 
 O registry fica no Git common-dir, em `wendkeep/worktrees-v1.json`, sob lock multiprocesso. Ele
-guarda identidade do repositório/worktree e o binding canônico; `.wendkeep.json` permanece
-inalterado. `.worktrees/` entra no ignore versionado e no exclude privado do repositório. A saída
-JSON de `list`/`status` não expõe path nem conteúdo do Vault. A saída humana apresenta, por
-worktree, slug, identidade, path do checkout, branch, HEAD, estado e saúde do binding.
+guarda identidade do repositório/worktree, binding canônico, PR e estado transitório de cleanup;
+`.wendkeep.json` permanece inalterado. Receipts ficam em
+`wendkeep/worktree-cleanup-receipts-v1.jsonl`. `.worktrees/` entra no ignore versionado e no exclude
+privado. A saída JSON de `list`/`status` não expõe path nem conteúdo do Vault.
 
 `create` é idempotente quando slug, path e branch já correspondem. Colisões falham fechadas.
-Falhas depois da reserva ficam como `failed`; rode `worktree status <slug>` e siga o campo
-`recovery`. `doctor` também lista dívida em `[worktrees]` sem repará-la.
+Falhas depois da reserva ficam como `failed`; rode `worktree status <slug>` e siga `recovery`.
+`doctor` também lista dívida de criação ou cleanup em `[worktrees]` sem repará-la.
 
-## VS Code e códigos de saída
+## VS Code
 
 `--open vscode` e `worktree open` validam `code --version` e abrem uma janela nova com `code -n`.
-Use `init --vscode-worktree-tasks` ou `sync --vscode-worktree-tasks` para criar tarefas locais;
-um `.vscode/tasks.json` existente ou rastreado, mesmo removido no checkout, nunca é sobrescrito.
+Use `init --vscode-worktree-tasks` ou `sync --vscode-worktree-tasks` para criar tarefas locais,
+incluindo **WendKeep: Finish merged worktree**; um `.vscode/tasks.json` existente ou rastreado,
+mesmo removido no checkout, nunca é sobrescrito.
 
-Exit `0` indica sucesso. Erro de uso, binding, segurança, Git ou editor retorna `2` com código
-estável `WENDKEEP_WORKTREE_*`. O comando nunca remove ou mescla uma worktree.
+Exit `0` indica sucesso. Erro de uso, binding, segurança, prova, Git ou editor retorna `2` com código
+estável `WENDKEEP_WORKTREE_*`. Nenhum comando faz merge ou usa force para descartar checkout.
 
 ## Exemplos
 
-```bash
+PowerShell:
+
+```powershell
 npx --no-install wendkeep worktree create auth --open vscode
-npx --no-install wendkeep worktree status auth --json
-npx --no-install wendkeep worktree list
+npx --no-install wendkeep worktree finish auth --pr 72 --open-main
+npx --no-install wendkeep worktree cleanup --merged --dry-run --json
+```
+
+POSIX:
+
+```bash
+npx --no-install wendkeep worktree cleanup --merged --apply
+npx --no-install wendkeep worktree remove spike --reason "PR cancelado"
+npx --no-install wendkeep worktree prune --dry-run
 ```
 
 ## Resultado esperado
 
-`create auth` produz `.worktrees/auth` na branch `wk/auth`; main e linked worktree resolvem o
-mesmo `projectId` e Vault, e o checkout principal permanece limpo.
+`create auth` produz `.worktrees/auth` na branch `wk/auth`. Depois do merge comprovado, `finish`
+remove o checkout e o ref local, fecha apenas seu active context e preserva Vault, sessões,
+evidências e receipt.
 
 ## Erros comuns e diagnóstico
 
@@ -77,13 +119,20 @@ mesmo `projectId` e Vault, e o checkout principal permanece limpo.
 - `WENDKEEP_WORKTREE_PATH_OUTSIDE_ROOT` ou `WENDKEEP_WORKTREE_PATH_SYMLINK_ESCAPE`: use uma raiz
   relativa contida no main worktree, sem symlink/junction intermediário.
 - `WENDKEEP_WORKTREE_COLLISION`: slug, path ou branch já representa outro estado; rode `status`.
-- `WENDKEEP_WORKTREE_GIT_FAILED` ou `WENDKEEP_WORKTREE_BASE_UNRESOLVED`: corrija o estado Git e
-  repita o comando indicado em `recovery`.
-- Erros `WENDKEEP_WORKTREE_REGISTRY_*`, `WENDKEEP_WORKTREE_*_MISMATCH` ou
-  `WENDKEEP_VAULT_*`: preserve os artefatos e use `doctor` para diagnosticar registry/binding.
+- `WENDKEEP_WORKTREE_PR_INVALID`, `WENDKEEP_WORKTREE_PR_NOT_MERGED`,
+  `WENDKEEP_WORKTREE_PR_MISMATCH` ou `WENDKEEP_WORKTREE_PR_MERGE_UNREACHABLE`: corrija/associe o PR,
+  atualize a base local e repita sem remover a worktree manualmente.
+- `WENDKEEP_WORKTREE_DIRTY`, `WENDKEEP_WORKTREE_ACTIVE_SESSION`,
+  `WENDKEEP_WORKTREE_ACTIVE_DELIVERY`, `WENDKEEP_WORKTREE_OUTBOX_PENDING` ou
+  `WENDKEEP_WORKTREE_HANDOFF_PENDING`: conclua a recuperação indicada pelo blocker.
+- `WENDKEEP_WORKTREE_CLEANUP_BUSY`: outra operação ainda possui a reserva; se a pasta já sumiu,
+  repita o mesmo comando/prova para retomar. Use `doctor` para reservations failed/incompletas.
+- `WENDKEEP_WORKTREE_REMOTE_UNAVAILABLE` ou `WENDKEEP_WORKTREE_REMOTE_DIVERGED`: a branch local é
+  preservada; recupere rede ou revise a divergência antes de autorizar novamente.
+- Erros `WENDKEEP_WORKTREE_REGISTRY_*`, `WENDKEEP_WORKTREE_*_MISMATCH` ou `WENDKEEP_VAULT_*`:
+  preserve os artefatos e use `doctor` para diagnosticar registry/binding.
 - `WENDKEEP_WORKTREE_EDITOR_NOT_FOUND` ou `WENDKEEP_WORKTREE_EDITOR_OPEN_FAILED`: disponibilize
   `code` no PATH ou use `--open none`.
-- Estado `failed`/`missing`: leia `recovery` em `status --json` e o bloco `[worktrees]` do `doctor`.
 
 ## Próximos passos
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.76.9",
+  "version": "0.77.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -41,7 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "precheck": "node --check src/worktree.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check packages/vault/src/worktree-metadata.mjs",
+    "precheck": "node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check packages/vault/src/worktree-metadata.mjs",
     "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/active-context-health.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/active-context-handoff-evidence.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",

package/packages/cli/src/index.mjs

@@ -249,7 +249,7 @@ async function main(argv) {
     }
     case 'worktree': {
       const { runWorktree } = await import('../../../src/worktree.mjs');
-      process.exit(runWorktree(rest));
+      process.exit(await runWorktree(rest));
       break;
     }
     case 'context': {