wendkeep 0.76.2 → 0.76.4

package/src/context.mjs

@@ -10,16 +10,23 @@ import {
   concurrentScopeConflicts,
   scopeForRegistry,
 } from '../hooks/project-scope.mjs';
+import { readVaultMarker } from './project-vault.mjs';
+import { sanitizeMemoryText } from '../packages/vault/src/memory-schema.mjs';
 
 export const CONTEXT_HELP = `wendkeep context <subcommand>
 
   switch <branch> [--create] [--session <id>] [--project <path>] [--vault <path>] [--json]
+  status --session <id> [--project <path>] [--vault <path>] [--json]
+  recover --session <id> --select <reserved|observed> --revision <n> --reason <text>
+    [--project <path>] [--vault <path>] [--json]
 
 Switches Git branch and the causal session scope together inside the same worktree.
 Without --session, exactly one active session must match the current scope.
+Status inventories reserved/observed recovery candidates without selecting one.
+Recover resolves a quarantined conflict only when the selected candidate still matches the checkout.
 `;
 
-const VALUE_OPTIONS = new Set(['--project', '--vault', '--session']);
+const VALUE_OPTIONS = new Set(['--project', '--vault', '--session', '--select', '--revision', '--reason']);
 const FLAG_OPTIONS = new Set(['--create', '--json']);
 
 function contextError(code, message) {
@@ -121,6 +128,247 @@ function contextRevision(entry) {
     ? entry.context_revision : 0;
 }
 
+function activeSessionEntry(registry, sessionId) {
+  const id = String(sessionId || '').trim();
+  if (!id) throw contextError('WENDKEEP_CONTEXT_SESSION', 'status requer --session <id>');
+  const entry = registry.sessions?.[id];
+  if (!entry || entry.status !== 'active') {
+    throw contextError('WENDKEEP_CONTEXT_SESSION', `sessão ativa não encontrada: ${id}`);
+  }
+  return { id, entry };
+}
+
+function validCandidateScope(scope, label) {
+  const required = [
+    'projectId', 'projectRoot', 'repoRoot', 'remote', 'branch', 'worktree',
+    'head', 'provider', 'sessionId',
+  ];
+  const complete = scope && typeof scope === 'object' && scope.complete === true
+    && required.every((field) => typeof scope[field] === 'string' && scope[field].trim());
+  const head = complete ? scope.head.trim() : '';
+  const branch = complete ? scope.branch.trim() : '';
+  const safeHead = /^[0-9a-f]{40,64}$/i.test(head);
+  const safeBranch = branch === `detached:${head}` || (
+    branch.length <= 255
+    && !branch.startsWith('/')
+    && !branch.endsWith('/')
+    && !branch.endsWith('.')
+    && !branch.endsWith('.lock')
+    && !branch.includes('..')
+    && !branch.includes('@{')
+    && !branch.includes('//')
+    && !/[\u0000-\u0020~^:?*[\]\\]/u.test(branch)
+  );
+  if (!complete || !safeHead || !safeBranch) {
+    throw contextError('WENDKEEP_CONTEXT_SCOPE_CONFLICT', `scope ${label} ausente ou incompleta`);
+  }
+  return scope;
+}
+
+function scopeMatchesActual(candidate, actual) {
+  return compareProjectScopes(candidate, actual).ok
+    && Boolean(candidate.head)
+    && candidate.head === actual.head;
+}
+
+function candidateSummary(id, candidate, actual) {
+  return {
+    id,
+    branch: candidate.branch || '',
+    head: candidate.head || '',
+    complete: candidate.complete === true,
+    matches_actual: scopeMatchesActual(candidate, actual),
+  };
+}
+
+function requiredRevision(value) {
+  const raw = String(value ?? '').trim();
+  const revision = Number(raw);
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(revision)) {
+    throw contextError('WENDKEEP_CONTEXT_ARGS', 'recover requer --revision <inteiro não negativo>');
+  }
+  return revision;
+}
+
+function recoveryReason(value) {
+  const raw = String(value || '').replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!raw) throw contextError('WENDKEEP_CONTEXT_ARGS', 'recover requer --reason <texto>');
+  if (raw.length > 240) throw contextError('WENDKEEP_CONTEXT_ARGS', '--reason excede 240 caracteres');
+  return sanitizeMemoryText(raw).replace(/\s+/g, ' ').trim();
+}
+
+function recoverySelection(value) {
+  const selected = String(value || '').trim();
+  if (!['reserved', 'observed'].includes(selected)) {
+    throw contextError('WENDKEEP_CONTEXT_ARGS', 'recover requer --select <reserved|observed>');
+  }
+  return selected;
+}
+
+function scopeIdentityMismatches(reserved, observed) {
+  const fields = ['projectId', 'remote', 'provider', 'sessionId'];
+  return fields.filter((field) => String(reserved?.[field] || '') !== String(observed?.[field] || ''));
+}
+
+function validateRecoveryIdentity(vaultBase, entry, sessionId, reserved, observed = null) {
+  const mismatches = observed ? scopeIdentityMismatches(reserved, observed) : [];
+  const candidates = observed ? [reserved, observed] : [reserved];
+  if (candidates.some((candidate) => candidate.sessionId !== sessionId)) mismatches.push('sessionId');
+  if (entry.provider && candidates.some((candidate) => candidate.provider !== entry.provider)) {
+    mismatches.push('provider');
+  }
+  let marker = null;
+  try { marker = readVaultMarker(vaultBase)?.marker || null; } catch { /* fail closed below */ }
+  if (!marker?.projectId || candidates.some((candidate) => candidate.projectId !== marker.projectId)) {
+    mismatches.push('projectId');
+  }
+  if (mismatches.length) {
+    throw contextError(
+      'WENDKEEP_CONTEXT_IDENTITY_CHANGED',
+      `candidatas divergem na identidade causal (${[...new Set(mismatches)].join(', ')})`,
+    );
+  }
+}
+
+function recoveryActualScope(projectRoot, expected, sessionId, spawn) {
+  return captureProjectScope({
+    input: { cwd: projectRoot },
+    projectRoot,
+    projectId: expected.projectId,
+    provider: expected.provider,
+    sessionId,
+    targetCwd: projectRoot,
+    spawn,
+  });
+}
+
+const CONFLICT_FIELDS = new Set([
+  'scope.projectId', 'scope.projectRoot', 'scope.repoRoot', 'scope.remote', 'scope.branch',
+  'scope.worktree', 'scope.provider', 'scope.sessionId', 'scope.incomplete',
+]);
+
+function sanitizedConflictFields(value) {
+  if (!Array.isArray(value) || value.some((field) => !CONFLICT_FIELDS.has(String(field)))) {
+    throw contextError('WENDKEEP_CONTEXT_SCOPE_CONFLICT', 'campos de conflito ausentes ou inválidos');
+  }
+  return [...new Set(value.map(String))].sort();
+}
+
+function receiptScope(candidate) {
+  return { branch: candidate.branch || '', head: candidate.head || '' };
+}
+
+export function inspectSessionContext({
+  vaultBase,
+  projectRoot = process.cwd(),
+  sessionId = '',
+  spawn = spawnSync,
+} = {}) {
+  const registry = readSessionRegistry(vaultBase);
+  const selected = activeSessionEntry(registry, sessionId);
+  const reserved = validCandidateScope(selected.entry.project_scope, 'reserved');
+  const conflict = selected.entry.project_scope_conflict === true;
+  const observed = conflict
+    ? validCandidateScope(selected.entry.project_scope_observed, 'observed')
+    : null;
+  validateRecoveryIdentity(vaultBase, selected.entry, selected.id, reserved, observed);
+  const actual = recoveryActualScope(projectRoot, reserved, selected.id, spawn);
+  const candidates = [candidateSummary('reserved', reserved, actual)];
+  if (observed) candidates.push(candidateSummary('observed', observed, actual));
+  return {
+    status: conflict ? 'conflict' : 'healthy',
+    session_id: selected.id,
+    revision: contextRevision(selected.entry),
+    conflict,
+    conflict_fields: conflict ? sanitizedConflictFields(selected.entry.project_scope_conflict_fields) : [],
+    candidates,
+  };
+}
+
+export function recoverSessionContext({
+  vaultBase,
+  projectRoot = process.cwd(),
+  sessionId = '',
+  select = '',
+  revision,
+  reason = '',
+  spawn = spawnSync,
+  mutateRegistry = mutateSessionRegistry,
+  now = () => new Date(),
+} = {}) {
+  const requestedSessionId = String(sessionId || '').trim();
+  if (!requestedSessionId) throw contextError('WENDKEEP_CONTEXT_SESSION', 'recover requer --session <id>');
+  const selectedId = recoverySelection(select);
+  const expectedRevision = requiredRevision(revision);
+  const safeReason = recoveryReason(reason);
+
+  return mutateRegistry(vaultBase, (registry) => {
+    const selected = activeSessionEntry(registry, requestedSessionId);
+    const entry = selected.entry;
+    if (entry.project_scope_conflict !== true) {
+      throw contextError('WENDKEEP_CONTEXT_SCOPE_CONFLICT', 'a sessão não possui conflito de scope ativo');
+    }
+    const currentRevision = contextRevision(entry);
+    if (currentRevision !== expectedRevision) {
+      throw contextError(
+        'WENDKEEP_CONTEXT_CAS_MISMATCH',
+        `context_revision mudou de ${expectedRevision} para ${currentRevision}; inspecione o status novamente`,
+      );
+    }
+    const reserved = validCandidateScope(entry.project_scope, 'reserved');
+    const observed = validCandidateScope(entry.project_scope_observed, 'observed');
+    validateRecoveryIdentity(vaultBase, entry, selected.id, reserved, observed);
+    const candidate = selectedId === 'reserved' ? reserved : observed;
+    const actual = recoveryActualScope(projectRoot, candidate, selected.id, spawn);
+    if (!scopeMatchesActual(candidate, actual)) {
+      throw contextError(
+        'WENDKEEP_CONTEXT_SCOPE_MISMATCH',
+        `a candidata ${selectedId} não corresponde integralmente ao checkout atual`,
+      );
+    }
+
+    const nextRevision = currentRevision + 1;
+    const at = now().toISOString();
+    const receipt = {
+      revision: nextRevision,
+      operation: 'recover',
+      selected: selectedId,
+      from: {
+        reserved: receiptScope(reserved),
+        observed: receiptScope(observed),
+      },
+      to: receiptScope(actual),
+      actor: { provider: candidate.provider || entry.provider || '', session_id: selected.id },
+      reason: safeReason,
+      at,
+    };
+    const {
+      project_scope_conflict: _conflict,
+      project_scope_conflict_fields: _conflictFields,
+      project_scope_observed: _observed,
+      ...preserved
+    } = entry;
+    registry.sessions[selected.id] = {
+      ...preserved,
+      project_scope: scopeForRegistry(actual, { authorizedActions: reserved.authorizedActions }),
+      context_revision: nextRevision,
+      context_recoveries: [
+        ...(Array.isArray(entry.context_recoveries) ? entry.context_recoveries : []),
+        receipt,
+      ],
+      last_seen: at,
+      updated_at: at,
+    };
+    return {
+      status: 'recovered',
+      session_id: selected.id,
+      selected: selectedId,
+      revision: nextRevision,
+      receipt,
+    };
+  });
+}
+
 function resolveSessionId(vaultBase, projectRoot, requested, spawn) {
   const registry = readSessionRegistry(vaultBase);
   if (requested) {
@@ -271,6 +519,12 @@ export function switchSessionContext({
 
 function output(result, json) {
   if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else if (Array.isArray(result.candidates)) {
+    process.stdout.write(`context ${result.status}: session ${result.session_id}; revision ${result.revision}; candidates ${result.candidates.map((candidate) => candidate.id).join(', ')}\n`);
+  }
+  else if (result.status === 'recovered') {
+    process.stdout.write(`context recovered: ${result.selected} selected (session ${result.session_id}; revision ${result.revision})\n`);
+  }
   else process.stdout.write(`context ${result.status}: ${result.branch} (session ${result.session_id}; revision ${result.revision})\n`);
 }
 
@@ -278,6 +532,27 @@ export function runContext(argv = []) {
   try {
     validateArgv(argv);
     const [sub, branch, ...extra] = positionals(argv);
+    if (sub === 'status' && !branch && !extra.length) {
+      const result = inspectSessionContext({
+        vaultBase: vaultOf(argv),
+        projectRoot: projectOf(argv),
+        sessionId: optionValue(argv, '--session'),
+      });
+      output(result, argv.includes('--json'));
+      return 0;
+    }
+    if (sub === 'recover' && !branch && !extra.length) {
+      const result = recoverSessionContext({
+        vaultBase: vaultOf(argv),
+        projectRoot: projectOf(argv),
+        sessionId: optionValue(argv, '--session'),
+        select: optionValue(argv, '--select'),
+        revision: optionValue(argv, '--revision'),
+        reason: optionValue(argv, '--reason'),
+      });
+      output(result, argv.includes('--json'));
+      return 0;
+    }
     if (sub !== 'switch' || !branch || extra.length) {
       throw contextError('WENDKEEP_CONTEXT_ARGS', 'use: wendkeep context switch <branch> [--create] [--session <id>]');
     }

package/src/spec.mjs

@@ -11,6 +11,7 @@ import {
 } from '../hooks/spec-core.mjs';
 import { activeChange, parseTasks } from '../hooks/change-core.mjs';
 import { getLocale } from '../hooks/locale.mjs';
+import { resolveCommandActiveContext } from './active-context-runtime.mjs';
 
 function resolveVault(argv) {
   let vault;
@@ -38,9 +39,21 @@ export function runSpec(argv) {
     const entry = rest.find((a) => a.startsWith(`${name}=`));
     return entry ? entry.slice(name.length + 1) : undefined;
   };
+  const commandContext = () => {
+    try {
+      return resolveCommandActiveContext({
+        vaultBase,
+        projectRoot: resolve(option('--project') || process.cwd()),
+        sessionId: option('--session') || process.env.CODEX_THREAD_ID || process.env.CLAUDE_SESSION_ID || '',
+      });
+    } catch (error) {
+      process.stderr.write(`wendkeep spec: ${error.code || 'WENDKEEP_ACTIVE_CONTEXT_FAILED'}: ${error.message}\n`);
+      process.exit(2);
+    }
+  };
 
   if (sub === 'effective') {
-    const slug = option('--change') || activeChange(vaultBase);
+    const slug = option('--change') || activeChange(vaultBase, { context: commandContext() });
     if (!slug) { process.stderr.write('wendkeep spec effective: no change (--change or current)\n'); process.exit(2); }
     const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
     let tasks = [];
@@ -74,7 +87,7 @@ export function runSpec(argv) {
   }
 
   if (sub === 'rebase') {
-    const slug = option('--change') || activeChange(vaultBase);
+    const slug = option('--change') || activeChange(vaultBase, { context: commandContext() });
     if (!slug) { process.stderr.write('wendkeep spec rebase: no change (--change or current)\n'); process.exit(2); }
     const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
     try { readFileSync(join(changeDir, 'proposta.md'), 'utf8'); }

package/src/verify.mjs

@@ -20,6 +20,7 @@ import {
 } from '../hooks/spec-core.mjs';
 import { addLesson } from '../hooks/lessons-core.mjs';
 import { getLocale } from '../hooks/locale.mjs';
+import { resolveCommandActiveContext } from './active-context-runtime.mjs';
 
 function today() {
   const d = new Date();
@@ -40,7 +41,20 @@ export function runVerify(argv) {
   // --project wins; otherwise climb from cwd to the nearest project marker (agent shells
   // keep their cwd across commands, so verify from a subdirectory is a recurring miss).
   const projectRoot = resolve(opt(argv, '--project') || findProjectRoot(process.cwd()) || process.cwd());
-  const slug = opt(argv, '--change') || activeChange(vaultBase);
+  let commandContext = null;
+  if (!opt(argv, '--change')) {
+    try {
+      commandContext = resolveCommandActiveContext({
+        vaultBase,
+        projectRoot,
+        sessionId: opt(argv, '--session') || process.env.CODEX_THREAD_ID || process.env.CLAUDE_SESSION_ID || '',
+      });
+    } catch (error) {
+      process.stderr.write(`wendkeep verify: ${error.code || 'WENDKEEP_ACTIVE_CONTEXT_FAILED'}: ${error.message}\n`);
+      process.exit(2);
+    }
+  }
+  const slug = opt(argv, '--change') || activeChange(vaultBase, { context: commandContext });
   if (!slug) { process.stderr.write('wendkeep verify: no change (--change or active).\n'); process.exit(2); }
 
   const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);