wendkeep 0.26.0 → 0.28.1

package/CHANGELOG.md

@@ -4,6 +4,65 @@ 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.28.1] — 2026-07-09
+
+Startup-contention fixes — root-caused from a real VSCode startup log where the memory injection
+silently dropped and MCPs timed out.
+
+### Fixed
+- **`brain-inject` timeout 15 → 45s.** The hook is healthy (~2.5s direct, ~4s via npx warm), but
+  Windows session startup runs several `npx` cold-starts at once (a sibling MCP took **26s** in the
+  log) and 15s silently killed the CORE+DIGEST injection for the whole session.
+- **context-mode double-registration eliminated.** Its plugin ships its **own** MCP server; wiring
+  an `.mcp.json` entry too registered it twice — two concurrent `npx context-mode` cold-starts,
+  both timing out. The companion is now **plugin-only** (on non-Claude agents add the MCP manually:
+  `npx -y context-mode`).
+- **`MCP_TIMEOUT=60000` default** added to the settings `env` by init (only when absent — a user
+  value is never clobbered), giving npx-launched stdio MCPs (wendkeep-vault included) headroom over
+  Claude Code's 30s default.
+
+### Upgrade
+- Existing installs: re-run `wendkeep init` (now recognizes your vault) to pick up the timeout +
+  `MCP_TIMEOUT`; remove a duplicated `context-mode` entry from `.mcp.json`/`enabledMcpjsonServers`
+  by hand if present.
+
+## [0.28.0] — 2026-07-09
+
+Three new hooks: decisions, subagents, plan progress.
+
+### Added
+- **Decision capture** (`PostToolUse` / `AskUserQuestion` → `hooks/decision-capture.mjs`): when the
+  agent asks the user to choose between options, the decision is recorded in `04-Decisões/` — the
+  question, **every** option (label + description), the user's choice (✅), and a wikilink to the
+  session. Explicit, high-signal decisions get full traceability in the graph. Shape validated
+  against real transcripts.
+- **Live subagent telemetry** (`SubagentStop` → `hooks/subagent-stop.mjs`): refreshes the session's
+  subagent/workflow cost notes the moment each subagent finishes (reuses `upsertSubagentUsage`), so
+  a session that never reaches `Stop` still has its telemetry. *Model choice stays the harness's
+  job — wendkeep observes, it does not impose a routing rule.*
+- **Plan progress log** (`TaskCompleted` → `hooks/task-log.mjs`): when a task is marked complete,
+  appends it to a durable `## Progresso do plano` section in the active session note (before
+  `## Encerramento`, so reopen can't strip it). A progress trail, not a fuzzy map to `tarefas.md`.
+
+All three are wired by `wendkeep init`, are fail-open, and localize (pt-BR / en). `--force`-free —
+they only read + append.
+
+## [0.27.0] — 2026-07-08
+
+### Fixed
+- **Re-running `wendkeep init` no longer re-asks for the vault (or language) — and can't split your
+  data.** On a project already set up, init now reads the registered vault from
+  `.claude/settings.json` (`OBSIDIAN_VAULT_PATH`) and the locked locale from the vault's
+  `.brain/config.json`, reuses both, and skips the prompts. Previously a re-run (e.g. after
+  `npm i -D wendkeep@latest`) offered the *derived* default (`.<project>-vault`); accepting it — or
+  mistyping the name — created a **second, divergent vault**. `--vault` / `--locale` still override.
+  New exported `detectRegisteredVault()` / `readVaultLocale()`. `src/init.mjs`.
+
+### Note
+- You do **not** need `wendkeep init` for a routine update: the hooks live in the package
+  (`settings.json` calls `npx wendkeep hook …`), so `npm i -D wendkeep@latest` updates them.
+  Re-run `init` only when a release adds new wiring (the CHANGELOG says so); it's idempotent.
+
 ## [0.26.0] — 2026-07-08
 
 ### Fixed

package/hooks/decision-capture.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// PostToolUse hook (matcher: AskUserQuestion). When the agent asks the user to choose between
+// options, this records the decision — the question, EVERY option (label + description), and the
+// user's choice — as a note in 04-Decisões, wikilinked to the session. Explicit, high-signal
+// decisions get full traceability in the graph (better than heuristic extraction). Fail-open.
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import {
+  readHookInput, writeHookOutput, getVaultBase, providerMeta, ensureDir, formatDate,
+  formatLocalIso, monthFolderRelFromDateStr, slugify, findActiveSessionByTranscript,
+  wikilinkFromRel, readControl, toVaultRelative,
+} from './obsidian-common.mjs';
+import { getLocale } from './locale.mjs';
+
+// The AskUserQuestion tool_output reads: `... "Question"="chosen labels"  "Q2"="..."`.
+export function parseAnswers(output) {
+  const map = {};
+  const re = /"([^"]+)"\s*=\s*"([^"]*)"/g;
+  let m;
+  while ((m = re.exec(String(output || '')))) map[m[1].trim()] = m[2].trim();
+  return map;
+}
+
+const clean = (s) => String(s || '').replace(/\r/g, '').replace(/\n{3,}/g, '\n\n').trim();
+
+// Render the decision note from an AskUserQuestion tool call.
+export function buildDecisionCaptureNote({ questions, answers, dateStr, startedAt, sessionRel, provider, localeId }) {
+  const en = localeId === 'en';
+  const src = sessionRel ? `\n  - "${wikilinkFromRel(sessionRel)}"` : ' []';
+  const title = clean(questions[0]?.question || (en ? 'User decision' : 'Decisão do usuário')).slice(0, 90);
+
+  const blocks = questions.map((q) => {
+    const chosen = (answers[clean(q.question)] || '').split(',').map((s) => s.trim()).filter(Boolean);
+    const isChosen = (label) => chosen.some((c) => c === label.trim() || c.includes(label.trim()) || label.trim().includes(c));
+    const opts = (q.options || [])
+      .map((o) => `| ${isChosen(o.label) ? '✅' : ''} | ${clean(o.label)} | ${clean(o.description).slice(0, 200)} |`)
+      .join('\n');
+    return `### ${clean(q.question)}
+${q.multiSelect ? (en ? '_(multiple choice)_' : '_(múltipla escolha)_') : ''}
+
+| | ${en ? 'Option' : 'Opção'} | ${en ? 'Description' : 'Descrição'} |
+|---|---|---|
+${opts || `| | — | — |`}
+
+**${en ? 'Chosen' : 'Escolhido'}:** ${chosen.length ? chosen.map((c) => `\`${c}\``).join(', ') : (en ? '(not recorded)' : '(não registrado)')}`;
+  }).join('\n\n');
+
+  return `---
+type: decision
+subtype: user-choice
+date: ${dateStr}
+started_at: ${startedAt}
+provider: ${provider.id}
+cssclasses:
+  - topic-decision
+tags:
+  - decisao
+  - escolha-usuario
+source:${src}
+---
+
+# ${title}
+
+> ${en ? 'Decision captured from an interactive question (options + the user\'s choice).' : 'Decisão capturada de uma pergunta interativa (opções + a escolha do usuário).'}
+
+${blocks}
+`;
+}
+
+export function captureDecision(vaultBase, input) {
+  const toolIn = input.tool_input || input.toolInput || {};
+  const questions = Array.isArray(toolIn.questions) ? toolIn.questions : [];
+  if (!questions.length) return null;
+
+  const answers = parseAnswers(input.tool_output ?? input.toolOutput ?? input.tool_response ?? '');
+  const loc = getLocale(vaultBase);
+  const now = new Date();
+  const dateStr = formatDate(now);
+  const provider = providerMeta(input.provider);
+
+  const matched = input.transcript_path ? findActiveSessionByTranscript(vaultBase, input.transcript_path) : null;
+  const sessionRel = matched?.session_file || readControl(vaultBase).session_file || '';
+
+  const dir = join(vaultBase, monthFolderRelFromDateStr(loc.folders.decisions, dateStr, vaultBase));
+  ensureDir(dir);
+  const slug = slugify(questions[0]?.question || 'decisao', 'decisao', 50);
+  const filePath = join(dir, `${dateStr}-escolha-${slug}.md`);
+  if (existsSync(filePath)) return { rel: toVaultRelative(vaultBase, filePath), skipped: true };
+
+  writeFileSync(filePath, buildDecisionCaptureNote({
+    questions, answers, dateStr, startedAt: formatLocalIso(now), sessionRel, provider, localeId: loc.id,
+  }), 'utf-8');
+  return { rel: toVaultRelative(vaultBase, filePath), skipped: false };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    if ((input.tool_name || input.toolName) === 'AskUserQuestion') {
+      captureDecision(getVaultBase(input), input);
+    }
+    writeHookOutput({});
+  } catch (error) {
+    process.stderr.write(`[wendkeep] decision-capture falhou: ${error.message}\n`);
+    writeHookOutput({});
+  }
+}

package/hooks/subagent-stop.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// SubagentStop hook: refresh this session's subagent/workflow telemetry the MOMENT a subagent
+// finishes — not only at the main Stop. Resilience: a session that never reaches Stop (crash,
+// window closed) still gets its subagent cost notes. Reuses the same upsertSubagentUsage the Stop
+// hook runs, so the output is identical; it just runs earlier + incrementally. Fail-open.
+//
+// Model choice for subagents stays the harness's job (agent frontmatter `model:` / the Task/
+// workflow `model` param). wendkeep OBSERVES (this telemetry) rather than dictating a routing rule.
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { readHookInput, writeHookOutput, getVaultBase, findActiveSessionByTranscript, readControl } from './obsidian-common.mjs';
+import { upsertSubagentUsage } from './subagent-usage.mjs';
+
+export function refreshSubagents(vaultBase, input) {
+  const transcriptPath = input.transcript_path || input.transcriptPath || '';
+  const matched = transcriptPath ? findActiveSessionByTranscript(vaultBase, transcriptPath) : null;
+  const sessionRel = matched?.session_file || readControl(vaultBase).session_file || '';
+  if (!sessionRel) return false;
+  const sessionPath = join(vaultBase, sessionRel);
+  if (!existsSync(sessionPath)) return false;
+  upsertSubagentUsage(sessionPath, transcriptPath);
+  return true;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    refreshSubagents(getVaultBase(input), input);
+    writeHookOutput({});
+  } catch (error) {
+    process.stderr.write(`[wendkeep] subagent-stop falhou: ${error.message}\n`);
+    writeHookOutput({});
+  }
+}

package/hooks/task-log.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// TaskCompleted hook: log plan/task progress into the active session note, so the session records
+// what the plan actually advanced through. It writes a durable "## Progresso do plano" section
+// placed BEFORE ## Encerramento (survives the reopen/strip cycle) and does NOT try to map to a
+// change's tarefas.md N.N (id-spaces differ, fuzzy) — it's a progress trail, not a task tracker.
+// The TaskCompleted payload shape isn't fully pinned, so the task text is pulled defensively from
+// any plausible field. Fail-open.
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { readHookInput, writeHookOutput, getVaultBase, findActiveSessionByTranscript, readControl, formatHourMinute } from './obsidian-common.mjs';
+import { getLocale } from './locale.mjs';
+
+// Pull the task's human text from whatever field the payload carries.
+export function taskText(input) {
+  const t = input.task || input.tool_input || input.payload || input;
+  const cand = t?.content || t?.text || t?.description || t?.title || t?.subject || t?.name
+    || t?.prompt || input.content || input.text || input.description || '';
+  return String(cand || '').replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 160);
+}
+
+// Append `line` at the END of a "## <heading>" section placed before ## Encerramento, so entries
+// read chronologically. Deduped. Pure.
+export function appendProgress(content, line, heading) {
+  if (content.includes(line)) return content; // dedup
+  const marker = `\n## ${heading}\n`;
+  const at = content.indexOf(marker);
+  if (at !== -1) {
+    const sectionStart = at + marker.length;
+    let end = content.indexOf('\n## ', sectionStart);
+    if (end === -1) end = content.length;
+    const head = content.slice(0, end).replace(/\s+$/, '');
+    return `${head}\n${line}\n${content.slice(end)}`;
+  }
+  const block = `## ${heading}\n\n${line}\n\n`;
+  const enc = content.indexOf('\n## Encerramento');
+  if (enc === -1) return `${content.trimEnd()}\n\n${block}`;
+  return `${content.slice(0, enc).trimEnd()}\n\n${block}${content.slice(enc + 1)}`;
+}
+
+export function logTask(vaultBase, input) {
+  const text = taskText(input);
+  if (!text) return false;
+  const transcriptPath = input.transcript_path || input.transcriptPath || '';
+  const matched = transcriptPath ? findActiveSessionByTranscript(vaultBase, transcriptPath) : null;
+  const sessionRel = matched?.session_file || readControl(vaultBase).session_file || '';
+  if (!sessionRel) return false;
+  const sessionPath = join(vaultBase, sessionRel);
+  if (!existsSync(sessionPath)) return false;
+
+  const heading = getLocale(vaultBase).id === 'en' ? 'Plan progress' : 'Progresso do plano';
+  const line = `- [x] ${formatHourMinute(new Date()).replace('-', ':')} ${text}`;
+  const content = readFileSync(sessionPath, 'utf8');
+  const next = appendProgress(content, line, heading);
+  if (next !== content) { writeFileSync(sessionPath, next, 'utf8'); return true; }
+  return false;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    logTask(getVaultBase(input), input);
+    writeHookOutput({});
+  } catch (error) {
+    process.stderr.write(`[wendkeep] task-log falhou: ${error.message}\n`);
+    writeHookOutput({});
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.26.0",
+  "version": "0.28.1",
   "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": {

package/src/init.mjs

@@ -126,6 +126,10 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
     added += 1;
   }
   s.env = { ...(s.env || {}), OBSIDIAN_VAULT_PATH: vaultPath };
+  // npx-launched stdio MCPs (wendkeep-vault included) can cold-start near/over Claude Code's 30s
+  // default under Windows startup contention (26s observed in a real log). Give them headroom —
+  // but never clobber a value the user already set.
+  if (!('MCP_TIMEOUT' in s.env)) s.env.MCP_TIMEOUT = '60000';
 
   // Claude Code plugin layer for the selected companions (additive, non-clobbering).
   const cp = companionSettingsPatch(companions);
@@ -249,6 +253,7 @@ const MESSAGES = {
     step3: '  3. Abra o Claude Code neste projeto e envie um prompt de teste.',
     step4: '  4. Confirme que uma nota aparece em 02-Sessões/<ano>/<mês>/DIA <dd>/ no vault.',
     updateLater: '  Atualize depois com: npm update wendkeep  (sem recopiar — os hooks vivem no pacote).\n',
+    vaultRegistered: (v, loc) => `\n  cofre já registrado neste projeto: ${v} (locale ${loc}) — pergunta pulada. Use --vault para mudar.`,
   },
   en: {
     header: '\nwendkeep init',
@@ -273,6 +278,7 @@ const MESSAGES = {
     step3: '  3. Open Claude Code in this project and send a test prompt.',
     step4: '  4. Confirm a note appears under 02-Sessões/<year>/<month>/DIA <dd>/ in the vault.',
     updateLater: '  Update later with: npm update wendkeep  (no re-copying — hooks live in the package).\n',
+    vaultRegistered: (v, loc) => `\n  vault already registered for this project: ${v} (locale ${loc}) — prompt skipped. Use --vault to change.`,
   },
 };
 
@@ -287,13 +293,39 @@ export function parseLocaleAnswer(ans) {
   return 'pt-BR';
 }
 
+// The vault path this project was set up with — read from .claude/settings.json's
+// OBSIDIAN_VAULT_PATH (written by a prior init). Empty when the project isn't configured yet.
+export function detectRegisteredVault(projectPath) {
+  try {
+    const s = JSON.parse(readFileSync(join(projectPath, '.claude', 'settings.json'), 'utf8'));
+    const v = s && s.env && s.env.OBSIDIAN_VAULT_PATH;
+    return typeof v === 'string' && v ? v : '';
+  } catch { return ''; }
+}
+
+// The locale locked in a vault's .brain/config.json (empty if absent/invalid).
+export function readVaultLocale(vaultPath) {
+  try {
+    const c = JSON.parse(readFileSync(join(vaultPath, '.brain', 'config.json'), 'utf8'));
+    return c && LOCALES[c.locale] ? c.locale : '';
+  } catch { return ''; }
+}
+
 export async function runInit(argv) {
   const args = parseArgs(argv);
   const projectPath = resolve(args.project || process.cwd());
   const log = (s) => process.stdout.write(`${s}\n`);
 
-  // Language first (i18n): an interactive TTY without --locale is asked the vault language;
-  // folders, prompts and scaffold all follow the answer.
+  // Recognize an already-configured project: the vault is registered in the project's
+  // settings.json (OBSIDIAN_VAULT_PATH) and its locale is locked in the vault's config.json.
+  // On re-run (e.g. after `npm i -D wendkeep@latest`) we reuse both and SKIP the language + vault
+  // prompts — asking again risks a divergent vault from a mistyped name. `--vault` / `--locale`
+  // override; the vault question is a once-per-project thing.
+  const registeredVault = args.vault ? '' : detectRegisteredVault(projectPath);
+  if (registeredVault && !args.locale) args.locale = readVaultLocale(registeredVault) || args.locale;
+
+  // Language first (i18n): an interactive TTY without --locale (and not already registered) is
+  // asked the vault language; folders, prompts and scaffold all follow the answer.
   if (!args.locale && process.stdin.isTTY && !args.yes) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ans = await rl.question('Idioma do vault / Vault language:\n  [1] Português (pt-BR)   [2] English (en)\n> ');
@@ -304,8 +336,10 @@ export async function runInit(argv) {
   const P = promptStrings(resolvedLocale);
   const M = initMessages(resolvedLocale);
 
-  let vaultPath = args.vault;
-  if (!vaultPath) {
+  let vaultPath = args.vault || registeredVault;
+  if (registeredVault) {
+    log(M.vaultRegistered(registeredVault, resolvedLocale));
+  } else if (!vaultPath) {
     const fallback = join(projectPath, deriveVaultDirName(projectPath));
     if (process.stdin.isTTY && !args.yes) {
       const rl = createInterface({ input: process.stdin, output: process.stdout });

package/src/taxonomy.mjs

@@ -44,6 +44,9 @@ export const HOOK_FILES = [
   'brain-reindex.mjs',
   'session-backfill.mjs',
   'import-sessions.mjs',
+  'decision-capture.mjs',
+  'subagent-stop.mjs',
+  'task-log.mjs',
   'vault-health.mjs',
   'understand-inject.mjs',
 ];
@@ -56,6 +59,9 @@ export const RUNNABLE_HOOKS = [
   'session-ensure',
   'session-stop',
   'session-backfill',
+  'decision-capture',
+  'subagent-stop',
+  'task-log',
   'brain-inject',
   'brain-recall',
   'brain-reindex',
@@ -81,10 +87,19 @@ export const SESSION_HOOKS = [
   // Memory + active-change injection. Runs FIRST on SessionStart (order -10, folds before
   // session-start) so the agent gets CORE + DIGEST + the active change + lessons as context.
   // matcher 'startup|clear|compact' re-injects after a compaction/clear, not only cold startup.
-  { event: 'SessionStart', matcher: 'startup|clear|compact', name: 'brain-inject', timeout: 15, order: -10, statusMessage: 'wendkeep: injecting memory + active change' },
+  // timeout 45 (was 15): measured ~4s warm via npx, but Windows startup contention (several npx
+  // cold-starts at once — a sibling MCP took 26s in a real log) blew 15s and silently dropped the
+  // memory injection for the whole session.
+  { event: 'SessionStart', matcher: 'startup|clear|compact', name: 'brain-inject', timeout: 45, order: -10, statusMessage: 'wendkeep: injecting memory + active change' },
   { event: 'SessionStart', matcher: 'startup', name: 'session-start', timeout: 30, statusMessage: 'wendkeep: opening Obsidian session' },
   { event: 'Stop', matcher: null, name: 'session-stop', timeout: 60, statusMessage: 'wendkeep: writing session checkpoint' },
   { event: 'UserPromptSubmit', matcher: null, name: 'session-ensure', timeout: 30, statusMessage: 'wendkeep: ensuring active session' },
+  // Capture an interactive decision (AskUserQuestion) — options + the user's choice — into 04-Decisões.
+  { event: 'PostToolUse', matcher: 'AskUserQuestion', name: 'decision-capture', timeout: 15, statusMessage: 'wendkeep: recording decision' },
+  // Refresh subagent/workflow telemetry as each subagent finishes (resilient to a missed Stop).
+  { event: 'SubagentStop', matcher: null, name: 'subagent-stop', timeout: 20, statusMessage: 'wendkeep: subagent telemetry' },
+  // Log plan/task progress into the active session note when a task is marked complete.
+  { event: 'TaskCompleted', matcher: null, name: 'task-log', timeout: 10, statusMessage: 'wendkeep: plan progress' },
 ];
 
 export function hookCommand(name) {
@@ -108,8 +123,10 @@ export const COMPANIONS = [
     default: false,
     marketplace: { source: 'git', url: 'https://github.com/mksglu/context-mode.git' },
     plugin: 'context-mode',
-    // Agent-agnostic: MCP server, self-updating via unpinned npx.
-    mcp: { key: 'context-mode', entry: { type: 'stdio', command: 'npx', args: ['-y', 'context-mode'] } },
+    // NO .mcp.json entry on purpose: the plugin ships its OWN MCP server, so wiring both
+    // double-registered it (two concurrent `npx context-mode` cold-starts at session start —
+    // both timed out in a real log). Plugin is the single source; on non-Claude agents add the
+    // MCP manually (`npx -y context-mode`).
   },
   {
     id: 'understand-anything',