wendkeep 0.66.4 → 0.67.0

package/hooks/subagent-stop.mjs

@@ -8,29 +8,283 @@
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
-import { readHookInput, writeHookOutput, getVaultBase, providerMeta } from './obsidian-common.mjs';
-import { updateSessionObservability } from './session-observability.mjs';
+import {
+  getVaultBase,
+  mutateSessionRegistry,
+  providerMeta,
+  readHookInput,
+  writeHookOutput,
+} from './obsidian-common.mjs';
+import { materializeSessionObservability } from './session-observability.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
+import { readCodexRolloutMeta } from './codex-rollout-meta.mjs';
+import { resolveObservabilityRoots } from './session-observability-lifecycle.mjs';
+import {
+  readObservabilityStore,
+  markObservabilityCheckpoint,
+  recordObservabilitySignal,
+  releaseObservabilityLease,
+  tryAcquireObservabilityLease,
+} from './session-observability-store.mjs';
 
-export function refreshSubagents(vaultBase, input) {
-  const { identity, entry } = resolveSessionEntry(vaultBase, input, providerMeta(input.provider).id);
+const SUBAGENT_COALESCE_MS = 250;
+const SUBAGENT_DEADLINE_MS = 15_000;
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function causalSnapshot(entry) {
+  const activationId = String(entry?.active_activation_id || '');
+  const activation = entry?.activations?.[activationId] || {};
+  return {
+    activationId,
+    activationEpoch: Number(activation.epoch || entry?.activation_epoch || 0),
+    turnSequence: Number(entry?.last_turn_sequence || activation.last_turn_sequence || 0),
+  };
+}
+
+function sameCausalSnapshot(left, right) {
+  return left.activationId === right.activationId
+    && left.activationEpoch === right.activationEpoch
+    && left.turnSequence === right.turnSequence;
+}
+
+function defaultMaterialize(request) {
+  return materializeSessionObservability({
+    vaultBase: request.vaultBase,
+    sessionPath: request.sessionPath,
+    transcriptPath: request.transcriptPath,
+    entry: request.entry,
+    canonicalConversationId: request.canonicalConversationId,
+    frontier: request.frontier,
+    signals: request.signals,
+    cache: request.cache,
+    mode: 'live',
+    deadlineAt: request.deadlineAt,
+    now: request.now,
+    allowNone: request.allowNone,
+    readRuntimeFrontier: request.readRuntimeFrontier,
+    withPublicationGuard: request.withPublicationGuard,
+    writeRegistryCheckpoint: request.writeRegistryCheckpoint,
+  });
+}
+
+function claudeRoots(entry) {
+  const paths = new Set();
+  const add = (value) => {
+    if (typeof value === 'string' && value.trim()) paths.add(value.trim());
+  };
+  add(entry?.transcript_path);
+  for (const path of entry?.transcript_paths || []) add(path);
+  for (const activation of Object.values(entry?.activations || {})) {
+    add(activation?.transcript_path);
+    for (const path of activation?.transcript_paths || []) add(path);
+  }
+  return { state: 'complete', rootPaths: [...paths], descendantPaths: [], diagnostics: [] };
+}
+
+export async function refreshSubagents(vaultBase, input, {
+  now = Date.now,
+  hookStartedAt = now(),
+  sleep = wait,
+  coalesceMs = SUBAGENT_COALESCE_MS,
+  deadlineMs = SUBAGENT_DEADLINE_MS,
+  resolveEntry = resolveSessionEntry,
+  readMeta = readCodexRolloutMeta,
+  mutateRegistry = mutateSessionRegistry,
+  recordSignal = recordObservabilitySignal,
+  readStore = readObservabilityStore,
+  acquireLease = tryAcquireObservabilityLease,
+  releaseLease = releaseObservabilityLease,
+  resolveRoots = resolveObservabilityRoots,
+  materialize = defaultMaterialize,
+} = {}) {
+  const deadlineAt = hookStartedAt + deadlineMs;
+  const provider = providerMeta(input.provider).id;
+  const { identity, entry } = resolveEntry(vaultBase, input, provider);
   if (identity.state !== 'resolved') return false;
-  const transcriptPath = identity.transcriptPath;
+  const childTranscriptPath = identity.transcriptPath;
   const sessionRel = entry?.session_file || '';
   if (!sessionRel) return false;
-  const sessionPath = join(vaultBase, sessionRel);
-  if (!existsSync(sessionPath)) return false;
-  updateSessionObservability({
-    vaultBase, sessionPath, transcriptPath, caller: 'subagent-stop',
-    canonicalConversationId: identity.canonicalConversationId,
+
+  let childParentThreadId = '';
+  if (identity.provider === 'codex') {
+    const childMeta = readMeta(childTranscriptPath);
+    if (!childMeta?.ok || !childMeta.meta?.source?.subagent) return false;
+    if (!childMeta.meta.id || childMeta.meta.id !== identity.transcriptId) return false;
+    if (childMeta.meta.session_id
+      && childMeta.meta.session_id !== identity.canonicalConversationId) return false;
+    childParentThreadId = String(
+      childMeta.meta.parent_thread_id
+      || childMeta.meta.source?.subagent?.thread_spawn?.parent_thread_id
+      || '',
+    );
+  }
+
+  const observed = causalSnapshot(entry);
+  const signal = mutateRegistry(vaultBase, (registry) => {
+    const current = registry.sessions?.[identity.canonicalConversationId];
+    if (!current || current.session_file !== sessionRel
+      || !sameCausalSnapshot(observed, causalSnapshot(current))) return null;
+    const recorded = recordSignal(vaultBase, identity.canonicalConversationId, {
+      rollout_id: identity.transcriptId,
+      transcript_path: childTranscriptPath,
+      parent_thread_id: childParentThreadId,
+      kind: 'started',
+      activation_id: observed.activationId,
+      activation_epoch: observed.activationEpoch,
+      turn_sequence: observed.turnSequence,
+    });
+    if (!recorded?.state) return recorded;
+    registry.sessions[identity.canonicalConversationId] = {
+      ...current,
+      observability_signal_sequence: recorded.sequence,
+      observability_checkpoint_sequence: Number(
+        recorded.state.observability_checkpoint_sequence
+        ?? current.observability_checkpoint_sequence
+        ?? 0,
+      ),
+      observability_dirty: Boolean(recorded.state.observability_dirty),
+    };
+    return recorded;
+  });
+  if (!signal?.state) return false;
+  if (!signal.state.observability_dirty) return true;
+
+  await sleep(coalesceMs);
+  if (now() >= deadlineAt) return true;
+
+  const latest = readStore(vaultBase, identity.canonicalConversationId);
+  if (!latest?.observability_dirty
+    || latest.observability_signal_sequence !== signal.sequence) return true;
+
+  const leaseNow = now();
+  if (leaseNow >= deadlineAt) return true;
+  const lease = acquireLease(vaultBase, identity.canonicalConversationId, {
+    signalSequence: signal.sequence,
+    now: leaseNow,
+    ttlMs: Math.max(1, deadlineAt - leaseNow),
   });
-  return true;
+  if (!lease?.acquired) return true;
+
+  try {
+    if (now() >= deadlineAt) return true;
+    const fresh = resolveEntry(vaultBase, input, provider);
+    if (fresh.identity?.state !== 'resolved'
+      || fresh.identity.canonicalConversationId !== identity.canonicalConversationId
+      || !fresh.entry?.session_file
+      || !sameCausalSnapshot(observed, causalSnapshot(fresh.entry))) return true;
+
+    const sessionPath = join(vaultBase, fresh.entry.session_file);
+    if (!existsSync(sessionPath)) return true;
+    const roots = identity.provider === 'codex'
+      ? resolveRoots(fresh.entry)
+      : claudeRoots(fresh.entry);
+    if (roots?.state !== 'complete' || !roots.rootPaths?.length) return true;
+
+    const runtimeState = lease.state || latest;
+    const frontier = {
+      canonical_session_id: identity.canonicalConversationId,
+      activation_id: observed.activationId || 'legacy',
+      activation_epoch: observed.activationEpoch,
+      turn_sequence: observed.turnSequence,
+      signal_sequence: signal.sequence,
+      roots_stat_hash: 'pending',
+      graph_cursor: 'pending',
+      source_manifest_hash: 'pending',
+    };
+    const readRuntimeFrontier = (candidateFrontier, guardContext) => {
+      const currentRuntime = readStore(vaultBase, identity.canonicalConversationId);
+      const currentEntry = guardContext?.entry;
+      const currentResolved = currentEntry
+        ? { identity: { state: 'resolved', canonicalConversationId: identity.canonicalConversationId }, entry: currentEntry }
+        : resolveEntry(vaultBase, input, provider);
+      if (currentResolved.identity?.state !== 'resolved'
+        || currentResolved.identity.canonicalConversationId !== identity.canonicalConversationId
+        || !currentResolved.entry) {
+        return { ...candidateFrontier, canonical_session_id: 'unresolved' };
+      }
+      const currentCausal = causalSnapshot(currentResolved.entry);
+      return {
+        ...candidateFrontier,
+        activation_id: currentCausal.activationId || 'legacy',
+        activation_epoch: currentCausal.activationEpoch,
+        turn_sequence: currentCausal.turnSequence,
+        signal_sequence: Math.max(
+          Number(currentRuntime?.observability_signal_sequence || 0),
+          Number(currentResolved.entry.observability_signal_sequence || 0),
+        ),
+      };
+    };
+    const withPublicationGuard = (_candidateFrontier, publishGuarded) => (
+      mutateRegistry(vaultBase, (registry) => publishGuarded({
+        registry,
+        entry: registry.sessions?.[identity.canonicalConversationId] || null,
+      }))
+    );
+    const writeRegistryCheckpoint = ({
+      frontier: checkpointFrontier,
+      state,
+      diagnostics,
+      snapshot,
+    }, guardContext) => {
+      const registry = guardContext?.registry;
+      const current = registry?.sessions?.[identity.canonicalConversationId];
+      if (!current) return null;
+      const currentSignal = Number(current.observability_signal_sequence || checkpointFrontier.signal_sequence);
+      registry.sessions[identity.canonicalConversationId] = {
+        ...current,
+        observability_signal_sequence: currentSignal,
+        observability_checkpoint_sequence: checkpointFrontier.signal_sequence,
+        observability_dirty: currentSignal > checkpointFrontier.signal_sequence,
+        observability_checkpoint_frontier: checkpointFrontier,
+        subagents_observability_state: state,
+        subagents_diagnostics: diagnostics || [],
+      };
+      return markObservabilityCheckpoint(vaultBase, identity.canonicalConversationId, {
+        checkpointSequence: checkpointFrontier.signal_sequence,
+        frontier: checkpointFrontier,
+        sourceManifest: snapshot?.subagents?.sourceManifest,
+        graphCache: snapshot?.subagents?.cache,
+        diagnostics,
+      });
+    };
+
+    await Promise.resolve(materialize({
+      vaultBase,
+      sessionPath,
+      entry: fresh.entry,
+      rootPaths: roots.rootPaths,
+      transcriptPath: roots.rootPaths[0],
+      caller: 'subagent-stop',
+      canonicalConversationId: identity.canonicalConversationId,
+      activationId: observed.activationId,
+      activationEpoch: observed.activationEpoch,
+      turnSequence: observed.turnSequence,
+      signalSequence: signal.sequence,
+      deadlineAt,
+      allowNone: false,
+      frontier,
+      signals: runtimeState.signals || [],
+      cache: runtimeState.graph_cache || null,
+      now,
+      readRuntimeFrontier,
+      withPublicationGuard,
+      writeRegistryCheckpoint,
+    }));
+    return true;
+  } finally {
+    releaseLease(vaultBase, identity.canonicalConversationId, {
+      ownerToken: lease.ownerToken,
+      signalSequence: signal.sequence,
+    });
+  }
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
+    const hookStartedAt = Date.now();
     const input = readHookInput();
-    refreshSubagents(getVaultBase(input), input);
+    await refreshSubagents(getVaultBase(input), input, { hookStartedAt });
     writeHookOutput({});
   } catch (error) {
     process.stderr.write(`[wendkeep] subagent-stop falhou: ${error.message}\n`);

package/hooks/subagent-usage.mjs

@@ -29,6 +29,49 @@ function walkAgentJsonl(dir) {
   return out;
 }
 
+function inspectAgentJsonlDirectory(dir) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (error) {
+    return { state: error?.code === 'ENOENT' ? 'absent' : 'error', files: [] };
+  }
+  const files = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    let stat;
+    try {
+      stat = statSync(path);
+    } catch {
+      return { state: 'error', files: [] };
+    }
+    if (stat.isDirectory()) {
+      const nested = inspectAgentJsonlDirectory(path);
+      if (nested.state === 'error' || nested.state === 'absent') return { state: 'error', files: [] };
+      files.push(...nested.files);
+    } else if (name.startsWith('agent-') && name.endsWith('.jsonl')) {
+      files.push(path);
+    }
+  }
+  return { state: 'ok', files };
+}
+
+function validJsonl(path) {
+  let lines;
+  try {
+    lines = readFileSync(path, 'utf8').split(/\r?\n/).filter((line) => line.trim());
+  } catch {
+    return false;
+  }
+  if (!lines.length) return false;
+  try {
+    for (const line of lines) JSON.parse(line);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // workflows/scripts/<name>-wf_<rid>.js  ->  { wf_<rid>: <name> }
 function workflowNameMap(sessionDir) {
   const map = {};
@@ -276,6 +319,28 @@ export function collectSubagentUsage(sessionDir) {
   };
 }
 
+// Schema-2 callers need to distinguish proven absence from read/parse failure. Keep the
+// legacy aggregate API above intact while exposing a fail-closed state for observability.
+export function collectClaudeSubagentUsageState(sessionDir) {
+  const scan = inspectAgentJsonlDirectory(join(sessionDir, 'subagents'));
+  if (scan.state === 'absent' || (scan.state === 'ok' && scan.files.length === 0)) {
+    return { state: 'none', diagnostics: [] };
+  }
+  if (scan.state !== 'ok' || scan.files.some((path) => !validJsonl(path))) {
+    return {
+      state: 'degraded',
+      diagnostics: [{ code: 'CHILD_META_INVALID', count: 1 }],
+    };
+  }
+  const collected = collectSubagentUsage(sessionDir);
+  return collected
+    ? { ...collected, state: 'complete', diagnostics: [] }
+    : {
+      state: 'degraded',
+      diagnostics: [{ code: 'CHILD_META_INVALID', count: 1 }],
+    };
+}
+
 function workflowLine(w) {
   const parts = [w.runId];
   if (w.status) parts.push(w.status);

package/hooks/token-usage.mjs

@@ -510,16 +510,19 @@ function detectTranscriptFormat(lines) {
   return 'codex';
 }
 
-export function parseTokenUsageFromTranscript(transcriptPath) {
+export function parseTokenUsageFromContent(content, { transcriptPath = '' } = {}) {
   const result = emptyParseResult(transcriptPath);
-  if (!transcriptPath || !existsSync(transcriptPath)) return result;
-
-  const lines = readFileSync(transcriptPath, 'utf-8').split('\n').filter(Boolean);
+  const lines = String(content || '').split('\n').filter(Boolean);
   return detectTranscriptFormat(lines) === 'claude'
     ? parseClaudeLines(lines, result)
     : parseCodexLines(lines, result);
 }
 
+export function parseTokenUsageFromTranscript(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return emptyParseResult(transcriptPath);
+  return parseTokenUsageFromContent(readFileSync(transcriptPath, 'utf-8'), { transcriptPath });
+}
+
 function modelCost(usage, model) {
   const normalized = normalizeModelName(model);
   const price = PRICE_REFERENCE[normalized];
@@ -935,6 +938,80 @@ export function collectSessionUsage({ sessionContent, transcriptPath }) {
   };
 }
 
+function normalizedTranscriptKey(value) {
+  return String(value || '').replace(/\.jsonl?$/i, '').trim().toLowerCase();
+}
+
+// Rebuild the main bucket from every validated top-level rollout. Existing history is used
+// only to preserve stable timestamps; an entry that is neither a known root nor a proven
+// descendant makes the reconstruction fail closed instead of silently deleting a legitimate
+// reopening.
+export function collectSessionUsageForRoots({
+  sessionContent,
+  rootPaths = [],
+  descendantIds = [],
+} = {}) {
+  const fmMatch = String(sessionContent || '').match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+
+  const roots = [...new Set(rootPaths.filter(Boolean))].sort((a, b) => String(a).localeCompare(String(b)));
+  const rootKeys = new Set(roots.map((path) => normalizedTranscriptKey(transcriptIdFromPath(path))));
+  const descendantKeys = new Set(descendantIds.map(normalizedTranscriptKey).filter(Boolean));
+  const existingEntries = parseUsageHistory(fmMatch[1]);
+  const unresolved = existingEntries.filter((entry) => {
+    const key = normalizedTranscriptKey(entry.transcript_id);
+    return key && !rootKeys.has(key) && !descendantKeys.has(key);
+  });
+  if (unresolved.length) {
+    return {
+      state: 'degraded',
+      diagnostics: [{ code: 'MAIN_TRANSCRIPT_UNRESOLVED', count: unresolved.length }],
+      entries: existingEntries,
+      content: sessionContent,
+    };
+  }
+
+  const entries = [];
+  const summaries = [];
+  for (const transcriptPath of roots) {
+    if (!existsSync(transcriptPath)) {
+      return {
+        state: 'degraded',
+        diagnostics: [{ code: 'MAIN_TRANSCRIPT_UNRESOLVED', count: 1 }],
+        entries: existingEntries,
+        content: sessionContent,
+      };
+    }
+    const summary = summarizeTokenUsage(parseTokenUsageFromTranscript(transcriptPath));
+    if (!summary.calls) {
+      return {
+        state: 'degraded',
+        diagnostics: [{ code: 'MAIN_TRANSCRIPT_UNRESOLVED', count: 1 }],
+        entries: existingEntries,
+        content: sessionContent,
+      };
+    }
+    const transcriptId = transcriptIdFromPath(transcriptPath);
+    const current = entryFromSummary(summary, transcriptId);
+    const previous = existingEntries.find((entry) => normalizedTranscriptKey(entry.transcript_id) === normalizedTranscriptKey(transcriptId));
+    if (previous && sameUsageData(previous, current)) current.atualizado_em = previous.atualizado_em;
+    entries.push(current);
+    summaries.push(summary);
+  }
+
+  const agg = aggregateEntries(entries);
+  const content = upsertSessionFrontmatter(sessionContent, agg, entries);
+  if (content === null) return null;
+  return {
+    state: 'complete',
+    diagnostics: [],
+    summaries,
+    aggregate: agg,
+    entries,
+    content,
+  };
+}
+
 export function updateSessionUsage({ vaultBase, sessionRel, sessionPath, transcriptPath, lockTimeoutMs }) {
   if (!sessionPath || !existsSync(sessionPath)) return null;
   let result = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.66.4",
+  "version": "0.67.0",
   "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": [
@@ -40,7 +40,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "check": "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/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check hooks/operating-profile-runtime.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-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",
+    "check": "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/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.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-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",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run",
@@ -70,6 +70,6 @@
   },
   "devDependencies": {
     "acorn": "^8.18.0",
-    "wendkeep": "^0.57.2"
+    "wendkeep": "^0.66.5"
   }
 }

package/packages/harness/src/operating-profile.mjs

@@ -6,8 +6,16 @@ export const OPERATING_PROFILES = Object.freeze([
   'ASSURE',
 ]);
 export const DEFAULT_OPERATING_PROFILE = 'GOVERN';
+export const ADAPTIVE_OPERATING_PROFILES = Object.freeze([
+  'FLOW',
+  'GUIDE',
+  'GOVERN',
+  'ASSURE',
+]);
 
 const PROFILE_SET = new Set(OPERATING_PROFILES);
+const ADAPTIVE_PROFILE_SET = new Set(ADAPTIVE_OPERATING_PROFILES);
+export const TASK_PROFILE_REASON_MAX_LENGTH = 500;
 
 function policy(profile, route, options) {
   return Object.freeze({
@@ -70,6 +78,125 @@ function canonicalProfile(value) {
   return value.trim().toUpperCase();
 }
 
+function taskProfileError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function taskProfile(value) {
+  const profile = canonicalProfile(value);
+  if (ADAPTIVE_PROFILE_SET.has(profile)) return profile;
+  throw taskProfileError(
+    'WENDKEEP_TASK_PROFILE_INVALID',
+    `Perfil temporário inválido: ${typeof value === 'string' ? `"${value}"` : String(value)}. `
+      + `Use ${ADAPTIVE_OPERATING_PROFILES.join(', ')}; OFF exige seleção humana persistente.`,
+  );
+}
+
+function taskReason(value) {
+  const reason = typeof value === 'string' ? value.trim() : '';
+  if (reason && reason.length <= TASK_PROFILE_REASON_MAX_LENGTH) return reason;
+  throw taskProfileError(
+    'WENDKEEP_TASK_PROFILE_REASON_INVALID',
+    `Motivo da rota temporária deve ter entre 1 e ${TASK_PROFILE_REASON_MAX_LENGTH} caracteres.`,
+  );
+}
+
+function taskSequence(value) {
+  const sequence = Number(value);
+  return Number.isSafeInteger(sequence) && sequence > 0 ? sequence : null;
+}
+
+function taskContextError() {
+  return taskProfileError(
+    'WENDKEEP_TASK_PROFILE_CONTEXT_INVALID',
+    'Rota temporária exige sessão, prompt causal, lease id e timestamp válidos.',
+  );
+}
+
+export function createTaskOperatingProfileLease({
+  profile,
+  reason,
+  sessionId,
+  turnId = '',
+  turnSequence,
+  leaseId,
+  issuedAt,
+} = {}) {
+  const selected = taskProfile(profile);
+  const auditedReason = taskReason(reason);
+  const session = typeof sessionId === 'string' ? sessionId.trim() : '';
+  const requestTurnId = typeof turnId === 'string' ? turnId.trim() : '';
+  const sequence = taskSequence(turnSequence);
+  const id = typeof leaseId === 'string' ? leaseId.trim() : '';
+  const issued = typeof issuedAt === 'string' ? issuedAt.trim() : '';
+  if (!session || !requestTurnId || sequence === null || !id || !issued || !Number.isFinite(Date.parse(issued))) {
+    throw taskContextError();
+  }
+  return {
+    lease_id: id,
+    state: 'active',
+    profile: selected,
+    requested_by: 'llm-harness',
+    reason: auditedReason,
+    session_id: session,
+    request_turn_id: requestTurnId,
+    request_turn_sequence: sequence,
+    issued_at: issued,
+    expires_on: 'request-stop',
+  };
+}
+
+export function evaluateTaskOperatingProfileLease(lease, {
+  sessionId = '',
+  turnId = '',
+  turnSequence,
+} = {}) {
+  if (lease === undefined || lease === null) return { state: 'absent' };
+  if (!lease || typeof lease !== 'object' || Array.isArray(lease)) return { state: 'invalid' };
+
+  let normalized;
+  try {
+    normalized = createTaskOperatingProfileLease({
+      profile: lease.profile,
+      reason: lease.reason,
+      sessionId: lease.session_id,
+      turnId: lease.request_turn_id,
+      turnSequence: lease.request_turn_sequence,
+      leaseId: lease.lease_id,
+      issuedAt: lease.issued_at,
+    });
+  } catch {
+    return {
+      state: 'invalid',
+      ...(typeof lease.lease_id === 'string' && lease.lease_id ? { lease_id: lease.lease_id } : {}),
+    };
+  }
+  if (lease.requested_by !== 'llm-harness' || lease.expires_on !== 'request-stop') {
+    return { state: 'invalid', lease_id: normalized.lease_id };
+  }
+  if (lease.state === 'consumed' || lease.state === 'expired') {
+    return { ...lease, ...normalized, state: lease.state };
+  }
+  if (lease.state !== 'active') return { state: 'invalid', lease_id: normalized.lease_id };
+
+  const currentSession = typeof sessionId === 'string' ? sessionId.trim() : '';
+  const currentTurnId = typeof turnId === 'string' ? turnId.trim() : '';
+  const currentSequence = taskSequence(turnSequence);
+  if (!currentSession || !currentTurnId || currentSequence === null) {
+    return { ...normalized, state: 'invalid' };
+  }
+  if (normalized.session_id !== currentSession) {
+    return { ...normalized, state: 'invalid' };
+  }
+  const turnIdMismatch = normalized.request_turn_id !== currentTurnId;
+  if (turnIdMismatch || normalized.request_turn_sequence !== currentSequence) {
+    return { ...normalized, state: 'expired' };
+  }
+  return normalized;
+}
+
 export function normalizeOperatingProfile(value, { strict = false } = {}) {
   const normalized = canonicalProfile(value);
   if (PROFILE_SET.has(normalized)) return normalized;