wendkeep 0.58.0 → 0.58.3

package/hooks/session-stop.mjs

@@ -14,7 +14,13 @@ import { mutateSessionNote } from './session-note-io.mjs';
 import { applyDerivedSections, provenanceSessions } from './derived-sections.mjs';
 import { buildSessionMemoryEvents, collectLifecycleEvidence } from './memory-handoff.mjs';
 import { enqueueMemoryEvent, projectMemoryOutbox } from './memory-store.mjs';
+import { detectMemoryMode } from './memory-mode.mjs';
 import { sanitizeMemoryText } from './memory-schema.mjs';
+import {
+  projectStopMemoryAttempt,
+  recordStopMemoryOutcome,
+  stageStopMemoryAttempt,
+} from './session-memory-lifecycle.mjs';
 import {
   ensureDir,
   findActiveSessionByTranscript,
@@ -526,6 +532,26 @@ export function parseTranscript(transcriptPath) {
   return parseCodexTranscript(transcriptPath);
 }
 
+export function resolveTurnIdentity(transcript, requestedTurnId = '') {
+  const turns = Array.isArray(transcript?.turns) ? transcript.turns : [];
+  const requested = String(requestedTurnId || '');
+  let index = requested
+    ? turns.findIndex((turn) => String(turn?.turnId || '') === requested)
+    : -1;
+  if (requested && index < 0) return null;
+  if (index < 0 && transcript?.latestTurnId) {
+    index = turns.findIndex((turn) => String(turn?.turnId || '') === String(transcript.latestTurnId));
+  }
+  if (index < 0) index = turns.length - 1;
+  const turn = turns[index];
+  if (!turn?.turnId) return null;
+  return {
+    id: String(turn.turnId),
+    order: index + 1,
+    observedAt: String(turn.timestamp || ''),
+  };
+}
+
 function compactText(text, max = 600) {
   const clean = redactSecrets(String(text || ''))
     .replace(/\r/g, '\n')
@@ -799,6 +825,9 @@ function shouldFinalizeSession() {
 }
 
 export function commitSessionMemory(vaultBase, handoff, { projectOptions = {} } = {}) {
+  if (detectMemoryMode(vaultBase).mode === 'legacy') {
+    return { status: 'legacy', eventCount: 0, eventIds: [], checkpoint: null };
+  }
   const events = buildSessionMemoryEvents(handoff);
   const eventIds = events.map((event) => event.event_id);
   try {
@@ -1091,7 +1120,18 @@ function pingObsidianVault(apiKey) {
   } catch {}
 }
 
-function main() {
+export function shouldAbortStopAfterStaging(causalStop, memoryAttempt) {
+  const rejectedByV2Revalidation = memoryAttempt?.memory_mode === 'v2'
+    && memoryAttempt?.state === 'skipped';
+  if (rejectedByV2Revalidation) return true;
+  return Boolean(
+    causalStop
+    && !causalStop.canPromoteMemory
+    && memoryAttempt?.state !== 'enqueued'
+  );
+}
+
+export function main({ stageMemory = stageStopMemoryAttempt } = {}) {
   const input = readHookInput();
   if (input.stop_hook_active) {
     writeHookOutput({});
@@ -1128,15 +1168,34 @@ function main() {
     return;
   }
 
-  const tx = parseTranscript(input.transcript_path || input.transcriptPath);
-  const turnId = input.turn_id || tx.latestTurnId || String(Date.now());
+  const tx = parseTranscript(identity.transcriptPath || input.transcript_path || input.transcriptPath);
+  const requestedTurnId = String(input.turn_id || input.turnId || '');
   const sessionId = identity.canonicalConversationId;
   const finalizing = shouldFinalizeSession();
+  const turnIdentity = resolveTurnIdentity(tx, requestedTurnId);
+  if (!turnIdentity) {
+    if (finalizing) {
+      const activeId = String(entry.active_activation_id || '');
+      const active = entry.activations?.[activeId] || {};
+      stageMemory(vaultBase, {
+        sessionId,
+        activationId: activeId,
+        activationEpoch: Number(active.epoch || entry.activation_epoch || 0),
+        turnId: requestedTurnId || 'unresolved-turn',
+        turnSequence: Number(entry.last_turn_sequence || 0),
+        disposition: 'ambiguous',
+        observedAt: new Date(0).toISOString(),
+      });
+    }
+    const message = 'wendkeep: Stop ambiguous; o turno solicitado não foi provado pelo transcript.';
+    process.stderr.write(`[wendkeep] ${message}\n`);
+    writeHookOutput({ systemMessage: message });
+    return;
+  }
+  const turnId = turnIdentity.id;
   const now = finalizing ? new Date() : null;
   const endedAt = finalizing ? formatLocalIso(now) : '';
-  const stopTurnSequence = Number.isSafeInteger(Number(input.turn_sequence))
-    ? Number(input.turn_sequence)
-    : Number(entry.last_turn_sequence || 0);
+  const stopTurnSequence = turnIdentity.order;
   const causalStop = finalizing
     ? mutateSessionRegistry(vaultBase, (registry) => {
       const activationId = resolveStopActivation(registry, {
@@ -1148,6 +1207,7 @@ function main() {
       const cas = applyStopActivation(registry, {
         session_id: sessionId,
         activation_id: activationId,
+        turn_id: turnId,
         turn_sequence: stopTurnSequence,
         ended_at: endedAt,
       });
@@ -1172,8 +1232,44 @@ function main() {
       };
     })
     : null;
-  if (causalStop && !causalStop.canPromoteMemory) {
-    const message = `wendkeep: Stop ${causalStop.stopDisposition}; uma activation mais nova foi preservada e a memória não foi promovida.`;
+  let memoryHandoff = null;
+  let memoryAttempt = null;
+  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 finalSummary = sessionFinalSummary(tx);
+    const memoryEvidence = collectLifecycleEvidence(vaultBase, {
+      changeSlug: entry.change_slug,
+      summary: finalSummary,
+      noteRel: sessionRel,
+    });
+    memoryHandoff = {
+      projectId,
+      identity,
+      activation: {
+        id: causalStop?.activationId || '',
+        epoch: Number(causalStop?.activation?.epoch || entry.activation_epoch || 0),
+      },
+      turn: { id: turnId, sequence: stopTurnSequence },
+      noteRel: sessionRel,
+      observedAt: turnIdentity.observedAt || new Date(0).toISOString(),
+      summary: finalSummary,
+      evidence: memoryEvidence,
+    };
+    memoryAttempt = stageMemory(vaultBase, {
+      handoff: memoryHandoff,
+      disposition: causalStop?.stopDisposition || 'ambiguous',
+    });
+  }
+  if (shouldAbortStopAfterStaging(causalStop, memoryAttempt)) {
+    const disposition = memoryAttempt?.disposition || causalStop?.stopDisposition || 'ambiguous';
+    if (disposition === 'duplicate' && memoryAttempt?.state === 'duplicate') {
+      writeHookOutput({});
+      return;
+    }
+    const message = `wendkeep: Stop ${disposition}; uma activation mais nova foi preservada e a memória não foi promovida.`;
     process.stderr.write(`[wendkeep] ${message}\n`);
     writeHookOutput({ systemMessage: message });
     return;
@@ -1248,40 +1344,24 @@ function main() {
     last_logged_turn_id: turnId,
   });
 
-  let projectId = '';
-  try {
-    projectId = JSON.parse(readFileSync(join(vaultBase, '.brain', 'PROJECT.json'), 'utf8')).projectId || '';
-  } catch { /* store validator reports a degraded handoff below */ }
-  const finalSummary = sessionFinalSummary(tx);
-  const memoryEvidence = collectLifecycleEvidence(vaultBase, {
-    changeSlug: entry.change_slug,
-    summary: finalSummary,
-    noteRel: sessionRel,
-  });
-  const memoryResult = commitSessionMemory(vaultBase, {
-    projectId,
-    identity,
-    activation: {
-      id: causalStop.activationId,
-      epoch: Number(causalStop.activation?.epoch || entry.activation_epoch || 0),
-    },
-    turn: { id: turnId, sequence: stopTurnSequence },
-    noteRel: sessionRel,
-    observedAt: new Date().toISOString(),
-    summary: finalSummary,
-    evidence: memoryEvidence,
-  });
-  mutateSessionRegistry(vaultBase, (registry) => {
-    const current = registry.sessions[sessionId];
-    if (!current) return null;
-    registry.sessions[sessionId] = {
-      ...current,
-      memory_status: memoryResult.status,
-      memory_activation_id: causalStop.activationId,
-      ...(memoryResult.checkpoint ? { memory_checkpoint: memoryResult.checkpoint } : {}),
-    };
-    return null;
-  });
+  const memoryResult = projectStopMemoryAttempt(vaultBase, memoryAttempt);
+  if (memoryResult.status === 'legacy') {
+    mutateSessionRegistry(vaultBase, (registry) => {
+      const current = registry.sessions[sessionId];
+      const active = current?.activations?.[current.active_activation_id || ''];
+      if (!current
+        || current.active_activation_id !== memoryAttempt.activation_id
+        || Number(active?.epoch || 0) !== Number(memoryAttempt.activation_epoch || 0)) return null;
+      registry.sessions[sessionId] = {
+        ...current,
+        memory_status: 'legacy',
+        memory_activation_id: memoryAttempt.activation_id,
+      };
+      return null;
+    });
+  } else {
+    recordStopMemoryOutcome(vaultBase, memoryAttempt, memoryResult);
+  }
 
   // Reconstrói índice (camada fria) + digest (camada quente) ao finalizar. Nunca derruba o Stop.
   try {

package/hooks/vault-health.mjs

@@ -12,6 +12,7 @@ import {
 } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
 import { parseSharedMemory, validateMemoryEvent } from './memory-schema.mjs';
+import { detectMemoryMode, LEGACY_MEMORY_WARNING } from './memory-mode.mjs';
 import { reduceMemoryEvents } from './memory-store.mjs';
 import { validateMemoryBundle } from '../src/validate-memory.mjs';
 
@@ -101,7 +102,9 @@ const MEMORY_REPAIR_COMMAND = 'wendkeep memory repair --vault <vault>';
 
 function readJsonLines(path, label) {
   if (!existsSync(path)) return { items: [], errors: [] };
-  const raw = readFileSync(path, 'utf8').replace(/\r\n/g, '\n');
+  let raw;
+  try { raw = readFileSync(path, 'utf8').replace(/\r\n/g, '\n'); }
+  catch (error) { return { items: [], errors: [`${label} ilegível: ${error?.message || error}`] }; }
   const lines = raw.endsWith('\n') ? raw.split('\n').slice(0, -1) : raw.split('\n');
   const items = [];
   const errors = [];
@@ -118,28 +121,137 @@ function readJsonLines(path, label) {
 
 function inspectOutbox(vaultBase, projectId) {
   const dir = join(vaultBase, '.brain', 'memory-outbox');
-  if (!existsSync(dir)) return { count: 0, errors: [] };
+  if (!existsSync(dir)) return { count: 0, errors: [], eventIds: new Set() };
   const files = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
   const errors = [];
+  const eventIds = new Set();
   for (const name of files) {
     const path = join(dir, name);
     try {
       const event = JSON.parse(readFileSync(path, 'utf8'));
       const validation = validateMemoryEvent(event, projectId ? { projectId } : {});
       if (!validation.ok) errors.push(`${name}: ${validation.errors.join(' ')}`);
+      else eventIds.add(event.event_id);
     } catch (error) {
       errors.push(`${name}: JSON inválido: ${error.message}`);
     }
   }
-  return { count: files.length, errors };
+  return { count: files.length, errors, eventIds };
+}
+
+function checkpointMatchesLedgerPrefix(checkpoint, eventIds, ledgerEvents) {
+  if (!checkpoint || typeof checkpoint !== 'object') return false;
+  if (!Number.isInteger(checkpoint.revision) || checkpoint.revision < 0) return false;
+  if (typeof checkpoint.event_cursor !== 'string' || !checkpoint.event_cursor) return false;
+  if (typeof checkpoint.state_hash !== 'string' || !checkpoint.state_hash) return false;
+
+  const cursorIndex = ledgerEvents.findIndex((event) => event?.event_id === checkpoint.event_cursor);
+  if (cursorIndex < 0) return false;
+  const prefix = ledgerEvents.slice(0, cursorIndex + 1);
+  const prefixIds = new Set(prefix.map((event) => event.event_id));
+  if (eventIds.some((eventId) => !prefixIds.has(eventId))) return false;
+
+  try {
+    const replay = reduceMemoryEvents(prefix);
+    return checkpoint.revision === replay.revision
+      && checkpoint.event_cursor === replay.eventCursor
+      && checkpoint.state_hash === replay.stateHash;
+  } catch {
+    return false;
+  }
+}
+
+function checkMemoryAttempts(registry, { ledgerEvents = [], outboxEventIds = new Set() } = {}) {
+  const failures = [];
+  const warnings = [];
+  const ledgerEventIds = new Set(ledgerEvents.map((event) => event?.event_id).filter(Boolean));
+  const attempts = Object.values(registry?.sessions || {})
+    .map((entry) => entry?.last_memory_attempt)
+    .filter((attempt) => attempt && typeof attempt === 'object' && attempt.memory_mode === 'v2');
+
+  for (const attempt of attempts) {
+    const state = String(attempt.state || '');
+    const disposition = String(attempt.disposition || '');
+    const eventIds = Array.isArray(attempt.event_ids)
+      ? [...new Set(attempt.event_ids.filter((eventId) => typeof eventId === 'string' && eventId))]
+      : [];
+
+    if (state === 'skipped' && disposition === 'ambiguous') {
+      failures.push(`Lifecycle de memória v2 ambíguo: Stop pulou a publicação sem identidade causal suficiente. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      continue;
+    }
+
+    if (state === 'skipped' && ['stale_turn', 'superseded'].includes(disposition)) {
+      if (eventIds.length) {
+        failures.push(`Stop stale/superseded emitiu event_ids apesar da rejeição causal. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      } else {
+        warnings.push('Stop stale/superseded foi descartado sem publicar memória.');
+      }
+      continue;
+    }
+
+    if (disposition !== 'applied') {
+      if (state === 'skipped') warnings.push('Attempt de memória v2 foi descartado sem publicação.');
+      else failures.push(`Attempt de memória v2 possui disposition não reconhecida para o estado informado. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      continue;
+    }
+
+    if (!eventIds.length) {
+      failures.push(`Attempt v2 aplicado não declarou event_ids; publicação perdida. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      continue;
+    }
+
+    if (state === 'enqueued' || state === 'degraded') {
+      const missing = eventIds.filter((eventId) => !ledgerEventIds.has(eventId) && !outboxEventIds.has(eventId));
+      if (missing.length) {
+        failures.push(`Attempt v2 perdeu ${missing.length} evento(s): ausentes do ledger e da outbox. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      } else {
+        warnings.push(`Attempt de memória v2 ${state} permanece recuperável: ${eventIds.length} evento(s) durável(is) no ledger e/ou outbox.`);
+      }
+      continue;
+    }
+
+    if (state === 'projected') {
+      const outsideLedger = eventIds.filter((eventId) => !ledgerEventIds.has(eventId));
+      if (outsideLedger.length) {
+        failures.push(`Attempt projetado perdeu ${outsideLedger.length} evento(s) no ledger. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      } else if (!checkpointMatchesLedgerPrefix(attempt.checkpoint, eventIds, ledgerEvents)) {
+        failures.push(`Checkpoint do attempt projetado diverge do prefixo rederivado do ledger. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+      }
+      continue;
+    }
+
+    failures.push(`Attempt de memória v2 possui state inválido. Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+  }
+
+  return { failures, warnings };
 }
 
 /**
  * Read-only consistency check for the local memory-v2 bundle. It intentionally
  * does not acquire MEMORY.lock or invoke the projector/repair paths.
  */
-export function checkMemoryBundle(vaultBase) {
+export function checkMemoryBundle(vaultBase, { registry } = {}) {
   const brain = join(vaultBase, '.brain');
+  const mode = detectMemoryMode(vaultBase);
+  if (mode.mode === 'legacy') {
+    return {
+      ok: true,
+      status: 'legacy',
+      failures: [],
+      warnings: [LEGACY_MEMORY_WARNING],
+      metrics: {
+        schemaVersion: null,
+        revision: null,
+        eventCursor: null,
+        stateHash: null,
+        ledgerEvents: 0,
+        pendingOutbox: 0,
+        candidates: 0,
+        activeConflicts: 0,
+      },
+    };
+  }
   const bundle = validateMemoryBundle(vaultBase);
   const failures = [];
   const warnings = [];
@@ -185,6 +297,13 @@ export function checkMemoryBundle(vaultBase) {
     }
   }
 
+  const lifecycle = checkMemoryAttempts(registry || readSessionRegistry(vaultBase), {
+    ledgerEvents: bundle.ledger?.events || [],
+    outboxEventIds: outbox.eventIds,
+  });
+  failures.push(...lifecycle.failures);
+  warnings.push(...lifecycle.warnings);
+
   const unresolved = candidates.items.filter((item) => !['resolved', 'rejected', 'superseded'].includes(item?.status));
   const activeConflicts = unresolved.filter((item) => item?.reason === 'conflict');
   const ordinaryCandidates = unresolved.filter((item) => item?.reason !== 'conflict');
@@ -310,7 +429,7 @@ export function runVaultHealth({ vaultBase, session = '' }) {
   ];
   let memory = { status: 'legacy', metrics: {} };
   if (memoryMarkers.some((path) => existsSync(path))) {
-    memory = checkMemoryBundle(vaultBase);
+    memory = checkMemoryBundle(vaultBase, { registry });
     failures.push(...memory.failures.map((item) => `Memória: ${item}`));
     warnings.push(...memory.warnings.map((item) => `Memória: ${item}`));
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.58.0",
+  "version": "0.58.3",
   "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": {
@@ -12,6 +12,8 @@
     "src",
     "hooks",
     "schema",
+    "docs/pt-BR/commands/*.md",
+    "docs/en/commands/*.md",
     "README.md",
     "README.en.md",
     "CHANGELOG.md"

package/src/memory.mjs

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
 import {
-  copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync,
+  copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync,
 } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { sanitizeMemoryText, renderSharedMemory, validateSharedMemory } from '../hooks/memory-schema.mjs';
 import {
   enqueueMemoryEvent, projectMemoryOutbox, repairMemoryLedger,
@@ -75,7 +75,11 @@ export function memoryStatus(vault) {
   return checkMemoryBundle(vault);
 }
 
-export function migrateMemory(vault, { apply = false, validateBundle = validateMemoryBundle } = {}) {
+export function migrateMemory(vault, {
+  apply = false,
+  validateBundle = validateMemoryBundle,
+  publishArtifact = writeFileAtomic,
+} = {}) {
   projectId(vault);
   const sharedPath = brainPath(vault, SHARED);
   const hadShared = existsSync(sharedPath);
@@ -95,16 +99,37 @@ export function migrateMemory(vault, { apply = false, validateBundle = validateM
   const sharedValidation = validateSharedMemory(emptyShared, { eventIds: new Set() });
   if (!sharedValidation.ok) throw new Error(`Migração inválida: ${sharedValidation.errors.join(' ')}`);
   if (backupPath && !existsSync(backupPath)) copyFileSync(sharedPath, backupPath);
+
+  // Build and validate a complete candidate vault away from the live paths. This makes
+  // the validation callback incapable of observing a half-published live bundle.
+  const stagingVault = mkdtempSync(join(dirname(vault), '.wendkeep-memory-stage-'));
+  const stagingBrain = join(stagingVault, BRAIN);
+  let stagedValidation;
+  try {
+    mkdirSync(stagingBrain, { recursive: true });
+    copyFileSync(brainPath(vault, 'CORE.md'), join(stagingBrain, 'CORE.md'));
+    copyFileSync(brainPath(vault, 'PROJECT.json'), join(stagingBrain, 'PROJECT.json'));
+    writeFileSync(join(stagingBrain, LEDGER), '', 'utf8');
+    writeFileSync(join(stagingBrain, SHARED), emptyShared, 'utf8');
+    writeFileSync(join(stagingBrain, CANDIDATES), candidateText(candidates), 'utf8');
+    stagedValidation = validateBundle(stagingVault);
+    if (!stagedValidation.ok) {
+      throw new Error(`Bundle migrado inválido: ${(stagedValidation.errors || []).join(' ')}`);
+    }
+  } finally {
+    rmSync(stagingVault, { recursive: true, force: true });
+  }
+
   const targets = [LEDGER, SHARED, CANDIDATES].map((name) => brainPath(vault, name));
   const before = new Map(targets.map((path) => [path, {
     existed: existsSync(path),
     content: existsSync(path) ? readFileSync(path, 'utf8') : '',
   }]));
   try {
-    if (!existsSync(brainPath(vault, LEDGER))) writeFileAtomic(brainPath(vault, LEDGER), '');
-    writeFileAtomic(sharedPath, emptyShared);
-    writeFileAtomic(brainPath(vault, CANDIDATES), candidateText(candidates));
-    const validation = validateBundle(vault);
+    if (!existsSync(brainPath(vault, LEDGER))) publishArtifact(brainPath(vault, LEDGER), '');
+    publishArtifact(sharedPath, emptyShared);
+    publishArtifact(brainPath(vault, CANDIDATES), candidateText(candidates));
+    const validation = validateMemoryBundle(vault);
     if (!validation.ok) throw new Error(`Bundle migrado inválido: ${validation.errors.join(' ')}`);
     return { status: 'migrated', alreadyV2: false, candidates: candidates.length, backupPath, validation };
   } catch (error) {

package/src/taxonomy.mjs

@@ -37,6 +37,7 @@ export const HOOK_FILES = [
   'memory-schema.mjs',
   'memory-store.mjs',
   'memory-handoff.mjs',
+  'session-memory-lifecycle.mjs',
   'change-core.mjs',
   'spec-core.mjs',
   'sensors-core.mjs',