wendkeep 0.58.1 → 0.58.3

package/hooks/session-stop.mjs

@@ -16,6 +16,11 @@ 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 {
+  projectStopMemoryAttempt,
+  recordStopMemoryOutcome,
+  stageStopMemoryAttempt,
+} from './session-memory-lifecycle.mjs';
 import {
   ensureDir,
   findActiveSessionByTranscript,
@@ -527,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')
@@ -1095,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({});
@@ -1132,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, {
@@ -1152,6 +1207,7 @@ function main() {
       const cas = applyStopActivation(registry, {
         session_id: sessionId,
         activation_id: activationId,
+        turn_id: turnId,
         turn_sequence: stopTurnSequence,
         ended_at: endedAt,
       });
@@ -1176,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;
@@ -1252,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

@@ -121,27 +121,117 @@ 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') {
@@ -207,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');
@@ -332,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.1",
+  "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/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',