wendkeep 0.68.0 → 0.68.5

package/CHANGELOG.md

@@ -4,6 +4,73 @@ 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.68.5] — 2026-08-14
+
+### Fixed
+
+- **O Stop passa a deixar um resultado durável por sessão, turno e estágio.** O ledger local,
+  append-only,
+  sanitizado distingue inserção, duplicata, caminho pulado, abortado, lock ocupado, falha e status
+  de observabilidade; o cursor só avança após confirmação da nota.
+- **A importação Codex compartilha a normalização de conteúdo sintético e ferramentas.**
+  `subagent_notification` não vira prompt, `turn_aborted` é explícito e a saída de uma
+  `custom_tool_call` não é contada como uma segunda chamada.
+- **O encerramento de uma sessão alinha a projeção e a autoridade causal.** O Stop marca a
+  activation e a sessão como `done` no `SESSION_REGISTRY.json` somente depois da publicação de
+  memória/observabilidade; `CURRENT_SESSION.md` continua sendo uma visão derivada e não lista
+  sessões já finalizadas.
+- **O release automático publica no npm por OIDC antes de criar tag e GitHub Release.** O
+  `auto-tag.yml` usa Node 24, prepara o registry público, ignora versões já publicadas com
+  `--prefer-online` e deixa a provenance ser gerada pela própria publicação confiável.
+
+## [0.68.4] — 2026-08-14
+
+### Fixed
+
+- **O guard de escopo do projeto passa a proteger mutações antes da ferramenta.** O `PreToolUse`
+  do Codex revalida sessão, projeto, raiz Git, remoto, branch/worktree e concorrência; mantém
+  `commit`, `push`, `pull`, `merge`, `publish` e operações destrutivas como capacidades
+  independentes, com bloqueio fail-closed para alvos ausentes ou divergentes.
+
+## [0.68.3] — 2026-08-13
+
+### Fixed
+
+- **Deferred replay reancora candidates de memória na fonte causal final.** Depois de uma
+  promoção legacy válida, um assert moderno reaplicado pelo replay não deixa mais os
+  candidates posteriores presos à fonte intermediária. A promoção explícita continua
+  exigindo o guard causal e mantém o fail-closed para linhagens incompletas ou ambíguas;
+  o ledger permanece append-only.
+
+## [0.68.2] — 2026-08-08
+
+### Fixed
+
+- **O guard do `npm run release` deixa de bloquear a tag criada pelo `auto-tag.yml`.** Os dois
+  automatismos assumem ordens opostas: o script publica no npm e então cria a tag, enquanto o
+  workflow cria a tag no merge em `main`, antes de qualquer publish. Quando o merge precedia o
+  publish — o caminho normal de um PR — o release abortava num estado perfeitamente publicável.
+  O guard passa a proteger a unicidade da versão no registry, não a ausência da tag: publica e
+  preserva a tag existente quando ela aponta para o commit corrente, e continua abortando se a
+  versão já foi lançada ou se a tag aponta para outro commit. A decisão virou função pura, então
+  a matriz de estados é verificável sem publicar nem mutar o repositório.
+
+## [0.68.1] — 2026-08-08
+
+### Fixed
+
+- **A contenção de locks do Vault deixa de expor `VAULT_PATH_UNSAFE` no Windows.** A revalidação de
+  uma falha transiente de resolução do lock público passa a decidir por um walk fresco do
+  componente, e não pelo `errno` reportado pela plataforma. O Windows devolve `UNKNOWN`, `EBADF` ou
+  `EPERM` onde o Linux devolve `ENOENT`, então a guarda de retry nunca disparava lá e promoções FLOW
+  concorrentes falhavam de forma intermitente com o código de fronteira física em vez do conflito de
+  promoção. Sufixo ausente ou diretório canônico estabilizado autorizam o retry; junction, symlink,
+  reparse point, componente redirecionado ou estado irresolvível persistente continuam falhando
+  fechado, e o orçamento de retry permanece único e limitado por aquisição.
+- **Falha de lock nos caminhos FLOW reporta o código do domínio.** `withFlowPromotionLock` e o store
+  de sessão passam a propagar `FLOW_VAULT_BOUNDARY` para a fronteira física, alinhando a superfície
+  de erro ao resto da saga de promoção.
+
 ## [0.68.0] — 2026-08-02
 
 ### Added

package/README.en.md

@@ -91,8 +91,11 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 
 ## Requirements
 
+The Codex scope guard treats `commit`, `push`, `pull`, `merge`, `publish`, and destructive
+operations as independent capabilities, including inside compound commands.
+
 - Node.js ≥ 18
-- An AI coding agent with hooks. `init` wires **Claude Code** and **Codex** automatically — Codex gets the seven hooks its event model supports and enumerates them untrusted, so approve its “Hooks need review” prompt once at startup (see [Notes & roadmap](#notes--roadmap))
+- An AI coding agent with hooks. `init` wires **Claude Code** and **Codex** automatically — Codex gets eight compatible hooks, including the scoped `PreToolUse` guard, and enumerates them untrusted, so approve its “Hooks need review” prompt once at startup (see [Notes & roadmap](#notes--roadmap))
 - Obsidian (to view the graph) — optional but the point
 
 ## Install & set up
@@ -107,7 +110,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 session hooks in **`.codex/hooks.json`** — seven of the twelve: `brain-inject` + `session-start` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `change-nag` on `Stop`, `subagent-stop` on `SubagentStop`, always in the `npx wendkeep hook <name>` form. The other five are left out because Codex offers no equivalent payload, tool *or* event: `change-guard` (a `PreToolUse` gate reading `tool_input.command`, but Codex's `exec` carries `tool_input` as a raw string rather than an object, so the gate would fail *open*), `change-warn` (a `PostToolUse` nudge resolving `tool_input.file_path`, a field `apply_patch`'s envelope does not carry — nothing to resolve, and nothing to gate), `plan-capture` (there is no `ExitPlanMode`; `update_plan` is a running TODO list, not an approval), `decision-capture` (`AskUserQuestion` is a Claude-only tool) and `task-log` (`TaskCompleted` is not in Codex's event enum). See [Notes & roadmap](#notes--roadmap) for the per-hook detail. The merge is non-destructive, on the same discipline as `settings.json`: it recognizes an already-wired group and never duplicates on re-init, preserves third-party hooks, saves a `.bak`, and `--force` updates `timeoutSec`/`statusMessage` in place; an unparseable `.codex/hooks.json` is left untouched with the merge written to `.codex/hooks.json.new`. **Codex enumerates every hook as untrusted and runs none of them until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**, and it prints a warning saying so. Anyone who already had hand-written wendkeep hooks in Codex gets one re-review prompt: `init` migrates the legacy `timeout` key (which Codex neither rejects nor reads, falling through to a 600s default) to `timeoutSec`, and that changes the hook's hashed identity.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — eight of the twelve: `brain-inject` + `session-start` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `change-nag` on `Stop`, `subagent-stop` 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. 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. 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`.
@@ -379,8 +382,9 @@ it does not expose memory values or content. After human review,
 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
-final modern source: the same session/activation/epoch and a higher turn advances; a lower turn is
-superseded. Repair migrates the checkpoint and mirror only when it proves the exact previous
+final modern source and, when causal supersession is proven, re-anchored to it; explicit promotion
+uses that anchor and crosses only the physical predecessors required by replay. The same
+session/activation/epoch and a higher turn advances; a lower turn is superseded. Repair migrates the checkpoint and mirror only when it proves the exact previous
 replay, attempt identity, and absence of a real conflict; it creates a backup and audit without
 appending or rewriting events. Ambiguity stays queued for explicit curation. Do not publish or
 install 0.66.2; use 0.66.3 or later. Decisions survive repair/replay;
@@ -393,7 +397,11 @@ acknowledgement pending on 0.66.4 or later, first run the targeted dry run
 registry/checkpoint. See syntax, preconditions, and fail-closed behavior in
 [memory and curation](docs/en/commands/memory.md).
 
-Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. On Codex, subagent prompts register their rollout for observability without advancing the main agent's sequence; `SubagentStop` reads the child from `agent_transcript_path` and persists its signal only when `parent_thread_id` matches a validated session root. The main Stop uses the registry's causal `turn_id` mapping before falling back to local transcript order. To recover missing markers while a conversation is open, `hook session-backfill` is a dry-run by default and never writes a Codex turn without `task_complete`. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
+Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. On Codex, subagent prompts register their rollout for observability without advancing the main agent's sequence; `SubagentStop` reads the child from `agent_transcript_path` and persists its signal only when `parent_thread_id` matches a validated session root. The main Stop uses the registry's causal `turn_id` mapping before falling back to local transcript order. Every terminal attempt writes a sanitized, idempotent receipt to `.brain/SESSION_ITERATION_OUTCOMES.jsonl`, distinguishing insertion, duplicate, skipped, aborted, busy-lock, failure, and observability status; the cursor advances only after note confirmation. `subagent_notification` is not a human prompt, `turn_aborted` is explicit, and custom tool output is not double-counted. To recover missing markers while a conversation is open, `hook session-backfill` is a dry-run by default and never writes a Codex turn without `task_complete`. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
+
+On definitive close, the activation and session become `done` in `SESSION_REGISTRY.json` only
+after memory/observability publication; `CURRENT_SESSION.md` is a derived view, not the identity
+authority, and does not list finalized sessions.
 
 ## Retroactive memory (`import`) — install today, remember yesterday
 
@@ -521,7 +529,7 @@ The archive **gate** blocks unless: the change scaffold is filled (G0), no task
 - **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
 - **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
-- Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Five hooks stay Claude‑only** because Codex has no equivalent payload, tool or event: `change-guard` (a `PreToolUse` gate that reads `tool_input.command`, but Codex's `exec` carries `tool_input` as a raw string rather than an object — the gate would fail *open*), `change-warn` (a `PostToolUse` nudge that resolves `tool_input.file_path`, which `apply_patch`'s envelope simply does not carry — nothing to resolve, and nothing to gate), `plan-capture` (no `ExitPlanMode` — `update_plan` is a running TODO list, not an approval), `decision-capture` (`AskUserQuestion` is Claude‑only) and `task-log` (`TaskCompleted` is not in Codex's event enum).
+- Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Eight Codex hooks are compatible**; `change-guard` validates the project lease in `PreToolUse` and denies mutations outside it. The four hooks without an equivalent remain Claude-only: `change-warn`, `plan-capture`, `decision-capture`, and `task-log`.
 - **Codex hooks start untrusted.** They are enumerated but not executed until you approve the “Hooks need review” prompt; `init` cannot pre‑approve them (`--dangerously-bypass-hook-trust` is per‑invocation and stores no trusted hash). Trust is keyed to the hook's identity, so hand‑written wendkeep Codex hooks predating `0.46.0` — which ran at the 600s default because they used `timeout` instead of `timeoutSec` — cost one re‑review after `init` corrects the key. Expected, not a regression. `import --source codex` still backfills past Codex sessions either way.
 
 ---

package/README.md

@@ -91,8 +91,11 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 
 ## Requirements
 
+The Codex scope guard treats `commit`, `push`, `pull`, `merge`, `publish`, and destructive
+operations as independent capabilities, including inside compound commands.
+
 - Node.js ≥ 18
-- An AI coding agent with hooks. `init` wires **Claude Code** and **Codex** automatically — Codex gets the seven hooks its event model supports and enumerates them untrusted, so approve its “Hooks need review” prompt once at startup (see [Notes & roadmap](#notes--roadmap))
+- An AI coding agent with hooks. `init` wires **Claude Code** and **Codex** automatically — Codex gets eight compatible hooks, including the scoped `PreToolUse` guard, and enumerates them untrusted, so approve its “Hooks need review” prompt once at startup (see [Notes & roadmap](#notes--roadmap))
 - Obsidian (to view the graph) — optional but the point
 
 ## Install & set up
@@ -107,7 +110,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 session hooks in **`.codex/hooks.json`** — seven of the twelve: `brain-inject` + `session-start` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `change-nag` on `Stop`, `subagent-stop` on `SubagentStop`, always in the `npx wendkeep hook <name>` form. The other five are left out because Codex offers no equivalent payload, tool *or* event: `change-guard` (a `PreToolUse` gate reading `tool_input.command`, but Codex's `exec` carries `tool_input` as a raw string rather than an object, so the gate would fail *open*), `change-warn` (a `PostToolUse` nudge resolving `tool_input.file_path`, a field `apply_patch`'s envelope does not carry — nothing to resolve, and nothing to gate), `plan-capture` (there is no `ExitPlanMode`; `update_plan` is a running TODO list, not an approval), `decision-capture` (`AskUserQuestion` is a Claude-only tool) and `task-log` (`TaskCompleted` is not in Codex's event enum). See [Notes & roadmap](#notes--roadmap) for the per-hook detail. The merge is non-destructive, on the same discipline as `settings.json`: it recognizes an already-wired group and never duplicates on re-init, preserves third-party hooks, saves a `.bak`, and `--force` updates `timeoutSec`/`statusMessage` in place; an unparseable `.codex/hooks.json` is left untouched with the merge written to `.codex/hooks.json.new`. **Codex enumerates every hook as untrusted and runs none of them until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**, and it prints a warning saying so. Anyone who already had hand-written wendkeep hooks in Codex gets one re-review prompt: `init` migrates the legacy `timeout` key (which Codex neither rejects nor reads, falling through to a 600s default) to `timeoutSec`, and that changes the hook's hashed identity.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — eight of the twelve: `brain-inject` + `session-start` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `change-nag` on `Stop`, `subagent-stop` 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. 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. 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`.
@@ -379,8 +382,9 @@ it does not expose memory values or content. After human review,
 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
-final modern source: the same session/activation/epoch and a higher turn advances; a lower turn is
-superseded. Repair migrates the checkpoint and mirror only when it proves the exact previous
+final modern source and, when causal supersession is proven, re-anchored to it; explicit promotion
+uses that anchor and crosses only the physical predecessors required by replay. The same
+session/activation/epoch and a higher turn advances; a lower turn is superseded. Repair migrates the checkpoint and mirror only when it proves the exact previous
 replay, attempt identity, and absence of a real conflict; it creates a backup and audit without
 appending or rewriting events. Ambiguity stays queued for explicit curation. Do not publish or
 install 0.66.2; use 0.66.3 or later. Decisions survive repair/replay;
@@ -393,7 +397,11 @@ acknowledgement pending on 0.66.4 or later, first run the targeted dry run
 registry/checkpoint. See syntax, preconditions, and fail-closed behavior in
 [memory and curation](docs/en/commands/memory.md).
 
-Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. On Codex, subagent prompts register their rollout for observability without advancing the main agent's sequence; `SubagentStop` reads the child from `agent_transcript_path` and persists its signal only when `parent_thread_id` matches a validated session root. The main Stop uses the registry's causal `turn_id` mapping before falling back to local transcript order. To recover missing markers while a conversation is open, `hook session-backfill` is a dry-run by default and never writes a Codex turn without `task_complete`. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
+Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. On Codex, subagent prompts register their rollout for observability without advancing the main agent's sequence; `SubagentStop` reads the child from `agent_transcript_path` and persists its signal only when `parent_thread_id` matches a validated session root. The main Stop uses the registry's causal `turn_id` mapping before falling back to local transcript order. Every terminal attempt writes a sanitized, idempotent receipt to `.brain/SESSION_ITERATION_OUTCOMES.jsonl`, distinguishing insertion, duplicate, skipped, aborted, busy-lock, failure, and observability status; the cursor advances only after note confirmation. `subagent_notification` is not a human prompt, `turn_aborted` is explicit, and custom tool output is not double-counted. To recover missing markers while a conversation is open, `hook session-backfill` is a dry-run by default and never writes a Codex turn without `task_complete`. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
+
+On definitive close, the activation and session become `done` in `SESSION_REGISTRY.json` only
+after memory/observability publication; `CURRENT_SESSION.md` is a derived view, not the identity
+authority, and does not list finalized sessions.
 
 ## Retroactive memory (`import`) — install today, remember yesterday
 
@@ -521,7 +529,7 @@ The archive **gate** blocks unless: the change scaffold is filled (G0), no task
 - **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
 - **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
-- Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Five hooks stay Claude‑only** because Codex has no equivalent payload, tool or event: `change-guard` (a `PreToolUse` gate that reads `tool_input.command`, but Codex's `exec` carries `tool_input` as a raw string rather than an object — the gate would fail *open*), `change-warn` (a `PostToolUse` nudge that resolves `tool_input.file_path`, which `apply_patch`'s envelope simply does not carry — nothing to resolve, and nothing to gate), `plan-capture` (no `ExitPlanMode` — `update_plan` is a running TODO list, not an approval), `decision-capture` (`AskUserQuestion` is Claude‑only) and `task-log` (`TaskCompleted` is not in Codex's event enum).
+- Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Eight Codex hooks are compatible**; `change-guard` validates the project lease in `PreToolUse` and denies mutations outside it. The four hooks without an equivalent remain Claude-only: `change-warn`, `plan-capture`, `decision-capture`, and `task-log`.
 - **Codex hooks start untrusted.** They are enumerated but not executed until you approve the “Hooks need review” prompt; `init` cannot pre‑approve them (`--dangerously-bypass-hook-trust` is per‑invocation and stores no trusted hash). Trust is keyed to the hook's identity, so hand‑written wendkeep Codex hooks predating `0.46.0` — which ran at the 600s default because they used `timeout` instead of `timeoutSec` — cost one re‑review after `init` corrects the key. Expected, not a regression. `import --source codex` still backfills past Codex sessions either way.
 
 ---

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

@@ -70,6 +70,18 @@ npx wendkeep sensors add api-contracts "npm run test:contracts" --severity criti
 An archived change promotes its delta into the living spec, preserves proposal/design/tasks/proof,
 and mints an ADR. Archive passes only with closed tasks, green required sensors, and a fresh verdict.
 
+## Tool-scope fence
+
+`change-guard` is also projected to Codex `PreToolUse`. Before a Git mutation or supported writing
+tool runs, it compares the session, project, Git root, remote, branch, and worktree with the lease
+recorded in `SESSION_REGISTRY.json`. Missing, ambiguous, concurrent, or cross-project targets are
+blocked before the tool.
+
+Codex blocks with `permissionDecision: "deny"`; `ask` is not a valid `PreToolUse` decision.
+`commit`, `push`, `pull`, `merge`, `publish`, and destructive operations remain separate capabilities,
+including when one command contains multiple actions. Switching projects requires a new explicit
+selection/lease; never carry authorization from another conversation.
+
 ## Common errors and diagnosis
 
 - `no change`: select one with `change use <slug>` or pass `--change`.

package/docs/en/commands/memory.md

@@ -108,7 +108,9 @@ npx wendkeep validate-memory --vault <v2-vault>
   the already validated JSON value without string coercion and copies the selected event's
   `canonical_session_id`, activation/epoch, `source_turn_id`, and `turn_sequence`. A later Stop
   from the same session/activation therefore advances the value instead of opening another candidate.
-  During replay, a transient candidate is re-evaluated against the final modern source. The same
+  During replay, a transient candidate is re-evaluated and, when causal supersession is proven,
+  re-anchored to the final modern source; explicit promotion uses that new anchor and includes only
+  the physical predecessors needed for replay. The same
   session/activation/epoch and a higher turn applies the Stop; a lower turn is superseded. A
   different, incomplete, or ambiguous identity keeps the candidate queued for curation. `memory
   repair` compares the old and current replay and migrates checkpoint+mirror only with exact

package/docs/en/commands/operating-profiles.md

@@ -33,6 +33,17 @@ change.
 - For FLOW, a Git repository, a path allowlist, a reason, and at least one existing sensor in
   `wendkeep.sensors.json`.
 
+### Tool scope and Git authorization
+
+Under `GOVERN`/`ASSURE`, Codex `PreToolUse` and the equivalent Claude gate validate the project lease
+before mutations. The lease includes the session, `project_id`, project root, Git root, remote,
+branch/worktree, and provider. `commit`, `push`, `pull`, `merge`, `publish`, and destructive operations
+are independent capabilities, including in compound commands; authorization never crosses projects or
+branches.
+
+If the host does not expose the effective directory, or the session is conflicted, the mutation is
+denied with a sanitized diagnostic. Read-only inspection may continue for investigation.
+
 ## Syntax
 
 ```bash

package/docs/en/commands/sessions-and-import.md

@@ -63,6 +63,13 @@ npx wendkeep import [options]
 - Observability is tri-state: `complete` publishes the full snapshot; `none` means zero proven by
   a causal Stop or stable offline scan; `degraded` preserves the previous snapshot and allowlisted
   diagnostics. An isolated `SubagentStop` never publishes `none`.
+- Every terminal `Stop`/`SubagentStop` attempt leaves a sanitized receipt in
+  `.brain/SESSION_ITERATION_OUTCOMES.jsonl`, keyed by session, `turn_id`, and stage. States
+  distinguish `inserted`, `duplicate`, `skipped`, `aborted`, `busy`, `failed`, and observability
+  statuses; the cursor advances only after the note is confirmed. The ledger is local, append-only,
+  idempotent, and never persists prompts, payloads, raw arguments, or raw errors.
+- In Codex, `subagent_notification` remains synthetic, `turn_aborted` is an explicit terminal
+  state, and `custom_tool_call_output` closes the existing call without counting a second tool.
 - When compacting conversations into `## Iterações`, the hook escapes code delimiters cut by the
   size limit; inline backticks and fences never remain open and consume the following line.
 - `session list` reads `SESSION_REGISTRY`; `show` displays one session and `use` only changes human
@@ -73,6 +80,10 @@ npx wendkeep import [options]
 - `import` reconciles observability even when no `wk-turn` is missing: a legacy schema, stale
   frontier, or unproven manifest triggers recomposition without duplicating iterations. A fresh
   checkpoint remains byte-identical; `degraded` is reported and does not change the note.
+- On definitive close, Stop marks the activation and session `done` in `SESSION_REGISTRY.json`
+  only after memory/observability publication; `CURRENT_SESSION.md` is a derived view and no
+  longer lists the finalized session. Hooks resolve identity from the registry and transcript,
+  never from the global pointer.
 - `hook session-backfill` recovers missing `wk-turn` markers for the selected session. Without
   `--write`, it only reports. On Codex, `missingTurns` contains only turns with `task_complete`;
   open turns appear under `incompleteTurns` and are never written. `--write` applies only completed
@@ -105,6 +116,8 @@ only recognized generated fields under `Iterações` and `Encerramento` are migr
 authored prose.
 Duplicate/stale hooks converge on the same frontier, and imports may refresh only observability
 without creating a new turn block.
+The per-attempt receipt in `SESSION_ITERATION_OUTCOMES.jsonl` distinguishes a confirmed duplicate
+from a busy lock or skipped path without reopening the original session.
 
 ## Common errors and diagnosis
 
@@ -122,6 +135,8 @@ without creating a new turn block.
 - Contaminated cost: validate `session_id → session_file → transcript_path → provider`.
 - `degraded` observability: preserve the note and run a targeted rebuild dry-run; never force a
   partial snapshot over the last `complete` one.
+- Missing or `busy` outcome ledger: preserve the transcript and note, inspect the Vault lock, and
+  retry the bounded hook/replay path; never mark the turn projected by hand.
 
 ## Next steps
 

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

@@ -70,6 +70,18 @@ npx wendkeep sensors add api-contracts "npm run test:contracts" --severity criti
 A change arquivada move seu delta para o spec vivo, preserva proposta/design/tarefas/evidência e
 gera um ADR. O archive só passa com tarefas fechadas, sensores exigidos verdes e verdict atual.
 
+## Cerca de escopo para ferramentas
+
+O `change-guard` também é projetado para o `PreToolUse` do Codex. Antes de uma mutação Git ou de
+uma ferramenta de escrita suportada, ele compara sessão, projeto, raiz Git, remoto, branch e
+worktree com a lease registrada no `SESSION_REGISTRY.json`. Um alvo ausente, ambíguo, concorrente ou
+fora do projeto é bloqueado antes da ferramenta.
+
+No Codex o bloqueio usa `permissionDecision: "deny"`; `ask` não é uma decisão válida de
+`PreToolUse`. `commit`, `push`, `pull`, `merge`, `publish` e operações destrutivas continuam
+capacidades separadas, inclusive quando um comando contém mais de uma ação. A troca de projeto
+exige uma nova seleção/lease; não use autorização de outra conversa.
+
 ## Erros comuns e diagnóstico
 
 - `no change`: selecione com `change use <slug>` ou informe `--change`.

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

@@ -106,7 +106,9 @@ npx wendkeep validate-memory --vault <cofre-v2>
   A decisão conserva, sem coerção para string, o valor JSON já validado e copia do evento escolhido
   `canonical_session_id`, activation/epoch, `source_turn_id` e `turn_sequence`. Por isso, um Stop
   posterior da mesma sessão/activation avança o valor em vez de abrir outro candidate. Durante o
-  replay, um candidate transitório é reavaliado contra a fonte moderna final. Mesma
+  replay, um candidate transitório é reavaliado e, quando a supersession causal é provada,
+  reancorado contra a fonte moderna final; a promoção explícita usa essa nova âncora e inclui
+  somente os predecessores físicos necessários. Mesma
   sessão/activation/epoch e turno maior aplica o Stop; turno menor fica superseded. Identidade
   divergente, incompleta ou ambígua mantém o candidate para curadoria. `memory repair` compara o
   replay anterior e o atual e só migra checkpoint+espelho com identidade exata, backup, audit e

package/docs/pt-BR/commands/operating-profiles.md

@@ -33,6 +33,17 @@ gates/policies do WendKeep; promova o trabalho para uma change.
 - Para FLOW, repositório Git, allowlist de paths, motivo e ao menos um sensor existente em
   `wendkeep.sensors.json`.
 
+### Escopo de ferramenta e autorização Git
+
+Em `GOVERN`/`ASSURE`, o `PreToolUse` do Codex e o gate equivalente do Claude validam a lease de
+projeto antes de mutações. A lease inclui sessão, `project_id`, raiz do projeto, raiz Git, remoto,
+branch/worktree e provider. `commit`, `push`, `pull`, `merge`, `publish` e operações destrutivas são
+capacidades independentes, inclusive em comandos compostos; uma autorização não atravessa projetos
+nem branches.
+
+Se o host não expuser o diretório efetivo, ou se a sessão estiver em conflito, a mutação é negada
+com diagnóstico sanitizado. Somente leitura pode continuar para investigação.
+
 ## Sintaxe
 
 ```bash

package/docs/pt-BR/commands/sessions-and-import.md

@@ -62,6 +62,13 @@ npx wendkeep import [opções]
 - A observabilidade usa tri-state: `complete` publica o snapshot integral; `none` representa zero
   comprovado por Stop causal ou scan offline estável; `degraded` preserva o snapshot anterior e
   diagnostics allowlisted. `SubagentStop` isolado nunca publica `none`.
+- Cada tentativa terminal de `Stop`/`SubagentStop` deixa um recibo sanitizado em
+  `.brain/SESSION_ITERATION_OUTCOMES.jsonl`, indexado por sessão, `turn_id` e estágio. Os estados
+  distinguem `inserted`, `duplicate`, `skipped`, `aborted`, `busy`, `failed` e os status de
+  observabilidade; o cursor só avança depois da confirmação da nota. O ledger é local, append-only,
+  idempotente e nunca persiste prompt, payload, argumento bruto ou erro bruto.
+- No Codex, `subagent_notification` continua sintético, `turn_aborted` é terminal explícito e
+  `custom_tool_call_output` fecha a chamada existente sem contar uma segunda ferramenta.
 - Ao compactar conversas em `## Iterações`, o hook escapa delimitadores de código cortados pelo
   limite de tamanho; backticks inline ou fences nunca ficam abertos para engolir a linha seguinte.
 - `session list` lê `SESSION_REGISTRY`; `show` exibe uma sessão e `use` muda apenas o foco humano
@@ -72,6 +79,10 @@ npx wendkeep import [opções]
 - `import` reconcilia a observabilidade mesmo quando nenhum `wk-turn` está ausente: schema legado,
   frontier stale ou manifest não comprovado disparam recomposição sem duplicar iterações. Um
   checkpoint fresco permanece byte-idêntico; `degraded` é reportado e não altera a nota.
+- No encerramento definitivo, o Stop fecha a activation e a sessão como `done` no
+  `SESSION_REGISTRY.json` depois de memória/observabilidade; `CURRENT_SESSION.md` é uma visão
+  derivada e deixa de listar a sessão finalizada. Hooks resolvem identidade pelo registry e pelo
+  transcript, nunca pelo ponteiro global.
 - `hook session-backfill` recupera `wk-turn` ausente da sessão selecionada. Sem `--write`, apenas
   relata. Em Codex, `missingTurns` contém somente turnos com `task_complete`; turnos ainda abertos
   aparecem em `incompleteTurns` e nunca são gravados. `--write` aplica apenas os candidatos
@@ -104,6 +115,8 @@ ao finalizar uma nota antiga, somente campos gerados reconhecíveis em `Iteraç
 `Encerramento` são migrados, sem reescrever a prosa autoral. Hooks
 duplicados/stale convergem no mesmo frontier, e importações podem atualizar só a observabilidade
 sem criar um novo bloco de turno.
+O recibo de cada tentativa em `SESSION_ITERATION_OUTCOMES.jsonl` permite diferenciar uma duplicata
+confirmada de um lock ocupado ou de um caminho que foi pulado, sem reabrir a sessão original.
 
 ## Erros comuns e diagnóstico
 
@@ -121,6 +134,8 @@ sem criar um novo bloco de turno.
 - Custo contaminado: valide `session_id → session_file → transcript_path → provider`.
 - Observabilidade `degraded`: preserve a nota e rode o rebuild direcionado em dry-run; não force
   um snapshot parcial sobre o último `complete`.
+- Ledger de resultado ausente ou com `busy`: preserve o transcript e a nota, confira o lock do Vault
+  e repita o hook/replay limitado; nunca marque o turno como projetado manualmente.
 
 ## Próximos passos