wendkeep 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ 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
+
+- **`wendkeep doctor` agora surfaça os órfãos do grafo com o comando de reparo.** Nova seção
+  `[links]`: conta notas derivadas sem sessão-fonte (→ `note relink`), artefatos de change
+  sem backlink (→ `change backlink`) e o estado das cores do grafo (→ `theme sync`); quando
+  tudo conectado, diz `grafo conectado`. Reusa as funções de reparo em dry-run — zero lógica
+  nova de detecção. Antes o dono do vault só descobria os órfãos olhando o grafo no Obsidian
+  e não sabia qual comando rodava.
+- **Sessão não mente "inativa" com atividade recente.** Nova seção `[sessão]`: quando o
+  control marca `inactive` mas a nota da sessão foi escrita há pouco, o doctor sinaliza
+  possível workflow/subagente em segundo plano — o control só reflete o lifecycle da
+  sessão-mãe, não a atividade de background. Capability `vault-doctor` (DIAG-1..4).
+
 ## [0.48.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,10 +1,12 @@
 // 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 } from 'node:fs';
-import { join } from 'node:path';
-import { activeChange, parseTasks } from './change-core.mjs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+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';
 import { getLocale } from './locale.mjs';
+import { readControl } from './obsidian-common.mjs';
 
 export function checkHarness(vaultBase, projectRoot) {
   const loc = getLocale(vaultBase);
@@ -63,3 +65,79 @@ export function checkHarness(vaultBase, projectRoot) {
 
   return { errors, warnings };
 }
+
+// --- diagnóstico de links do grafo (read-only, reusa os reparos em dry-run) -----
+// Surfaça os órfãos que o doctor não enxergava: notas derivadas sem sessão-fonte,
+// artefatos de change sem backlink, e o estado das cores do grafo. Cada não-zero tem um
+// comando de reparo (note relink / change backlink / theme sync).
+export function checkVaultLinks(vaultBase) {
+  let derivedOrphans = 0;
+  try { derivedOrphans = relinkDerivedNotes(vaultBase, {}).linked.length; } catch { /* sem notas derivadas */ }
+  let artifactOrphans = 0;
+  try { artifactOrphans = backfillArtifactLinks(vaultBase, {}).changed.length; } catch { /* sem changes */ }
+  let graphColors = null; // true=com grupos · false=vazio/ausente de cores · null=sem graph.json
+  try {
+    const g = JSON.parse(readFileSync(join(vaultBase, '.obsidian', 'graph.json'), 'utf8'));
+    graphColors = Array.isArray(g.colorGroups) && g.colorGroups.length > 0;
+  } catch { graphColors = null; }
+  return { derivedOrphans, artifactOrphans, graphColors };
+}
+
+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';
+  const sessionRel = unquoteControl(active ? control.session_file : (control.last_session_file || control.session_file));
+  let ageMs = null;
+  if (sessionRel) {
+    try { ageMs = now - statSync(join(vaultBase, sessionRel)).mtimeMs; } catch { ageMs = null; }
+  }
+  const backgroundSuspected = !active && sessionRel !== '' && ageMs !== null && ageMs >= 0 && ageMs < windowMs;
+  return { lastSession: sessionRel, active, ageMs, backgroundSuspected };
+}