wendkeep 0.76.2 → 0.76.4

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.76.4] — 2026-08-22
+
+### Added
+
+- **Registry multi-contexto.** `active_contexts` mantém change, branch e HEAD por
+  `repository_id` + `worktree_id` + `work_session_id`, com schema, revisão, CAS e writes atômicos;
+  duas worktrees ou sessões deixam de sobrescrever o foco operacional umas das outras.
+- **Resolução causal de change.** Change, spec e verify usam a sessão/worktree chamadora; ausência
+  de sessão só aceita um contexto inequívoco e qualquer ambiguidade falha fechado.
+- **Compatibilidade conservadora.** `CURRENT_CHANGE.md` é somente projeção quando há um único
+  contexto ativo, e a migração legada não inventa worktree ou sessão quando a identidade não pode
+  ser provada.
+
+## [0.76.3] — 2026-08-21
+
+### Added
+
+- **Recuperação explícita do contexto em quarentena.** `context status --session <id>` inventaria
+  candidatas `reserved`/`observed` sem paths locais; `context recover` exige seleção, revisão CAS,
+  motivo e correspondência integral com o checkout/HEAD antes de limpar o conflito.
+- **Receipt pós-conflito.** A recuperação preserva change, lease e autorizações, incrementa a revisão
+  e registra evidência sanitizada `from/to`; revision stale, identidade divergente ou falha de
+  persistência mantêm registry e quarentena intactos.
+
 ## [0.76.2] — 2026-08-21
 
 ### Fixed

package/README.en.md

@@ -115,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
@@ -239,7 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 |---|---|---|
 | **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) |
-| **Active context** | `context switch`, causal branch transition, and rollback | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.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) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |

package/README.md

@@ -115,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
@@ -239,7 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 |---|---|---|
 | **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) |
-| **Active context** | `context switch`, causal branch transition, and rollback | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.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) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |

package/docs/en/commands/changes-and-verification.md

@@ -25,12 +25,12 @@ Initialize the project, keep the vault healthy, and provide a valid `wendkeep.se
 ## Syntax
 
 ```bash
-npx wendkeep change new <slug> [--simple|--guide]
-npx wendkeep change status [slug]
-npx wendkeep spec effective --change <slug>
+npx wendkeep change new <slug> [--simple|--guide] [--session <id>]
+npx wendkeep change status [slug] [--session <id>]
+npx wendkeep spec effective [--change <slug>] [--session <id>]
 npx wendkeep sensors list
-npx wendkeep verify [--deep] [--change <slug>]
-npx wendkeep change archive <slug>
+npx wendkeep verify [--deep] [--change <slug>] [--session <id>]
+npx wendkeep change archive <slug> [--session <id>]
 ```
 
 ## Options and exit codes
@@ -43,6 +43,8 @@ npx wendkeep change archive <slug>
   without archiving it.
 - `change continue <archived> <new>` starts follow-up work without inheriting stale proof.
 - `change bind <slug> --session <id>` attaches an existing session.
+- `--session <id>` selects the causal `active_contexts` entry for implicit commands. Without it,
+  only one unambiguous active context for the worktree is accepted; ambiguity returns exit `2`.
 - `change relink [--apply]` and `change backlink [--apply]` repair graph links; preview is default.
 - `change abandon <slug>` drops work without an ADR; `archive --force` needs explicit human choice.
 - `wendkeep spec list|show|effective|migrate|rebase` manages living contracts and deltas.
@@ -54,6 +56,7 @@ npx wendkeep change archive <slug>
 
 ```bash
 npx wendkeep change new tenant-login
+npx wendkeep change use tenant-login --session <id>
 npx wendkeep change new internal-adjustment --guide
 npx wendkeep spec effective --change tenant-login
 npx wendkeep change done 1.1 --change tenant-login
@@ -82,6 +85,10 @@ tool runs, it compares the session, project, Git root, remote, branch, and workt
 recorded in `SESSION_REGISTRY.json`. Missing, ambiguous, concurrent, or cross-project targets are
 blocked before the tool.
 
+Implicit change focus comes from `active_contexts`, not `CURRENT_CHANGE.md`. Its key combines
+`repository_id`, `worktree_id`, and `work_session_id`; the Markdown pointer remains only a
+compatibility projection when there is one unambiguous context.
+
 The [local Observer](observer.md) is a read-only observability projection: the vault and change
 remain local authorities. Observer queries do not complete, archive, repair, or promote state in a
 vault.

package/docs/en/commands/context.md

@@ -4,18 +4,19 @@
 
 ## Purpose
 
-Switch the Git branch and the same session's causal scope together inside the current worktree,
-without opening a new session or weakening the guard.
+Inspect and move the same session's causal scope with proof of the current checkout: during a
+normal branch transition or when explicitly recovering a divergence already under quarantine.
 
 ## When to use
 
-Use `context switch` when an active session must create or select another branch in the same
-worktree and continue mutating the repository after the transition.
+Use `context switch` to create or select another branch in the same worktree. If the registry
+already records `project_scope_conflict`, use `context status` to inventory `reserved` and
+`observed` without local paths; recover only through `context recover` and an explicit human choice.
 
 ## When not to use
 
-Do not use it to move to another worktree, adopt an already-divergent scope, repair the registry,
-or replace `worktree create`. Those cases require a separate physical context or explicit diagnosis.
+Do not use it to move to another worktree, hand-edit the registry, or replace `worktree create`.
+Recovery never selects a candidate automatically or accepts a scope that no longer matches HEAD.
 
 ## Prerequisites
 
@@ -27,6 +28,8 @@ or replace `worktree create`. Those cases require a separate physical context or
 
 ```bash
 npx --no-install wendkeep context switch <branch> [--create] [--session <id>] [--project <root>] [--vault <vault>] [--json]
+npx --no-install wendkeep context status --session <id> [--project <root>] [--vault <vault>] [--json]
+npx --no-install wendkeep context recover --session <id> --select <reserved|observed> --revision <n> --reason <text> [--project <root>] [--vault <vault>] [--json]
 ```
 
 Without `--session`, exactly one active session must fully match the current scope. `--create`
@@ -36,6 +39,9 @@ uses `git switch -c`; without it, the command follows `git switch` semantics.
 
 - `--create`: create the branch from the current HEAD.
 - `--session <id>`: select the causal session explicitly; recommended whenever selection is unclear.
+- `--select <reserved|observed>`: select exactly one quarantined candidate; required for recovery.
+- `--revision <n>`: CAS against the revision returned by `context status`; required for recovery.
+- `--reason <text>`: auditable reason, sanitized and limited to 240 characters.
 - `--project <root>` and `--vault <vault>`: select the binding and paths for manual use.
 - `--json`: emit status, session id, branch, HEAD, revision, and event without exposing the Vault.
 
@@ -49,6 +55,8 @@ ambiguity, scope mismatch, conflict, Git failure, or rollback returns `2` with a
 npx --no-install wendkeep context switch wk/auth --create
 npx --no-install wendkeep context switch main --session 019abc-session-id
 npx --no-install wendkeep context switch wk/auth --session 019abc-session-id --json
+npx --no-install wendkeep context status --session 019abc-session-id --json
+npx --no-install wendkeep context recover --session 019abc-session-id --select observed --revision 7 --reason "checkout confirmed"
 ```
 
 Do not replace it with the raw command below while the harness is active:
@@ -70,11 +78,38 @@ authorizations are preserved.
 If validation or persistence fails after the switch, rollback restores the previous branch or
 detached HEAD; a branch created by the failed attempt is removed as well.
 
+During recovery, both candidates must be complete and retain the same causal identity. The selected
+candidate must fully match the current project, repository, remote, worktree, branch, and HEAD.
+Under the registry lock, the command revalidates the revision, increments `context_revision`,
+preserves the change/lease/authorizations, clears only the quarantine, and appends a sanitized
+receipt to `context_recoveries`. Any failure leaves the registry and quarantine byte-identical.
+This is fail-closed: no candidate, receipt, or partial scope is published after a failed check.
+
+### Multi-context change registry
+
+`SESSION_REGISTRY.json` keeps `active_contexts` with its own schema and revision. Each entry is
+identified by `repository_id` + `worktree_id` + `work_session_id`; branch, HEAD, and `change_slug`
+belong to that entry. Two worktrees can therefore select different changes without overwriting
+each other's operational focus.
+
+With an explicit causal session, change, spec, and verify resolve only the matching entry. Without
+a session, only one active entry for the worktree is accepted; two sessions produce ambiguity and
+the operation must fail closed without silently selecting a change.
+
+`CURRENT_CHANGE.md` is only a derived projection: it contains a change when there is one single,
+unambiguous active context. With zero or multiple contexts it stays empty. Migration is conservative
+and never invents a worktree or session identity. The legacy pointer becomes a context only
+when one active session, a complete scope, and worktree metadata prove one identity.
+
 ## Common errors and diagnosis
 
 - `WENDKEEP_CONTEXT_AMBIGUOUS`: pass `--session <id>`; no candidate is selected silently.
-- `WENDKEEP_CONTEXT_SCOPE_MISMATCH` or `WENDKEEP_CONTEXT_SCOPE_CONFLICT`: return to the reserved
-  checkout or diagnose the session; the command never adopts a post-hoc divergence.
+- `WENDKEEP_CONTEXT_SCOPE_MISMATCH`: the selected candidate does not prove the current checkout/HEAD;
+  run `context status` again and select only a candidate with `matches_actual: true`.
+- `WENDKEEP_CONTEXT_SCOPE_CONFLICT`: the session is not quarantined or a candidate is missing.
+- `WENDKEEP_CONTEXT_CAS_MISMATCH`: the revision changed; discard the stale decision and rerun status.
+- `WENDKEEP_CONTEXT_IDENTITY_CHANGED`: candidates belong to different causal identities; preserve
+  quarantine and diagnose the registry.
 - `WENDKEEP_CONTEXT_CONFLICT`: another active context occupies the target; use another
   branch/worktree or close the competing context correctly.
 - `WENDKEEP_CONTEXT_GIT`: fix the branch, conflicting dirty state, or Git error and retry.

package/docs/pt-BR/commands/changes-and-verification.md

@@ -25,12 +25,12 @@ Tenha o projeto inicializado, um vault saudável e `wendkeep.sensors.json` váli
 ## Sintaxe
 
 ```bash
-npx wendkeep change new <slug> [--simple|--guide]
-npx wendkeep change status [slug]
-npx wendkeep spec effective --change <slug>
+npx wendkeep change new <slug> [--simple|--guide] [--session <id>]
+npx wendkeep change status [slug] [--session <id>]
+npx wendkeep spec effective [--change <slug>] [--session <id>]
 npx wendkeep sensors list
-npx wendkeep verify [--deep] [--change <slug>]
-npx wendkeep change archive <slug>
+npx wendkeep verify [--deep] [--change <slug>] [--session <id>]
+npx wendkeep change archive <slug> [--session <id>]
 ```
 
 ## Opções e códigos de saída
@@ -43,6 +43,8 @@ npx wendkeep change archive <slug>
   trabalho sem arquivar.
 - `change continue <arquivada> <nova>` abre continuação sem herdar evidência antiga.
 - `change bind <slug> --session <id>` liga uma sessão existente.
+- `--session <id>` seleciona o `active_contexts` causal nos comandos implícitos. Sem a opção,
+  somente um contexto ativo inequívoco da worktree é aceito; ambiguidade retorna exit `2`.
 - `change relink [--apply]` e `change backlink [--apply]` reparam o grafo; dry-run é o padrão.
 - `change abandon <slug>` descarta sem ADR; `archive --force` exige decisão humana explícita.
 - `wendkeep spec list|show|effective|migrate|rebase` administra contratos vivos e deltas.
@@ -54,6 +56,7 @@ npx wendkeep change archive <slug>
 
 ```bash
 npx wendkeep change new login-tenant
+npx wendkeep change use login-tenant --session <id>
 npx wendkeep change new ajuste-interno --guide
 npx wendkeep spec effective --change login-tenant
 npx wendkeep change done 1.1 --change login-tenant
@@ -82,6 +85,10 @@ uma ferramenta de escrita suportada, ele compara sessão, projeto, raiz Git, rem
 worktree com a lease registrada no `SESSION_REGISTRY.json`. Um alvo ausente, ambíguo, concorrente ou
 fora do projeto é bloqueado antes da ferramenta.
 
+O foco implícito de change vem de `active_contexts`, não de `CURRENT_CHANGE.md`. A chave combina
+`repository_id`, `worktree_id` e `work_session_id`; o ponteiro Markdown permanece apenas como
+projeção compatível quando existe um único contexto inequívoco.
+
 O [Observer local](observer.md) é uma projeção read-only da observabilidade: o vault e a change
 continuam autoridades locais. Consultas do Observer não concluem, arquivam, reparam ou promovem
 estado no vault.

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

@@ -4,18 +4,19 @@
 
 ## Objetivo
 
-Trocar a branch Git e a scope causal da mesma sessão juntas, dentro da worktree atual, sem abrir
-uma nova sessão e sem relaxar o guard.
+Inspecionar e mover a scope causal da mesma sessão com prova do checkout atual: durante uma troca
+de branch normal ou ao recuperar explicitamente uma divergência já colocada em quarentena.
 
 ## Quando usar
 
-Use `context switch` quando uma sessão ativa precisa criar ou selecionar outra branch na mesma
-worktree e deve continuar mutando o repositório depois da troca.
+Use `context switch` para criar ou selecionar outra branch na mesma worktree. Se o registry já
+registrou `project_scope_conflict`, use `context status` para inventariar `reserved` e `observed`
+sem paths locais; recupere somente com `context recover` e uma seleção humana explícita.
 
 ## Quando não usar
 
-Não use para mudar de worktree, adotar uma scope já divergente, reparar o registry ou substituir
-`worktree create`. Esses casos exigem outro contexto físico ou diagnóstico explícito.
+Não use para mudar de worktree, editar o registry à mão ou substituir `worktree create`. Recovery
+não escolhe a candidata automaticamente e não aceita uma scope que deixou de corresponder ao HEAD.
 
 ## Pré-requisitos
 
@@ -27,6 +28,8 @@ Não use para mudar de worktree, adotar uma scope já divergente, reparar o regi
 
 ```bash
 npx --no-install wendkeep context switch <branch> [--create] [--session <id>] [--project <raiz>] [--vault <cofre>] [--json]
+npx --no-install wendkeep context status --session <id> [--project <raiz>] [--vault <cofre>] [--json]
+npx --no-install wendkeep context recover --session <id> --select <reserved|observed> --revision <n> --reason <texto> [--project <raiz>] [--vault <cofre>] [--json]
 ```
 
 Sem `--session`, exatamente uma sessão ativa deve corresponder integralmente à scope atual. Use
@@ -36,6 +39,9 @@ Sem `--session`, exatamente uma sessão ativa deve corresponder integralmente à
 
 - `--create`: cria a branch a partir do HEAD atual.
 - `--session <id>`: seleciona explicitamente a sessão causal; recomendado quando houver dúvida.
+- `--select <reserved|observed>`: escolhe exatamente uma candidata da quarentena; obrigatório no recovery.
+- `--revision <n>`: CAS contra a revisão exibida por `context status`; obrigatório no recovery.
+- `--reason <texto>`: justificativa auditável, sanitizada e limitada a 240 caracteres.
 - `--project <raiz>` e `--vault <cofre>`: selecionam binding e paths para uso manual.
 - `--json`: emite status, session id, branch, HEAD, revisão e evento sem expor o Vault.
 
@@ -48,6 +54,8 @@ scope divergente, conflito, falha Git ou rollback retorna `2` com um código `WE
 npx --no-install wendkeep context switch wk/auth --create
 npx --no-install wendkeep context switch main --session 019abc-session-id
 npx --no-install wendkeep context switch wk/auth --session 019abc-session-id --json
+npx --no-install wendkeep context status --session 019abc-session-id --json
+npx --no-install wendkeep context recover --session 019abc-session-id --select observed --revision 7 --reason "checkout confirmado"
 ```
 
 Não substitua pelo comando cru abaixo quando o harness estiver ativo:
@@ -68,11 +76,37 @@ worktree, provider e session id não mudaram, incrementa `context_revision` e an
 Se qualquer validação ou persistência falhar depois do switch, o rollback restaura a branch ou
 detached HEAD anterior; uma branch criada pela tentativa também é removida.
 
+No recovery, ambas as candidatas precisam ser completas e manter a mesma identidade causal. A
+selecionada deve corresponder integralmente a projeto, repositório, remoto, worktree, branch e HEAD
+atuais. Sob o lock do registry, o comando revalida a revisão, incrementa `context_revision`, preserva
+change/lease/autorizações, limpa somente a quarentena e anexa um receipt sanitizado em
+`context_recoveries`. Qualquer falha deixa registry e quarentena byte a byte intactos.
+
+### Registry multi-contexto de changes
+
+O `SESSION_REGISTRY.json` mantém `active_contexts` com schema e revisão próprios. Cada entrada é
+identificada por `repository_id` + `worktree_id` + `work_session_id`; branch, HEAD e `change_slug`
+pertencem a essa entrada. Assim, duas worktrees podem selecionar changes diferentes sem
+sobrescrever o foco uma da outra.
+
+Com sessão causal explícita, change, spec e verify resolvem somente a entrada correspondente. Sem
+sessão, uma única entrada ativa da worktree pode ser usada; duas sessões compatíveis causam
+ambiguidade e a operação falha fechada, sem escolher uma change em silêncio.
+
+`CURRENT_CHANGE.md` é apenas uma projeção derivada: contém a change somente quando existe um único
+contexto ativo inequívoco. Com zero ou múltiplos contextos, fica vazio. A migração é conservadora:
+não inventa uma identidade de worktree ou sessão. O ponteiro legado só vira contexto quando uma sessão
+ativa, scope completa e metadados da worktree provam uma única identidade.
+
 ## Erros comuns e diagnóstico
 
 - `WENDKEEP_CONTEXT_AMBIGUOUS`: informe `--session <id>`; nenhuma candidata é escolhida em silêncio.
-- `WENDKEEP_CONTEXT_SCOPE_MISMATCH` ou `WENDKEEP_CONTEXT_SCOPE_CONFLICT`: volte ao checkout
-  reservado ou diagnostique a sessão; o comando não adota uma divergência posterior.
+- `WENDKEEP_CONTEXT_SCOPE_MISMATCH`: a candidata escolhida não prova o checkout/HEAD atual; rode
+  `context status` novamente e selecione apenas uma candidata com `matches_actual: true`.
+- `WENDKEEP_CONTEXT_SCOPE_CONFLICT`: a sessão não está em quarentena ou uma candidata está ausente.
+- `WENDKEEP_CONTEXT_CAS_MISMATCH`: a revisão mudou; descarte a decisão antiga e repita o status.
+- `WENDKEEP_CONTEXT_IDENTITY_CHANGED`: as candidatas pertencem a identidades causais diferentes;
+  preserve a quarentena e diagnostique o registry.
 - `WENDKEEP_CONTEXT_CONFLICT`: outro contexto ativo ocupa o destino; use outra branch/worktree ou
   encerre corretamente o contexto concorrente.
 - `WENDKEEP_CONTEXT_GIT`: corrija a branch, dirty state conflitante ou erro do Git e repita.

package/hooks/active-context-store.mjs

@@ -0,0 +1,232 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { mutateSessionRegistry, readSessionRegistry } from './obsidian-common.mjs';
+import { mkdirVaultPath, writeVaultFileSync } from './vault-path-safety.mjs';
+
+export const ACTIVE_CONTEXTS_SCHEMA_VERSION = 1;
+const POINTER = '.brain/CURRENT_CHANGE.md';
+const ID_PATTERN = /^[A-Za-z0-9._-]{1,160}$/;
+const SLUG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/;
+
+function contextError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function requiredId(value, label) {
+  const normalized = String(value || '').trim();
+  if (!ID_PATTERN.test(normalized)) {
+    throw contextError('WENDKEEP_ACTIVE_CONTEXT_IDENTITY_INVALID', `${label} inválido ou ausente`);
+  }
+  return normalized;
+}
+
+function optionalText(value, maxLength = 240) {
+  const normalized = String(value || '').trim();
+  return normalized.length <= maxLength ? normalized : normalized.slice(0, maxLength);
+}
+
+function normalizeIdentity(identity = {}, { requireWorkSession = true } = {}) {
+  const workSessionId = requireWorkSession
+    ? requiredId(identity.workSessionId ?? identity.work_session_id, 'work_session_id')
+    : optionalText(identity.workSessionId ?? identity.work_session_id, 160);
+  return {
+    projectId: requiredId(identity.projectId ?? identity.project_id, 'project_id'),
+    repositoryId: requiredId(identity.repositoryId ?? identity.repository_id, 'repository_id'),
+    worktreeId: requiredId(identity.worktreeId ?? identity.worktree_id, 'worktree_id'),
+    workSessionId,
+    branch: optionalText(identity.branch, 240),
+    headSha: optionalText(identity.headSha ?? identity.head_sha, 80),
+  };
+}
+
+export function activeContextKey(identity) {
+  const normalized = normalizeIdentity(identity);
+  return `${normalized.repositoryId}:${normalized.worktreeId}:${normalized.workSessionId}`;
+}
+
+function contextsOf(registry) {
+  return registry?.active_contexts && typeof registry.active_contexts === 'object'
+    && !Array.isArray(registry.active_contexts)
+    ? registry.active_contexts : {};
+}
+
+function currentGlobalRevision(registry) {
+  const value = Number(registry?.active_contexts_revision);
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function currentContextRevision(context) {
+  const value = Number(context?.revision);
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function activeContexts(registry) {
+  return Object.entries(contextsOf(registry)).filter(([, context]) => context?.state === 'active');
+}
+
+function legacyProjection(registry) {
+  const active = activeContexts(registry);
+  if (active.length !== 1) return '';
+  return String(active[0][1]?.change_slug || '').trim();
+}
+
+export function projectLegacyActiveChange(vaultBase, registry = readSessionRegistry(vaultBase)) {
+  const slug = legacyProjection(registry);
+  mkdirVaultPath(vaultBase, join(vaultBase, '.brain'), { label: 'raiz de controle da change' });
+  writeVaultFileSync(
+    vaultBase,
+    join(vaultBase, POINTER),
+    slug ? `change: ${slug}\n` : 'change:\n',
+    'utf8',
+    { label: 'projeção legada CURRENT_CHANGE.md' },
+  );
+  return slug;
+}
+
+export function resolveActiveContext(vaultBase, query = {}) {
+  const normalized = normalizeIdentity(query, { requireWorkSession: false });
+  const registry = readSessionRegistry(vaultBase);
+  let workSessionId = normalized.workSessionId;
+  const sessionId = optionalText(query.sessionId ?? query.session_id, 160);
+  if (!workSessionId && sessionId) {
+    const entry = registry.sessions?.[sessionId];
+    if (entry?.status !== 'active' || !entry.work_session_id) {
+      throw contextError('WENDKEEP_ACTIVE_CONTEXT_NOT_FOUND', 'sessão causal ativa não encontrada');
+    }
+    workSessionId = String(entry.work_session_id);
+  }
+
+  const candidates = activeContexts(registry).filter(([, context]) => (
+    context.project_id === normalized.projectId
+    && context.repository_id === normalized.repositoryId
+    && context.worktree_id === normalized.worktreeId
+    && (!workSessionId || context.work_session_id === workSessionId)
+  ));
+  if (!candidates.length) {
+    throw contextError('WENDKEEP_ACTIVE_CONTEXT_NOT_FOUND', 'active context não encontrado para a identidade informada');
+  }
+  if (candidates.length > 1) {
+    throw contextError(
+      'WENDKEEP_ACTIVE_CONTEXT_AMBIGUOUS',
+      'mais de um active context corresponde à worktree; informe a sessão causal',
+    );
+  }
+  return structuredClone(candidates[0][1]);
+}
+
+export function mutateActiveContext(vaultBase, identity, updater, {
+  expectedRevision,
+  now = new Date().toISOString(),
+  mutateRegistry = mutateSessionRegistry,
+} = {}) {
+  const normalized = normalizeIdentity(identity);
+  const key = activeContextKey(normalized);
+  const result = mutateRegistry(vaultBase, (registry) => {
+    const contexts = contextsOf(registry);
+    const existing = contexts[key] || null;
+    const revision = currentContextRevision(existing);
+    if (expectedRevision !== undefined && Number(expectedRevision) !== revision) {
+      throw contextError(
+        'WENDKEEP_ACTIVE_CONTEXT_STALE',
+        `active context revision mudou de ${expectedRevision} para ${revision}`,
+      );
+    }
+    const base = existing || {
+      project_id: normalized.projectId,
+      repository_id: normalized.repositoryId,
+      worktree_id: normalized.worktreeId,
+      work_session_id: normalized.workSessionId,
+      branch: normalized.branch,
+      head_sha: normalized.headSha,
+      change_slug: '',
+      state: 'active',
+      revision: 0,
+      updated_at: String(now),
+    };
+    const updated = updater(structuredClone(base));
+    if (!updated || typeof updated !== 'object' || Array.isArray(updated)) {
+      throw contextError('WENDKEEP_ACTIVE_CONTEXT_INVALID', 'mutação retornou active context inválido');
+    }
+    for (const [field, expected] of [
+      ['project_id', normalized.projectId],
+      ['repository_id', normalized.repositoryId],
+      ['worktree_id', normalized.worktreeId],
+      ['work_session_id', normalized.workSessionId],
+    ]) {
+      if (updated[field] !== expected) {
+        throw contextError('WENDKEEP_ACTIVE_CONTEXT_IDENTITY_MISMATCH', `${field} não pode mudar`);
+      }
+    }
+    const next = {
+      ...updated,
+      branch: normalized.branch || optionalText(updated.branch, 240),
+      head_sha: normalized.headSha || optionalText(updated.head_sha, 80),
+      state: updated.state === 'closed' ? 'closed' : 'active',
+      revision: revision + 1,
+      updated_at: String(now),
+    };
+    registry.active_contexts_schema = ACTIVE_CONTEXTS_SCHEMA_VERSION;
+    registry.active_contexts_revision = currentGlobalRevision(registry) + 1;
+    registry.active_contexts = { ...contexts, [key]: next };
+    return { key, context: structuredClone(next), registryRevision: registry.active_contexts_revision };
+  });
+  projectLegacyActiveChange(vaultBase);
+  return result;
+}
+
+export function setActiveContextChange(vaultBase, identity, slug, options = {}) {
+  const normalizedSlug = String(slug || '').trim();
+  if (!SLUG_PATTERN.test(normalizedSlug)) {
+    throw contextError('WENDKEEP_ACTIVE_CONTEXT_CHANGE_INVALID', 'change_slug inválido ou ausente');
+  }
+  return mutateActiveContext(vaultBase, identity, (context) => ({
+    ...context,
+    change_slug: normalizedSlug,
+    state: 'active',
+  }), options);
+}
+
+export function clearActiveContextChange(vaultBase, identity, options = {}) {
+  return mutateActiveContext(vaultBase, identity, (context) => ({
+    ...context,
+    change_slug: '',
+    state: 'active',
+  }), options);
+}
+
+function legacyPointer(vaultBase) {
+  try {
+    return readFileSync(join(vaultBase, POINTER), 'utf8').match(/^change:\s*(.+)$/m)?.[1]?.trim() || '';
+  } catch {
+    return '';
+  }
+}
+
+export function migrateLegacyActiveContext(vaultBase, {
+  identityForSession,
+  now = new Date().toISOString(),
+} = {}) {
+  const slug = legacyPointer(vaultBase);
+  if (!slug) return { migrated: false, reason: 'no-pointer' };
+  const registry = readSessionRegistry(vaultBase);
+  if (Object.keys(contextsOf(registry)).length) return { migrated: false, reason: 'already-initialized' };
+  if (typeof identityForSession !== 'function') return { migrated: false, reason: 'identity-unavailable' };
+
+  const candidates = [];
+  for (const [sessionId, entry] of Object.entries(registry.sessions || {})) {
+    if (entry?.status !== 'active' || entry?.project_scope?.complete !== true || !entry?.work_session_id) continue;
+    let candidate;
+    try { candidate = normalizeIdentity(identityForSession(sessionId, entry)); } catch { continue; }
+    if (candidate.projectId !== entry.project_scope.projectId
+      || candidate.workSessionId !== String(entry.work_session_id)) continue;
+    candidates.push(candidate);
+  }
+  if (candidates.length !== 1) {
+    return { migrated: false, reason: candidates.length ? 'ambiguous' : 'identity-unavailable' };
+  }
+  const result = setActiveContextChange(vaultBase, candidates[0], slug, { now });
+  return { migrated: true, key: result.key, context: result.context };
+}