wendkeep 0.48.0 → 0.50.0

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.48.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 } 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';
 
@@ -60,5 +60,29 @@ export function runDoctor(argv) {
   for (const e of errors) process.stdout.write(`  ✗ ${e}\n`);
   for (const w of warnings) process.stdout.write(`  ! ${w}\n`);
 
+  // 3. Link/graph health — órfãos que o grafo do Obsidian mostraria, com o comando de reparo.
+  const links = checkVaultLinks(vaultBase);
+  const graphLabel = links.graphColors === true ? 'com cores' : links.graphColors === false ? 'sem cores' : 'sem graph.json';
+  process.stdout.write(`\n[links] ${links.derivedOrphans} derivada(s) órfã(s) · ${links.artifactOrphans} artefato(s) órfão(s) · grafo: ${graphLabel}\n`);
+  if (links.derivedOrphans) process.stdout.write('  → wendkeep note relink --apply\n');
+  if (links.artifactOrphans) process.stdout.write('  → wendkeep change backlink --apply\n');
+  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) {
+    const label = act.active
+      ? 'ativa'
+      : act.backgroundSuspected
+        ? `inativa no control, mas escrita há ${Math.round((act.ageMs || 0) / 1000)}s — possível workflow/subagente em background`
+        : 'inativa';
+    process.stdout.write(`[sessão] última: ${act.lastSession} (${label})\n`);
+  }
+
   process.exit(healthStatus !== 0 || errors.length ? 1 : 0);
 }