wendkeep 0.58.3 → 0.59.0

package/hooks/obsidian-common.mjs

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
-import { releaseLockDir } from './session-note-io.mjs';
+import { LOCK_BUSY, mutateSessionNote, withPathLock } from './session-note-io.mjs';
 import { basename, dirname, join, relative } from 'path';
 import { getLocale } from './locale.mjs';
 import { resolveProjectVault } from '../src/project-vault.mjs';
+import {
+  assertVaultPathSafe, mkdirVaultPath, writeVaultFileAtomic,
+} from './vault-path-safety.mjs';
 
 // Deprecated export kept for consumers that imported it before 0.39.0. Automatic
 // hooks never use this fallback: an unbound project fails closed.
@@ -212,9 +215,12 @@ export function yamlQuote(value = '') {
 
 export function readControl(vaultBase) {
   const path = controlPath(vaultBase);
-  if (!existsSync(path)) return {};
+  const checked = assertVaultPathSafe(vaultBase, path, {
+    expectedType: 'file', label: 'CURRENT_SESSION.md',
+  });
+  if (!checked.exists) return {};
 
-  const content = readFileSync(path, 'utf-8');
+  const content = readFileSync(checked.target, 'utf-8');
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) return {};
 
@@ -228,7 +234,10 @@ export function readControl(vaultBase) {
 
 export function writeControl(vaultBase, data) {
   const path = controlPath(vaultBase);
-  ensureDir(dirname(path));
+  mkdirVaultPath(vaultBase, dirname(path), { label: 'diretório do CURRENT_SESSION' });
+  assertVaultPathSafe(vaultBase, path, {
+    expectedType: 'file', label: 'CURRENT_SESSION.md',
+  });
 
   const status = data.status || 'inactive';
   const sessionFile = data.session_file || '';
@@ -275,15 +284,20 @@ ${activeRows}
 Regra crítica: sempre anexar conteúdo à sessão ativa. Nunca sobrescrever o histórico de iterações.
 `;
 
-  writeFileSync(path, content, 'utf-8');
+  writeVaultFileAtomic(vaultBase, path, content, 'utf-8', {
+    label: 'CURRENT_SESSION.md',
+  });
 }
 
 export function readSessionRegistry(vaultBase) {
   const path = registryPath(vaultBase);
-  if (!existsSync(path)) return { version: 2, sessions: {} };
+  const checked = assertVaultPathSafe(vaultBase, path, {
+    expectedType: 'file', label: 'SESSION_REGISTRY.json',
+  });
+  if (!checked.exists) return { version: 2, sessions: {} };
 
   try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    const parsed = JSON.parse(readFileSync(checked.target, 'utf-8'));
     return {
       version: Math.max(2, parsed.version || 1),
       sessions: parsed.sessions && typeof parsed.sessions === 'object' ? parsed.sessions : {},
@@ -295,48 +309,18 @@ export function readSessionRegistry(vaultBase) {
 
 export function writeSessionRegistry(vaultBase, registry) {
   const path = registryPath(vaultBase);
-  ensureDir(dirname(path));
+  mkdirVaultPath(vaultBase, dirname(path), { label: 'diretório do SESSION_REGISTRY' });
   // Escrita atômica: grava em tmp e renomeia (rename é atômico no mesmo volume),
   // evitando registry truncado/corrompido quando dois hooks gravam ao mesmo tempo.
-  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf-8');
-  renameSync(tmp, path);
-}
-
-function registryLockPath(vaultBase) {
-  return `${registryPath(vaultBase)}.lock`;
-}
-
-function waitBriefly(ms) {
-  const signal = new Int32Array(new SharedArrayBuffer(4));
-  Atomics.wait(signal, 0, 0, ms);
+  writeVaultFileAtomic(vaultBase, path, `${JSON.stringify(registry, null, 2)}\n`, 'utf-8', {
+    label: 'SESSION_REGISTRY.json',
+  });
 }
 
 export function mutateSessionRegistry(vaultBase, mutator, { timeoutMs = 2000 } = {}) {
-  const lock = registryLockPath(vaultBase);
-  ensureDir(dirname(lock));
-  const deadline = Date.now() + timeoutMs;
-  while (true) {
-    try {
-      mkdirSync(lock);
-      break;
-    } catch (error) {
-      if (error?.code === 'EEXIST') {
-        try {
-          if (Date.now() - statSync(lock).mtimeMs > 10_000) {
-            releaseLockDir(lock);
-            continue;
-          }
-        } catch { /* outro processo pode ter liberado o lock */ }
-      }
-      if (error?.code !== 'EEXIST' || Date.now() >= deadline) {
-        throw new Error(`SESSION_REGISTRY lock indisponível: ${error.message}`);
-      }
-      waitBriefly(10);
-    }
-  }
-
-  try {
+  const path = registryPath(vaultBase);
+  mkdirVaultPath(vaultBase, dirname(path), { label: 'diretório do SESSION_REGISTRY' });
+  const outcome = withPathLock(path, () => {
     const registry = readSessionRegistry(vaultBase);
     const before = JSON.stringify(registry);
     registry.version = 2;
@@ -345,11 +329,11 @@ export function mutateSessionRegistry(vaultBase, mutator, { timeoutMs = 2000 } =
       writeSessionRegistry(vaultBase, registry);
     }
     return result;
-  } finally {
-    // 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);
+  }, { timeoutMs, vaultBase });
+  if (outcome === LOCK_BUSY) {
+    throw new Error('SESSION_REGISTRY lock indisponível: lock ocupado até o timeout.');
   }
+  return outcome;
 }
 
 function meaningfulPatch(patch = {}) {
@@ -756,13 +740,13 @@ export function sweepStaleSessionsFile(vaultBase, now = new Date(), maxIdleMs =
 // já fechada com o mesmo `endedAt`). Devolve true se gravou.
 export function closeSessionNoteFile(vaultBase, sessionFileRel, endedAt) {
   if (!sessionFileRel) return false;
-  const path = join(vaultBase, sessionFileRel);
-  if (!existsSync(path)) return false;
-  const content = readFileSync(path, 'utf-8');
-  const next = closeSessionNote(content, endedAt);
-  if (next === content) return false;
-  writeFileSync(path, next, 'utf-8');
-  return true;
+  const checked = assertVaultPathSafe(vaultBase, join(vaultBase, sessionFileRel), {
+    expectedType: 'file', label: 'nota de sessão encerrada',
+  });
+  if (!checked.exists) return false;
+  return mutateSessionNote(checked.target, (content) => closeSessionNote(content, endedAt), {
+    vaultBase,
+  }).written;
 }
 
 // Marca de sessão ainda aberta no corpo da nota (template do hook de início).

package/hooks/operating-profile-runtime.mjs

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  DEFAULT_OPERATING_PROFILE,
+  normalizeOperatingProfile,
+  operatingProfilePolicy,
+  resolveOperatingProfile,
+} from '../src/operating-profile.mjs';
+import { findProjectBinding, resolveProjectVault } from '../src/project-vault.mjs';
+import { readSessionRegistry } from './obsidian-common.mjs';
+import { resolveSessionIdentity } from './session-identity.mjs';
+
+function bindingDiagnostic(error, configPath = '') {
+  return {
+    code: error?.code || 'WENDKEEP_VAULT_CONFIG_INVALID',
+    message: error?.message
+      || `Configuração WendKeep inválida${configPath ? ` em "${configPath}"` : ''}.`,
+  };
+}
+
+function readResolvedConfig(resolution, suppliedConfig) {
+  if (suppliedConfig && typeof suppliedConfig === 'object' && !Array.isArray(suppliedConfig)) {
+    return { config: suppliedConfig, bindingError: null };
+  }
+  if (resolution?.config && typeof resolution.config === 'object' && !Array.isArray(resolution.config)) {
+    return { config: resolution.config, bindingError: null };
+  }
+  if (!resolution?.configPath || !existsSync(resolution.configPath)) {
+    return { config: {}, bindingError: null };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(resolution.configPath, 'utf8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return { config: parsed, bindingError: null };
+    }
+    return {
+      config: {},
+      bindingError: bindingDiagnostic(null, resolution.configPath),
+    };
+  } catch (error) {
+    return {
+      config: {},
+      bindingError: bindingDiagnostic(error, resolution.configPath),
+    };
+  }
+}
+
+function sessionOverride(entry) {
+  if (!entry || !Object.prototype.hasOwnProperty.call(entry, 'operating_profile')) return null;
+  const raw = entry.operating_profile;
+  try {
+    return {
+      profile: normalizeOperatingProfile(raw, { strict: true }),
+      source: 'session-override',
+      valid: true,
+      configured: true,
+      raw,
+    };
+  } catch {
+    return {
+      profile: DEFAULT_OPERATING_PROFILE,
+      source: 'session-override-invalid',
+      valid: false,
+      configured: true,
+      raw,
+    };
+  }
+}
+
+function canonicalPath(value) {
+  const path = resolve(value).replaceAll('\\', '/');
+  return process.platform === 'win32' ? path.toLowerCase() : path;
+}
+
+function matchingProjectBinding(vaultResolution, input) {
+  if (vaultResolution?.config) {
+    return { binding: null, bindingError: vaultResolution.bindingError || null };
+  }
+  if (vaultResolution?.bindingError) {
+    return { binding: null, bindingError: vaultResolution.bindingError };
+  }
+  const start = input?.cwd
+    || input?.project_dir
+    || input?.projectDir
+    || input?.workspace?.cwd
+    || vaultResolution?.projectRoot
+    || process.cwd();
+  try {
+    const binding = findProjectBinding(start);
+    return {
+      binding: binding && canonicalPath(binding.base) === canonicalPath(vaultResolution.base)
+        ? binding
+        : null,
+      bindingError: vaultResolution.bindingError || null,
+    };
+  } catch (error) {
+    // An explicitly supplied vault is authoritative even when an unrelated
+    // nearby project config is malformed, but corruption remains observable.
+    if (input?.obsidian_vault_path
+      || ['explicit', 'payload', 'legacy-project-settings'].includes(vaultResolution?.source)) {
+      return { binding: null, bindingError: bindingDiagnostic(error) };
+    }
+    throw error;
+  }
+}
+
+// Resolution precedence for hooks: explicit session override -> project binding -> GOVERN.
+// Binding corruption is never interpreted as OFF: an authoritative Vault keeps the Keep Core
+// alive under GOVERN and carries a visible diagnostic to each entrypoint.
+export function resolveHookOperatingProfile({
+  input = {},
+  resolution = null,
+  config = null,
+  provider,
+} = {}) {
+  const initialResolution = resolution || resolveProjectVault({ input });
+  const matched = matchingProjectBinding(initialResolution, input);
+  const binding = matched.binding;
+  const vaultResolution = binding ? {
+    ...initialResolution,
+    projectRoot: binding.projectRoot,
+    projectId: binding.config.projectId,
+    configPath: binding.configPath,
+    config: binding.config,
+  } : initialResolution;
+  const configState = readResolvedConfig(vaultResolution, config);
+  const bindingError = initialResolution.bindingError
+    || matched.bindingError
+    || configState.bindingError
+    || null;
+  const project = resolveOperatingProfile(bindingError ? {} : configState.config);
+  const identity = resolveSessionIdentity(vaultResolution.base, input, provider);
+  const entry = identity.state === 'resolved'
+    ? readSessionRegistry(vaultResolution.base).sessions?.[identity.canonicalConversationId] || null
+    : null;
+  const selected = sessionOverride(entry) || project;
+  return {
+    ...selected,
+    policy: operatingProfilePolicy(selected.profile),
+    vaultBase: vaultResolution.base,
+    projectRoot: vaultResolution.projectRoot,
+    identity,
+    entry,
+    resolution: vaultResolution,
+    ...(bindingError ? { bindingError } : {}),
+  };
+}
+
+export function hookProfilePolicy(profile = DEFAULT_OPERATING_PROFILE) {
+  return operatingProfilePolicy(profile);
+}
+
+// Prefix the profile so change-core's 64-char filename cap can never truncate it away.
+export function profileSentinelId(sessionId, profile = DEFAULT_OPERATING_PROFILE) {
+  return `${normalizeOperatingProfile(profile).toLowerCase()}--${sessionId || 'nosession'}`;
+}

package/hooks/plan-capture.mjs

@@ -9,7 +9,6 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
   formatDate,
-  getVaultBase,
   readHookInput,
   slugify,
   upsertSessionRegistry,
@@ -18,6 +17,7 @@ import {
 } from './obsidian-common.mjs';
 import { activeChange, newChange } from './change-core.mjs';
 import { getLocale } from './locale.mjs';
+import { hookProfilePolicy, resolveHookOperatingProfile } from './operating-profile-runtime.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
 
 // O plano aprovado chega por um de três canais, conforme a versão do Claude Code:
@@ -87,7 +87,9 @@ export function planTasks(plan) {
   return boxes.map((m, i) => `- [${m[1]}] 1.${i + 1} ${m[2].trim()}`);
 }
 
-export function capturePlan(vaultBase, input) {
+export function capturePlan(vaultBase, input, { profile = 'GOVERN' } = {}) {
+  const policy = hookProfilePolicy(profile);
+  if (!policy.harness) return null;
   const plan = extractPlan(input);
   if (!plan) return null;
   const loc = getLocale(vaultBase);
@@ -111,6 +113,10 @@ export function capturePlan(vaultBase, input) {
     };
   }
 
+  // FLOW deliberately has no implicit change lifecycle. It may enrich a change the user
+  // explicitly opened, but an approved plan alone must not create one.
+  if (!policy.requiresChange) return null;
+
   const slug = planSlug(plan);
   newChange(vaultBase, slug, { dateStr, sessionRel });
   upsertSessionRegistry(vaultBase, identity.canonicalConversationId, { change_slug: slug });
@@ -156,7 +162,12 @@ ${en ? 'See design.md and plano-aprovado.md (captured from the approved plan-mod
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const input = readHookInput();
-    const r = capturePlan(getVaultBase(input), input);
+    const runtime = resolveHookOperatingProfile({ input });
+    if (runtime.bindingError) {
+      const code = runtime.bindingError.code || 'WENDKEEP_VAULT_CONFIG_INVALID';
+      throw new Error(`${code}: ${runtime.bindingError.message || 'binding WendKeep inválido'}`);
+    }
+    const r = capturePlan(runtime.vaultBase, input, { profile: runtime.profile });
     if (!r) { writeHookOutput({}); }
     else writeHookOutput({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: r.context } });
   } catch (error) {

package/hooks/sensors-core.mjs

@@ -5,6 +5,16 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
+export const SENSOR_VAULT_ENV = 'WENDKEEP_SENSOR_VAULT';
+
+export function sensorProcessEnv(vaultBase, inherited = process.env) {
+  return {
+    ...inherited,
+    OBSIDIAN_VAULT_PATH: vaultBase,
+    [SENSOR_VAULT_ENV]: vaultBase,
+  };
+}
+
 export function loadSensors(projectRoot, file = 'wendkeep.sensors.json') {
   return loadSensorsDetailed(projectRoot, file).sensors;
 }
@@ -37,17 +47,19 @@ export function findProjectRoot(startDir) {
 }
 
 export function requiredSensors(tasks) {
-  return [...new Set((tasks || []).map((t) => t.sensor).filter(Boolean))];
+  return [...new Set((tasks || []).flatMap((task) => (
+    Array.isArray(task.sensors) && task.sensors.length ? task.sensors : [task.sensor]
+  )).filter(Boolean))];
 }
 
-export function runSensors(sensors, ids, { spawn = spawnSync, cwd, now } = {}) {
+export function runSensors(sensors, ids, { spawn = spawnSync, cwd, env, now } = {}) {
   const byId = Object.fromEntries((sensors || []).map((s) => [s.id, s]));
   const ts = now || new Date().toISOString();
   const evidence = [];
   for (const id of ids) {
     const s = byId[id];
     if (!s) { evidence.push({ id, status: 'red', ts, severity: 'critical', note: 'sensor não definido' }); continue; }
-    const r = spawn(s.command, [], { cwd, shell: true, stdio: 'ignore' });
+    const r = spawn(s.command, [], { cwd, shell: true, stdio: 'ignore', ...(env ? { env } : {}) });
     const entry = { id, status: (r.status ?? 1) === 0 ? 'green' : 'red', ts, severity: s.severity || 'critical' };
     if (s.type === 'mutation' && s.report) {
       // Delegated mutation (Wave B): read the tool's mutation-testing-elements report and

package/hooks/session-backfill.mjs

@@ -12,6 +12,7 @@ import {
   readControl,
   readSessionRegistry,
 } from './obsidian-common.mjs';
+import { assertVaultPathSafe } from './vault-path-safety.mjs';
 
 function parseArgs(argv) {
   const args = { write: false, limit: 0, session: '' };
@@ -71,8 +72,11 @@ export function backfillSessions({ vaultBase, write = false, limit = 0, session
     if (args.limit && report.scanned >= args.limit) break;
     report.scanned += 1;
 
-    const sessionPath = join(vaultBase, entry.session_file);
-    if (!existsSync(sessionPath) || !existsSync(entry.transcript_path)) {
+    const checkedSession = assertVaultPathSafe(vaultBase, join(vaultBase, entry.session_file), {
+      expectedType: 'file', label: 'nota de sessão do backfill',
+    });
+    const sessionPath = checkedSession.target;
+    if (!checkedSession.exists || !existsSync(entry.transcript_path)) {
       report.missing.push({
         session: entry.session_file,
         sessionExists: existsSync(sessionPath),
@@ -106,6 +110,7 @@ export function backfillSessions({ vaultBase, write = false, limit = 0, session
           buildIterationBlock(tx, { turn_id: turn.turnId, now: turn.timestamp }),
           turn.turnId,
           tx,
+          vaultBase,
         );
         if (inserted) {
           report.inserted += 1;

package/hooks/session-ensure.mjs

@@ -214,7 +214,7 @@ function maybeRetitleSession({ vaultBase, relPath, startedAt, input }) {
   const sessionPath = join(vaultBase, nextRelPath);
   const outcome = mutateSessionNote(sessionPath, (content) => (
     updateSessionDescription(content, { relPath: nextRelPath, summary, startedAt })
-  ));
+  ), { vaultBase });
 
   return { relPath: nextRelPath, summary, changed: nextRelPath !== relPath || outcome.written };
 }
@@ -226,8 +226,10 @@ function stripClosingSection(content) {
   return `${content.slice(0, index).trimEnd()}\n`;
 }
 
-function reopenSessionFile(sessionPath) {
-  mutateSessionNote(sessionPath, (content) => stripClosingSection(updateSessionFrontmatter(content)));
+function reopenSessionFile(vaultBase, sessionPath) {
+  mutateSessionNote(sessionPath, (content) => stripClosingSection(updateSessionFrontmatter(content)), {
+    vaultBase,
+  });
 }
 
 function findSessionForInput(vaultBase, input, control) {
@@ -260,7 +262,7 @@ function activateExistingSession({ vaultBase, relPath, startedAt, sessionId, inp
   const sessionPath = join(vaultBase, relPath);
   if (!existsSync(sessionPath)) return false;
 
-  reopenSessionFile(sessionPath);
+  reopenSessionFile(vaultBase, sessionPath);
   const nextStartedAt = startedAt || formatLocalIso(now);
   writeControl(vaultBase, {
     status: 'active',

package/hooks/session-iteration.mjs

@@ -0,0 +1,65 @@
+import { hasTurnMarker, normalizeTurnMarkers, turnMarker } from './obsidian-common.mjs';
+import { hasSessionFrontmatter, mutateSessionNote } from './session-note-io.mjs';
+
+const ITERATION_ANCHORS = [
+  '\n## Agentes, tokens e custos',
+  '\n## Uso de tokens e custos',
+  '\n## Decisões geradas nesta sessão',
+  '\n## Bugs gerados nesta sessão',
+  '\n## Aprendizados gerados nesta sessão',
+  '\n## Arquivos consultados',
+  '\n## Arquivos criados ou alterados',
+  '\n## Pendências',
+  '\n## Encerramento',
+];
+
+export function insertIterationContent(original, { markerId, block }) {
+  if (!markerId) throw new TypeError('markerId é obrigatório');
+  let content = normalizeTurnMarkers(String(original || ''));
+  if (hasTurnMarker(content, markerId)) return { content, inserted: false };
+
+  const rendered = `\n${String(block || '').trim()}\n${turnMarker(markerId)}\n`;
+  const iterations = content.indexOf('\n## Iterações');
+  if (iterations !== -1) {
+    const anchors = ITERATION_ANCHORS
+      .map((anchor) => content.indexOf(anchor, iterations + 1))
+      .filter((index) => index !== -1)
+      .sort((left, right) => left - right);
+    if (anchors.length) {
+      const at = anchors[0];
+      content = `${content.slice(0, at).trimEnd()}\n${rendered}\n${content.slice(at).replace(/^\n+/, '')}`;
+    } else {
+      const lineEnd = content.indexOf('\n', iterations + 1);
+      const at = lineEnd === -1 ? content.length : lineEnd + 1;
+      content = `${content.slice(0, at).trimEnd()}\n${rendered}\n${content.slice(at).replace(/^\n+/, '')}`;
+    }
+    return { content, inserted: true };
+  }
+
+  const closing = content.indexOf('\n## Encerramento');
+  if (closing !== -1) {
+    content = `${content.slice(0, closing).trimEnd()}\n\n## Iterações\n${rendered}\n${content.slice(closing).replace(/^\n+/, '')}`;
+  } else {
+    content = `${content.trimEnd()}\n\n## Iterações\n${rendered}`;
+  }
+  return { content, inserted: true };
+}
+
+export function projectSessionIteration(sessionPath, input, options = {}) {
+  let inserted = false;
+  let invalidFrontmatter = false;
+  const outcome = mutateSessionNote(sessionPath, (content) => {
+    if (!hasSessionFrontmatter(content)) {
+      invalidFrontmatter = true;
+      return null;
+    }
+    const result = insertIterationContent(content, input);
+    inserted = result.inserted;
+    return result.content;
+  }, options);
+  return {
+    inserted,
+    written: outcome.written,
+    reason: invalidFrontmatter ? 'invalid-frontmatter' : outcome.reason,
+  };
+}

package/hooks/session-memory-lifecycle.mjs

@@ -246,11 +246,16 @@ export function projectStopMemoryAttempt(vaultBase, attempt, overrides = {}) {
       });
     }
     return outcome(attempt, 'projected', {
-      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.ledgerCursor || projection.eventCursor,
+          state_hash: projection.stateHash,
+          ...(projection.ledgerCursor && projection.eventCursor !== projection.ledgerCursor
+            ? { causal_event_cursor: projection.eventCursor }
+            : {}),
+        },
     });
   } catch (error) {
     return outcome(attempt, 'degraded', {