wendkeep 0.68.1 → 0.68.6

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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.6] — 2026-08-16
+
+### Fixed
+
+- **A orientação de atualização em monorepos pnpm agora resolve a versão publicada antes da
+  instalação.** README e guias bilíngues deixam de oferecer `X.Y.Z` como argumento copiável,
+  explicam o cooldown silencioso de `@latest` e orientam a regeneração segura do lock quando a
+  integridade do tarball divergir.
+
+## [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

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`.
@@ -173,24 +176,37 @@ The install stays outside `sync` on purpose: a running process cannot replace it
 keep going — the code in memory would still be the old one.
 
 In a **pnpm** monorepo the install command differs (`npm` in a pnpm repo fails with
-`Cannot read properties of null (reading 'matches')`) and the version must be **exact**:
-
-```bash
-pnpm add -D -w wendkeep@X.Y.Z --config.minimumReleaseAge=0 && npx --no-install wendkeep sync --project . --yes
+`Cannot read properties of null (reading 'matches')`). Resolve the published version first and
+reuse exactly the value returned:
+
+```powershell
+$version = pnpm view wendkeep version
+pnpm add -D -w "wendkeep@$version" --config.minimumReleaseAge=0
+pnpm install --update-checksums --config.minimumReleaseAge=0
+pnpm exec wendkeep sync --project . --yes
 ```
 
 > **Do not ask pnpm for `wendkeep@latest`.** pnpm 11 ignores packages published in the last
 > 24h by default (`minimumReleaseAge`, a supply-chain guard) — and it does not complain: it
 > installs the previous version, exits 0, and the only hint is a quiet `(X.Y.Z is available)`
 > in the output. You end up on the old version thinking you upgraded. Check with
-> `npx wendkeep --version`.
+> `pnpm exec wendkeep --version`.
+>
+> Do not edit only the version or integrity in `pnpm-lock.yaml`. `pnpm add` and
+> `pnpm install --update-checksums` must recalculate the complete entry. If the lock is already
+> inconsistent and `ERR_PNPM_TARBALL_INTEGRITY` appears, prune the local store and repeat:
+>
+> ```powershell
+> pnpm store prune
+> pnpm install --update-checksums --config.minimumReleaseAge=0
+> ```
 >
 > After installing, record the exception in `pnpm-workspace.yaml` — **pnpm does not write
 > that line for you**:
 >
 > ```yaml
 > minimumReleaseAgeExclude:
->   - wendkeep@X.Y.Z
+>   - wendkeep@<the version returned by pnpm view>
 > ```
 >
 > Without it, CI's `pnpm install` fails with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` until
@@ -379,8 +395,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 +410,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 +542,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`.
@@ -173,24 +176,37 @@ The install stays outside `sync` on purpose: a running process cannot replace it
 keep going — the code in memory would still be the old one.
 
 In a **pnpm** monorepo the install command differs (`npm` in a pnpm repo fails with
-`Cannot read properties of null (reading 'matches')`) and the version must be **exact**:
-
-```bash
-pnpm add -D -w wendkeep@X.Y.Z --config.minimumReleaseAge=0 && npx --no-install wendkeep sync --project . --yes
+`Cannot read properties of null (reading 'matches')`). Resolve the published version first and
+reuse exactly the value returned:
+
+```powershell
+$version = pnpm view wendkeep version
+pnpm add -D -w "wendkeep@$version" --config.minimumReleaseAge=0
+pnpm install --update-checksums --config.minimumReleaseAge=0
+pnpm exec wendkeep sync --project . --yes
 ```
 
 > **Do not ask pnpm for `wendkeep@latest`.** pnpm 11 ignores packages published in the last
 > 24h by default (`minimumReleaseAge`, a supply-chain guard) — and it does not complain: it
 > installs the previous version, exits 0, and the only hint is a quiet `(X.Y.Z is available)`
 > in the output. You end up on the old version thinking you upgraded. Check with
-> `npx wendkeep --version`.
+> `pnpm exec wendkeep --version`.
+>
+> Do not edit only the version or integrity in `pnpm-lock.yaml`. `pnpm add` and
+> `pnpm install --update-checksums` must recalculate the complete entry. If the lock is already
+> inconsistent and `ERR_PNPM_TARBALL_INTEGRITY` appears, prune the local store and repeat:
+>
+> ```powershell
+> pnpm store prune
+> pnpm install --update-checksums --config.minimumReleaseAge=0
+> ```
 >
 > After installing, record the exception in `pnpm-workspace.yaml` — **pnpm does not write
 > that line for you**:
 >
 > ```yaml
 > minimumReleaseAgeExclude:
->   - wendkeep@X.Y.Z
+>   - wendkeep@<the version returned by pnpm view>
 > ```
 >
 > Without it, CI's `pnpm install` fails with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` until
@@ -379,8 +395,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 +410,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 +542,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/getting-started.md

@@ -60,14 +60,22 @@ npm install --save-dev wendkeep@latest
 npx wendkeep sync --yes
 ```
 
-With pnpm, pin a concrete version because minimum-release-age policies may keep `latest` silently
-behind:
+With pnpm, query the published version and reuse the returned value. Minimum-release-age policies
+may keep `latest` silently behind; in a monorepo, `-w` targets the workspace root:
 
-```bash
-pnpm add -D wendkeep@X.Y.Z --config.minimumReleaseAge=0
+```powershell
+$version = pnpm view wendkeep version
+pnpm add -D -w "wendkeep@$version" --config.minimumReleaseAge=0
+pnpm install --update-checksums --config.minimumReleaseAge=0
 pnpm exec wendkeep sync --yes
 ```
 
+Do not edit only the version or integrity in `pnpm-lock.yaml`. If
+`ERR_PNPM_TARBALL_INTEGRITY` appears after a manual edit, run `pnpm store prune` and repeat
+`pnpm install --update-checksums --config.minimumReleaseAge=0`. The
+`minimumReleaseAgeExclude` entry in `pnpm-workspace.yaml` is also manual and must use the
+version returned by `pnpm view`; pnpm does not write that line.
+
 ## Expected result
 
 The project receives `.wendkeep.json`, managed Claude/Codex hooks, skill definitions, and an

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/getting-started.md

@@ -60,14 +60,22 @@ npm install --save-dev wendkeep@latest
 npx wendkeep sync --yes
 ```
 
-Com pnpm, informe uma versão concreta porque políticas de idade mínima podem manter `latest`
-atrasado silenciosamente:
+Com pnpm, consulte a versão publicada e reutilize o valor retornado. Políticas de idade mínima
+podem manter `latest` atrasado silenciosamente; em um monorepo, `-w` aponta para o workspace raiz:
 
-```bash
-pnpm add -D wendkeep@X.Y.Z --config.minimumReleaseAge=0
+```powershell
+$version = pnpm view wendkeep version
+pnpm add -D -w "wendkeep@$version" --config.minimumReleaseAge=0
+pnpm install --update-checksums --config.minimumReleaseAge=0
 pnpm exec wendkeep sync --yes
 ```
 
+Não edite apenas a versão ou a integridade no `pnpm-lock.yaml`. Se aparecer
+`ERR_PNPM_TARBALL_INTEGRITY` depois de uma edição manual, rode `pnpm store prune` e repita
+`pnpm install --update-checksums --config.minimumReleaseAge=0`. A exceção
+`minimumReleaseAgeExclude` do `pnpm-workspace.yaml` também é manual e deve usar a versão
+retornada por `pnpm view`; o pnpm não escreve essa linha.
+
 ## Resultado esperado
 
 O projeto recebe `.wendkeep.json`, hooks gerenciados de Claude/Codex, definições de skills e um

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