wendkeep 0.67.1 → 0.67.3

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.67.3] — 2026-08-02
+
+### Fixed
+
+- **Conflitos semânticos agora levam a uma curadoria humana executável.** O doctor diferencia
+  candidates em conflito de corrupção estrutural, explica que `memory repair` não escolhe um
+  vencedor e mostra `memory candidates --active --vault <vault>` com o Vault resolvido, seguido
+  pelos modelos explícitos para promover ou rejeitar a decisão.
+- **A inspeção de candidates deixa de exigir leitura direta do sidecar.** O novo comando read-only
+  `memory candidates [--active]` devolve somente `candidate_id`, `reason`, `status`, `memory_key` e
+  `event_ids`, sem valores ou conteúdo, em ordem determinística e sem alterar o bundle de memória.
+
+## [0.67.2] — 2026-08-02
+
+### Fixed
+
+- **O doctor agora exibe comandos de reparo executáveis no projeto.** Os diagnósticos de memória
+  e observabilidade usam `npx --no-install wendkeep`, informam o Vault absoluto resolvido em
+  `--vault` e
+  mantêm a sequência segura de inspeção (dry-run) antes da variante explícita com `--apply`.
+- **O doctor continua somente leitura.** A correção altera apenas as recomendações exibidas; o
+  reparo continua exigindo execução humana do comando `--apply`.
+
 ## [0.67.1] — 2026-08-02
 
 ### Fixed

package/README.en.md

@@ -346,20 +346,20 @@ Codex uses `session_id`/`turn_id` plus transcript order, with no artificial caus
 `DIGEST.md` is no longer the operational handoff: it remains the `/brain-recall` bridge and legacy-vault fallback. A vault without SHARED receives CORE+DIGEST with a deprecation warning; migrate during the compatibility window:
 
 ```bash
-wendkeep memory status --gate --vault .MyApp-vault
-wendkeep memory migrate --vault .MyApp-vault          # preview, zero writes
-wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2 bundle
+npx --no-install wendkeep memory status --gate --vault .MyApp-vault
+npx --no-install wendkeep memory migrate --vault .MyApp-vault          # preview, zero writes
+npx --no-install wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2 bundle
 ```
 
 ### Health and recovery
 
-Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
+Use `npx --no-install wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
 immediately after valid migration is healthy. The gate correlates `last_memory_attempt`, outbox,
 ledger, SHARED, and checkpoint: `degraded` with a durable outbox is a warning; an ambiguous attempt,
 lost publication, or mismatched checkpoint blocks. See [migration](docs/en/commands/memory-migration.md)
 and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
-If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to back up
+If status blocks, preserve the evidence and run `npx --no-install wendkeep memory repair --vault <vault>` to back up
 the corrupt ledger, retain valid lines, and re-project. Repair remains structural: its only narrow
 acknowledgement exception covers attempts entirely represented by the outbox consumed by that same
 run; it does not scan or reclassify historical attempts. Valid pre-0.59 causal checkpoints and
@@ -369,8 +369,10 @@ backup/audit; divergent mirrors fail closed. A demonstrably superseded
 ambiguity uses `memory reconcile <session> --by-session <successor>
 --reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
 without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
-explicit, durable curation: `memory promote <id> --event <event-id>` selects one event from the
-candidate, while `memory reject <id>` keeps the current value. The decision is idempotent, and a
+explicit, durable curation: `memory candidates --active --vault <vault>` lists only safe IDs and
+metadata in read-only mode — it does not expose memory values or content. After human review,
+`memory promote <id> --event <event-id>` selects one event from the candidate, while
+`memory reject <id>` keeps the current value. `memory repair` does not choose a winner. The decision is idempotent, and a
 new promotion accepts a later Stop from the same session/activation without recreating a conflict.
 A promotion written by 0.66.1 remains historical: if the next Stop forms a new candidate, update
 to 0.66.3 and run `memory repair`. During replay, a transient candidate is re-evaluated against the

package/README.md

@@ -346,20 +346,20 @@ Codex uses `session_id`/`turn_id` plus transcript order, with no artificial caus
 `DIGEST.md` is no longer the operational handoff: it remains the `/brain-recall` bridge and legacy-vault fallback. A vault without SHARED receives CORE+DIGEST with a deprecation warning; migrate during the compatibility window:
 
 ```bash
-wendkeep memory status --gate --vault .MyApp-vault
-wendkeep memory migrate --vault .MyApp-vault          # preview, zero writes
-wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2 bundle
+npx --no-install wendkeep memory status --gate --vault .MyApp-vault
+npx --no-install wendkeep memory migrate --vault .MyApp-vault          # preview, zero writes
+npx --no-install wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2 bundle
 ```
 
 ### Health and recovery
 
-Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
+Use `npx --no-install wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
 immediately after valid migration is healthy. The gate correlates `last_memory_attempt`, outbox,
 ledger, SHARED, and checkpoint: `degraded` with a durable outbox is a warning; an ambiguous attempt,
 lost publication, or mismatched checkpoint blocks. See [migration](docs/en/commands/memory-migration.md)
 and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
-If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to back up
+If status blocks, preserve the evidence and run `npx --no-install wendkeep memory repair --vault <vault>` to back up
 the corrupt ledger, retain valid lines, and re-project. Repair remains structural: its only narrow
 acknowledgement exception covers attempts entirely represented by the outbox consumed by that same
 run; it does not scan or reclassify historical attempts. Valid pre-0.59 causal checkpoints and
@@ -369,8 +369,10 @@ backup/audit; divergent mirrors fail closed. A demonstrably superseded
 ambiguity uses `memory reconcile <session> --by-session <successor>
 --reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
 without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
-explicit, durable curation: `memory promote <id> --event <event-id>` selects one event from the
-candidate, while `memory reject <id>` keeps the current value. The decision is idempotent, and a
+explicit, durable curation: `memory candidates --active --vault <vault>` lists only safe IDs and
+metadata in read-only mode — it does not expose memory values or content. After human review,
+`memory promote <id> --event <event-id>` selects one event from the candidate, while
+`memory reject <id>` keeps the current value. `memory repair` does not choose a winner. The decision is idempotent, and a
 new promotion accepts a later Stop from the same session/activation without recreating a conflict.
 A promotion written by 0.66.1 remains historical: if the next Stop forms a new candidate, update
 to 0.66.3 and run `memory repair`. During replay, a transient candidate is re-evaluated against the

package/docs/en/commands/costs-and-observability.md

@@ -24,9 +24,9 @@ A consistent registry, complete price table, and transcript access for rebuilt s
 ## Syntax
 
 ```bash
-npx wendkeep stats [--vault <vault>] [--json]
-npx wendkeep cost [--since <date>] [--top [N]] [--trend day|week|month] [--write] [--json]
-npx wendkeep cost rebuild [--session <id|file>] [--limit N] [--max-graph-nodes N] [--max-fallback-days N] [--max-fallback-candidates N] [--apply] [--json]
+npx --no-install wendkeep stats [--vault <vault>] [--json]
+npx --no-install wendkeep cost [--since <date>] [--top [N]] [--trend day|week|month] [--write] [--json]
+npx --no-install wendkeep cost rebuild [--session <id|file>] [--vault <vault>] [--limit N] [--max-graph-nodes N] [--max-fallback-days N] [--max-fallback-candidates N] [--apply] [--json]
 ```
 
 ## Options and exit codes
@@ -50,11 +50,11 @@ npx wendkeep cost rebuild [--session <id|file>] [--limit N] [--max-graph-nodes N
 ## Examples
 
 ```bash
-npx wendkeep stats --vault .MyApp-vault
-npx wendkeep cost --since 2026-07-01 --top 10 --trend week
-npx wendkeep cost rebuild --session 019abc --json
-npx wendkeep cost rebuild --session 019abc --max-graph-nodes 8192 --json
-npx wendkeep cost rebuild --session 019abc --apply
+npx --no-install wendkeep stats --vault .MyApp-vault
+npx --no-install wendkeep cost --since 2026-07-01 --top 10 --trend week
+npx --no-install wendkeep cost rebuild --session 019abc --json --vault .MyApp-vault
+npx --no-install wendkeep cost rebuild --session 019abc --max-graph-nodes 8192 --json --vault .MyApp-vault
+npx --no-install wendkeep cost rebuild --session 019abc --json --vault .MyApp-vault --apply
 ```
 
 ## Expected result

package/docs/en/commands/maintenance-and-diagnostics.md

@@ -23,11 +23,11 @@ Run from the project root or provide `--project` and `--vault` explicitly.
 ## Syntax
 
 ```bash
-npx wendkeep doctor [--vault <vault>]
-npx wendkeep sync-defs [--check|--reseed] --vault <vault> --project <root>
-npx wendkeep theme sync --vault <vault>
-npx wendkeep --version
-npx wendkeep --help
+npx --no-install wendkeep doctor [--vault <vault>]
+npx --no-install wendkeep sync-defs [--check|--reseed] --vault <vault> --project <root>
+npx --no-install wendkeep theme sync --vault <vault>
+npx --no-install wendkeep --version
+npx --no-install wendkeep --help
 ```
 
 ## Options and exit codes
@@ -53,12 +53,13 @@ npx wendkeep --help
 Post-update checklist:
 
 ```bash
-npx wendkeep --version
-npx wendkeep sync-defs --check --vault .MyApp-vault --project .
-npx wendkeep doctor --vault .MyApp-vault
-npx wendkeep memory status --gate --vault .MyApp-vault
-npx wendkeep cost rebuild --session <id> --json
-npx wendkeep cost rebuild --session <id> --apply
+npx --no-install wendkeep --version
+npx --no-install wendkeep sync-defs --check --vault .MyApp-vault --project .
+npx --no-install wendkeep doctor --vault .MyApp-vault
+npx --no-install wendkeep memory status --gate --vault .MyApp-vault
+npx --no-install wendkeep memory candidates --active --vault .MyApp-vault
+npx --no-install wendkeep cost rebuild --session <id> --json --vault .MyApp-vault
+npx --no-install wendkeep cost rebuild --session <id> --json --vault .MyApp-vault --apply
 ```
 
 ## Expected result
@@ -74,14 +75,20 @@ dry-run path before any write.
 
 - `no vault`: run from the bound root or pass `--vault`.
 - `defs stale`: confirm the version and run `sync-defs --reseed`.
-- Legacy vault: this is a non-blocking warning; plan `memory migrate --apply` separately.
+- Legacy vault: this is a non-blocking warning; doctor shows
+  `npx --no-install wendkeep memory migrate --apply --vault <vault>` with the resolved Vault, but
+  migration remains opt-in and must be planned separately.
 - `degraded` plus an intact outbox: warning; preserve the outbox and allow idempotent replay.
 - `ambiguous`, lost publication, or a mismatched checkpoint: blocking; preserve registry, ledger,
   outbox, and SHARED so `last_memory_attempt` can be correlated before repair.
 - Corrupt bundle: preserve evidence and run `memory status --gate` before `memory repair`.
+- An active semantic conflict requires a human decision: `memory repair` does not choose a winner.
+  List safe IDs with `memory candidates --active --vault <vault>`, review the evidence, and then use
+  `memory promote <candidate-id> --event <event-id> --vault <vault>` to select an event or
+  `memory reject <candidate-id> --vault <vault>` to keep the current operational value.
 - `legacy`/`degraded`/`stale`/`manifest-unproven` observability: run
-  `wendkeep cost rebuild --session <id> --json`, review diagnostics, and only then authorize
-  `--apply`.
+  `npx --no-install wendkeep cost rebuild --session <id> --json --vault <vault>`, review diagnostics,
+  and only then authorize the second variant with `--apply`.
 
 ## Next steps
 

package/docs/en/commands/memory.md

@@ -24,6 +24,7 @@ Pass the vault explicitly in automation. Preserve backups and evidence before re
 
 ```bash
 npx wendkeep memory status [--gate] --vault <vault>
+npx wendkeep memory candidates [--active] --vault <vault>
 npx wendkeep memory repair --vault <vault>
 npx wendkeep memory recover-attempt <session> [--apply] --vault <vault>
 npx wendkeep memory reconcile <ambiguous-session> --by-session <successor-session> --reason <reason> [--apply] --vault <vault>
@@ -36,6 +37,13 @@ npx wendkeep validate-memory --vault <v2-vault>
 ## Options and exit codes
 
 - `memory status` is read-only; `--gate` exits `1` only for blocking state.
+- `memory candidates` is read-only and prints deterministic JSON containing only `candidate_id`,
+  `reason`, `status`, `memory_key`, and `event_ids`; it does not expose memory values or content and
+  does not create a lock or mutate the bundle. `--active` omits terminal candidates (`resolved`,
+  `rejected`, and `superseded`). A missing status is normalized to `active`.
+- For `memory candidates`, exit `0` means a valid inventory (including empty or conflicted), exit
+  `1` means an invalid sidecar/unsafe topology, and exit `2` means a missing `--vault`, unknown or
+  duplicate option, extra argument, or an invalid value passed to `--active`.
 - `Stop` writes events to the outbox before acknowledging `last_memory_attempt: enqueued`, then the
   projector runs outside the registry lock. Retrying the same attempt reuses its frozen event IDs
   and can project them at most once.
@@ -105,6 +113,7 @@ npx wendkeep validate-memory --vault <v2-vault>
 
 ```bash
 npx wendkeep memory status --gate --vault .MyApp-vault
+npx wendkeep memory candidates --active --vault .MyApp-vault
 npx wendkeep memory recover-attempt session-123 --vault .MyApp-vault
 npx wendkeep memory recover-attempt session-123 --apply --vault .MyApp-vault
 npx wendkeep memory reconcile old --by-session current --reason "delivery continued" --vault .MyApp-vault
@@ -121,6 +130,9 @@ state of the last attempt. CORE stays hand-curated and canonical; SHARED stays a
 operational projection. After successful projection, an attempt checkpoint may be a valid prefix
 of a global projection that has already advanced with concurrent events.
 
+`memory candidates` returns `status: "ok"` and the sanitized candidate list in stable order; with
+`--active`, the list contains only decisions still open for human curation.
+
 ## Common errors and diagnosis
 
 - `legacy`: follow the migration guide; this is not corruption.

package/docs/pt-BR/commands/costs-and-observability.md

@@ -24,9 +24,9 @@ Registry consistente, tabela de preços completa e acesso aos transcripts das se
 ## Sintaxe
 
 ```bash
-npx wendkeep stats [--vault <cofre>] [--json]
-npx wendkeep cost [--since <data>] [--top [N]] [--trend day|week|month] [--write] [--json]
-npx wendkeep cost rebuild [--session <id|arquivo>] [--limit N] [--max-graph-nodes N] [--max-fallback-days N] [--max-fallback-candidates N] [--apply] [--json]
+npx --no-install wendkeep stats [--vault <cofre>] [--json]
+npx --no-install wendkeep cost [--since <data>] [--top [N]] [--trend day|week|month] [--write] [--json]
+npx --no-install wendkeep cost rebuild [--session <id|arquivo>] [--vault <cofre>] [--limit N] [--max-graph-nodes N] [--max-fallback-days N] [--max-fallback-candidates N] [--apply] [--json]
 ```
 
 ## Opções e códigos de saída
@@ -50,11 +50,11 @@ npx wendkeep cost rebuild [--session <id|arquivo>] [--limit N] [--max-graph-node
 ## Exemplos
 
 ```bash
-npx wendkeep stats --vault .MeuApp-vault
-npx wendkeep cost --since 2026-07-01 --top 10 --trend week
-npx wendkeep cost rebuild --session 019abc --json
-npx wendkeep cost rebuild --session 019abc --max-graph-nodes 8192 --json
-npx wendkeep cost rebuild --session 019abc --apply
+npx --no-install wendkeep stats --vault .MeuApp-vault
+npx --no-install wendkeep cost --since 2026-07-01 --top 10 --trend week
+npx --no-install wendkeep cost rebuild --session 019abc --json --vault .MeuApp-vault
+npx --no-install wendkeep cost rebuild --session 019abc --max-graph-nodes 8192 --json --vault .MeuApp-vault
+npx --no-install wendkeep cost rebuild --session 019abc --json --vault .MeuApp-vault --apply
 ```
 
 ## Resultado esperado

package/docs/pt-BR/commands/maintenance-and-diagnostics.md

@@ -23,11 +23,11 @@ Execute na raiz do projeto ou informe `--project`/`--vault` explicitamente.
 ## Sintaxe
 
 ```bash
-npx wendkeep doctor [--vault <cofre>]
-npx wendkeep sync-defs [--check|--reseed] --vault <cofre> --project <raiz>
-npx wendkeep theme sync --vault <cofre>
-npx wendkeep --version
-npx wendkeep --help
+npx --no-install wendkeep doctor [--vault <cofre>]
+npx --no-install wendkeep sync-defs [--check|--reseed] --vault <cofre> --project <raiz>
+npx --no-install wendkeep theme sync --vault <cofre>
+npx --no-install wendkeep --version
+npx --no-install wendkeep --help
 ```
 
 ## Opções e códigos de saída
@@ -53,12 +53,13 @@ npx wendkeep --help
 Checklist pós-atualização:
 
 ```bash
-npx wendkeep --version
-npx wendkeep sync-defs --check --vault .MeuApp-vault --project .
-npx wendkeep doctor --vault .MeuApp-vault
-npx wendkeep memory status --gate --vault .MeuApp-vault
-npx wendkeep cost rebuild --session <id> --json
-npx wendkeep cost rebuild --session <id> --apply
+npx --no-install wendkeep --version
+npx --no-install wendkeep sync-defs --check --vault .MeuApp-vault --project .
+npx --no-install wendkeep doctor --vault .MeuApp-vault
+npx --no-install wendkeep memory status --gate --vault .MeuApp-vault
+npx --no-install wendkeep memory candidates --active --vault .MeuApp-vault
+npx --no-install wendkeep cost rebuild --session <id> --json --vault .MeuApp-vault
+npx --no-install wendkeep cost rebuild --session <id> --json --vault .MeuApp-vault --apply
 ```
 
 ## Resultado esperado
@@ -74,13 +75,20 @@ ou sem manifest comprovado e oferece um caminho dry-run antes de qualquer escrit
 
 - `no vault`: execute da raiz vinculada ou passe `--vault`.
 - `defs stale`: confirme a versão e rode `sync-defs --reseed`.
-- Vault legado: é warning não bloqueante; planeje `memory migrate --apply` separadamente.
+- Vault legado: é warning não bloqueante; o doctor mostra
+  `npx --no-install wendkeep memory migrate --apply --vault <cofre>` com o Vault resolvido, mas a
+  migração continua sendo opt-in e deve ser planejada separadamente.
 - `degraded` + outbox íntegra: warning; preserve a outbox e permita replay idempotente.
 - `ambiguous`, publicação perdida ou checkpoint divergente: bloqueante; preserve registry, ledger,
   outbox e SHARED para correlacionar `last_memory_attempt` antes de reparar.
 - Bundle corrompido: preserve a evidência e use `memory status --gate` antes de `memory repair`.
+- Conflito semântico ativo exige decisão humana: `memory repair` não escolhe vencedor. Liste os IDs
+  seguros com `memory candidates --active --vault <cofre>`, revise a evidência e então use
+  `memory promote <candidate-id> --event <event-id> --vault <cofre>` para selecionar um evento ou
+  `memory reject <candidate-id> --vault <cofre>` para manter o valor operacional atual.
 - Observabilidade `legacy`/`degraded`/`stale`/`manifest-unproven`: rode
-  `wendkeep cost rebuild --session <id> --json`, revise diagnostics e só então autorize `--apply`.
+  `npx --no-install wendkeep cost rebuild --session <id> --json --vault <cofre>`, revise diagnostics
+  e só então autorize a segunda variante com `--apply`.
 
 ## Próximos passos
 

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

@@ -24,6 +24,7 @@ Informe o vault explicitamente em automações. Preserve backups e evidências a
 
 ```bash
 npx wendkeep memory status [--gate] --vault <cofre>
+npx wendkeep memory candidates [--active] --vault <cofre>
 npx wendkeep memory repair --vault <cofre>
 npx wendkeep memory recover-attempt <sessão> [--apply] --vault <cofre>
 npx wendkeep memory reconcile <sessão-ambígua> --by-session <sessão-sucessora> --reason <motivo> [--apply] --vault <cofre>
@@ -36,6 +37,13 @@ npx wendkeep validate-memory --vault <cofre-v2>
 ## Opções e códigos de saída
 
 - `memory status` é read-only; `--gate` retorna exit `1` apenas para estado bloqueante.
+- `memory candidates` é read-only e imprime JSON determinístico com somente `candidate_id`,
+  `reason`, `status`, `memory_key` e `event_ids`; não expõe valores nem conteúdo da memória e não
+  cria lock nem altera o bundle. `--active` omite candidates terminais (`resolved`, `rejected` e
+  `superseded`). Status ausente é normalizado para `active`.
+- Em `memory candidates`, exit `0` indica inventário válido (inclusive vazio ou com conflitos),
+  exit `1` indica sidecar inválido/topologia insegura e exit `2` indica `--vault` ausente, opção
+  desconhecida/duplicada, argumento extra ou valor indevido em `--active`.
 - O `Stop` grava os eventos na outbox antes de reconhecer `last_memory_attempt: enqueued`; depois o
   projector roda fora do lock do registry. Retry do mesmo attempt reutiliza os event IDs congelados
   e pode projetá-los no máximo uma vez.
@@ -103,6 +111,7 @@ npx wendkeep validate-memory --vault <cofre-v2>
 
 ```bash
 npx wendkeep memory status --gate --vault .MeuApp-vault
+npx wendkeep memory candidates --active --vault .MeuApp-vault
 npx wendkeep memory recover-attempt sessao-123 --vault .MeuApp-vault
 npx wendkeep memory recover-attempt sessao-123 --apply --vault .MeuApp-vault
 npx wendkeep memory reconcile antiga --by-session atual --reason "entrega continuada" --vault .MeuApp-vault
@@ -119,6 +128,9 @@ causal do último attempt. CORE permanece canônico e curado à mão; SHARED per
 operacional verificável. Depois de uma projeção bem-sucedida, o checkpoint do attempt pode ser um
 prefixo válido de uma projeção global que já avançou com eventos concorrentes.
 
+`memory candidates` retorna `status: "ok"` e a lista sanitizada de candidates em ordem estável;
+com `--active`, a lista contém somente decisões ainda abertas para curadoria humana.
+
 ## Erros comuns e diagnóstico
 
 - `legacy`: siga o guia de migração; não é corrupção.

package/hooks/harness-doctor.mjs

@@ -8,7 +8,12 @@ import { buildEffectiveRequirementPackage, checkSpecsState, evaluateVerdict, tas
 import { getLocale } from './locale.mjs';
 import { priceForModel } from './token-usage.mjs';
 import { countMissing, indexDerivedBySession, listSessionNotes, missingDerivedLinks } from './derived-sections.mjs';
-import { readControl, readSessionRegistry } from './obsidian-common.mjs';
+import {
+  quoteCommandArgument,
+  readControl,
+  readSessionRegistry,
+  WENDKEEP_COMMAND,
+} from './obsidian-common.mjs';
 import { parseObservabilityCheckpoint } from './session-observability-state.mjs';
 import { readObservabilityStore } from './session-observability-store.mjs';
 import { assessObservabilityFreshness } from './session-observability-lifecycle.mjs';
@@ -20,6 +25,7 @@ export function checkSessionObservability(vaultBase, deps = {}) {
   const statSource = deps.statSource || statSync;
   const registry = readRegistry(vaultBase);
   const result = { ok: true, scanned: 0, healthy: 0, issues: [] };
+  const commandPrefix = `${WENDKEEP_COMMAND} cost rebuild`;
   const entries = Object.entries(registry?.sessions || {})
     .map(([sessionId, entry]) => ({ sessionId, ...entry }))
     .filter((entry) => entry.session_file)
@@ -32,7 +38,7 @@ export function checkSessionObservability(vaultBase, deps = {}) {
     try { content = readNote(notePath, 'utf8'); } catch { continue; }
     if (!entry.provider && /^provider:\s*["']?claude/m.test(content)) continue;
     result.scanned += 1;
-    const command = `wendkeep cost rebuild --session ${entry.sessionId} --json`;
+    const command = `${commandPrefix} --session ${quoteCommandArgument(entry.sessionId)} --json --vault ${quoteCommandArgument(vaultBase)}`;
     const checkpoint = parseObservabilityCheckpoint(content);
     if (!checkpoint) {
       result.issues.push({

package/hooks/obsidian-common.mjs

@@ -67,6 +67,14 @@ export function getVaultBase(input = {}) {
   return resolveVault(input).base;
 }
 
+// Diagnostic commands must use the project-local package even when `wendkeep` is not installed
+// globally. Quotes preserve resolved Windows paths with spaces in copy/pasteable output.
+export const WENDKEEP_COMMAND = 'npx --no-install wendkeep';
+
+export function quoteCommandArgument(value) {
+  return `"${String(value ?? '').replaceAll('"', '\\"')}"`;
+}
+
 // Diagnostic logger. No-op unless WENDKEEP_DEBUG is set, so it never pollutes the
 // stdout hook contract during normal runs but makes fail-open paths debuggable.
 export function debugLog(...args) {

package/hooks/vault-health.mjs

@@ -6,8 +6,10 @@ import {
   controlPath,
   getVaultBase,
   listMarkdownFiles,
+  quoteCommandArgument,
   readControl,
   readSessionRegistry,
+  WENDKEEP_COMMAND,
   wikilinkFromRel,
 } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
@@ -98,8 +100,24 @@ function linkedNotesFromSession(content) {
   return notes;
 }
 
-const MEMORY_STATUS_COMMAND = 'wendkeep memory status --gate --vault <vault>';
-const MEMORY_REPAIR_COMMAND = 'wendkeep memory repair --vault <vault>';
+const memoryStatusCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory status --gate --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryRepairCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory repair --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryMigrateCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory migrate --apply --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryCandidatesCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory candidates --active --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryPromoteCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory promote <candidate-id> --event <event-id> --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryRejectCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory reject <candidate-id> --vault ${quoteCommandArgument(vaultBase)}`
+);
 
 function readJsonLines(vaultBase, path, label) {
   let checked;
@@ -279,13 +297,13 @@ function checkMemoryAttempts(registry, {
       : [];
 
     if (state === 'skipped' && disposition === 'ambiguous') {
-      failures.push(`Lifecycle de memória v2 ambíguo: Stop pulou a publicação sem identidade causal suficiente. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      failures.push(`Lifecycle de memória v2 ambíguo: Stop pulou a publicação sem identidade causal suficiente. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       continue;
     }
 
     if (state === 'skipped' && ['stale_turn', 'superseded'].includes(disposition)) {
       if (eventIds.length) {
-        failures.push(`Stop stale/superseded emitiu event_ids apesar da rejeição causal. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+        failures.push(`Stop stale/superseded emitiu event_ids apesar da rejeição causal. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       } else {
         warnings.push('Stop stale/superseded foi descartado sem publicar memória.');
       }
@@ -294,12 +312,12 @@ function checkMemoryAttempts(registry, {
 
     if (disposition !== 'applied') {
       if (state === 'skipped') warnings.push('Attempt de memória v2 foi descartado sem publicação.');
-      else failures.push(`Attempt de memória v2 possui disposition não reconhecida para o estado informado. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      else failures.push(`Attempt de memória v2 possui disposition não reconhecida para o estado informado. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       continue;
     }
 
     if (!eventIds.length) {
-      failures.push(`Attempt v2 aplicado não declarou event_ids; publicação perdida. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      failures.push(`Attempt v2 aplicado não declarou event_ids; publicação perdida. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       continue;
     }
 
@@ -317,7 +335,7 @@ function checkMemoryAttempts(registry, {
     if (typeof attempt.turn_id !== 'string' || !attempt.turn_id) invalidAttemptFields.push('turn_id');
     if (!Number.isInteger(attempt.turn_sequence) || attempt.turn_sequence < 0) invalidAttemptFields.push('turn_sequence');
     if (invalidAttemptFields.length) {
-      failures.push(`Attempt v2 da sessão ${sessionId} possui identidade causal inválida (${invalidAttemptFields.join(', ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      failures.push(`Attempt v2 da sessão ${sessionId} possui identidade causal inválida (${invalidAttemptFields.join(', ')}). Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       continue;
     }
     const causalMismatches = [];
@@ -330,14 +348,14 @@ function checkMemoryAttempts(registry, {
       if (fields.length) causalMismatches.push(`${eventId}: ${fields.join(', ')}`);
     }
     if (causalMismatches.length) {
-      failures.push(`Attempt v2 da sessão ${sessionId} referencia evento(s) com identidade causal divergente (${causalMismatches.join('; ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      failures.push(`Attempt v2 da sessão ${sessionId} referencia evento(s) com identidade causal divergente (${causalMismatches.join('; ')}). Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       continue;
     }
 
     if (state === 'enqueued' || state === 'degraded') {
       const missing = eventIds.filter((eventId) => !ledgerEventIds.has(eventId) && !outboxEventIds.has(eventId));
       if (missing.length) {
-        failures.push(`Attempt v2 perdeu ${missing.length} evento(s): ausentes do ledger e da outbox. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+        failures.push(`Attempt v2 perdeu ${missing.length} evento(s): ausentes do ledger e da outbox. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       } else if (
         state === 'enqueued'
         && eventIds.every((eventId) => ledgerEventIds.has(eventId))
@@ -353,14 +371,14 @@ function checkMemoryAttempts(registry, {
     if (state === 'projected') {
       const outsideLedger = eventIds.filter((eventId) => !ledgerEventIds.has(eventId));
       if (outsideLedger.length) {
-        failures.push(`Attempt projetado perdeu ${outsideLedger.length} evento(s) no ledger. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+        failures.push(`Attempt projetado perdeu ${outsideLedger.length} evento(s) no ledger. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       } else if (!checkpointMatchesLedgerPrefix(attempt.checkpoint, eventIds, ledgerEvents, vaultBase)) {
-        failures.push(`Checkpoint do attempt projetado diverge do prefixo rederivado do ledger. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+        failures.push(`Checkpoint do attempt projetado diverge do prefixo rederivado do ledger. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
       }
       continue;
     }
 
-    failures.push(`Attempt de memória v2 possui state inválido. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+    failures.push(`Attempt de memória v2 possui state inválido. Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
   }
 
   return { failures, warnings };
@@ -391,7 +409,7 @@ export function checkMemoryBundle(vaultBase, { registry } = {}) {
       ok: true,
       status: 'legacy',
       failures: [],
-      warnings: [LEGACY_MEMORY_WARNING],
+      warnings: [`${LEGACY_MEMORY_WARNING} Comando com Vault resolvido: ${memoryMigrateCommand(vaultBase)}.`],
       metrics: memoryMetrics(),
     };
   }
@@ -410,26 +428,26 @@ export function checkMemoryBundle(vaultBase, { registry } = {}) {
   const ledgerCorrupt = (bundle.ledger?.errors || []).length > 0;
   if (ledgerCorrupt) {
     for (const error of bundle.ledger.errors) {
-      failures.push(`${error} Execute com segurança: ${MEMORY_REPAIR_COMMAND}.`);
+      failures.push(`${error} Execute com segurança: ${memoryRepairCommand(vaultBase)}.`);
     }
   }
   for (const error of bundle.errors || []) {
     if (error.startsWith('ledger:')) continue;
-    failures.push(`${error} Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+    failures.push(`${error} Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
   }
 
   if (outbox.errors.length) {
-    failures.push(`Outbox corrompida (${outbox.errors.join('; ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+    failures.push(`Outbox corrompida (${outbox.errors.join('; ')}). Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
   }
   if (candidates.errors.length) {
-    failures.push(`${candidates.errors.join('; ')} Execute com segurança: ${MEMORY_REPAIR_COMMAND}.`);
+    failures.push(`${candidates.errors.join('; ')} Execute com segurança: ${memoryRepairCommand(vaultBase)}.`);
   }
 
   let replay = null;
   if (bundle.ledger?.ok) {
     try { replay = deriveMemoryProjection(vaultBase, bundle.ledger.events); }
     catch (error) {
-      failures.push(`Ledger não pode ser reduzido: ${error.message}. Execute com segurança: ${MEMORY_REPAIR_COMMAND}.`);
+      failures.push(`Ledger não pode ser reduzido: ${error.message}. Execute com segurança: ${memoryRepairCommand(vaultBase)}.`);
     }
   }
   if (replay && bundle.shared?.ok) {
@@ -438,7 +456,7 @@ export function checkMemoryBundle(vaultBase, { registry } = {}) {
     if (metadata.event_cursor !== replay.ledgerCursor) divergences.push(`event_cursor ${metadata.event_cursor} != ${replay.ledgerCursor}`);
     if (metadata.state_hash !== replay.stateHash) divergences.push(`state_hash ${metadata.state_hash} != ${replay.stateHash}`);
     if (divergences.length) {
-      failures.push(`Projeção SHARED stale/lag (${divergences.join('; ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      failures.push(`Projeção SHARED stale/lag (${divergences.join('; ')}). Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
     }
   }
 
@@ -460,7 +478,12 @@ export function checkMemoryBundle(vaultBase, { registry } = {}) {
   const activeConflicts = unresolved.filter((item) => item?.reason === 'conflict');
   const ordinaryCandidates = unresolved.filter((item) => item?.reason !== 'conflict');
   if (activeConflicts.length) {
-    failures.push(`${activeConflicts.length} conflito ativo em chave operacional (${activeConflicts.map((item) => item.memory_key || item.candidate_id).join(', ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+    const keys = [...new Set(activeConflicts.map((item) => item.memory_key || item.candidate_id))]
+      .sort((left, right) => String(left).localeCompare(String(right)));
+    const label = activeConflicts.length === 1
+      ? '1 conflito ativo'
+      : `${activeConflicts.length} conflitos ativos`;
+    failures.push(`${label} em chave operacional (${keys.join(', ')}). Conflito semântico exige curadoria humana; memory repair não escolhe vencedor. Liste IDs seguros com: ${memoryCandidatesCommand(vaultBase)}. Depois da revisão, use ${memoryPromoteCommand(vaultBase)} ou ${memoryRejectCommand(vaultBase)}.`);
   }
   if (outbox.count) warnings.push(`${outbox.count} evento(s) pendente(s) na outbox; execute o projector quando seguro.`);
   if (ordinaryCandidates.length) warnings.push(`${ordinaryCandidates.length} candidate(s) aguardando curadoria humana.`);
@@ -585,7 +608,7 @@ export function runVaultHealth({ vaultBase, session = '' }) {
     failures.push(...memory.failures.map((item) => `Memória: ${item}`));
     warnings.push(...memory.warnings.map((item) => `Memória: ${item}`));
   } else {
-    warnings.push(`Bundle de memória v2 ausente (vault legado); inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+    warnings.push(`Bundle de memória v2 ausente (vault legado); inspecione com: ${memoryStatusCommand(vaultBase)}.`);
   }
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.67.1",
+  "version": "0.67.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": [
@@ -70,6 +70,6 @@
   },
   "devDependencies": {
     "acorn": "^8.18.0",
-    "wendkeep": "^0.67.0"
+    "wendkeep": "^0.67.2"
   }
 }

package/packages/cli/src/index.mjs

@@ -99,7 +99,7 @@ Usage:
                            in session notes from the linked derived notes — the body used to lag
                            behind the closing block. Dry-run by default · --apply · --json.
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
-  wendkeep memory <sub>          Shared memory v2: status | migrate [--apply] | repair |
+  wendkeep memory <sub>          Shared memory v2: status | candidates [--active] | migrate [--apply] | repair |
                            recover-attempt <session> [--apply] |
                            reconcile <session> --by-session <session> --reason <text> [--apply] |
                            promote <candidate> [--event <event-id>] | reject <candidate>. --vault P.

package/src/memory.mjs

@@ -237,6 +237,48 @@ function readCandidates(vault) {
     .split('\n').filter(Boolean).map((line) => JSON.parse(line));
 }
 
+const TERMINAL_CANDIDATE_STATUSES = new Set(['resolved', 'rejected', 'superseded']);
+
+function lexicalCompare(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function sanitizedCandidate(candidate, index) {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} inválido.`);
+  }
+  const required = ['candidate_id', 'reason', 'memory_key'];
+  const missing = required.filter((field) => typeof candidate[field] !== 'string' || !candidate[field]);
+  if (missing.length) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} sem ${missing.join(', ')}.`);
+  }
+  if (candidate.status !== undefined && (typeof candidate.status !== 'string' || !candidate.status)) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} possui status inválido.`);
+  }
+  const eventIds = candidate.event_ids ?? [];
+  if (!Array.isArray(eventIds) || eventIds.some((eventId) => typeof eventId !== 'string' || !eventId)) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} possui event_ids inválidos.`);
+  }
+  return {
+    candidate_id: candidate.candidate_id,
+    reason: candidate.reason,
+    status: candidate.status || 'active',
+    memory_key: candidate.memory_key,
+    event_ids: [...eventIds].sort(lexicalCompare),
+  };
+}
+
+export function listMemoryCandidates(vault, { activeOnly = false } = {}) {
+  const candidates = readCandidates(vault)
+    .map(sanitizedCandidate)
+    .filter((candidate) => !activeOnly || !TERMINAL_CANDIDATE_STATUSES.has(candidate.status))
+    .sort((left, right) => lexicalCompare(left.memory_key, right.memory_key)
+      || lexicalCompare(left.candidate_id, right.candidate_id));
+  return { status: 'ok', candidates };
+}
+
 function priorCandidateDecision(vault, candidateId) {
   return readMemoryLedger(vault).events.find(
     (event) => event.candidate_decision?.candidate_id === candidateId,
@@ -1897,10 +1939,49 @@ function parseRecoverAttemptArgs(argv) {
   };
 }
 
+function parseCandidatesArgs(argv) {
+  const seen = new Set();
+  let activeOnly = false;
+  let vault = '';
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw memoryUsageError(`memory candidates recebeu argumento posicional extra: ${token}.`);
+    }
+
+    const equalAt = token.indexOf('=');
+    const name = equalAt >= 0 ? token.slice(0, equalAt) : token;
+    if (name !== '--active' && name !== '--vault') {
+      throw memoryUsageError(`memory candidates recebeu opção desconhecida: ${name}.`);
+    }
+    if (seen.has(name)) {
+      throw memoryUsageError(`memory candidates recebeu opção duplicada: ${name}.`);
+    }
+    seen.add(name);
+
+    if (name === '--active') {
+      if (equalAt >= 0) throw memoryUsageError('--active não aceita valor.');
+      activeOnly = true;
+      continue;
+    }
+
+    const value = equalAt >= 0 ? token.slice(equalAt + 1) : argv[index + 1];
+    if (!value || !value.trim() || value.startsWith('--')) {
+      throw memoryUsageError('--vault requer valor não vazio que não comece com --.');
+    }
+    vault = value;
+    if (equalAt < 0) index += 1;
+  }
+
+  return { activeOnly, vault };
+}
+
 export function runMemory(argv) {
   const [sub, positional] = argv;
   let reconcileArgs = null;
   let recoverAttemptArgs = null;
+  let candidatesArgs = null;
   if (sub === 'reconcile') {
     try {
       reconcileArgs = parseReconcileArgs(argv);
@@ -1919,14 +2000,26 @@ export function runMemory(argv) {
       return;
     }
   }
+  if (sub === 'candidates') {
+    try {
+      candidatesArgs = parseCandidatesArgs(argv);
+    } catch (error) {
+      process.stderr.write(`wendkeep memory: ${error.message}\n`);
+      process.exitCode = error.code === 'WENDKEEP_MEMORY_USAGE' ? 2 : 1;
+      return;
+    }
+  }
   const vault = (
-    recoverAttemptArgs?.vault || reconcileArgs?.vault || option(argv, '--vault')
+    recoverAttemptArgs?.vault || reconcileArgs?.vault || candidatesArgs?.vault || option(argv, '--vault')
   ) || process.env.OBSIDIAN_VAULT_PATH;
   if (!vault) { process.stderr.write('wendkeep memory: passe --vault <path>.\n'); process.exitCode = 2; return; }
   if (!existsSync(vault)) { process.stderr.write(`wendkeep memory: not found: ${vault}\n`); process.exitCode = 2; return; }
   try {
     let result;
     if (sub === 'status') result = memoryStatus(vault);
+    else if (sub === 'candidates') {
+      result = listMemoryCandidates(vault, { activeOnly: candidatesArgs.activeOnly });
+    }
     else if (sub === 'migrate') result = migrateMemory(vault, { apply: argv.includes('--apply') });
     else if (sub === 'repair') result = repairMemory(vault);
     else if (sub === 'reconcile') {
@@ -1950,7 +2043,7 @@ export function runMemory(argv) {
         action: sub, candidateId: positional, ...(eventId ? { eventId } : {}),
       });
     }
-    else { process.stderr.write('wendkeep memory: use status | migrate [--apply] | repair | recover-attempt <session> [--apply] | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> [--event <event-id>] | reject <candidate>.\n'); process.exitCode = 2; return; }
+    else { process.stderr.write('wendkeep memory: use status | candidates [--active] | migrate [--apply] | repair | recover-attempt <session> [--apply] | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> [--event <event-id>] | reject <candidate>.\n'); process.exitCode = 2; return; }
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     if (sub === 'status' && argv.includes('--gate')) process.exitCode = result.status === 'blocked' ? 1 : 0;
     else if (sub === 'reconcile' && reconcileArgs.apply) process.exitCode = result.health?.status === 'blocked' ? 1 : 0;