wendkeep 0.75.3 → 0.76.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.75.3",
+  "version": "0.76.1",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -41,6 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
+    "precheck": "node --check src/worktree.mjs && node --check src/context.mjs && node --check packages/vault/src/worktree-metadata.mjs",
     "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",

package/packages/cli/src/index.mjs

@@ -1,5 +1,5 @@
 // wendkeep CLI — canonical private runtime.
-//   wendkeep init [--vault <path>] [--project <path>] [--no-mcp] [--yes] [--force]
+//   wendkeep init [--vault <path>] [--project <path>] [--no-mcp] [--yes] [--force] [--vscode-worktree-tasks]
 //   wendkeep hook <name>      (invoked by the agent's settings.json; pipes stdin/stdout)
 //   wendkeep doctor [--vault <path>]
 //   wendkeep --version | --help
@@ -33,6 +33,7 @@ Usage:
                            (default: none — opt in explicitly). dotcontext is legacy — the native a2 loop replaces it.
     --no-companions        Skip companion plugins/MCP entirely.
     --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
+    --vscode-worktree-tasks Create local, Git-excluded VS Code tasks for managed worktrees.
     --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry
                            if already global), project, or none.
     --dotcontext-hooks <v> dotcontext hooks: full (default), light (no PostToolUse), none.
@@ -46,10 +47,18 @@ Usage:
                            command — the three steps that repeat identically after every
                            package update. Stops at the first failing step. Install the
                            package first (npm i -D wendkeep@latest); a running process
-                           cannot replace itself. · --vault P · --profile <name> · --yes.
+                           cannot replace itself. · --vault P · --profile <name> · --yes
+                           · --vscode-worktree-tasks.
 
   wendkeep doctor [--vault P]  Health check. --scope core|runtime · --strict for CI/release.
   wendkeep observer <sub>     Local multi-project Observer: serve | register | publish | reconcile | status.
+  wendkeep worktree create <slug> [--base ref] [--branch name] [--open vscode|none] [--json]
+  wendkeep worktree list [--json]
+  wendkeep worktree status [slug] [--json]
+  wendkeep worktree open <slug> [--editor vscode] [--json]
+                           Managed linked worktrees under .worktrees (branch default wk/<slug>).
+  wendkeep context switch <branch> [--create] [--session <id>] [--json]
+                           Switch Git branch and the causal session scope in the same worktree.
   wendkeep change <sub>        Change lifecycle: new [--simple|--guide] | use | bind <slug> --session <id> | continue | list | show |
                            status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
                            archive exige verdict (rode verify --deep); abandon descarta sem ADR.
@@ -193,6 +202,9 @@ async function main(argv) {
     } else if (cmd === 'profile') {
       const { PROFILE_HELP } = await import('../../../src/profile.mjs');
       process.stdout.write(PROFILE_HELP);
+    } else if (cmd === 'context') {
+      const { CONTEXT_HELP } = await import('../../../src/context.mjs');
+      process.stdout.write(CONTEXT_HELP);
     } else {
       process.stdout.write(HELP);
     }
@@ -206,7 +218,7 @@ async function main(argv) {
     // `sync` starts with `init` and resolves the freshly bound Vault itself. Pre-resolving
     // here would prevent that repair step from reporting a corrupt binding as its own
     // first-stage failure (and could never make it as far as the guarded init).
-    && !['init', 'sync', 'hook', 'observer', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
+    && !['init', 'sync', 'worktree', 'hook', 'observer', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
     await preferProjectVault(rest);
   }
   switch (cmd) {
@@ -229,6 +241,16 @@ async function main(argv) {
       if (rest[0] !== 'serve') process.exit(observerExitCode);
       break;
     }
+    case 'worktree': {
+      const { runWorktree } = await import('../../../src/worktree.mjs');
+      process.exit(runWorktree(rest));
+      break;
+    }
+    case 'context': {
+      const { runContext } = await import('../../../src/context.mjs');
+      process.exit(runContext(rest));
+      break;
+    }
     case 'sync': {
       const { runSync } = await import('../../../src/sync.mjs');
       process.exit(await runSync(rest));

package/packages/vault/src/index.mjs

@@ -1,4 +1,5 @@
 export * from './project-vault.mjs';
+export * from './worktree-metadata.mjs';
 export * from './vault-path-safety.mjs';
 export * from './locale.mjs';
 export * from './memory-schema.mjs';

package/packages/vault/src/project-vault.mjs

@@ -9,6 +9,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+import { resolveWorktreeVaultBinding } from './worktree-metadata.mjs';
 
 export const PROJECT_CONFIG_FILE = '.wendkeep.json';
 export const PROJECT_MARKER_REL = '.brain/PROJECT.json';
@@ -203,7 +204,7 @@ export function resolveProjectVault({
     bindingFailure = error;
   }
   if (binding) {
-    const result = {
+    let result = {
       base: binding.base,
       source: 'project-config',
       projectRoot: binding.projectRoot,
@@ -211,7 +212,29 @@ export function resolveProjectVault({
       configPath: binding.configPath,
       config: binding.config,
     };
-    if (validateIdentity) validateMarker(result);
+    if (validateIdentity) {
+      try {
+        validateMarker(result);
+      } catch (error) {
+        const canUsePrivateBinding = error?.code === 'WENDKEEP_VAULT_MARKER_MISSING'
+          && !isAbsolute(binding.config.vault);
+        if (!canUsePrivateBinding) throw error;
+        const privateBinding = resolveWorktreeVaultBinding({
+          startDir: start,
+          projectId: binding.config.projectId,
+        });
+        if (!privateBinding) throw error;
+        result = {
+          ...result,
+          base: privateBinding.base,
+          source: 'worktree-registry',
+          projectRoot: privateBinding.projectRoot,
+          repositoryId: privateBinding.repositoryId,
+          registryPath: privateBinding.registryPath,
+        };
+        validateMarker(result);
+      }
+    }
     return result;
   }
 

package/packages/vault/src/worktree-metadata.mjs

@@ -0,0 +1,274 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+export const WORKTREE_REGISTRY_SCHEMA = 1;
+export const WORKTREE_REGISTRY_REL = 'wendkeep/worktrees-v1.json';
+
+function worktreeError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function gitOutput(startDir, args, spawn = spawnSync) {
+  const result = spawn('git', args, {
+    cwd: startDir,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_GIT_FAILED',
+      String(result.stderr || result.error?.message || `git ${args[0]} falhou`).trim(),
+    );
+  }
+  return String(result.stdout || '').trim();
+}
+
+function absoluteGitPath(repoRoot, value) {
+  return resolve(isAbsolute(value) ? value : join(repoRoot, value));
+}
+
+function parseWorktreeList(text) {
+  const records = [];
+  let current = null;
+  for (const line of String(text || '').split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) {
+      current = { path: resolve(line.slice('worktree '.length)) };
+      records.push(current);
+    } else if (current && line.startsWith('HEAD ')) {
+      current.head = line.slice('HEAD '.length);
+    } else if (current && line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+    } else if (current && line === 'bare') {
+      current.bare = true;
+    } else if (current && line === 'detached') {
+      current.detached = true;
+    }
+  }
+  return records;
+}
+
+export function discoverWorktreeRepository({ startDir = process.cwd(), spawn = spawnSync } = {}) {
+  const repoRoot = resolve(gitOutput(startDir, ['rev-parse', '--show-toplevel'], spawn));
+  const commonDir = absoluteGitPath(
+    repoRoot,
+    gitOutput(repoRoot, ['rev-parse', '--git-common-dir'], spawn),
+  );
+  const gitDir = absoluteGitPath(
+    repoRoot,
+    gitOutput(repoRoot, ['rev-parse', '--git-dir'], spawn),
+  );
+  const worktrees = parseWorktreeList(gitOutput(repoRoot, ['worktree', 'list', '--porcelain'], spawn));
+  const main = worktrees.find((entry) => !entry.bare) || null;
+  if (!main) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_MAIN_UNRESOLVED',
+      'Não foi possível localizar a worktree principal do repositório.',
+    );
+  }
+  return {
+    repoRoot,
+    commonDir,
+    gitDir,
+    mainWorktree: main.path,
+    worktrees,
+  };
+}
+
+function sleep(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+export function withWorktreeRegistryLock(registryPath, operation, {
+  timeoutMs = 5_000,
+  staleMs = 30_000,
+  now = () => Date.now(),
+} = {}) {
+  const lockPath = `${registryPath}.lock`;
+  const startedAt = now();
+  mkdirSync(dirname(registryPath), { recursive: true });
+  while (true) {
+    try {
+      mkdirSync(lockPath);
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (now() - statSync(lockPath).mtimeMs > staleMs) {
+          rmSync(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch (inspectError) {
+        if (inspectError?.code !== 'ENOENT') throw inspectError;
+        continue;
+      }
+      if (now() - startedAt >= timeoutMs) {
+        throw worktreeError(
+          'WENDKEEP_WORKTREE_REGISTRY_BUSY',
+          `Registry de worktrees ocupado: ${registryPath}`,
+        );
+      }
+      sleep(20);
+    }
+  }
+  try {
+    return operation();
+  } finally {
+    rmSync(lockPath, { recursive: true, force: true });
+  }
+}
+
+function atomicJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (existsSync(path) && readFileSync(path, 'utf8') === content) return false;
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
+  renameSync(temporary, path);
+  return true;
+}
+
+function validateRegistry(value, path) {
+  if (
+    value?.schemaVersion !== WORKTREE_REGISTRY_SCHEMA
+    || typeof value.repositoryId !== 'string'
+    || !value.repositoryId
+    || typeof value.projectId !== 'string'
+    || !value.projectId
+    || typeof value.vaultPath !== 'string'
+    || !value.vaultPath
+    || !value.entries
+    || typeof value.entries !== 'object'
+    || Array.isArray(value.entries)
+  ) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_REGISTRY_INVALID',
+      `Registry de worktrees incompleto em "${path}".`,
+    );
+  }
+  return value;
+}
+
+function parseRegistry(path) {
+  let value;
+  try {
+    value = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_REGISTRY_INVALID',
+      `Registry de worktrees inválido em "${path}": ${error.message}`,
+    );
+  }
+  return validateRegistry(value, path);
+}
+
+export function readWorktreeRegistry(repository) {
+  const path = join(repository.commonDir, ...WORKTREE_REGISTRY_REL.split('/'));
+  return existsSync(path) ? { path, registry: parseRegistry(path) } : { path, registry: null };
+}
+
+export function resolveWorktreeVaultBinding({ startDir = process.cwd(), projectId } = {}) {
+  let repository;
+  try {
+    repository = discoverWorktreeRepository({ startDir });
+  } catch (error) {
+    if (error?.code === 'WENDKEEP_WORKTREE_GIT_FAILED') return null;
+    throw error;
+  }
+  const { path, registry } = readWorktreeRegistry(repository);
+  if (!registry) return null;
+  if (registry.projectId !== projectId) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_PROJECT_MISMATCH',
+      `Registry "${path}" pertence ao projeto "${registry.projectId}", não "${projectId}".`,
+    );
+  }
+  return {
+    base: resolve(registry.vaultPath),
+    projectId: registry.projectId,
+    repositoryId: registry.repositoryId,
+    registryPath: path,
+    projectRoot: repository.mainWorktree,
+    repository,
+  };
+}
+
+export function mutateWorktreeRegistry(repository, mutator) {
+  if (!repository?.commonDir || typeof mutator !== 'function') {
+    throw worktreeError('WENDKEEP_WORKTREE_REPOSITORY_INVALID', 'Repositório Git inválido.');
+  }
+  const registryPath = join(repository.commonDir, ...WORKTREE_REGISTRY_REL.split('/'));
+  return withWorktreeRegistryLock(registryPath, () => {
+    if (!existsSync(registryPath)) {
+      throw worktreeError(
+        'WENDKEEP_WORKTREE_REGISTRY_MISSING',
+        `Registry de worktrees ausente em "${registryPath}".`,
+      );
+    }
+    const current = parseRegistry(registryPath);
+    const next = validateRegistry(mutator(structuredClone(current)), registryPath);
+    atomicJson(registryPath, next);
+    return next;
+  });
+}
+
+export function worktreeIdentity(repositoryId, gitDir) {
+  return createHash('sha256')
+    .update(`${repositoryId}\n${resolve(gitDir).replaceAll('\\', '/').toLowerCase()}\n`)
+    .digest('hex');
+}
+
+export function ensureWorktreeMetadata({
+  repository,
+  projectId,
+  vaultPath,
+  worktreesRoot = '.worktrees',
+} = {}) {
+  if (!repository?.commonDir || !repository?.gitDir) {
+    throw worktreeError('WENDKEEP_WORKTREE_REPOSITORY_INVALID', 'Repositório Git inválido.');
+  }
+  const registryPath = join(repository.commonDir, ...WORKTREE_REGISTRY_REL.split('/'));
+  const normalizedVault = resolve(String(vaultPath || ''));
+  const registry = withWorktreeRegistryLock(registryPath, () => {
+    const current = existsSync(registryPath) ? parseRegistry(registryPath) : null;
+    if (current && current.projectId !== projectId) {
+      throw worktreeError(
+        'WENDKEEP_WORKTREE_PROJECT_MISMATCH',
+        `Registry pertence a outro projeto: ${current.projectId}.`,
+      );
+    }
+    if (current && resolve(current.vaultPath) !== normalizedVault) {
+      throw worktreeError(
+        'WENDKEEP_WORKTREE_VAULT_MISMATCH',
+        'Registry aponta para outro Vault canônico.',
+      );
+    }
+    const next = current || {
+      schemaVersion: WORKTREE_REGISTRY_SCHEMA,
+      repositoryId: randomUUID(),
+      projectId,
+      vaultPath: normalizedVault,
+      worktreesRoot,
+      entries: {},
+    };
+    atomicJson(registryPath, next);
+    return next;
+  });
+  return {
+    registryPath,
+    repositoryId: registry.repositoryId,
+    currentWorktreeId: worktreeIdentity(registry.repositoryId, repository.gitDir),
+    registry,
+  };
+}