wendkeep 0.66.4 → 0.66.5

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.66.5] — 2026-08-01
+
+### Fixed
+
+- **A observabilidade Codex passa a registrar o grafo completo de subagentes.** Metadata é
+  lida incrementalmente mesmo em rollouts grandes; descendentes em dias posteriores ou níveis
+  aninhados são atribuídos uma única vez, enquanto transcripts top-level permanecem no bucket
+  principal e sinais duplicados ou atrasados não regridem o snapshot publicado.
+- **SessionStop e SubagentStop convergem sob frontier causal e estado explícito.** O schema 2
+  distingue `complete`, `none` e `degraded`, coalesce rajadas com lease, preserva o último
+  snapshot íntegro diante de fonte incompleta e mantém cache/runtime reconstruíveis sem publicar
+  zero silencioso.
+- **Rebuild, import e doctor agora reconciliam a observabilidade persistida.** Preview permanece
+  sem escrita, apply rejeita resultado parcial, import atualiza notas completas porém stale e o
+  doctor correlaciona checkpoint, manifest e dirty para expor degradação real.
+
+### Security
+
+- **Diagnostics e provas públicas aplicam uma fronteira de privacidade estável.** Somente pares
+  allowlisted `{code,count}` podem ser persistidos; paths, identificadores, prompts e exceções
+  brutas ficam fora de fixtures, evidências e notas de release.
+
 ## [0.66.4] — 2026-07-30
 
 ### Fixed

package/README.en.md

@@ -211,10 +211,10 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |
-| **Sessions and import** | hooks, registry, session focus, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
+| **Sessions and import** | causal hooks, observability reconciliation, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
-| **Costs and observability** | stats, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
-| **Maintenance and diagnostics** | doctor, definition drift, theme, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
+| **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and

package/README.md

@@ -211,10 +211,10 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |
-| **Sessions and import** | hooks, registry, session focus, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
+| **Sessions and import** | causal hooks, observability reconciliation, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
-| **Costs and observability** | stats, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
-| **Maintenance and diagnostics** | doctor, definition drift, theme, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
+| **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and

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

@@ -26,7 +26,7 @@ A consistent registry, complete price table, and transcript access for rebuilt s
 ```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] [--apply] [--json]
+npx wendkeep cost rebuild [--session <id|file>] [--limit N] [--max-graph-nodes N] [--max-fallback-days N] [--max-fallback-candidates N] [--apply] [--json]
 ```
 
 ## Options and exit codes
@@ -34,10 +34,18 @@ npx wendkeep cost rebuild [--session <id|file>] [--limit N] [--apply] [--json]
 - `wendkeep stats` emits one shareable line or JSON.
 - `wendkeep cost` aggregates total/model/day; `--trend` adds projection and `--write` refreshes
   `00-Custo.md`.
-- `wendkeep cost rebuild` is dry-run by default; `--apply` writes notes and
-  `.brain/COST_REBUILD.json`.
-- Exit `0` means a consistent calculation; non-zero reports insufficient registry, price,
-  transcript, or parsing state.
+- `wendkeep cost rebuild` is dry-run by default and performs **zero writes**: it acquires no write
+  lock, changes no note, registry, or runtime state, and does not create `.brain/COST_REBUILD.json`.
+- `--apply` publishes only `complete` or `none` candidates. The `none` state clears the section
+  only after a stable offline scan proves that no subagent was started.
+- A `degraded` or `stale` candidate returns exit `1` and preserves the note without changes; the
+  batch continues so other safe sessions can be processed and the report can expose sanitized
+  diagnostic codes.
+- The `--max-graph-nodes`, `--max-fallback-days`, and `--max-fallback-candidates` overrides are
+  exclusively for a targeted rebuild with `--session`. Using them without `--session` is invalid
+  usage and returns exit `2`; hooks, import, and bulk rebuild retain the default limits.
+- Exit `0` means a consistent preview/apply; exit `1` means a partial `degraded`/`stale` result;
+  exit `2` means invalid syntax or context.
 
 ## Examples
 
@@ -45,12 +53,16 @@ npx wendkeep cost rebuild [--session <id|file>] [--limit N] [--apply] [--json]
 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
 ```
 
 ## Expected result
 
-Totals retain input/output/cache/reasoning dimensions by model and period. Rebuild shows a preview
-before changing notes and leaves a reproducible report when applied.
+Totals retain input/output/cache/reasoning dimensions by model and period. Tri-state composition
+returns `complete`, `none`, or `degraded`, plus a frontier, manifest, and sanitized diagnostics.
+Run and review the dry-run before repeating the same command with `--apply`; a semantically
+identical second apply preserves the note, checkpoint, report, and mtime.
 
 ## Common errors and diagnosis
 
@@ -58,6 +70,8 @@ before changing notes and leaves a reproducible report when applied.
 - Wrong-provider costs: validate the session identity chain.
 - Missing transcript: do not estimate silently; keep the gap visible.
 - Duplicated parent/subagent/fork totals: verify registry relationships and deduplication.
+- `degraded`/`stale`: preserve the note and inspect diagnostics/frontier before authorizing apply.
+- Rejected override: add `--session <id|file>` or remove the three targeted limits.
 
 ## Next steps
 

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

@@ -39,6 +39,11 @@ npx wendkeep --help
   events remain durable in the outbox/ledger is a recoverable warning.
 - An ambiguous attempt, a lost event ID (absent from ledger and outbox), `projected` state found
   only in the outbox, or a mismatched checkpoint is blocking.
+- For session observability, `legacy`, `degraded`, `stale`, and `manifest-unproven` require
+  reconciliation or more evidence. Only fresh `none` and fresh `complete` are healthy: frontier,
+  checkpoint, root stat, and source manifest must agree.
+- `doctor` remains read-only. It recommends the targeted dry-run first and only advises repeating
+  the command with `--apply` after human review.
 - `sync-defs --check` detects drift without writes; `--reseed` restores packaged `wk-*` skills.
 - `theme sync` reapplies the CSS snippet and graph groups without recreating the vault.
 - `wendkeep --version` prints the running version; `wendkeep --help` lists the public interface.
@@ -52,6 +57,8 @@ 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
 ```
 
 ## Expected result
@@ -59,7 +66,9 @@ npx wendkeep memory status --gate --vault .MyApp-vault
 Doctor names sessions, registry, links, notes, prices, derived sections, and memory as healthy or
 provides a specific diagnostic/repair command. For memory, it distinguishes a valid initial empty
 state, recoverable pending replay, and lost/divergent lifecycle state. It never repairs implicitly
-or echoes private projector-error content into its report.
+or echoes private projector-error content into its report. For session observability, it separates
+fresh `none`/`complete` from legacy, degraded, stale, or manifest-unproven state and gives a
+dry-run path before any write.
 
 ## Common errors and diagnosis
 
@@ -70,6 +79,9 @@ or echoes private projector-error content into its report.
 - `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`.
+- `legacy`/`degraded`/`stale`/`manifest-unproven` observability: run
+  `wendkeep cost rebuild --session <id> --json`, review diagnostics, and only then authorize
+  `--apply`.
 
 ## Next steps
 

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

@@ -46,6 +46,14 @@ npx wendkeep import [options]
 - `Stop` accepts only a transcript-proven turn from the compatible active activation. Duplicates
   are no-ops; stale/superseded Stops neither publish memory nor overwrite a newer epoch's
   checkpoint.
+- `Stop` receives an absolute **45 s** deadline from hook entry. Reads check the clock between
+  rollouts and on every chunk; reaching the limit returns `degraded` before the host timeout.
+- `SubagentStop` receives an absolute **15 s** deadline. Signals arriving within the **250 ms**
+  window are coalesced: only the highest sequence recomposes/publishes, without losing the last
+  child.
+- 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`.
 - 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
@@ -53,6 +61,9 @@ npx wendkeep import [options]
 - `import --source all|claude|codex`, `--since`, `--limit`, `--from`, and `--codex-from` bound scope.
 - `--dry-run`/`--json` support audit before writes; `--stamp-ids` and `--rescan-decisions` address
   specific historical gaps.
+- `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.
 - Exit `0` means consistent processing; non-zero reports invalid source/config/write instead of
   presenting silent partial success.
 
@@ -71,6 +82,8 @@ registry keeps one `SessionStart` epoch per activation plus the latest native tu
 `Stop` events may acknowledge turns in that epoch without closing it. Repeated imports of the
 same `session_id` deduplicate; human focus does not close or re-identify live hooks. Every
 automatic iteration remains valid Markdown even when a message must be truncated.
+Duplicate/stale hooks converge on the same frontier, and imports may refresh only observability
+without creating a new turn block.
 
 ## Common errors and diagnosis
 
@@ -82,6 +95,8 @@ automatic iteration remains valid Markdown even when a message must be truncated
 - Fork duplicates: bound source/date and inspect `forked_from_id`/`source.subagent`.
 - Codex does not capture: approve hooks and start a new session after `sync`.
 - 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.
 
 ## Next steps
 

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

@@ -26,7 +26,7 @@ Registry consistente, tabela de preços completa e acesso aos transcripts das se
 ```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] [--apply] [--json]
+npx wendkeep cost rebuild [--session <id|arquivo>] [--limit N] [--max-graph-nodes N] [--max-fallback-days N] [--max-fallback-candidates N] [--apply] [--json]
 ```
 
 ## Opções e códigos de saída
@@ -34,10 +34,18 @@ npx wendkeep cost rebuild [--session <id|arquivo>] [--limit N] [--apply] [--json
 - `wendkeep stats` gera uma linha compartilhável ou JSON.
 - `wendkeep cost` agrega total/modelo/dia; `--trend` inclui projeção e `--write` atualiza
   `00-Custo.md`.
-- `wendkeep cost rebuild` é dry-run por padrão; `--apply` grava notas e
-  `.brain/COST_REBUILD.json`.
-- Exit `0` indica cálculo consistente; não zero indica registry, preço, transcript ou parsing
-  insuficiente.
+- `wendkeep cost rebuild` é dry-run por padrão e tem **zero escrita**: não adquire lock de
+  gravação, não altera nota, registry ou runtime e não cria `.brain/COST_REBUILD.json`.
+- `--apply` publica somente candidatos `complete` ou `none`. O estado `none` só zera a seção
+  quando um scan offline estável comprovou que nenhum subagente foi iniciado.
+- Um candidato `degraded` ou `stale` produz exit `1` e preserva a nota sem alteração; o lote
+  continua para que outras sessões seguras possam ser processadas e o relatório exponha os
+  códigos sanitizados.
+- Os overrides `--max-graph-nodes`, `--max-fallback-days` e `--max-fallback-candidates` são
+  exclusivamente para rebuild direcionado com `--session`. Usá-los sem `--session` é uso inválido
+  e produz exit `2`; hooks, import e rebuild em lote mantêm os limites padrão.
+- Exit `0` significa preview/aplicação consistente; exit `1` indica resultado parcial
+  `degraded`/`stale`; exit `2` indica sintaxe ou contexto inválido.
 
 ## Exemplos
 
@@ -45,12 +53,16 @@ npx wendkeep cost rebuild [--session <id|arquivo>] [--limit N] [--apply] [--json
 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
 ```
 
 ## Resultado esperado
 
-Totais preservam dimensões de input/output/cache/reasoning por modelo e período. Rebuild mostra a
-prévia antes de alterar notas e deixa um relatório reproduzível quando aplicado.
+Totais preservam dimensões de input/output/cache/reasoning por modelo e período. A composição
+tri-state devolve `complete`, `none` ou `degraded`, mais frontier, manifest e diagnostics
+sanitizados. Rode e revise o dry-run antes de repetir o mesmo comando com `--apply`; uma segunda
+aplicação semanticamente idêntica preserva nota, checkpoint, relatório e mtime.
 
 ## Erros comuns e diagnóstico
 
@@ -58,6 +70,8 @@ prévia antes de alterar notas e deixa um relatório reproduzível quando aplica
 - Custos de provider errado: valide a cadeia de identidade da sessão.
 - Transcript ausente: não estime silenciosamente; mantenha a lacuna visível.
 - Total duplicado por subagent/fork: confirme relação pai/subagent e deduplicação do registry.
+- `degraded`/`stale`: preserve a nota e investigue diagnostics/frontier antes de autorizar apply.
+- Override rejeitado: acrescente `--session <id|arquivo>` ou remova os três limites direcionados.
 
 ## Próximos passos
 

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

@@ -39,6 +39,11 @@ npx wendkeep --help
   continuam duráveis na outbox/ledger é warning recuperável.
 - Attempt ambíguo, event ID perdido (ausente de ledger e outbox), estado `projected` apenas na
   outbox ou checkpoint divergente são falhas bloqueantes.
+- Para observabilidade de sessão, `legacy`, `degraded`, `stale` e `manifest-unproven` exigem
+  reconciliação ou evidência adicional. Somente `none` fresco e `complete` fresco são saudáveis:
+  frontier, checkpoint, root stat e source manifest precisam concordar.
+- O `doctor` permanece somente leitura/read-only. Ele recomenda primeiro o dry-run direcionado;
+  somente depois da revisão humana orienta repetir com `--apply`.
 - `sync-defs --check` detecta drift sem gravar; `--reseed` restaura skills `wk-*` do pacote.
 - `theme sync` reaplica snippet CSS e grupos do grafo sem recriar o cofre.
 - `wendkeep --version` imprime a versão executada; `wendkeep --help` lista a interface pública.
@@ -52,6 +57,8 @@ 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
 ```
 
 ## Resultado esperado
@@ -59,7 +66,9 @@ npx wendkeep memory status --gate --vault .MeuApp-vault
 O doctor nomeia sessões, registry, links, notas, preços, derivadas e memória como saudáveis ou
 fornece um comando específico de diagnóstico/reparo. Na memória, ele distingue vazio inicial
 válido, replay pendente recuperável e lifecycle perdido/divergente. Nenhum reparo é aplicado
-implicitamente nem o conteúdo privado do erro do projector é reproduzido no relatório.
+implicitamente nem o conteúdo privado do erro do projector é reproduzido no relatório. Na
+observabilidade de sessão, ele separa `none`/`complete` frescos de estado legado, degradado, stale
+ou sem manifest comprovado e oferece um caminho dry-run antes de qualquer escrita.
 
 ## Erros comuns e diagnóstico
 
@@ -70,6 +79,8 @@ implicitamente nem o conteúdo privado do erro do projector é reproduzido no re
 - `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`.
+- Observabilidade `legacy`/`degraded`/`stale`/`manifest-unproven`: rode
+  `wendkeep cost rebuild --session <id> --json`, revise diagnostics e só então autorize `--apply`.
 
 ## Próximos passos
 

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

@@ -46,6 +46,13 @@ npx wendkeep import [opções]
 - `Stop` aceita somente o turno comprovado pelo transcript e pela activation ativa compatível.
   Duplicatas são no-op; Stops stale/superseded não publicam memória nem sobrescrevem o checkpoint
   de um epoch mais novo.
+- `Stop` recebe deadline absoluto de **45 s** desde a entrada do hook. A leitura verifica o relógio
+  entre rollouts e a cada chunk; ao atingir o limite, devolve `degraded` antes do timeout do host.
+- `SubagentStop` recebe deadline absoluto de **15 s**. Sinais que chegam na janela de **250 ms**
+  são coalescidos: somente a maior sequência recompõe/publica, sem perder o último filho.
+- 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`.
 - 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
@@ -53,6 +60,9 @@ npx wendkeep import [opções]
 - `import --source all|claude|codex`, `--since`, `--limit`, `--from` e `--codex-from` limitam escopo.
 - `--dry-run`/`--json` permitem auditar antes de gravar; `--stamp-ids` e `--rescan-decisions`
   corrigem históricos específicos.
+- `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.
 - Exit `0` indica processamento consistente; exit não zero indica configuração, fonte ou escrita
   inválida sem transformar isso em sucesso parcial silencioso.
 
@@ -70,7 +80,9 @@ Cada sessão canônica aponta para provider, transcript, arquivo de nota e custo
 O registry mantém um epoch de `SessionStart` por activation e o turno nativo mais recente; vários
 `Stop` podem confirmar turnos do mesmo epoch sem fechá-lo. Importações repetidas do mesmo
 `session_id` são deduplicadas; o foco humano não encerra nem altera a identidade dos hooks. Cada
-iteração automática permanece Markdown válido mesmo quando uma fala precisa ser truncada.
+iteração automática permanece Markdown válido mesmo quando uma fala precisa ser truncada. Hooks
+duplicados/stale convergem no mesmo frontier, e importações podem atualizar só a observabilidade
+sem criar um novo bloco de turno.
 
 ## Erros comuns e diagnóstico
 
@@ -82,6 +94,8 @@ iteração automática permanece Markdown válido mesmo quando uma fala precisa
 - Duplicatas de forks: limite por fonte/data e revise `forked_from_id`/`source.subagent`.
 - Codex não captura: aprove os hooks e reinicie a sessão após `sync`.
 - 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`.
 
 ## Próximos passos
 

package/hooks/codex-rollout-meta.mjs

@@ -0,0 +1,112 @@
+import {
+  closeSync,
+  openSync,
+  readSync,
+} from 'node:fs';
+
+export const DEFAULT_CODEX_META_LINE_BYTES = 4 * 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+
+function trimCarriageReturn(buffer) {
+  return buffer.length > 0 && buffer[buffer.length - 1] === 0x0d
+    ? buffer.subarray(0, buffer.length - 1)
+    : buffer;
+}
+
+// Codex writes session_meta as the first physical JSONL line. Read only that line: the
+// transcript body can be hundreds of MiB and is irrelevant to identity/discovery.
+export function readFirstJsonlLine(
+  path,
+  { maxBytes = DEFAULT_CODEX_META_LINE_BYTES } = {},
+) {
+  if (typeof path !== 'string' || !path) {
+    return { ok: false, reason: 'INVALID_PATH' };
+  }
+
+  const limit = Number(maxBytes);
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    return { ok: false, reason: 'READ_ERROR' };
+  }
+
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const parts = [];
+    let totalBytes = 0;
+
+    while (totalBytes <= limit) {
+      // The extra byte distinguishes an exactly-at-limit line followed by LF from a line
+      // whose content exceeds the limit.
+      const remaining = (limit + 1) - totalBytes;
+      const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, remaining));
+      const bytesRead = readSync(fd, chunk, 0, chunk.length, null);
+
+      if (bytesRead === 0) {
+        if (totalBytes === 0) return { ok: false, reason: 'EMPTY_FILE' };
+        const lineBuffer = trimCarriageReturn(Buffer.concat(parts, totalBytes));
+        return {
+          ok: true,
+          line: lineBuffer.toString('utf8'),
+          lineBytes: lineBuffer.length,
+        };
+      }
+
+      const bytes = chunk.subarray(0, bytesRead);
+      const newlineAt = bytes.indexOf(0x0a);
+      if (newlineAt !== -1) {
+        if (totalBytes + newlineAt > limit) {
+          return { ok: false, reason: 'LINE_TOO_LONG' };
+        }
+        parts.push(bytes.subarray(0, newlineAt));
+        const lineBuffer = trimCarriageReturn(Buffer.concat(parts, totalBytes + newlineAt));
+        if (lineBuffer.length === 0) return { ok: false, reason: 'EMPTY_FILE' };
+        return {
+          ok: true,
+          line: lineBuffer.toString('utf8'),
+          lineBytes: lineBuffer.length,
+        };
+      }
+
+      parts.push(bytes);
+      totalBytes += bytesRead;
+      if (totalBytes > limit) return { ok: false, reason: 'LINE_TOO_LONG' };
+    }
+
+    return { ok: false, reason: 'LINE_TOO_LONG' };
+  } catch {
+    return { ok: false, reason: 'READ_ERROR' };
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* already closed */ }
+    }
+  }
+}
+
+export function readCodexRolloutMeta(
+  path,
+  { maxLineBytes = DEFAULT_CODEX_META_LINE_BYTES } = {},
+) {
+  const first = readFirstJsonlLine(path, { maxBytes: maxLineBytes });
+  if (!first.ok) return first;
+
+  let event;
+  try {
+    event = JSON.parse(first.line);
+  } catch {
+    return { ok: false, reason: 'INVALID_JSON' };
+  }
+
+  if (!event || typeof event !== 'object' || Array.isArray(event)
+    || event.type !== 'session_meta') {
+    return { ok: false, reason: 'NOT_SESSION_META' };
+  }
+  if (!event.payload || typeof event.payload !== 'object' || Array.isArray(event.payload)) {
+    return { ok: false, reason: 'INVALID_META' };
+  }
+
+  return {
+    ok: true,
+    meta: event.payload,
+    lineBytes: first.lineBytes,
+  };
+}