wendkeep 0.58.3 → 0.59.0

package/hooks/session-note-io.mjs

@@ -7,32 +7,105 @@
 //
 // `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';
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import {
+  assertVaultPathSafe, VAULT_LOCK_BUSY, withVaultPathLock, writeVaultFileAtomic,
+} from './vault-path-safety.mjs';
 
 export const LOCK_BUSY = Symbol('wendkeep:lock-busy');
+export const LOCK_OWNER_FILE = '.owner.json';
+
+function lockOwnerPath(lock) {
+  return `${lock}/${LOCK_OWNER_FILE}`;
+}
+
+function readLockOwner(lock) {
+  try {
+    const owner = JSON.parse(readFileSync(lockOwnerPath(lock), 'utf8'));
+    if (owner?.v !== 1 || !Number.isInteger(owner.pid) || owner.pid <= 0
+        || typeof owner.token !== 'string' || !owner.token) return null;
+    return owner;
+  } catch {
+    return null;
+  }
+}
+
+function processIsAlive(pid) {
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but this user cannot signal it.
+    return error?.code === 'EPERM';
+  }
+}
+
+function releaseUnownedLockDir(lock) {
+  try { unlinkSync(lockOwnerPath(lock)); }
+  catch (error) { if (error?.code !== 'ENOENT') return false; }
+  return releaseLockDir(lock);
+}
 
 // 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) {
+// Locks owner-aware contêm apenas `.owner.json`; locks legados continuam vazios.
+// Quando `expectedToken` é informado, um finally antigo jamais remove um lock que já
+// foi substituído por outro dono (proteção contra ABA).
+export function releaseLockDir(lock, expectedToken = '') {
   try {
+    const ownerPath = lockOwnerPath(lock);
+    if (expectedToken) {
+      const owner = readLockOwner(lock);
+      if (owner?.token !== expectedToken) return false;
+      unlinkSync(ownerPath);
+    } else if (existsSync(ownerPath)) {
+      return false;
+    }
     rmdirSync(lock);
+    return true;
   } catch (error) {
-    if (error?.code === 'ENOENT') return;
-    try { rmSync(lock, { recursive: true, force: true }); } catch { /* lock preso: melhor seguir */ }
+    if (error?.code === 'ENOENT') return true;
+    return false;
   }
 }
 
 const FRONTMATTER = /^---\n[\s\S]*?\n---/;
 
+function inferVaultBase(path) {
+  if (!path) return '';
+  let cursor = resolve(dirname(path));
+  while (true) {
+    try {
+      const brain = lstatSync(join(cursor, '.brain'));
+      if (brain.isDirectory() || brain.isSymbolicLink()) return cursor;
+    } catch (error) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) return '';
+    cursor = parent;
+  }
+}
+
 export function hasSessionFrontmatter(content) {
   return typeof content === 'string' && FRONTMATTER.test(content);
 }
 
-export function writeFileAtomic(path, content, encoding = 'utf-8') {
+export function writeFileAtomic(path, content, encoding = 'utf-8', { vaultBase = '' } = {}) {
+  if (vaultBase) {
+    return writeVaultFileAtomic(vaultBase, path, content, encoding, {
+      label: 'nota de sessão atômica',
+    });
+  }
   // 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);
@@ -46,19 +119,46 @@ function waitBriefly(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 } = {}) {
+export function withPathLock(path, fn, {
+  timeoutMs = 2000,
+  staleMs = 10_000,
+  vaultBase = '',
+} = {}) {
+  if (vaultBase) {
+    const outcome = withVaultPathLock(vaultBase, path, fn, { timeoutMs, staleMs });
+    return outcome === VAULT_LOCK_BUSY ? LOCK_BUSY : outcome;
+  }
   const lock = `${path}.lock`;
   const deadline = Date.now() + timeoutMs;
+  const token = randomUUID();
 
   while (true) {
     try {
       mkdirSync(lock);
+      try {
+        writeFileSync(lockOwnerPath(lock), `${JSON.stringify({
+          v: 1,
+          pid: process.pid,
+          token,
+          created_at: new Date().toISOString(),
+        })}\n`, { encoding: 'utf8', flag: 'wx' });
+      } catch (error) {
+        // No owner was published, so this is still a legacy-empty directory owned by us.
+        releaseUnownedLockDir(lock);
+        throw error;
+      }
       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);
+        if (Date.now() - statSync(lock).mtimeMs > staleMs) {
+          const owner = readLockOwner(lock);
+          // An old mtime is not proof of death: synchronous critical sections cannot
+          // heartbeat. Reap only a legacy-empty lock or a verified dead PID.
+          if (owner) {
+            if (!processIsAlive(owner.pid)) releaseLockDir(lock, owner.token);
+          } else releaseUnownedLockDir(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.
@@ -70,7 +170,7 @@ export function withPathLock(path, fn, { timeoutMs = 2000, staleMs = 10_000 } =
   try {
     return fn();
   } finally {
-    releaseLockDir(lock);
+    releaseLockDir(lock, token);
   }
 }
 
@@ -78,16 +178,31 @@ export function withPathLock(path, fn, { timeoutMs = 2000, staleMs = 10_000 } =
 // 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 vaultBase = options.vaultBase || inferVaultBase(path);
+  let target = path;
+  if (vaultBase) {
+    const checked = assertVaultPathSafe(vaultBase, path, {
+      expectedType: 'file', label: 'nota de sessão',
+    });
+    if (!checked.exists) return { written: false, reason: 'missing', content: null };
+    target = checked.target;
+  } else if (!path || !existsSync(path)) {
+    return { written: false, reason: 'missing', content: null };
+  }
 
-  const outcome = withPathLock(path, () => {
-    const original = readFileSync(path, 'utf-8');
+  const outcome = withPathLock(target, () => {
+    if (vaultBase) {
+      assertVaultPathSafe(vaultBase, target, {
+        allowMissing: false, expectedType: 'file', label: 'nota de sessão',
+      });
+    }
+    const original = readFileSync(target, '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);
+    writeFileAtomic(target, next, 'utf-8', { vaultBase });
     return { written: true, reason: 'ok', content: next };
-  }, options);
+  }, { ...options, vaultBase });
 
   if (outcome === LOCK_BUSY) return { written: false, reason: 'busy', content: null };
   return outcome;

package/hooks/session-observability.mjs

@@ -159,7 +159,9 @@ export function buildSessionObservability({ sessionContent, transcriptPath }) {
   return { snapshot, content: upsertObservabilitySection(content, renderSessionObservability(snapshot)) };
 }
 
-export function updateSessionObservability({ sessionPath, transcriptPath, caller = 'unknown', canonicalConversationId = '', lockTimeoutMs }) {
+export function updateSessionObservability({
+  vaultBase = '', sessionPath, transcriptPath, caller = 'unknown', canonicalConversationId = '', lockTimeoutMs,
+}) {
   if (!sessionPath || !existsSync(sessionPath)) return null;
   const identity = inspectTranscriptIdentity(transcriptPath);
   let snapshot = null;
@@ -184,7 +186,7 @@ export function updateSessionObservability({ sessionPath, transcriptPath, caller
     if (!result) return null;
     snapshot = result.snapshot;
     return result.content;
-  }, lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {});
+  }, { ...(lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {}), vaultBase });
 
   // '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

@@ -16,6 +16,7 @@ import { buildSessionMemoryEvents, collectLifecycleEvidence } from './memory-han
 import { enqueueMemoryEvent, projectMemoryOutbox } from './memory-store.mjs';
 import { detectMemoryMode } from './memory-mode.mjs';
 import { sanitizeMemoryText } from './memory-schema.mjs';
+import { assertVaultPathSafe } from './vault-path-safety.mjs';
 import {
   projectStopMemoryAttempt,
   recordStopMemoryOutcome,
@@ -552,12 +553,38 @@ export function resolveTurnIdentity(transcript, requestedTurnId = '') {
   };
 }
 
+function escapeMarkdownBackticks(text) {
+  let escaped = '';
+  let precedingBackslashes = 0;
+  for (const char of String(text || '')) {
+    if (char === '\\') {
+      escaped += char;
+      precedingBackslashes += 1;
+      continue;
+    }
+    if (char === '`') {
+      if (precedingBackslashes % 2 === 0) escaped += '\\';
+      escaped += char;
+      precedingBackslashes = 0;
+      continue;
+    }
+    escaped += char;
+    precedingBackslashes = 0;
+  }
+  return escaped;
+}
+
 function compactText(text, max = 600) {
   const clean = redactSecrets(String(text || ''))
     .replace(/\r/g, '\n')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
-  return truncate(clean || 'Não capturado automaticamente.', max);
+  const source = clean || 'Não capturado automaticamente.';
+  const compact = source.replace(/\s+/g, ' ').trim();
+  const clipped = truncate(source, max);
+  // Um corte no meio de código inline/fence pode casar com backticks da próxima
+  // entrada gerada. Só snippets realmente truncados perdem a formatação incompleta.
+  return compact.length > max ? escapeMarkdownBackticks(clipped) : clipped;
 }
 
 function selectTurn(tx, turnId) {
@@ -801,7 +828,7 @@ function relocateOrphanIterations(content) {
   return insertIntoIteracoes(head, `\n${demoted}`);
 }
 
-export function insertIteration(sessionPath, block, turnId, tx) {
+export function insertIteration(sessionPath, block, turnId, tx, vaultBase = '') {
   let inserted = false;
   // Sob lock: outro hook (subagent-stop) pode estar reescrevendo a mesma nota agora.
   mutateSessionNote(sessionPath, (original) => {
@@ -815,7 +842,7 @@ export function insertIteration(sessionPath, block, turnId, tx) {
     content = insertIntoIteracoes(content, block);
     inserted = true;
     return applyDedicatedSections(content, tx);
-  });
+  }, { vaultBase });
   return inserted;
 }
 
@@ -846,11 +873,13 @@ export function commitSessionMemory(vaultBase, handoff, { projectOptions = {} }
       status: 'projected',
       eventCount: events.length,
       eventIds,
-      checkpoint: {
-        revision: projection.revision,
-        event_cursor: projection.eventCursor,
-        state_hash: projection.stateHash,
-      },
+      checkpoint: projection.checkpoint && typeof projection.checkpoint === 'object'
+        ? { ...projection.checkpoint }
+        : {
+          revision: projection.revision,
+          event_cursor: projection.eventCursor,
+          state_hash: projection.stateHash,
+        },
     };
   } catch (error) {
     return {
@@ -981,7 +1010,7 @@ function replaceClosingSection(content, closing) {
   return `${content.slice(0, index).trimEnd()}\n\n${closing}\n`;
 }
 
-export function finalizeSessionFile(sessionPath, tx, created, endedAt) {
+export function finalizeSessionFile(sessionPath, tx, created, endedAt, vaultBase = '') {
   const pending = extractPending(tx.rawTextForDetection);
   const links = (items) => items.length ? items.map((rel) => `  - ${wikilinkFromRel(rel)}`).join('\n') : '  - Nenhuma';
   const summary = sessionFinalSummary(tx);
@@ -1009,7 +1038,7 @@ ${formatPendingClosing(pending)}
       created,
     ),
     closing,
-  ));
+  ), { vaultBase });
 }
 
 export function sessionFinalSummary(tx) {
@@ -1098,7 +1127,7 @@ function applyLinearLinks(sessionPath, tx, vaultBase, sessionRel) {
 
   mutateSessionNote(sessionPath, (original) => (
     upsertListSection(ensureSection(original, 'Issues Linear', '\n## Encerramento'), 'Issues Linear', lines, null)
-  ));
+  ), { vaultBase });
 }
 
 // Triggers Obsidian Local REST API to re-index the vault after file writes.
@@ -1162,11 +1191,14 @@ export function main({ stageMemory = stageStopMemoryAttempt } = {}) {
     return;
   }
 
-  const sessionPath = join(vaultBase, sessionRel);
-  if (!existsSync(sessionPath)) {
+  const checkedSession = assertVaultPathSafe(vaultBase, join(vaultBase, sessionRel), {
+    expectedType: 'file', label: 'nota de sessão do Stop',
+  });
+  if (!checkedSession.exists) {
     writeHookOutput({});
     return;
   }
+  const sessionPath = checkedSession.target;
 
   const tx = parseTranscript(identity.transcriptPath || input.transcript_path || input.transcriptPath);
   const requestedTurnId = String(input.turn_id || input.turnId || '');
@@ -1237,8 +1269,20 @@ export function main({ stageMemory = stageStopMemoryAttempt } = {}) {
   if (finalizing) {
     let projectId = '';
     try {
-      projectId = JSON.parse(readFileSync(join(vaultBase, '.brain', 'PROJECT.json'), 'utf8')).projectId || '';
-    } catch { /* the staging validator exposes an observable failure below */ }
+      const projectPath = join(vaultBase, '.brain', 'PROJECT.json');
+      let checkedProject = assertVaultPathSafe(vaultBase, projectPath, {
+        expectedType: 'file', label: 'autoridade PROJECT.json do Stop',
+      });
+      if (checkedProject.exists) {
+        checkedProject = assertVaultPathSafe(vaultBase, checkedProject.target, {
+          allowMissing: false, expectedType: 'file', label: 'autoridade PROJECT.json do Stop',
+        });
+        projectId = JSON.parse(readFileSync(checkedProject.target, 'utf8')).projectId || '';
+      }
+    } catch (error) {
+      if (error?.code === 'VAULT_PATH_UNSAFE') throw error;
+      /* the staging validator exposes ordinary missing/invalid PROJECT below */
+    }
     const finalSummary = sessionFinalSummary(tx);
     const memoryEvidence = collectLifecycleEvidence(vaultBase, {
       changeSlug: entry.change_slug,
@@ -1274,7 +1318,7 @@ export function main({ stageMemory = stageStopMemoryAttempt } = {}) {
     writeHookOutput({ systemMessage: message });
     return;
   }
-  const logged = insertIteration(sessionPath, buildIterationBlock(tx, input), turnId, tx);
+  const logged = insertIteration(sessionPath, buildIterationBlock(tx, input), turnId, tx, vaultBase);
 
   try {
     applyLinearLinks(sessionPath, tx, vaultBase, sessionRel);
@@ -1283,7 +1327,9 @@ export function main({ stageMemory = stageStopMemoryAttempt } = {}) {
   }
 
   try {
-    updateSessionObservability({ sessionPath, transcriptPath, caller: 'stop', canonicalConversationId: sessionId });
+    updateSessionObservability({
+      vaultBase, sessionPath, transcriptPath, caller: 'stop', canonicalConversationId: sessionId,
+    });
   } catch (error) {
     process.stderr.write(`[wendkeep] Token usage falhou: ${error.message}\n`);
   }
@@ -1318,7 +1364,7 @@ export function main({ stageMemory = stageStopMemoryAttempt } = {}) {
     createLinkedNotes(vaultBase, formatDate(now), sessionRel, tx),
     findLinkedDerivedNotes(vaultBase, sessionRel),
   );
-  finalizeSessionFile(sessionPath, tx, created, endedAt);
+  finalizeSessionFile(sessionPath, tx, created, endedAt, vaultBase);
   // Link durável sessão↔change: uma seção "Mudanças" ANTES de `## Encerramento`. O append antigo
   // (após o Encerramento) era apagado a cada reopen por stripClosingSection, perdendo a aresta do
   // grafo quando a change fechava antes do turno seguinte. Aqui sobrevive ao reopen e acumula toda
@@ -1331,7 +1377,7 @@ export function main({ stageMemory = stageStopMemoryAttempt } = {}) {
     if (wl) {
       mutateSessionNote(sessionPath, (cur) => (
         upsertListSection(ensureSection(cur, 'Mudanças', '\n## Encerramento'), 'Mudanças', [`- ${wl}`], null)
-      ));
+      ), { vaultBase });
     }
   } catch { /* nunca derruba o Stop */ }
   writeControl(vaultBase, {

package/hooks/spec-core.mjs

@@ -1,10 +1,12 @@
 // hooks/spec-core.mjs — living spec (07-Specs) + change delta merge (OpenSpec native).
 // Pure parsing/merge + promoteSpecs (fs). No import from change-core (avoids a cycle).
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { ensureDir } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
+import {
+  assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, writeVaultFileSync,
+} from './vault-path-safety.mjs';
 
 // Short stable fingerprint of tarefas.md — freshness check between package/verdict and gate.
 export function tasksHashOf(md) {
@@ -122,8 +124,14 @@ export function livingSpecCapabilities(vaultBase) {
 
 export function adoptSpecsState(vaultBase) {
   const state = { version: 1, generatedAt: new Date().toISOString(), specs: readLivingSpecs(vaultBase) };
-  ensureDir(join(vaultBase, '.brain'));
-  writeFileSync(join(vaultBase, SPECS_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  mkdirVaultPath(vaultBase, join(vaultBase, '.brain'), { label: 'raiz do estado de specs' });
+  writeVaultFileSync(
+    vaultBase,
+    join(vaultBase, SPECS_STATE_FILE),
+    `${JSON.stringify(state, null, 2)}\n`,
+    'utf8',
+    { label: 'estado consolidado de specs' },
+  );
   return state;
 }
 
@@ -150,17 +158,32 @@ function recordPromotedSpecs(vaultBase, capabilities) {
     else delete specs[capability];
   }
   const state = { version: 1, generatedAt: new Date().toISOString(), specs };
-  writeFileSync(join(vaultBase, SPECS_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  writeVaultFileSync(
+    vaultBase,
+    join(vaultBase, SPECS_STATE_FILE),
+    `${JSON.stringify(state, null, 2)}\n`,
+    'utf8',
+    { label: 'estado consolidado de specs' },
+  );
   return state;
 }
 
 export function captureSpecBaseline(vaultBase, changeDir, { refresh = false } = {}) {
   const path = join(changeDir, SPEC_BASELINE_FILE);
-  if (!refresh && existsSync(path)) {
+  const checked = assertVaultPathSafe(vaultBase, path, {
+    expectedType: 'file', label: 'baseline de specs da change',
+  });
+  if (!refresh && checked.exists) {
     try { return JSON.parse(readFileSync(path, 'utf8')); } catch { /* rebuild malformed baseline */ }
   }
   const baseline = { version: 1, capturedAt: new Date().toISOString(), specs: readLivingSpecs(vaultBase) };
-  writeFileSync(path, `${JSON.stringify(baseline, null, 2)}\n`, 'utf8');
+  writeVaultFileSync(
+    vaultBase,
+    path,
+    `${JSON.stringify(baseline, null, 2)}\n`,
+    'utf8',
+    { label: 'baseline de specs da change' },
+  );
   return baseline;
 }
 
@@ -325,7 +348,7 @@ export function ensureSpecsReadme(vaultBase) {
   const loc = getLocale(vaultBase);
   const en = loc.id === 'en';
   const dir = join(vaultBase, loc.folders.specs);
-  ensureDir(dir);
+  mkdirVaultPath(vaultBase, dir, { label: 'raiz de specs consolidadas' });
   const body = en
     ? `# Specs — generated living contract
 
@@ -355,7 +378,48 @@ Pense como código-fonte vs commits: esta pasta é o *código atual* de cada cap
   \`wendkeep change archive\` promove para esta pasta.
 - Histórico por mudança → \`${loc.folders.changes}/_arquivo/\`. Contrato atual → aqui.
 `;
-  writeFileSync(join(dir, 'README.md'), body, 'utf8');
+  writeVaultFileSync(vaultBase, join(dir, 'README.md'), body, 'utf8', { label: 'README de specs' });
+}
+
+export function assertSpecPromotionTargetsSafe(vaultBase, changeDir, specs) {
+  const loc = getLocale(vaultBase);
+  const specsRoot = join(vaultBase, loc.folders.specs);
+  const checkedRoot = assertVaultPathSafe(vaultBase, specsRoot, {
+    expectedType: 'directory', label: 'raiz de specs consolidadas',
+  });
+  const targets = [
+    { path: join(specsRoot, 'README.md'), expectedType: 'file', label: 'README de specs' },
+    { path: join(vaultBase, '.brain'), expectedType: 'directory', label: 'raiz do estado de specs' },
+    { path: join(vaultBase, SPECS_STATE_FILE), expectedType: 'file', label: 'estado consolidado de specs' },
+  ];
+  if (checkedRoot.exists) {
+    for (const name of readdirSync(checkedRoot.target)) {
+      if (!name.endsWith('.md')) continue;
+      targets.push({
+        path: join(checkedRoot.target, name),
+        allowMissing: false,
+        expectedType: 'file',
+        label: `spec consolidada existente ${name}`,
+      });
+    }
+  }
+  for (const capability of specs) {
+    targets.push(
+      {
+        path: join(changeDir, 'specs', capability, 'spec.md'),
+        allowMissing: false,
+        expectedType: 'file',
+        label: `delta da spec ${capability}`,
+      },
+      {
+        path: join(specsRoot, `${capability}.md`),
+        expectedType: 'file',
+        label: `spec consolidada ${capability}`,
+      },
+    );
+  }
+  assertVaultPathsSafe(vaultBase, targets);
+  return { specsRoot: checkedRoot.target };
 }
 
 // Merge each capability's delta (in the change) into the living spec in 07-Specs.
@@ -364,6 +428,7 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
   const specsDir = loc.folders.specs;
   const promoted = [];
   const warnings = [];
+  const { specsRoot } = assertSpecPromotionTargetsSafe(vaultBase, changeDir, specs);
   const state = checkSpecsState(vaultBase);
   const unmanaged = state.missing ? [] : state.changed.filter((capability) => specs.includes(capability));
   if (unmanaged.length) {
@@ -371,6 +436,7 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
   }
   const conflicts = specConflicts(vaultBase, changeDir, specs);
   if (conflicts.length) throw new Error(`conflito de spec: ${conflicts.join('; ')} — reconcilie o delta e rode \`wendkeep spec rebase --change <slug> --accept-current\``);
+  const materialized = [];
   for (const cap of specs) {
     let deltaMd;
     try { deltaMd = readFileSync(join(changeDir, 'specs', cap, 'spec.md'), 'utf8'); }
@@ -382,10 +448,23 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
     try { current = parseRequirements(readFileSync(livePath, 'utf8')); } catch { /* nova capability */ }
     const applied = applyDelta(current, delta);
     warnings.push(...applied.warnings.map((w) => `${cap}: ${w}`));
-    ensureDir(join(vaultBase, specsDir));
     const footer = changeWikilink ? `Atualizado por ${changeWikilink} em ${dateStr}.` : '';
-    writeFileSync(livePath, renderSpec(cap, applied.reqs, { footer, reqHeading: loc.reqHeading }), 'utf8');
-    promoted.push(cap);
+    materialized.push({
+      capability: cap,
+      livePath,
+      content: renderSpec(cap, applied.reqs, { footer, reqHeading: loc.reqHeading }),
+    });
+  }
+  mkdirVaultPath(vaultBase, specsRoot, { label: 'raiz de specs consolidadas' });
+  for (const item of materialized) {
+    writeVaultFileSync(
+      vaultBase,
+      item.livePath,
+      item.content,
+      'utf8',
+      { label: `spec consolidada ${item.capability}` },
+    );
+    promoted.push(item.capability);
   }
   recordPromotedSpecs(vaultBase, promoted);
   ensureSpecsReadme(vaultBase); // self-heal the explainer so existing vaults get it on archive

package/hooks/subagent-stop.mjs

@@ -20,7 +20,10 @@ export function refreshSubagents(vaultBase, input) {
   if (!sessionRel) return false;
   const sessionPath = join(vaultBase, sessionRel);
   if (!existsSync(sessionPath)) return false;
-  updateSessionObservability({ sessionPath, transcriptPath, caller: 'subagent-stop', canonicalConversationId: identity.canonicalConversationId });
+  updateSessionObservability({
+    vaultBase, sessionPath, transcriptPath, caller: 'subagent-stop',
+    canonicalConversationId: identity.canonicalConversationId,
+  });
   return true;
 }
 

package/hooks/subagent-usage.mjs

@@ -340,7 +340,7 @@ 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, { lockTimeoutMs } = {}) {
+export function upsertSubagentUsage(sessionPath, transcriptPath, { lockTimeoutMs, vaultBase = '' } = {}) {
   if (!sessionPath || !existsSync(sessionPath)) return false;
   const collected = collectSubagentUsage(sessionDirFromTranscript(transcriptPath));
   if (!collected) return false;
@@ -377,6 +377,6 @@ export function upsertSubagentUsage(sessionPath, transcriptPath, { lockTimeoutMs
     };
     content = setFrontmatterField(content, 'custo_por_modelo_json', `'${JSON.stringify(ledger).replaceAll("'", "''")}'`);
     return upsertSection(content, '## Subagents & Workflows', renderSubagentSection(collected));
-  }, lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {});
+  }, { ...(lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {}), vaultBase });
   return outcome.written;
 }

package/hooks/task-log.mjs

@@ -52,7 +52,9 @@ export function logTask(vaultBase, input) {
 
   const heading = getLocale(vaultBase).id === 'en' ? 'Plan progress' : 'Progresso do plano';
   const line = `- [x] ${formatHourMinute(new Date()).replace('-', ':')} ${text}`;
-  return mutateSessionNote(sessionPath, (content) => appendProgress(content, line, heading)).written;
+  return mutateSessionNote(sessionPath, (content) => appendProgress(content, line, heading), {
+    vaultBase,
+  }).written;
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/hooks/token-usage.mjs

@@ -986,7 +986,7 @@ export function updateSessionUsage({ vaultBase, sessionRel, sessionPath, transcr
     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 } : {});
+  }, { ...(lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {}), vaultBase });
   return outcome.written || outcome.reason === 'unchanged' ? result : null;
 }