wendkeep 0.78.0 → 0.80.0

package/src/release-provenance.mjs

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { cpSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
+import { evaluateReleaseChain } from './provenance-gate.mjs';
 
 const DEPENDENCY_FIELDS = Object.freeze([
   'dependencies',
@@ -52,6 +53,50 @@ export function packIntegrityInIsolatedCopy(root, { execute = execFileSync } = {
   }
 }
 
+/**
+ * Calculate the publishable tarball from an immutable target commit. A local,
+ * detached clone keeps lifecycle mutations and an incidental worktree out of
+ * the observation.
+ */
+export function collectArtifactAtCommit({
+  repoRoot,
+  targetCommit,
+  execute = execFileSync,
+} = {}) {
+  if (!repoRoot || !/^[0-9a-f]{40}$/i.test(String(targetCommit || ''))) {
+    return { ok: false, state: 'unproven', reasonCodes: ['PROVENANCE_COMMIT_MISSING'] };
+  }
+  const tempRoot = mkdtempSync(join(tmpdir(), 'wendkeep-release-target-'));
+  const targetRoot = join(tempRoot, 'target');
+  try {
+    execute('git', ['clone', '--quiet', '--no-checkout', '--local', repoRoot, targetRoot], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: false,
+    });
+    execute('git', ['checkout', '--quiet', '--detach', targetCommit], {
+      cwd: targetRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: false,
+    });
+    const integrity = packIntegrityInIsolatedCopy(targetRoot, { execute });
+    if (!integrity) return {
+      ok: false, state: 'unproven', commit: targetCommit,
+      reasonCodes: ['PROVENANCE_INTEGRITY_UNOBSERVED'],
+    };
+    return {
+      ok: true,
+      state: 'verified',
+      commit: targetCommit,
+      integrity,
+      reasonCodes: [],
+    };
+  } catch {
+    return {
+      ok: false, state: 'reported', commit: targetCommit,
+      reasonCodes: ['PROVENANCE_SOURCE_UNAVAILABLE'],
+    };
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
 export function packageHasSelfDependency(pkg = {}) {
   const name = String(pkg.name || '');
   if (!name) return false;
@@ -66,7 +111,10 @@ export function evaluateReleaseProvenance({
   publishedIntegrity = '',
   localIntegrity = '',
   requirePublished = false,
+  chain = null,
+  context = null,
 } = {}) {
+  if (chain) return evaluateReleaseChain({ chain, context: context || {} });
   const tag = `v${version}`;
   if (tagCommit && tagCommit !== headCommit) {
     return {

package/src/task-contracts.mjs

@@ -0,0 +1,510 @@
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+} from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { parseTasks } from '../hooks/change-core.mjs';
+import { getLocale } from '../hooks/locale.mjs';
+import { buildEffectiveRequirementPackage, contentHashOf, tasksHashOf } from '../hooks/spec-core.mjs';
+import { activeContextKey, resolveActiveContext } from '../hooks/active-context-store.mjs';
+
+const IGNORED_DIRECTORIES = new Set(['.git', '.worktrees', 'node_modules', 'dist']);
+const BINDING_FIELDS = [
+  ['active_context_id', 'TASK_CONTRACT_STALE_CONTEXT'],
+  ['head_sha', 'TASK_CONTRACT_STALE_HEAD'],
+  ['tasks_sha256', 'TASK_CONTRACT_STALE_TASKS'],
+  ['effective_spec_sha256', 'TASK_CONTRACT_STALE_SPEC'],
+  ['artifact_manifest_sha256', 'TASK_CONTRACT_STALE_ARTIFACT_MANIFEST'],
+];
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function canonicalJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function sha256(value) {
+  return createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+
+function uniqueStrings(values) {
+  const list = Array.isArray(values) ? values : (values === undefined || values === null ? [] : [values]);
+  return [...new Set(list.map((value) => String(value).trim()).filter(Boolean))];
+}
+
+function bindingFrom(input) {
+  return {
+    project_id: String(input.projectId || ''),
+    active_context_id: String(input.activeContextId || ''),
+    head_sha: String(input.headSha || ''),
+    tasks_sha256: String(input.tasksSha256 || ''),
+    effective_spec_sha256: String(input.effectiveSpecSha256 || ''),
+    artifact_manifest_sha256: String(input.artifactManifestSha256 || ''),
+  };
+}
+
+export function deriveTaskContracts(input = {}) {
+  const changeSlug = String(input.changeSlug || '').trim();
+  const projectId = String(input.projectId || '').trim();
+  if (!projectId || !changeSlug) {
+    throw Object.assign(new Error('projectId and changeSlug are required'), { code: 'TASK_CONTRACT_IDENTITY_MISSING' });
+  }
+  const binding = bindingFrom(input);
+  const artifactSpecs = new Map((input.artifactSpecs ?? []).map((spec) => [String(spec.name || ''), spec]));
+  return (input.tasks ?? []).map((task) => {
+    const taskId = String(task.id || '').trim();
+    const phase = String(task.phase || 'execute').trim().toLowerCase();
+    if (!['execute', 'verify'].includes(phase)) {
+      throw Object.assign(new Error(`invalid task phase for ${taskId}: ${phase}`), { code: 'TASK_PHASE_INVALID' });
+    }
+    const lease = input.taskLeases?.[`${changeSlug}:${taskId}`];
+    const activeLease = lease?.state === 'active' && Date.parse(String(lease.expires_at || '')) > Date.now()
+      ? lease : null;
+    const dependencies = uniqueStrings(task.dependencies);
+    const requiredArtifacts = uniqueStrings(task.artifacts);
+    const authored = {
+      change_slug: changeSlug,
+      task_id: taskId,
+      title: String(task.text || '').trim(),
+      phase,
+      checked: task.done === true,
+      requirement_ids: uniqueStrings(task.reqs),
+      required_sensors: uniqueStrings(task.sensors ?? (task.sensor ? [task.sensor] : [])),
+      required_artifacts: requiredArtifacts,
+      dependencies,
+      binding,
+      artifact_specs: requiredArtifacts.map((name) => artifactSpecs.get(name) ?? { name }),
+    };
+    return {
+      schema_version: 1,
+      contract_id: sha256(`${projectId}\0${changeSlug}\0${taskId}`),
+      task_id: taskId,
+      change_slug: changeSlug,
+      title: authored.title,
+      phase,
+      status: task.done === true ? 'pending-evaluation' : (dependencies.length ? 'blocked' : 'ready'),
+      inputs: uniqueStrings(task.inputs),
+      expected_outputs: uniqueStrings(task.expectedOutputs),
+      acceptance_criteria: uniqueStrings(task.acceptanceCriteria ?? [authored.title]),
+      requirement_ids: authored.requirement_ids,
+      required_sensors: authored.required_sensors,
+      required_artifacts: authored.required_artifacts,
+      dependencies,
+      owner: activeLease?.owner_session_id ?? null,
+      work_session_id: activeLease?.owner_work_session_id ?? null,
+      evidence_envelope_id: input.evidenceEnvelopeId ?? null,
+      checked: authored.checked,
+      authored_sha256: sha256(canonicalJson(authored)),
+      binding,
+    };
+  });
+}
+
+function taskFinding(code, field, expected, observed) {
+  return {
+    code,
+    field,
+    expected: expected ?? null,
+    observed: observed ?? null,
+    recovery: 'rebuild and re-evaluate the task contract in the active context',
+  };
+}
+
+export function evaluateTaskContract(contract, options = {}) {
+  const currentBinding = options.currentBinding ?? contract.binding ?? {};
+  const blockingFindings = [];
+  for (const [field, code] of BINDING_FIELDS) {
+    if (String(contract.binding?.[field] ?? '') !== String(currentBinding?.[field] ?? '')) {
+      blockingFindings.push(taskFinding(code, field, contract.binding?.[field], currentBinding?.[field]));
+    }
+  }
+  if (contract.checked !== true) {
+    blockingFindings.push(taskFinding('TASK_CHECKBOX_OPEN', 'checked', true, contract.checked === true));
+  }
+
+  const availableRequirements = new Set(uniqueStrings(options.availableRequirementIds));
+  const missingRequirements = uniqueStrings(contract.requirement_ids).filter((id) => !availableRequirements.has(id));
+  const sensors = new Map((options.sensorResults ?? []).map((sensor) => [String(sensor.id || ''), sensor]));
+  const missingSensors = uniqueStrings(contract.required_sensors)
+    .filter((id) => sensors.get(id)?.status !== 'green');
+  const artifacts = new Map((options.artifactResults ?? []).map((artifact) => [String(artifact.name || ''), artifact]));
+  const missingArtifacts = uniqueStrings(contract.required_artifacts)
+    .filter((name) => artifacts.get(name)?.satisfied !== true);
+  const completedTasks = new Set(uniqueStrings(options.completedTaskIds));
+  const openDependencies = uniqueStrings(contract.dependencies).filter((id) => !completedTasks.has(id));
+
+  for (const id of missingRequirements) blockingFindings.push(taskFinding('TASK_REQUIREMENT_MISSING', 'requirement_ids', id, null));
+  for (const id of missingSensors) blockingFindings.push(taskFinding('TASK_SENSOR_MISSING_OR_RED', 'required_sensors', id, sensors.get(id)?.status ?? null));
+  for (const name of missingArtifacts) blockingFindings.push(taskFinding('TASK_ARTIFACT_MISSING', 'required_artifacts', name, null));
+  for (const id of openDependencies) blockingFindings.push(taskFinding('TASK_DEPENDENCY_OPEN', 'dependencies', id, null));
+
+  const canComplete = blockingFindings.length === 0;
+  return {
+    task_id: contract.task_id,
+    contract_id: contract.contract_id,
+    phase: contract.phase || 'execute',
+    can_complete: canComplete,
+    status: canComplete ? 'completed' : (blockingFindings.some((finding) => finding.code.startsWith('TASK_CONTRACT_STALE_')) ? 'stale' : 'blocked'),
+    missing_requirements: missingRequirements,
+    missing_sensors: missingSensors,
+    missing_artifacts: missingArtifacts,
+    open_dependencies: openDependencies,
+    blocking_findings: blockingFindings,
+  };
+}
+
+function artifactError(code, message, details = {}) {
+  return Object.assign(new Error(message), { code, ...details });
+}
+
+function insideRoot(root, target) {
+  const rel = relative(root, target);
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+
+function safeRelativePath(projectRoot, value) {
+  const raw = String(value || '').replaceAll('\\', '/');
+  if (!raw || isAbsolute(raw) || raw.split('/').includes('..')) {
+    throw artifactError('TASK_ARTIFACT_PATH_ESCAPE', `artifact path escapes project: ${raw}`);
+  }
+  const root = realpathSync(projectRoot);
+  const target = resolve(root, raw);
+  if (!insideRoot(root, target)) throw artifactError('TASK_ARTIFACT_PATH_ESCAPE', `artifact path escapes project: ${raw}`);
+  if (existsSync(target)) {
+    const real = realpathSync(target);
+    if (!insideRoot(root, real)) throw artifactError('TASK_ARTIFACT_PATH_ESCAPE', `artifact target escapes project: ${raw}`);
+  }
+  return { raw, root, target };
+}
+
+function globRegExp(pattern) {
+  let source = '';
+  const normalized = String(pattern || '').replaceAll('\\', '/');
+  for (let index = 0; index < normalized.length; index += 1) {
+    const char = normalized[index];
+    if (char === '*' && normalized[index + 1] === '*') {
+      index += 1;
+      if (normalized[index + 1] === '/') {
+        index += 1;
+        source += '(?:.*/)?';
+      } else source += '.*';
+    } else if (char === '*') source += '[^/]*';
+    else if (char === '?') source += '[^/]';
+    else source += char.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+function scanProject(projectRoot, limits = {}) {
+  const root = realpathSync(projectRoot);
+  const maxEntries = Number.isSafeInteger(limits.maxEntries) ? limits.maxEntries : 10_000;
+  const timeoutMs = Number.isFinite(limits.timeoutMs) ? limits.timeoutMs : 2_000;
+  const started = Date.now();
+  const files = [];
+  const walk = (dir, prefix = '') => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (Date.now() - started > timeoutMs) throw artifactError('TASK_ARTIFACT_SCAN_TIMEOUT', 'artifact scan timed out');
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name)) continue;
+      const absolute = resolve(dir, entry.name);
+      if (entry.isSymbolicLink()) {
+        const real = realpathSync(absolute);
+        if (!insideRoot(root, real)) throw artifactError('TASK_ARTIFACT_PATH_ESCAPE', `artifact symlink escapes project: ${rel}`);
+        continue;
+      }
+      if (entry.isDirectory()) walk(absolute, rel);
+      else {
+        files.push(rel.replaceAll('\\', '/'));
+        if (files.length > maxEntries) throw artifactError('TASK_ARTIFACT_SCAN_LIMIT', `artifact scan exceeded ${maxEntries} entries`);
+      }
+    }
+  };
+  walk(root);
+  return files;
+}
+
+export function evaluateArtifactSpecs({ projectRoot, specs = [], registeredArtifacts = [], limits = {} } = {}) {
+  const registered = new Map(registeredArtifacts.map((artifact) => [String(artifact.name || ''), artifact]));
+  let files = null;
+  const results = specs.map((spec) => {
+    const name = String(spec.name || '').trim();
+    const type = String(spec.type || '').trim();
+    if (!name || !['name', 'path', 'glob', 'file-count'].includes(type)) {
+      throw artifactError('TASK_ARTIFACT_SPEC_INVALID', `invalid artifact spec: ${name || '(unnamed)'}`);
+    }
+    if (registered.has(name)) return { name, type, satisfied: true, count: 1, source: 'registered' };
+    if (type === 'name') return { name, type, satisfied: false, count: 0, source: 'registry' };
+    if (spec.fromFilesystem !== true) return { name, type, satisfied: false, count: 0, source: 'filesystem-disabled' };
+
+    if (type === 'path') {
+      const checked = safeRelativePath(projectRoot, spec.path);
+      const satisfied = existsSync(checked.target) && !lstatSync(checked.target).isSymbolicLink();
+      return { name, type, satisfied, count: satisfied ? 1 : 0, source: 'filesystem' };
+    }
+
+    safeRelativePath(projectRoot, spec.glob);
+    files ??= scanProject(projectRoot, limits);
+    const matcher = globRegExp(spec.glob);
+    const count = files.filter((file) => matcher.test(file)).length;
+    if (type === 'glob') return { name, type, satisfied: count > 0, count, source: 'filesystem' };
+    const min = Number.isSafeInteger(spec.min) ? spec.min : 1;
+    const max = Number.isSafeInteger(spec.max) ? spec.max : Number.POSITIVE_INFINITY;
+    return { name, type, satisfied: count >= min && count <= max, count, source: 'filesystem' };
+  });
+  return { ok: results.every((result) => result.satisfied), results };
+}
+
+function readJson(path, fallback) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) {
+    if (error?.code === 'ENOENT') return fallback;
+    throw Object.assign(new Error(`invalid JSON: ${path}`), { code: 'TASK_CONTRACT_JSON_INVALID', cause: error });
+  }
+}
+
+function artifactManifest(changeDir) {
+  const path = join(changeDir, 'artifacts.json');
+  const raw = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const parsed = raw ? readJson(path, {}) : {};
+  if (raw && (parsed?.schema_version !== 1 || !Array.isArray(parsed?.artifacts))) {
+    throw Object.assign(new Error('artifacts.json must use schema_version 1 and an artifacts array'), {
+      code: 'TASK_ARTIFACT_MANIFEST_INVALID',
+    });
+  }
+  return { raw, specs: parsed?.artifacts ?? [], hash: contentHashOf(raw) };
+}
+
+export function buildTaskContractSnapshot({
+  vaultBase,
+  projectRoot,
+  changeSlug,
+  identity,
+  context = null,
+  registeredArtifacts = [],
+  artifactLimits,
+} = {}) {
+  const slug = String(changeSlug || '').trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(slug)) {
+    throw Object.assign(new Error(`invalid change slug: ${slug}`), { code: 'TASK_CHANGE_INVALID' });
+  }
+  const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
+  let tarefasMd;
+  try { tarefasMd = readFileSync(join(changeDir, 'tarefas.md'), 'utf8'); }
+  catch (error) {
+    throw Object.assign(new Error(`change not found: ${slug}`), { code: 'TASK_CHANGE_NOT_FOUND', cause: error });
+  }
+  const tasks = parseTasks(tarefasMd);
+  const reqIds = uniqueStrings(tasks.flatMap((task) => task.reqs ?? []));
+  const effective = buildEffectiveRequirementPackage(vaultBase, changeDir, reqIds);
+  const manifest = artifactManifest(changeDir);
+  const evidence = readJson(join(changeDir, 'evidencia.json'), null);
+  const causalContext = context || resolveActiveContext(vaultBase, identity);
+  const binding = {
+    projectId: identity.projectId,
+    activeContextId: activeContextKey(identity),
+    headSha: identity.headSha,
+    tasksSha256: tasksHashOf(tarefasMd),
+    effectiveSpecSha256: effective.hash,
+    artifactManifestSha256: manifest.hash,
+  };
+  const contracts = deriveTaskContracts({
+    ...binding,
+    changeSlug: slug,
+    tasks,
+    artifactSpecs: manifest.specs,
+    taskLeases: causalContext?.task_leases ?? {},
+    evidenceEnvelopeId: evidence?.envelope_id ?? null,
+  });
+  const artifactEvaluation = evaluateArtifactSpecs({
+    projectRoot,
+    specs: manifest.specs,
+    registeredArtifacts,
+    limits: artifactLimits,
+  });
+  return {
+    schema_version: 1,
+    change_slug: slug,
+    binding: bindingFrom(binding),
+    contracts,
+    requirement_ids: effective.requirements.map((requirement) => requirement.id).filter(Boolean),
+    missing_requirement_ids: effective.missing,
+    sensor_results: evidence?.sensors ?? [],
+    evidence_envelope_id: evidence?.envelope_id ?? null,
+    artifact_results: artifactEvaluation.results,
+  };
+}
+
+export function evaluateTaskContracts(snapshot) {
+  const completed = new Set();
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const contract of snapshot.contracts ?? []) {
+      if (completed.has(contract.task_id)) continue;
+      const result = evaluateTaskContract(contract, {
+        currentBinding: snapshot.binding,
+        availableRequirementIds: snapshot.requirement_ids,
+        sensorResults: snapshot.sensor_results,
+        artifactResults: snapshot.artifact_results,
+        completedTaskIds: [...completed],
+      });
+      if (result.can_complete) {
+        completed.add(contract.task_id);
+        changed = true;
+      }
+    }
+  }
+  return (snapshot.contracts ?? []).map((contract) => evaluateTaskContract(contract, {
+    currentBinding: snapshot.binding,
+    availableRequirementIds: snapshot.requirement_ids,
+    sensorResults: snapshot.sensor_results,
+    artifactResults: snapshot.artifact_results,
+    completedTaskIds: [...completed].filter((id) => id !== contract.task_id),
+  }));
+}
+
+export function deriveHandoffContract(input = {}) {
+  const contract = {
+    schema_version: 1,
+    from: String(input.from || ''),
+    to: String(input.to || ''),
+    active_context_id: String(input.activeContextId || ''),
+    task_id: String(input.taskId || ''),
+    task_contract_id: String(input.taskContractId || ''),
+    artifacts: uniqueStrings(input.artifacts),
+    evidence: uniqueStrings(input.evidence),
+    decisions: uniqueStrings(input.decisions),
+    next_actions: uniqueStrings(input.nextActions),
+    blockers: uniqueStrings(input.blockers),
+    head_sha: String(input.headSha || ''),
+    tasks_sha256: String(input.tasksSha256 || ''),
+    spec_sha256: String(input.specSha256 || ''),
+    authority: 'verified',
+  };
+  for (const field of ['from', 'to', 'active_context_id', 'head_sha', 'tasks_sha256', 'spec_sha256']) {
+    if (!contract[field]) {
+      throw Object.assign(new Error(`handoff field is required: ${field}`), { code: 'HANDOFF_CONTRACT_INVALID' });
+    }
+  }
+  contract.handoff_id = sha256(canonicalJson(contract));
+  return contract;
+}
+
+export function normalizeHandoffContract(value) {
+  if (typeof value === 'string') {
+    const summary = value.trim();
+    return summary ? { schema_version: 0, authority: 'legacy-reported', summary } : null;
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  if (value.schema_version !== 1) {
+    const summary = String(value.summary || '').trim();
+    return summary ? { schema_version: 0, authority: 'legacy-reported', summary } : null;
+  }
+  const normalized = {
+    schema_version: 1,
+    handoff_id: String(value.handoff_id || ''),
+    from: String(value.from || ''),
+    to: String(value.to || ''),
+    active_context_id: String(value.active_context_id || ''),
+    task_id: String(value.task_id || ''),
+    task_contract_id: String(value.task_contract_id || ''),
+    artifacts: uniqueStrings(value.artifacts),
+    evidence: uniqueStrings(value.evidence),
+    decisions: uniqueStrings(value.decisions),
+    next_actions: uniqueStrings(value.next_actions),
+    blockers: uniqueStrings(value.blockers),
+    head_sha: String(value.head_sha || ''),
+    tasks_sha256: String(value.tasks_sha256 || ''),
+    spec_sha256: String(value.spec_sha256 || ''),
+    authority: value.authority === 'verified' ? 'verified' : 'reported',
+  };
+  if (!normalized.handoff_id || !normalized.active_context_id || !normalized.head_sha
+    || !normalized.tasks_sha256 || !normalized.spec_sha256) {
+    throw Object.assign(new Error('structured handoff is incomplete'), { code: 'HANDOFF_CONTRACT_INVALID' });
+  }
+  return normalized;
+}
+
+export function evaluateHandoffContract(contract, current = {}) {
+  if (!contract || contract.schema_version !== 1) {
+    return { state: 'legacy-reported', blocking_findings: [] };
+  }
+  const findings = [];
+  for (const [field, code] of [
+    ['head_sha', 'HANDOFF_STALE_HEAD'],
+    ['tasks_sha256', 'HANDOFF_STALE_TASKS'],
+    ['spec_sha256', 'HANDOFF_STALE_SPEC'],
+  ]) {
+    if (String(contract[field] || '') !== String(current[field] || '')) findings.push({ code, field });
+  }
+  return { state: findings.length ? 'stale' : 'verified', blocking_findings: findings };
+}
+
+export function assertStructuredHandoffForProfile(profile, contract) {
+  if (String(profile || '').toUpperCase() === 'ASSURE'
+    && (!contract || contract.schema_version !== 1 || contract.authority !== 'verified')) {
+    throw Object.assign(new Error('ASSURE requires a verified structured handoff'), {
+      code: 'HANDOFF_STRUCTURED_REQUIRED',
+    });
+  }
+  return contract;
+}
+
+export function buildStructuredTaskHandoff({
+  profile = 'GOVERN',
+  sessionId = '',
+  snapshot = null,
+  evaluations = [],
+  context = {},
+  shared = null,
+} = {}) {
+  const base = shared && typeof shared === 'object' && !Array.isArray(shared) ? { ...shared } : {};
+  if (!snapshot) {
+    assertStructuredHandoffForProfile(profile, null);
+    return Object.keys(base).length ? base : null;
+  }
+  const activeLease = Object.values(context?.task_leases || {}).find((lease) => (
+    lease?.state === 'active' && lease.owner_session_id === String(sessionId)
+  ));
+  const selectedEvaluation = evaluations.find((item) => item.task_id === activeLease?.task_id)
+    || evaluations.find((item) => !item.can_complete)
+    || evaluations[0]
+    || null;
+  const selectedContract = snapshot.contracts?.find((item) => item.task_id === selectedEvaluation?.task_id)
+    || snapshot.contracts?.[0]
+    || null;
+  const blockers = uniqueStrings([
+    ...uniqueStrings(base.blockers),
+    ...(selectedEvaluation?.blocking_findings ?? []).map((finding) => finding.code),
+  ]);
+  const contract = deriveHandoffContract({
+    from: sessionId,
+    to: base.to || 'next-session',
+    activeContextId: snapshot.binding?.active_context_id,
+    taskId: selectedContract?.task_id || '',
+    taskContractId: selectedContract?.contract_id || '',
+    artifacts: (snapshot.artifact_results ?? []).filter((item) => item.satisfied).map((item) => item.name),
+    evidence: snapshot.evidence_envelope_id ? [snapshot.evidence_envelope_id] : [],
+    decisions: base.decisions,
+    nextActions: base.next_actions,
+    blockers,
+    headSha: snapshot.binding?.head_sha,
+    tasksSha256: snapshot.binding?.tasks_sha256,
+    specSha256: snapshot.binding?.effective_spec_sha256,
+  });
+  assertStructuredHandoffForProfile(profile, contract);
+  return {
+    ...base,
+    tasks_hash: snapshot.binding.tasks_sha256,
+    spec_hash: snapshot.binding.effective_spec_sha256,
+    handoff_contract: contract,
+  };
+}

package/src/task-leases.mjs

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { activeContextKey } from '../hooks/active-context-store.mjs';
+import { mutateSessionRegistry } from '../hooks/obsidian-common.mjs';
+
+function leaseError(code, message, details = {}) {
+  return Object.assign(new Error(message), { code, ...details });
+}
+
+function contextsOf(registry) {
+  return registry.active_contexts && typeof registry.active_contexts === 'object'
+    && !Array.isArray(registry.active_contexts) ? registry.active_contexts : {};
+}
+
+function leaseKey(changeSlug, taskId) {
+  return `${String(changeSlug)}:${String(taskId)}`;
+}
+
+function expiresAt(lease) {
+  const value = Date.parse(String(lease?.expires_at || ''));
+  return Number.isFinite(value) ? value : 0;
+}
+
+function bumpContext(context, now) {
+  context.revision = Number.isSafeInteger(Number(context.revision)) ? Number(context.revision) + 1 : 1;
+  context.updated_at = now.toISOString();
+}
+
+export function claimTaskLease({
+  vaultBase,
+  identity,
+  changeSlug,
+  taskId,
+  ownerSessionId,
+  leaseSeconds = 900,
+  now = new Date(),
+} = {}) {
+  const key = leaseKey(changeSlug, taskId);
+  const contextKey = activeContextKey(identity);
+  const duration = Number(leaseSeconds);
+  if (!Number.isSafeInteger(duration) || duration < 1 || duration > 86_400) {
+    throw leaseError('TASK_LEASE_DURATION_INVALID', 'lease duration must be between 1 and 86400 seconds');
+  }
+  return mutateSessionRegistry(vaultBase, (registry) => {
+    const contexts = contextsOf(registry);
+    const target = contexts[contextKey];
+    if (!target || target.state !== 'active') throw leaseError('TASK_ACTIVE_CONTEXT_NOT_FOUND', 'active context not found');
+    if (String(target.change_slug || '') !== String(changeSlug || '')) {
+      throw leaseError('TASK_CHANGE_CONTEXT_MISMATCH', 'task change differs from active context');
+    }
+
+    for (const context of Object.values(contexts)) {
+      const existing = context?.task_leases?.[key];
+      if (!existing || existing.state !== 'active') continue;
+      if (expiresAt(existing) <= now.getTime()) {
+        existing.state = 'expired';
+        existing.expired_at = now.toISOString();
+        bumpContext(context, now);
+        continue;
+      }
+      if (existing.owner_session_id === String(ownerSessionId)
+        && existing.owner_work_session_id === identity.workSessionId) return structuredClone(existing);
+      throw leaseError('TASK_LEASE_CONFLICT', `task ${taskId} is claimed by another active session`, {
+        owner_session_id: existing.owner_session_id,
+      });
+    }
+
+    const lease = {
+      schema_version: 1,
+      lease_id: randomUUID(),
+      change_slug: String(changeSlug),
+      task_id: String(taskId),
+      owner_session_id: String(ownerSessionId),
+      owner_work_session_id: String(identity.workSessionId),
+      state: 'active',
+      claimed_at: now.toISOString(),
+      expires_at: new Date(now.getTime() + duration * 1000).toISOString(),
+    };
+    target.task_leases = { ...(target.task_leases || {}), [key]: lease };
+    bumpContext(target, now);
+    registry.active_contexts_revision = Number(registry.active_contexts_revision || 0) + 1;
+    return structuredClone(lease);
+  });
+}
+
+export function releaseTaskLease({ vaultBase, identity, changeSlug, taskId, ownerSessionId, now = new Date() } = {}) {
+  const key = leaseKey(changeSlug, taskId);
+  return mutateSessionRegistry(vaultBase, (registry) => {
+    const contexts = contextsOf(registry);
+    let found = null;
+    for (const context of Object.values(contexts)) {
+      const lease = context?.task_leases?.[key];
+      if (lease?.state === 'active') { found = { context, lease }; break; }
+    }
+    if (!found) throw leaseError('TASK_LEASE_NOT_FOUND', `no active lease for task ${taskId}`);
+    if (found.lease.owner_session_id !== String(ownerSessionId)
+      || found.lease.owner_work_session_id !== identity.workSessionId) {
+      throw leaseError('TASK_LEASE_NOT_OWNER', `session does not own task ${taskId}`);
+    }
+    found.lease.state = 'released';
+    found.lease.released_at = now.toISOString();
+    bumpContext(found.context, now);
+    registry.active_contexts_revision = Number(registry.active_contexts_revision || 0) + 1;
+    return structuredClone(found.lease);
+  });
+}