wendkeep 0.76.2 → 0.76.3

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.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 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** | `context switch/status/recover`, 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 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** | `context switch/status/recover`, 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/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,22 @@ 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.
+
 ## 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/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,21 @@ 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.
+
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.76.2",
+  "version": "0.76.3",
   "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": [

package/packages/cli/src/index.mjs

@@ -59,6 +59,9 @@ Usage:
                            Managed linked worktrees under .worktrees (branch default wk/<slug>).
   wendkeep context switch <branch> [--create] [--session <id>] [--json]
                            Switch Git branch and the causal session scope in the same worktree.
+  wendkeep context status --session <id> [--json]
+  wendkeep context recover --session <id> --select reserved|observed --revision <n> --reason <text> [--json]
+                           Inspect or explicitly recover a quarantined causal scope conflict.
   wendkeep change <sub>        Change lifecycle: new [--simple|--guide] | use | bind <slug> --session <id> | continue | list | show |
                            status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
                            archive exige verdict (rode verify --deep); abandon descarta sem ADR.

package/src/context.mjs

@@ -10,16 +10,23 @@ import {
   concurrentScopeConflicts,
   scopeForRegistry,
 } from '../hooks/project-scope.mjs';
+import { readVaultMarker } from './project-vault.mjs';
+import { sanitizeMemoryText } from '../packages/vault/src/memory-schema.mjs';
 
 export const CONTEXT_HELP = `wendkeep context <subcommand>
 
   switch <branch> [--create] [--session <id>] [--project <path>] [--vault <path>] [--json]
+  status --session <id> [--project <path>] [--vault <path>] [--json]
+  recover --session <id> --select <reserved|observed> --revision <n> --reason <text>
+    [--project <path>] [--vault <path>] [--json]
 
 Switches Git branch and the causal session scope together inside the same worktree.
 Without --session, exactly one active session must match the current scope.
+Status inventories reserved/observed recovery candidates without selecting one.
+Recover resolves a quarantined conflict only when the selected candidate still matches the checkout.
 `;
 
-const VALUE_OPTIONS = new Set(['--project', '--vault', '--session']);
+const VALUE_OPTIONS = new Set(['--project', '--vault', '--session', '--select', '--revision', '--reason']);
 const FLAG_OPTIONS = new Set(['--create', '--json']);
 
 function contextError(code, message) {
@@ -121,6 +128,247 @@ function contextRevision(entry) {
     ? entry.context_revision : 0;
 }
 
+function activeSessionEntry(registry, sessionId) {
+  const id = String(sessionId || '').trim();
+  if (!id) throw contextError('WENDKEEP_CONTEXT_SESSION', 'status requer --session <id>');
+  const entry = registry.sessions?.[id];
+  if (!entry || entry.status !== 'active') {
+    throw contextError('WENDKEEP_CONTEXT_SESSION', `sessão ativa não encontrada: ${id}`);
+  }
+  return { id, entry };
+}
+
+function validCandidateScope(scope, label) {
+  const required = [
+    'projectId', 'projectRoot', 'repoRoot', 'remote', 'branch', 'worktree',
+    'head', 'provider', 'sessionId',
+  ];
+  const complete = scope && typeof scope === 'object' && scope.complete === true
+    && required.every((field) => typeof scope[field] === 'string' && scope[field].trim());
+  const head = complete ? scope.head.trim() : '';
+  const branch = complete ? scope.branch.trim() : '';
+  const safeHead = /^[0-9a-f]{40,64}$/i.test(head);
+  const safeBranch = branch === `detached:${head}` || (
+    branch.length <= 255
+    && !branch.startsWith('/')
+    && !branch.endsWith('/')
+    && !branch.endsWith('.')
+    && !branch.endsWith('.lock')
+    && !branch.includes('..')
+    && !branch.includes('@{')
+    && !branch.includes('//')
+    && !/[\u0000-\u0020~^:?*[\]\\]/u.test(branch)
+  );
+  if (!complete || !safeHead || !safeBranch) {
+    throw contextError('WENDKEEP_CONTEXT_SCOPE_CONFLICT', `scope ${label} ausente ou incompleta`);
+  }
+  return scope;
+}
+
+function scopeMatchesActual(candidate, actual) {
+  return compareProjectScopes(candidate, actual).ok
+    && Boolean(candidate.head)
+    && candidate.head === actual.head;
+}
+
+function candidateSummary(id, candidate, actual) {
+  return {
+    id,
+    branch: candidate.branch || '',
+    head: candidate.head || '',
+    complete: candidate.complete === true,
+    matches_actual: scopeMatchesActual(candidate, actual),
+  };
+}
+
+function requiredRevision(value) {
+  const raw = String(value ?? '').trim();
+  const revision = Number(raw);
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(revision)) {
+    throw contextError('WENDKEEP_CONTEXT_ARGS', 'recover requer --revision <inteiro não negativo>');
+  }
+  return revision;
+}
+
+function recoveryReason(value) {
+  const raw = String(value || '').replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!raw) throw contextError('WENDKEEP_CONTEXT_ARGS', 'recover requer --reason <texto>');
+  if (raw.length > 240) throw contextError('WENDKEEP_CONTEXT_ARGS', '--reason excede 240 caracteres');
+  return sanitizeMemoryText(raw).replace(/\s+/g, ' ').trim();
+}
+
+function recoverySelection(value) {
+  const selected = String(value || '').trim();
+  if (!['reserved', 'observed'].includes(selected)) {
+    throw contextError('WENDKEEP_CONTEXT_ARGS', 'recover requer --select <reserved|observed>');
+  }
+  return selected;
+}
+
+function scopeIdentityMismatches(reserved, observed) {
+  const fields = ['projectId', 'remote', 'provider', 'sessionId'];
+  return fields.filter((field) => String(reserved?.[field] || '') !== String(observed?.[field] || ''));
+}
+
+function validateRecoveryIdentity(vaultBase, entry, sessionId, reserved, observed = null) {
+  const mismatches = observed ? scopeIdentityMismatches(reserved, observed) : [];
+  const candidates = observed ? [reserved, observed] : [reserved];
+  if (candidates.some((candidate) => candidate.sessionId !== sessionId)) mismatches.push('sessionId');
+  if (entry.provider && candidates.some((candidate) => candidate.provider !== entry.provider)) {
+    mismatches.push('provider');
+  }
+  let marker = null;
+  try { marker = readVaultMarker(vaultBase)?.marker || null; } catch { /* fail closed below */ }
+  if (!marker?.projectId || candidates.some((candidate) => candidate.projectId !== marker.projectId)) {
+    mismatches.push('projectId');
+  }
+  if (mismatches.length) {
+    throw contextError(
+      'WENDKEEP_CONTEXT_IDENTITY_CHANGED',
+      `candidatas divergem na identidade causal (${[...new Set(mismatches)].join(', ')})`,
+    );
+  }
+}
+
+function recoveryActualScope(projectRoot, expected, sessionId, spawn) {
+  return captureProjectScope({
+    input: { cwd: projectRoot },
+    projectRoot,
+    projectId: expected.projectId,
+    provider: expected.provider,
+    sessionId,
+    targetCwd: projectRoot,
+    spawn,
+  });
+}
+
+const CONFLICT_FIELDS = new Set([
+  'scope.projectId', 'scope.projectRoot', 'scope.repoRoot', 'scope.remote', 'scope.branch',
+  'scope.worktree', 'scope.provider', 'scope.sessionId', 'scope.incomplete',
+]);
+
+function sanitizedConflictFields(value) {
+  if (!Array.isArray(value) || value.some((field) => !CONFLICT_FIELDS.has(String(field)))) {
+    throw contextError('WENDKEEP_CONTEXT_SCOPE_CONFLICT', 'campos de conflito ausentes ou inválidos');
+  }
+  return [...new Set(value.map(String))].sort();
+}
+
+function receiptScope(candidate) {
+  return { branch: candidate.branch || '', head: candidate.head || '' };
+}
+
+export function inspectSessionContext({
+  vaultBase,
+  projectRoot = process.cwd(),
+  sessionId = '',
+  spawn = spawnSync,
+} = {}) {
+  const registry = readSessionRegistry(vaultBase);
+  const selected = activeSessionEntry(registry, sessionId);
+  const reserved = validCandidateScope(selected.entry.project_scope, 'reserved');
+  const conflict = selected.entry.project_scope_conflict === true;
+  const observed = conflict
+    ? validCandidateScope(selected.entry.project_scope_observed, 'observed')
+    : null;
+  validateRecoveryIdentity(vaultBase, selected.entry, selected.id, reserved, observed);
+  const actual = recoveryActualScope(projectRoot, reserved, selected.id, spawn);
+  const candidates = [candidateSummary('reserved', reserved, actual)];
+  if (observed) candidates.push(candidateSummary('observed', observed, actual));
+  return {
+    status: conflict ? 'conflict' : 'healthy',
+    session_id: selected.id,
+    revision: contextRevision(selected.entry),
+    conflict,
+    conflict_fields: conflict ? sanitizedConflictFields(selected.entry.project_scope_conflict_fields) : [],
+    candidates,
+  };
+}
+
+export function recoverSessionContext({
+  vaultBase,
+  projectRoot = process.cwd(),
+  sessionId = '',
+  select = '',
+  revision,
+  reason = '',
+  spawn = spawnSync,
+  mutateRegistry = mutateSessionRegistry,
+  now = () => new Date(),
+} = {}) {
+  const requestedSessionId = String(sessionId || '').trim();
+  if (!requestedSessionId) throw contextError('WENDKEEP_CONTEXT_SESSION', 'recover requer --session <id>');
+  const selectedId = recoverySelection(select);
+  const expectedRevision = requiredRevision(revision);
+  const safeReason = recoveryReason(reason);
+
+  return mutateRegistry(vaultBase, (registry) => {
+    const selected = activeSessionEntry(registry, requestedSessionId);
+    const entry = selected.entry;
+    if (entry.project_scope_conflict !== true) {
+      throw contextError('WENDKEEP_CONTEXT_SCOPE_CONFLICT', 'a sessão não possui conflito de scope ativo');
+    }
+    const currentRevision = contextRevision(entry);
+    if (currentRevision !== expectedRevision) {
+      throw contextError(
+        'WENDKEEP_CONTEXT_CAS_MISMATCH',
+        `context_revision mudou de ${expectedRevision} para ${currentRevision}; inspecione o status novamente`,
+      );
+    }
+    const reserved = validCandidateScope(entry.project_scope, 'reserved');
+    const observed = validCandidateScope(entry.project_scope_observed, 'observed');
+    validateRecoveryIdentity(vaultBase, entry, selected.id, reserved, observed);
+    const candidate = selectedId === 'reserved' ? reserved : observed;
+    const actual = recoveryActualScope(projectRoot, candidate, selected.id, spawn);
+    if (!scopeMatchesActual(candidate, actual)) {
+      throw contextError(
+        'WENDKEEP_CONTEXT_SCOPE_MISMATCH',
+        `a candidata ${selectedId} não corresponde integralmente ao checkout atual`,
+      );
+    }
+
+    const nextRevision = currentRevision + 1;
+    const at = now().toISOString();
+    const receipt = {
+      revision: nextRevision,
+      operation: 'recover',
+      selected: selectedId,
+      from: {
+        reserved: receiptScope(reserved),
+        observed: receiptScope(observed),
+      },
+      to: receiptScope(actual),
+      actor: { provider: candidate.provider || entry.provider || '', session_id: selected.id },
+      reason: safeReason,
+      at,
+    };
+    const {
+      project_scope_conflict: _conflict,
+      project_scope_conflict_fields: _conflictFields,
+      project_scope_observed: _observed,
+      ...preserved
+    } = entry;
+    registry.sessions[selected.id] = {
+      ...preserved,
+      project_scope: scopeForRegistry(actual, { authorizedActions: reserved.authorizedActions }),
+      context_revision: nextRevision,
+      context_recoveries: [
+        ...(Array.isArray(entry.context_recoveries) ? entry.context_recoveries : []),
+        receipt,
+      ],
+      last_seen: at,
+      updated_at: at,
+    };
+    return {
+      status: 'recovered',
+      session_id: selected.id,
+      selected: selectedId,
+      revision: nextRevision,
+      receipt,
+    };
+  });
+}
+
 function resolveSessionId(vaultBase, projectRoot, requested, spawn) {
   const registry = readSessionRegistry(vaultBase);
   if (requested) {
@@ -271,6 +519,12 @@ export function switchSessionContext({
 
 function output(result, json) {
   if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else if (Array.isArray(result.candidates)) {
+    process.stdout.write(`context ${result.status}: session ${result.session_id}; revision ${result.revision}; candidates ${result.candidates.map((candidate) => candidate.id).join(', ')}\n`);
+  }
+  else if (result.status === 'recovered') {
+    process.stdout.write(`context recovered: ${result.selected} selected (session ${result.session_id}; revision ${result.revision})\n`);
+  }
   else process.stdout.write(`context ${result.status}: ${result.branch} (session ${result.session_id}; revision ${result.revision})\n`);
 }
 
@@ -278,6 +532,27 @@ export function runContext(argv = []) {
   try {
     validateArgv(argv);
     const [sub, branch, ...extra] = positionals(argv);
+    if (sub === 'status' && !branch && !extra.length) {
+      const result = inspectSessionContext({
+        vaultBase: vaultOf(argv),
+        projectRoot: projectOf(argv),
+        sessionId: optionValue(argv, '--session'),
+      });
+      output(result, argv.includes('--json'));
+      return 0;
+    }
+    if (sub === 'recover' && !branch && !extra.length) {
+      const result = recoverSessionContext({
+        vaultBase: vaultOf(argv),
+        projectRoot: projectOf(argv),
+        sessionId: optionValue(argv, '--session'),
+        select: optionValue(argv, '--select'),
+        revision: optionValue(argv, '--revision'),
+        reason: optionValue(argv, '--reason'),
+      });
+      output(result, argv.includes('--json'));
+      return 0;
+    }
     if (sub !== 'switch' || !branch || extra.length) {
       throw contextError('WENDKEEP_CONTEXT_ARGS', 'use: wendkeep context switch <branch> [--create] [--session <id>]');
     }