wendkeep 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.50.0] — 2026-07-23
+
+### Fixed
+
+- **Nota de sessão não empilha mais frontmatter.** Uma nota real fechou com 4 blocos de
+  frontmatter no topo: o Obsidian só parseia o primeiro, então `type`/`date`/`provider`/
+  `status`/`tags`/`source` sumiram do painel de propriedades e os outros 3 blocos viraram
+  texto do corpo. Duas falhas somadas: (1) `upsertSessionFrontmatter` **prependava** um
+  frontmatter novo quando o regex não casava — numa nota existente isso nunca é "faltou
+  frontmatter", é conteúdo truncado; (2) os escritores da nota faziam read-modify-write com
+  `writeFileSync` cru, sem lock. Como `subagent-stop` dispara uma vez por subagent (a sessão
+  danificada teve 46), um hook lia o arquivo já truncado por outro e caía no prepend.
+  Agora todo hook que reescreve a nota (`token-usage`, `subagent-usage`,
+  `session-observability`, `session-stop`, `session-ensure`, `decision-capture`, `task-log`)
+  grava por `mutateSessionNote`: lock por `mkdir` + escrita atômica (`tmp` + `rename`), e
+  frontmatter ilegível **aborta** a gravação em vez de prependar. Um teste-guarda estrutural
+  impede que um escritor novo volte ao `writeFileSync` cru. Capability
+  `session-observability` (OBS-5, OBS-6).
+- **Lock liberado em caminho acentuado.** `fs.rmSync(dir, { recursive: true, force: true })`
+  é um **no-op silencioso** no Windows (Node 24) quando o caminho contém caractere
+  não-ASCII — não remove e não lança (medido: 20/20 falhas em `02-Sessões`, `ação`,
+  `Mudanças`; 0/20 em ASCII). Como toda nota de sessão vive sob `02-Sessões/`, o lock ficava
+  preso e o segundo escritor desistia — perda silenciosa de turnos. A liberação passa a usar
+  `rmdirSync`. O mesmo defeito estava latente no lock do `SESSION_REGISTRY.json`, que
+  travaria após a primeira mutação num vault sob pasta acentuada.
+
+### Added
+
+- **`wendkeep doctor` surfaça notas de sessão com frontmatter empilhado.** Nova seção
+  `[notas]`: conta e lista as notas danificadas pela escrita concorrente (versões
+  anteriores a esta); quando não há nenhuma, diz `frontmatter íntegro`. `---` no corpo
+  (regra horizontal, separador de tabela) não é falso positivo. Capability `vault-doctor`
+  (DIAG-5).
+
 ## [0.49.0] — 2026-07-23
 
 ### Added

package/README.md

@@ -150,7 +150,7 @@ Restart Codex and Claude Code after reseeding their generated skills.
 | `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
 | `wendkeep --version` / `--help` | Version / usage. |
 
-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.
+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. 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.
 
 ## Retroactive memory (`import`) — install today, remember yesterday
 

package/hooks/decision-capture.mjs

@@ -13,6 +13,7 @@ import {
 } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
+import { mutateSessionNote } from './session-note-io.mjs';
 
 // Decision notes follow the ADR naming convention: ADR-NNNN-<slug>, NNNN a 4-digit sequential
 // number assigned in the order decisions are made (getNextAdrNumber scans the whole 04-Decisões).
@@ -189,10 +190,11 @@ export function captureDecision(vaultBase, input) {
   if (sessionRel) {
     try {
       const sessionPath = join(vaultBase, sessionRel);
-      let session = readFileSync(sessionPath, 'utf8');
       const wikilink = wikilinkFromRel(rel);
       const link = `- ${wikilink}`;
-      if (!session.includes(wikilink)) {
+      mutateSessionNote(sessionPath, (original) => {
+        if (original.includes(wikilink)) return null;
+        let session = original;
         const heading = '\n## Decisões geradas nesta sessão\n';
         const at = session.indexOf(heading);
         if (at !== -1) {
@@ -209,8 +211,8 @@ export function captureDecision(vaultBase, input) {
           const section = `\n## Decisões geradas nesta sessão\n\n${link}\n`;
           session = anchor === -1 ? `${session.trimEnd()}${section}` : `${session.slice(0, anchor).trimEnd()}${section}${session.slice(anchor)}`;
         }
-        writeFileSync(sessionPath, session, 'utf8');
-      }
+        return session;
+      });
     } catch { /* backlink auxiliar nunca derruba a captura */ }
   }
   return { rel, skipped: false };

package/hooks/harness-doctor.mjs

@@ -1,7 +1,7 @@
 // hooks/harness-doctor.mjs — integrity checks for the a2 harness state (Wave B).
 // Pure-ish (fs reads only). `wendkeep doctor` reports errors (exit 1) + warnings.
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { activeChange, parseTasks, backfillArtifactLinks } from './change-core.mjs';
 import { relinkDerivedNotes } from './linked-notes.mjs';
 import { buildEffectiveRequirementPackage, checkSpecsState, evaluateVerdict, tasksHashOf, validateSpecImpact } from './spec-core.mjs';
@@ -88,6 +88,48 @@ const unquoteControl = (v) => String(v ?? '').replace(/^"(.*)"$/, '$1').trim();
 // O control marca `inactive` quando a sessão-mãe encerra, mesmo com um workflow/subagente
 // ainda vivo em background. Se a nota da sessão foi escrita há pouco apesar do `inactive`,
 // sinaliza a atividade recente — o doctor deixa de dizer "inativa" quando não está.
+// Conta blocos de frontmatter empilhados no TOPO da nota — a assinatura do prepend que a
+// escrita concorrente sem lock produzia. `---` no corpo (regra horizontal, separador de
+// tabela) não conta: só reabertura imediata após o fechamento do bloco anterior.
+function stackedFrontmatterBlocks(content) {
+  let rest = content;
+  let blocks = 0;
+  while (/^---\n/.test(rest)) {
+    const close = rest.indexOf('\n---', 4);
+    if (close < 0) break;
+    blocks += 1;
+    rest = rest.slice(close + 4).trimStart();
+  }
+  return blocks;
+}
+
+export function checkStackedFrontmatter(vaultBase) {
+  const root = join(vaultBase, '02-Sessões');
+  const notes = [];
+  const walk = (dir) => {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) { walk(abs); continue; }
+      if (!entry.name.endsWith('.md')) continue;
+      try {
+        if (stackedFrontmatterBlocks(readFileSync(abs, 'utf-8')) > 1) notes.push(abs);
+      } catch { /* nota ilegível não é o dano que esta checagem descreve */ }
+    }
+  };
+  walk(root);
+  return { count: notes.length, notes };
+}
+
+// Formatador puro pra que a saída do doctor seja testável sem process.exit.
+export function renderStackedFrontmatterLines(vaultBase, stacked) {
+  const lines = [`[notas] ${stacked.count} sessão(ões) com frontmatter empilhado`];
+  for (const abs of stacked.notes) lines.push(`  ✗ ${relative(vaultBase, abs)}`);
+  if (!stacked.count) lines.push('  frontmatter íntegro ✓');
+  return lines;
+}
+
 export function checkSessionActivity(vaultBase, { now = Date.now(), windowMs = 5 * 60000 } = {}) {
   const control = readControl(vaultBase);
   const active = unquoteControl(control.status) === 'active';

package/hooks/obsidian-common.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { releaseLockDir } from './session-note-io.mjs';
 import { basename, dirname, join, relative } from 'path';
 import { getLocale } from './locale.mjs';
 import { resolveProjectVault } from '../src/project-vault.mjs';
@@ -323,7 +324,7 @@ export function mutateSessionRegistry(vaultBase, mutator, { timeoutMs = 2000 } =
       if (error?.code === 'EEXIST') {
         try {
           if (Date.now() - statSync(lock).mtimeMs > 10_000) {
-            rmSync(lock, { recursive: true, force: true });
+            releaseLockDir(lock);
             continue;
           }
         } catch { /* outro processo pode ter liberado o lock */ }
@@ -342,7 +343,9 @@ export function mutateSessionRegistry(vaultBase, mutator, { timeoutMs = 2000 } =
     writeSessionRegistry(vaultBase, registry);
     return result;
   } finally {
-    rmSync(lock, { recursive: true, force: true });
+    // rmSync recursivo não remove diretório em caminho não-ASCII no Windows — ver
+    // releaseLockDir. Vault sob pasta acentuada travaria o registry após a 1ª mutação.
+    releaseLockDir(lock);
   }
 }
 

package/hooks/session-ensure.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
+import { existsSync, renameSync, statSync, writeFileSync } from 'fs';
 import { basename, dirname, join } from 'path';
 import {
   controlPath,
@@ -31,6 +31,7 @@ import {
   yamlQuote,
 } from './obsidian-common.mjs';
 import { resolveSessionIdentity } from './session-identity.mjs';
+import { mutateSessionNote } from './session-note-io.mjs';
 
 function sessionIdFromInput(input) {
   return input.session_id || input.sessionId || input.codex_session_id || '';
@@ -194,11 +195,11 @@ function maybeRetitleSession({ vaultBase, relPath, startedAt, input }) {
   }
 
   const sessionPath = join(vaultBase, nextRelPath);
-  const content = readFileSync(sessionPath, 'utf-8');
-  const updated = updateSessionDescription(content, { relPath: nextRelPath, summary, startedAt });
-  if (updated !== content) writeFileSync(sessionPath, updated, 'utf-8');
+  const outcome = mutateSessionNote(sessionPath, (content) => (
+    updateSessionDescription(content, { relPath: nextRelPath, summary, startedAt })
+  ));
 
-  return { relPath: nextRelPath, summary, changed: nextRelPath !== relPath || updated !== content };
+  return { relPath: nextRelPath, summary, changed: nextRelPath !== relPath || outcome.written };
 }
 
 function stripClosingSection(content) {
@@ -209,9 +210,7 @@ function stripClosingSection(content) {
 }
 
 function reopenSessionFile(sessionPath) {
-  const content = readFileSync(sessionPath, 'utf-8');
-  const reopened = stripClosingSection(updateSessionFrontmatter(content));
-  writeFileSync(sessionPath, reopened, 'utf-8');
+  mutateSessionNote(sessionPath, (content) => stripClosingSection(updateSessionFrontmatter(content)));
 }
 
 function findSessionForInput(vaultBase, input, control) {

package/hooks/session-note-io.mjs

@@ -0,0 +1,94 @@
+// Gravação da nota de sessão: atômica e serializada.
+//
+// O hook `subagent-stop` dispara uma vez por subagent, então vários processos fazem
+// read-modify-write na MESMA nota ao mesmo tempo. Com `writeFileSync` cru, um leitor pode
+// pegar o arquivo já truncado por outro escritor; quem lê um topo sem `---` acabava
+// prependando um frontmatter novo, empilhando blocos na nota (visto em produção: 4 blocos).
+//
+// `obsidian-common.mjs` já resolvia isso para o SESSION_REGISTRY.json; aqui o mesmo par
+// (tmp + rename, lock por mkdir) fica disponível para a nota de sessão.
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from 'node:fs';
+
+export const LOCK_BUSY = Symbol('wendkeep:lock-busy');
+
+// ATENÇÃO: no Windows (Node 24), `rmSync(dir, { recursive: true, force: true })` é um NO-OP
+// SILENCIOSO quando o caminho contém caractere não-ASCII — não remove e não lança. Medido:
+// 20/20 falhas em `02-Sessões`, `ação`, `Mudanças`; 0/20 em caminho ASCII. Como TODA nota de
+// sessão vive sob `02-Sessões/`, usar rmSync aqui deixaria o lock preso para sempre e o
+// segundo escritor desistiria de gravar — perdendo turnos em silêncio.
+// O lock é sempre um diretório vazio, então `rmdirSync` basta e funciona em qualquer caminho.
+export function releaseLockDir(lock) {
+  try {
+    rmdirSync(lock);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return;
+    try { rmSync(lock, { recursive: true, force: true }); } catch { /* lock preso: melhor seguir */ }
+  }
+}
+
+const FRONTMATTER = /^---\n[\s\S]*?\n---/;
+
+export function hasSessionFrontmatter(content) {
+  return typeof content === 'string' && FRONTMATTER.test(content);
+}
+
+export function writeFileAtomic(path, content, encoding = 'utf-8') {
+  // rename é atômico no mesmo volume: ou o leitor vê o arquivo antigo inteiro, ou o novo.
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, content, encoding);
+  renameSync(tmp, path);
+}
+
+function waitBriefly(ms) {
+  const signal = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(signal, 0, 0, ms);
+}
+
+// Roda `fn` com o lock do arquivo tomado. Devolve LOCK_BUSY quando o lock não veio dentro
+// do timeout — o chamador desiste da gravação em vez de gravar sem lock.
+export function withPathLock(path, fn, { timeoutMs = 2000, staleMs = 10_000 } = {}) {
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + timeoutMs;
+
+  while (true) {
+    try {
+      mkdirSync(lock);
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        // Lock morto (processo caiu antes do finally) não pode travar a sessão inteira.
+        if (Date.now() - statSync(lock).mtimeMs > staleMs) releaseLockDir(lock);
+      } catch { /* outro processo pode ter liberado o lock no meio da checagem */ }
+      // O deadline é checado SEMPRE, inclusive depois de tentar remover um lock morto:
+      // `releaseLockDir` engole a falha, então um `continue` direto giraria para sempre.
+      if (Date.now() >= deadline) return LOCK_BUSY;
+      waitBriefly(10);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    releaseLockDir(lock);
+  }
+}
+
+// Lock -> read -> mutator -> escrita atômica.
+// O mutator devolve o conteúdo novo, ou `null` para abortar sem gravar (o caminho
+// fail-closed de quem leu uma nota corrompida).
+export function mutateSessionNote(path, mutator, options = {}) {
+  if (!path || !existsSync(path)) return { written: false, reason: 'missing', content: null };
+
+  const outcome = withPathLock(path, () => {
+    const original = readFileSync(path, 'utf-8');
+    const next = mutator(original);
+    if (next === null || next === undefined) return { written: false, reason: 'aborted', content: original };
+    if (next === original) return { written: false, reason: 'unchanged', content: original };
+    writeFileAtomic(path, next);
+    return { written: true, reason: 'ok', content: next };
+  }, options);
+
+  if (outcome === LOCK_BUSY) return { written: false, reason: 'busy', content: null };
+  return outcome;
+}

package/hooks/session-observability.mjs

@@ -1,8 +1,9 @@
 // Single atomic writer for session usage, models, reasoning/effort and subagents.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { collectSessionUsage } from './token-usage.mjs';
 import { collectSubagentUsage, collectCodexSubagentUsage, sessionDirFromTranscript } from './subagent-usage.mjs';
 import { inspectTranscriptIdentity } from './session-identity.mjs';
+import { hasSessionFrontmatter, mutateSessionNote } from './session-note-io.mjs';
 
 const HEADING = '## Agentes, tokens e custos';
 const LEGACY_HEADINGS = ['## Uso de tokens e custos', '## Subagents & Workflows'];
@@ -158,23 +159,33 @@ export function buildSessionObservability({ sessionContent, transcriptPath }) {
   return { snapshot, content: upsertObservabilitySection(content, renderSessionObservability(snapshot)) };
 }
 
-export function updateSessionObservability({ sessionPath, transcriptPath, caller = 'unknown', canonicalConversationId = '' }) {
+export function updateSessionObservability({ sessionPath, transcriptPath, caller = 'unknown', canonicalConversationId = '', lockTimeoutMs }) {
   if (!sessionPath || !existsSync(sessionPath)) return null;
-  const sessionContent = readFileSync(sessionPath, 'utf8');
-  const noteProvider = sessionContent.match(/^provider:\s*"?([^"\n]+)"?/m)?.[1]?.trim() || 'unknown';
   const identity = inspectTranscriptIdentity(transcriptPath);
-  if ((noteProvider === 'codex' && identity.transcriptProvider !== 'openai')
-    || (noteProvider === 'claude' && identity.transcriptProvider !== 'anthropic')) {
-    throw new Error(`observability provider mismatch: note=${noteProvider}, transcript=${identity.transcriptProvider}`);
-  }
-  let annotated = setFrontmatterField(sessionContent, 'observability_caller', `"${caller}"`);
-  annotated = setFrontmatterField(annotated, 'observability_session_id', `"${canonicalConversationId || identity.canonicalConversationId || ''}"`);
-  annotated = setFrontmatterField(annotated, 'observability_transcript_id', `"${identity.transcriptId || ''}"`);
-  if (!/^observability_updated_at:/m.test(annotated)) {
-    annotated = setFrontmatterField(annotated, 'observability_updated_at', `"${new Date().toISOString()}"`);
-  }
-  const result = buildSessionObservability({ sessionContent: annotated, transcriptPath });
-  if (!result) return null;
-  writeFileSync(sessionPath, result.content, 'utf8');
-  return result.snapshot;
+  let snapshot = null;
+
+  // `subagent-stop` dispara uma vez por subagent: sem o lock, dois processos leem a mesma
+  // nota e o segundo grava por cima — ou pior, lê o arquivo já truncado pelo primeiro.
+  const outcome = mutateSessionNote(sessionPath, (sessionContent) => {
+    // Fail-closed: leitura sem frontmatter íntegro é conteúdo truncado, não nota nova.
+    if (!hasSessionFrontmatter(sessionContent)) return null;
+    const noteProvider = sessionContent.match(/^provider:\s*"?([^"\n]+)"?/m)?.[1]?.trim() || 'unknown';
+    if ((noteProvider === 'codex' && identity.transcriptProvider !== 'openai')
+      || (noteProvider === 'claude' && identity.transcriptProvider !== 'anthropic')) {
+      throw new Error(`observability provider mismatch: note=${noteProvider}, transcript=${identity.transcriptProvider}`);
+    }
+    let annotated = setFrontmatterField(sessionContent, 'observability_caller', `"${caller}"`);
+    annotated = setFrontmatterField(annotated, 'observability_session_id', `"${canonicalConversationId || identity.canonicalConversationId || ''}"`);
+    annotated = setFrontmatterField(annotated, 'observability_transcript_id', `"${identity.transcriptId || ''}"`);
+    if (!/^observability_updated_at:/m.test(annotated)) {
+      annotated = setFrontmatterField(annotated, 'observability_updated_at', `"${new Date().toISOString()}"`);
+    }
+    const result = buildSessionObservability({ sessionContent: annotated, transcriptPath });
+    if (!result) return null;
+    snapshot = result.snapshot;
+    return result.content;
+  }, lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {});
+
+  // 'unchanged' também é sucesso: a nota já estava em dia, o snapshot vale.
+  return outcome.written || outcome.reason === 'unchanged' ? snapshot : null;
 }

package/hooks/session-stop.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { request } from 'http';
 import { pathToFileURL } from 'url';
@@ -10,6 +10,7 @@ import { activeChangeLink, pruneChangeSentinels } from './change-core.mjs';
 import { getLocale } from './locale.mjs';
 import { updateSessionObservability } from './session-observability.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
+import { mutateSessionNote } from './session-note-io.mjs';
 import {
   ensureDir,
   findActiveSessionByTranscript,
@@ -768,20 +769,21 @@ function relocateOrphanIterations(content) {
 }
 
 export function insertIteration(sessionPath, block, turnId, tx) {
-  const original = readFileSync(sessionPath, 'utf-8');
-  // Self-heal: migrate any legacy `codex-turn` markers to the neutral name on this write.
-  let content = normalizeTurnMarkers(original);
-  if (hasTurnMarker(content, turnId)) {
-    // Turno já registrado: ainda assim repara órfãos e seções dedicadas.
-    const repaired = applyDedicatedSections(relocateOrphanIterations(content), tx);
-    if (repaired !== original) writeFileSync(sessionPath, repaired, 'utf-8');
-    return false;
-  }
-  content = relocateOrphanIterations(content);
-  content = insertIntoIteracoes(content, block);
-  content = applyDedicatedSections(content, tx);
-  if (content !== original) writeFileSync(sessionPath, content, 'utf-8');
-  return true;
+  let inserted = false;
+  // Sob lock: outro hook (subagent-stop) pode estar reescrevendo a mesma nota agora.
+  mutateSessionNote(sessionPath, (original) => {
+    // Self-heal: migrate any legacy `codex-turn` markers to the neutral name on this write.
+    let content = normalizeTurnMarkers(original);
+    if (hasTurnMarker(content, turnId)) {
+      // Turno já registrado: ainda assim repara órfãos e seções dedicadas.
+      return applyDedicatedSections(relocateOrphanIterations(content), tx);
+    }
+    content = relocateOrphanIterations(content);
+    content = insertIntoIteracoes(content, block);
+    inserted = true;
+    return applyDedicatedSections(content, tx);
+  });
+  return inserted;
 }
 
 function shouldFinalizeSession() {
@@ -921,12 +923,10 @@ ${links(created.learnings)}
 ${formatPendingClosing(pending)}
 `;
 
-  const content = readFileSync(sessionPath, 'utf-8');
-  const finalized = replaceClosingSection(
+  mutateSessionNote(sessionPath, (content) => replaceClosingSection(
     replacePendingSection(updateFrontmatter(content, endedAt), pending),
     closing,
-  );
-  writeFileSync(sessionPath, finalized, 'utf-8');
+  ));
 }
 
 // --- Vínculo Sessão ↔ Issues Linear (03-Linear) -------------------------------
@@ -1007,10 +1007,9 @@ function applyLinearLinks(sessionPath, tx, vaultBase, sessionRel) {
     .sort((a, b) => a[0].localeCompare(b[0], undefined, { numeric: true }))
     .map(([id, rel]) => `- ${id} — ${wikilinkFromRel(rel)}`);
 
-  let content = readFileSync(sessionPath, 'utf-8');
-  content = ensureSection(content, 'Issues Linear', '\n## Encerramento');
-  content = upsertListSection(content, 'Issues Linear', lines, null);
-  writeFileSync(sessionPath, content, 'utf-8');
+  mutateSessionNote(sessionPath, (original) => (
+    upsertListSection(ensureSection(original, 'Issues Linear', '\n## Encerramento'), 'Issues Linear', lines, null)
+  ));
 }
 
 // Triggers Obsidian Local REST API to re-index the vault after file writes.
@@ -1129,10 +1128,9 @@ function main() {
       : activeChangeLink(vaultBase);
     const wl = (chgLink.match(/\[\[[^\]]+\]\]/) || [])[0];
     if (wl) {
-      let cur = readFileSync(sessionPath, 'utf8');
-      cur = ensureSection(cur, 'Mudanças', '\n## Encerramento');
-      cur = upsertListSection(cur, 'Mudanças', [`- ${wl}`], null);
-      writeFileSync(sessionPath, cur, 'utf8');
+      mutateSessionNote(sessionPath, (cur) => (
+        upsertListSection(ensureSection(cur, 'Mudanças', '\n## Encerramento'), 'Mudanças', [`- ${wl}`], null)
+      ));
     }
   } catch { /* nunca derruba o Stop */ }
   writeControl(vaultBase, {

package/hooks/subagent-usage.mjs

@@ -2,7 +2,8 @@
 // only reads the MAIN transcript; a session that spawns subagents/workflows (e.g. a Workflow
 // run) burns tokens in sibling transcripts the note never recorded. This scans them.
 // Reuses token-usage.mjs's parser. Provider-gated by structure (Claude Code layout).
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { hasSessionFrontmatter, mutateSessionNote } from './session-note-io.mjs';
 import { basename, join } from 'node:path';
 import { parseTokenUsageFromTranscript, summarizeTokenUsage } from './token-usage.mjs';
 
@@ -339,39 +340,43 @@ function upsertSection(content, heading, body) {
 }
 
 // Stop-hook entry: scan the session's subagents/workflows, fold into the note. Fail-open.
-export function upsertSubagentUsage(sessionPath, transcriptPath) {
+export function upsertSubagentUsage(sessionPath, transcriptPath, { lockTimeoutMs } = {}) {
   if (!sessionPath || !existsSync(sessionPath)) return false;
   const collected = collectSubagentUsage(sessionDirFromTranscript(transcriptPath));
   if (!collected) return false;
   const a = collected.aggregate;
-  let content = readFileSync(sessionPath, 'utf8');
-  content = setFrontmatterField(content, 'subagents_count', a.count);
-  content = setFrontmatterField(content, 'subagents_tokens_total', a.tokens);
-  content = setFrontmatterField(content, 'subagents_custo_usd', a.cost);
-  content = setFrontmatterField(content, 'subagents_tools', `"${(a.tools || []).join(', ')}"`);
-  content = setFrontmatterField(content, 'subagents_wasted_usd', a.wasted || 0);
-  content = setFrontmatterField(content, 'tokens_total_incl_subagents', frontmatterNumber(content, 'tokens_total') + a.tokens);
-  content = setFrontmatterField(content, 'custo_total_incl_subagents_usd', round4(frontmatterNumber(content, 'custo_modelo_usd') + a.cost));
-  let mainRows = [];
-  try {
-    const main = summarizeTokenUsage(parseTokenUsageFromTranscript(transcriptPath));
-    mainRows = (main.modelRows || []).map((r) => ({
-      provider: r.provider || '?', model: r.model || '?', source: 'main', calls: r.calls || 0,
-      tokens: tokensTotal(r.usage), cost: round4(r.costs?.model || 0),
-    }));
-  } catch { /* preserve legacy aggregate fallback */ }
-  if (!mainRows.length) {
-    const mainModel = (content.match(/^custo_modelo_label:\s*["']?([^"'\r\n]+)["']?\s*$/m) || [])[1] || '?';
-    mainRows = [{ model: mainModel, source: 'main', cost: round4(frontmatterNumber(content, 'custo_modelo_usd')), tokens: frontmatterNumber(content, 'tokens_total') }];
-  }
-  const ledger = [...mainRows, ...(a.modelRows || [])];
-  collected.combined = {
-    tokens: frontmatterNumber(content, 'tokens_total') + a.tokens,
-    cost: round4(frontmatterNumber(content, 'custo_modelo_usd') + a.cost),
-    models: ledger,
-  };
-  content = setFrontmatterField(content, 'custo_por_modelo_json', `'${JSON.stringify(ledger).replaceAll("'", "''")}'`);
-  content = upsertSection(content, '## Subagents & Workflows', renderSubagentSection(collected));
-  writeFileSync(sessionPath, content, 'utf8');
-  return true;
+  const outcome = mutateSessionNote(sessionPath, (original) => {
+    // Fail-closed: sem frontmatter íntegro, `setFrontmatterField` viraria no-op silencioso
+    // e a gravação só reescreveria conteúdo truncado por cima do original.
+    if (!hasSessionFrontmatter(original)) return null;
+    let content = original;
+    content = setFrontmatterField(content, 'subagents_count', a.count);
+    content = setFrontmatterField(content, 'subagents_tokens_total', a.tokens);
+    content = setFrontmatterField(content, 'subagents_custo_usd', a.cost);
+    content = setFrontmatterField(content, 'subagents_tools', `"${(a.tools || []).join(', ')}"`);
+    content = setFrontmatterField(content, 'subagents_wasted_usd', a.wasted || 0);
+    content = setFrontmatterField(content, 'tokens_total_incl_subagents', frontmatterNumber(content, 'tokens_total') + a.tokens);
+    content = setFrontmatterField(content, 'custo_total_incl_subagents_usd', round4(frontmatterNumber(content, 'custo_modelo_usd') + a.cost));
+    let mainRows = [];
+    try {
+      const main = summarizeTokenUsage(parseTokenUsageFromTranscript(transcriptPath));
+      mainRows = (main.modelRows || []).map((r) => ({
+        provider: r.provider || '?', model: r.model || '?', source: 'main', calls: r.calls || 0,
+        tokens: tokensTotal(r.usage), cost: round4(r.costs?.model || 0),
+      }));
+    } catch { /* preserve legacy aggregate fallback */ }
+    if (!mainRows.length) {
+      const mainModel = (content.match(/^custo_modelo_label:\s*["']?([^"'\r\n]+)["']?\s*$/m) || [])[1] || '?';
+      mainRows = [{ model: mainModel, source: 'main', cost: round4(frontmatterNumber(content, 'custo_modelo_usd')), tokens: frontmatterNumber(content, 'tokens_total') }];
+    }
+    const ledger = [...mainRows, ...(a.modelRows || [])];
+    collected.combined = {
+      tokens: frontmatterNumber(content, 'tokens_total') + a.tokens,
+      cost: round4(frontmatterNumber(content, 'custo_modelo_usd') + a.cost),
+      models: ledger,
+    };
+    content = setFrontmatterField(content, 'custo_por_modelo_json', `'${JSON.stringify(ledger).replaceAll("'", "''")}'`);
+    return upsertSection(content, '## Subagents & Workflows', renderSubagentSection(collected));
+  }, lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {});
+  return outcome.written;
 }

package/hooks/task-log.mjs

@@ -5,12 +5,13 @@
 // change's tarefas.md N.N (id-spaces differ, fuzzy) — it's a progress trail, not a task tracker.
 // The TaskCompleted payload shape isn't fully pinned, so the task text is pulled defensively from
 // any plausible field. Fail-open.
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
 import { readHookInput, writeHookOutput, getVaultBase, formatHourMinute, providerMeta } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
+import { mutateSessionNote } from './session-note-io.mjs';
 
 // Pull the task's human text from whatever field the payload carries.
 export function taskText(input) {
@@ -51,10 +52,7 @@ export function logTask(vaultBase, input) {
 
   const heading = getLocale(vaultBase).id === 'en' ? 'Plan progress' : 'Progresso do plano';
   const line = `- [x] ${formatHourMinute(new Date()).replace('-', ':')} ${text}`;
-  const content = readFileSync(sessionPath, 'utf8');
-  const next = appendProgress(content, line, heading);
-  if (next !== content) { writeFileSync(sessionPath, next, 'utf8'); return true; }
-  return false;
+  return mutateSessionNote(sessionPath, (content) => appendProgress(content, line, heading)).written;
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/hooks/token-usage.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { mutateSessionNote } from './session-note-io.mjs';
 import { basename, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import {
@@ -788,7 +789,11 @@ function buildUsageFrontmatter(agg, entries) {
 function upsertSessionFrontmatter(content, agg, entries) {
   const managedYaml = buildUsageFrontmatter(agg, entries);
   const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return `---\n${managedYaml}\n---\n\n${content}`;
+  // Fail-closed: a nota de sessão SEMPRE nasce com frontmatter (session-start). Não casar
+  // aqui significa conteúdo truncado — tipicamente uma leitura que pegou o arquivo no meio
+  // da escrita de outro hook. Prependar um bloco novo transformava essa leitura ruim em
+  // dano permanente (notas com 4 frontmatters empilhados, vistas em produção).
+  if (!match) return null;
 
   const clean = stripManagedFrontmatter(match[1]);
   const nextFrontmatter = [clean, managedYaml].filter(Boolean).join('\n');
@@ -960,6 +965,7 @@ export function collectSessionUsage({ sessionContent, transcriptPath }) {
 
   const agg = aggregateEntries(entries);
   const withFrontmatter = upsertSessionFrontmatter(sessionContent, agg, entries);
+  if (withFrontmatter === null) return null; // conteúdo corrompido: nenhum escritor grava
   return {
     summary,
     aggregate: agg,
@@ -968,13 +974,15 @@ export function collectSessionUsage({ sessionContent, transcriptPath }) {
   };
 }
 
-export function updateSessionUsage({ vaultBase, sessionRel, sessionPath, transcriptPath }) {
+export function updateSessionUsage({ vaultBase, sessionRel, sessionPath, transcriptPath, lockTimeoutMs }) {
   if (!sessionPath || !existsSync(sessionPath)) return null;
-  const result = collectSessionUsage({ sessionContent: readFileSync(sessionPath, 'utf-8'), transcriptPath });
-  if (!result) return null;
-  const withSection = upsertUsageSection(result.content, buildUsageSection(result.aggregate, result.entries, result.summary));
-  writeFileSync(sessionPath, withSection, 'utf-8');
-  return result;
+  let result = null;
+  const outcome = mutateSessionNote(sessionPath, (sessionContent) => {
+    result = collectSessionUsage({ sessionContent, transcriptPath });
+    if (!result) return null; // sem usage OU conteúdo corrompido: não grava
+    return upsertUsageSection(result.content, buildUsageSection(result.aggregate, result.entries, result.summary));
+  }, lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {});
+  return outcome.written || outcome.reason === 'unchanged' ? result : null;
 }
 
 function parseCliArgs(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {
@@ -46,6 +46,6 @@
     "url": "https://github.com/rogersialves/wendkeep/issues"
   },
   "devDependencies": {
-    "wendkeep": "^0.45.0"
+    "wendkeep": "^0.49.0"
   }
 }

package/src/doctor.mjs

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { checkHarness, checkVaultLinks, checkSessionActivity } from '../hooks/harness-doctor.mjs';
+import { checkHarness, checkVaultLinks, checkSessionActivity, checkStackedFrontmatter, renderStackedFrontmatterLines } from '../hooks/harness-doctor.mjs';
 import { checkSyncDefs } from './sync-defs.mjs';
 import { resolveProjectVault } from './project-vault.mjs';
 
@@ -69,6 +69,10 @@ export function runDoctor(argv) {
   if (links.graphColors === false) process.stdout.write('  → wendkeep theme sync (feche o Obsidian antes)\n');
   if (!links.derivedOrphans && !links.artifactOrphans && links.graphColors !== false) process.stdout.write('  grafo conectado ✓\n');
 
+  // 3b. Notas de sessão com frontmatter empilhado — dano de escrita concorrente (pré-lock).
+  const stacked = checkStackedFrontmatter(vaultBase);
+  process.stdout.write(`\n${renderStackedFrontmatterLines(vaultBase, stacked).join('\n')}\n`);
+
   // 4. Sessão: não mente "inativa" quando há atividade recente (workflow/subagente em background).
   const act = checkSessionActivity(vaultBase);
   if (act.lastSession) {