wendkeep 0.66.4 → 0.66.5

package/hooks/harness-doctor.mjs

@@ -8,7 +8,88 @@ import { buildEffectiveRequirementPackage, checkSpecsState, evaluateVerdict, tas
 import { getLocale } from './locale.mjs';
 import { priceForModel } from './token-usage.mjs';
 import { countMissing, indexDerivedBySession, listSessionNotes, missingDerivedLinks } from './derived-sections.mjs';
-import { readControl } from './obsidian-common.mjs';
+import { readControl, readSessionRegistry } from './obsidian-common.mjs';
+import { parseObservabilityCheckpoint } from './session-observability-state.mjs';
+import { readObservabilityStore } from './session-observability-store.mjs';
+import { assessObservabilityFreshness } from './session-observability-lifecycle.mjs';
+
+export function checkSessionObservability(vaultBase, deps = {}) {
+  const readRegistry = deps.readRegistry || readSessionRegistry;
+  const readStore = deps.readStore || readObservabilityStore;
+  const readNote = deps.readNote || readFileSync;
+  const statSource = deps.statSource || statSync;
+  const registry = readRegistry(vaultBase);
+  const result = { ok: true, scanned: 0, healthy: 0, issues: [] };
+  const entries = Object.entries(registry?.sessions || {})
+    .map(([sessionId, entry]) => ({ sessionId, ...entry }))
+    .filter((entry) => entry.session_file)
+    .sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+
+  for (const entry of entries) {
+    if (entry.provider && entry.provider !== 'codex') continue;
+    const notePath = join(vaultBase, entry.session_file);
+    let content;
+    try { content = readNote(notePath, 'utf8'); } catch { continue; }
+    if (!entry.provider && /^provider:\s*["']?claude/m.test(content)) continue;
+    result.scanned += 1;
+    const command = `wendkeep cost rebuild --session ${entry.sessionId} --json`;
+    const checkpoint = parseObservabilityCheckpoint(content);
+    if (!checkpoint) {
+      result.issues.push({
+        sessionId: entry.sessionId, status: 'legacy', diagnostics: [], command,
+      });
+      continue;
+    }
+    if (checkpoint.state === 'degraded') {
+      result.issues.push({
+        sessionId: entry.sessionId,
+        status: 'degraded',
+        diagnostics: checkpoint.diagnostics,
+        command,
+      });
+      continue;
+    }
+
+    let runtime;
+    try { runtime = readStore(vaultBase, entry.sessionId); } catch {
+      runtime = null;
+    }
+    const assessment = assessObservabilityFreshness({
+      checkpoint,
+      runtimeState: runtime,
+      statSource,
+    });
+    if (!assessment.fresh) {
+      result.issues.push({
+        sessionId: entry.sessionId,
+        status: assessment.status,
+        diagnostics: assessment.diagnostics,
+        command,
+      });
+      continue;
+    }
+    result.healthy += 1;
+  }
+  result.ok = result.issues.length === 0;
+  return result;
+}
+
+export function renderSessionObservabilityLines(result) {
+  const issues = result?.issues || [];
+  const lines = [
+    `[observabilidade] ${result?.healthy || 0} saudável(is) · ${issues.length} reparável(is)`,
+  ];
+  for (const issue of issues) {
+    const diagnostics = issue.diagnostics?.length
+      ? ` (${issue.diagnostics.map(({ code, count }) => `${code}:${count}`).join(', ')})`
+      : '';
+    lines.push(`  ✗ ${issue.sessionId}: ${issue.status}${diagnostics}`);
+    lines.push(`    → ${issue.command}`);
+    lines.push(`    → ${issue.command} --apply`);
+  }
+  if (!issues.length) lines.push('  ✓ frontiers, checkpoints e manifests consistentes');
+  return lines;
+}
 
 export function checkHarness(vaultBase, projectRoot) {
   const loc = getLocale(vaultBase);

package/hooks/import-sessions.mjs

@@ -16,10 +16,20 @@ import {
 } from './session-stop.mjs';
 import { buildSessionContent, allocateSessionPath } from './session-start.mjs';
 import { createLinkedNotes } from './linked-notes.mjs';
-import { updateSessionObservability } from './session-observability.mjs';
+import {
+  composeSessionObservability,
+  publishSessionObservability,
+} from './session-observability.mjs';
 import { readSessionRegistry, upsertSessionRegistry, removeSessionRegistryEntry, formatLocalIso, formatDate, providerMeta, isBootstrapPrompt } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
 import { captureProseDecisions } from './decision-capture.mjs';
+import { readCodexRolloutMeta } from './codex-rollout-meta.mjs';
+import {
+  parseObservabilityCheckpoint,
+  sanitizeObservabilityDiagnostics,
+} from './session-observability-state.mjs';
+import { readObservabilityStore } from './session-observability-store.mjs';
+import { assessObservabilityFreshness } from './session-observability-lifecycle.mjs';
 
 // Claude encodes a project's absolute path as its `.claude/projects` dir name by replacing each
 // path separator and the drive colon with '-'. `C:\GitHub\WendKeep` -> `C--GitHub-WendKeep`.
@@ -97,41 +107,6 @@ function readPrefix(path, bytes = 4096) {
   }
 }
 
-// Read the first physical line in full, growing the buffer until a newline is found (capped).
-// A fixed prefix truncated any rollout whose session_meta line exceeded the window, silently
-// dropping that session from discovery — Codex meta lines can be large (env, git, instructions).
-function readFirstLine(path, maxBytes = 4 * 1024 * 1024) {
-  let fd;
-  try {
-    fd = openSync(path, 'r');
-    const chunk = Buffer.alloc(65536);
-    let acc = '';
-    let pos = 0;
-    while (pos < maxBytes) {
-      const n = readSync(fd, chunk, 0, chunk.length, pos);
-      if (n <= 0) break;
-      acc += chunk.slice(0, n).toString('utf-8');
-      const nl = acc.indexOf('\n');
-      if (nl >= 0) return acc.slice(0, nl);
-      pos += n;
-    }
-    return acc; // single-line file, or gave up at the cap
-  } catch {
-    return '';
-  } finally {
-    if (fd !== undefined) { try { closeSync(fd); } catch { /* already closed */ } }
-  }
-}
-
-// Pull the session_meta payload (id + cwd). session_meta is line 1 of a rollout.
-function readSessionMeta(path) {
-  const line = readFirstLine(path);
-  if (!line.trim()) return null;
-  let e;
-  try { e = JSON.parse(line); } catch { return null; }
-  return e.type === 'session_meta' ? (e.payload || {}) : null;
-}
-
 // The `session_id` recorded in a note's frontmatter (empty when absent).
 function noteSessionId(path) {
   const m = readPrefix(path, 2048).match(/^session_id:\s*["']?([^"'\r\n]+)["']?\s*$/m);
@@ -189,8 +164,9 @@ export function discoverCodexTranscripts(projectPath, fromDir) {
   if (!dir || !existsSync(dir)) return { dir, transcripts: [] };
   const transcripts = [];
   for (const path of walkFiles(dir, /\.jsonl$/i)) {
-    const meta = readSessionMeta(path);
-    if (!meta || !meta.id) continue;
+    const metaResult = readCodexRolloutMeta(path);
+    if (!metaResult.ok || !metaResult.meta.id) continue;
+    const meta = metaResult.meta;
     if (projectPath && !cwdMatchesProject(meta.cwd, projectPath)) continue;
     // A subagent thread's rollout is a SIBLING file of its parent's — same dir, own id. The
     // meta says what the file IS; ignoring it turned hierarchy into a duplicate session note.
@@ -248,11 +224,6 @@ export function importSession(vaultBase, txPath, opts = {}) {
     insertIteration(absPath, block, turn.turnId, tx, vaultBase);
   }
 
-  // Cost + subagent telemetry, exactly like the live Stop hook. Fail-open.
-  try {
-    updateSessionObservability({ vaultBase, sessionPath: absPath, transcriptPath: txPath });
-  } catch { /* observability is best-effort */ }
-
   // Finalize: derived notes + closing section + ended_at from the last turn.
   const endedAt = formatLocalIso(endDate);
   const created = mergeCreatedNotes(
@@ -271,6 +242,17 @@ export function importSession(vaultBase, txPath, opts = {}) {
     imported: true,
   });
 
+  // Materialize only after the authoritative registry entry exists. This gives import the
+  // same causal CAS + runtime manifest as live hooks instead of a note-only legacy snapshot.
+  try {
+    reconcileImportedObservability({
+      vaultBase,
+      sessionId,
+      sessionPath: absPath,
+      transcriptPath: txPath,
+    });
+  } catch { /* observability is best-effort and reported on a later reconciliation */ }
+
   return { sessionId, relPath, turns: turns.length };
 }
 
@@ -333,12 +315,105 @@ export function stampSessionIds(vaultBase) {
   return report;
 }
 
+export function reconcileImportedObservability({
+  vaultBase,
+  sessionId,
+  sessionPath,
+  transcriptPath,
+  dryRun = false,
+} = {}, dependencies = {}) {
+  const readRegistry = dependencies.readRegistry || readSessionRegistry;
+  const readStore = dependencies.readStore || readObservabilityStore;
+  const compose = dependencies.compose || composeSessionObservability;
+  const publish = dependencies.publish || publishSessionObservability;
+  if (!vaultBase || !sessionId || !sessionPath || !existsSync(sessionPath)) {
+    return {
+      status: 'degraded',
+      diagnostics: [{ code: 'PARENT_META_INVALID', count: 1 }],
+    };
+  }
+
+  let entry;
+  let content;
+  let runtimeState;
+  try {
+    entry = readRegistry(vaultBase)?.sessions?.[sessionId];
+    content = readFileSync(sessionPath, 'utf8');
+    runtimeState = readStore(vaultBase, sessionId);
+  } catch {
+    return { status: 'degraded', diagnostics: [{ code: 'CACHE_INVALID', count: 1 }] };
+  }
+  if (!entry) {
+    return {
+      status: 'degraded',
+      diagnostics: [{ code: 'PARENT_META_INVALID', count: 1 }],
+    };
+  }
+  const checkpoint = parseObservabilityCheckpoint(content);
+  const assessment = assessObservabilityFreshness({ checkpoint, runtimeState });
+  if (assessment.fresh) return { status: 'fresh', diagnostics: [] };
+
+  let candidate;
+  try {
+    candidate = compose({
+      sessionContent: content,
+      sessionEntry: { ...entry, transcript_path: entry.transcript_path || transcriptPath },
+      canonicalConversationId: sessionId,
+      runtimeState,
+      allowNone: true,
+      mode: 'offline',
+    });
+  } catch {
+    return {
+      status: 'degraded',
+      diagnostics: [{ code: 'PARENT_META_INVALID', count: 1 }],
+    };
+  }
+  const diagnostics = sanitizeObservabilityDiagnostics(candidate?.diagnostics || []);
+  if (candidate?.state === 'degraded') return { status: 'degraded', diagnostics };
+  if (candidate?.state !== 'complete' && candidate?.state !== 'none') {
+    return {
+      status: 'degraded',
+      diagnostics: [{ code: 'PARENT_META_INVALID', count: 1 }],
+    };
+  }
+  if (dryRun) return { status: 'would-reconcile', diagnostics };
+
+  let outcome;
+  try {
+    outcome = publish({
+      vaultBase,
+      sessionPath,
+      canonicalConversationId: sessionId,
+      candidate,
+      caller: 'import-reconcile',
+      allowSourceRefresh: true,
+      allowDegradedRecovery: true,
+    });
+  } catch {
+    return { status: 'degraded', diagnostics: [{ code: 'CACHE_INVALID', count: 1 }] };
+  }
+  if (outcome?.status === 'published' || outcome?.status === 'unchanged') {
+    return { status: 'published', diagnostics };
+  }
+  if (outcome?.status === 'stale' || outcome?.status === 'conflict') {
+    return {
+      status: 'stale',
+      diagnostics: [{ code: 'STALE_FRONTIER', count: 1 }],
+    };
+  }
+  return { status: 'degraded', diagnostics };
+}
+
 // Import every not-yet-captured transcript from the requested source(s). Deduped by session_id
 // against the registry. Options: { projectPath, source ('all'|'claude'|'codex'), from, codexFrom,
 // since (ISO/date), limit, dryRun }. importSession is provider-agnostic, so both sources share
 // the same dedup + import loop.
 export function runImport(vaultBase, opts = {}) {
-  const { projectPath = process.cwd(), source = 'all', from = '', codexFrom = '', since = '', limit = 0, dryRun = false } = opts;
+  const {
+    projectPath = process.cwd(), source = 'all', from = '', codexFrom = '', since = '',
+    limit = 0, dryRun = false, reconcileObservability = reconcileImportedObservability,
+  } = opts;
   const src = String(source).toLowerCase();
   const transcripts = [];
   let claudeDir = '';
@@ -355,7 +430,57 @@ export function runImport(vaultBase, opts = {}) {
   }
   const notes = capturedSessionNotes(vaultBase);
   const sinceMs = since ? Date.parse(since) : 0;
-  const report = { source: src, claudeDir, codexDir, scanned: transcripts.length, imported: 0, repaired: 0, skipped: 0, subagents: 0, errors: [], sessions: [] };
+  const report = {
+    source: src, claudeDir, codexDir, scanned: transcripts.length, imported: 0,
+    repaired: 0, skipped: 0, subagents: 0, observabilityReconciled: 0,
+    observabilityFresh: 0, observabilityDegraded: 0, errors: [], sessions: [],
+  };
+
+  const degradedObservability = () => ({
+    status: 'degraded',
+    diagnostics: [{ code: 'CACHE_INVALID', count: 1 }],
+  });
+  const reportableObservabilityStatuses = new Set([
+    'degraded', 'fresh', 'published', 'stale', 'unchanged', 'would-reconcile',
+  ]);
+  const sanitizeReportedObservability = (result) => {
+    try {
+      const status = String(result?.status || 'degraded');
+      if (!reportableObservabilityStatuses.has(status)) return degradedObservability();
+      const projected = (result?.diagnostics || []).map((diagnostic) => ({
+        code: diagnostic?.code,
+        count: diagnostic?.count,
+      }));
+      return { status, diagnostics: sanitizeObservabilityDiagnostics(projected) };
+    } catch {
+      return degradedObservability();
+    }
+  };
+
+  const reconcileExistingObservability = (transcript, sessionPath, turns) => {
+    if (typeof reconcileObservability !== 'function') return null;
+    let result;
+    try {
+      result = reconcileObservability({
+        vaultBase,
+        sessionId: transcript.sessionId,
+        sessionPath,
+        transcriptPath: transcript.path,
+        dryRun,
+      });
+    } catch {
+      result = degradedObservability();
+    }
+    const observability = sanitizeReportedObservability(result);
+    if (observability.status === 'fresh' || observability.status === 'unchanged') {
+      report.observabilityFresh++;
+    } else if (observability.status === 'published' || observability.status === 'would-reconcile') {
+      report.observabilityReconciled++;
+    } else {
+      report.observabilityDegraded++;
+    }
+    return observability;
+  };
 
   let done = 0;
   for (const t of transcripts) {
@@ -390,7 +515,14 @@ export function runImport(vaultBase, opts = {}) {
     if (existingNote) {
       const have = noteTurnIds(existingNote);
       const missing = turns.filter((turn) => !have.has(String(turn.turnId)));
-      if (!missing.length) { report.skipped++; continue; }
+      if (!missing.length) {
+        const observability = reconcileExistingObservability(t, existingNote, 0);
+        if (observability) report.sessions.push({
+          sessionId: t.sessionId, turns: 0, observability,
+        });
+        report.skipped++;
+        continue;
+      }
       if (dryRun) {
         report.sessions.push({ sessionId: t.sessionId, turns: missing.length, repaired: true, dryRun: true });
         report.repaired++;
@@ -404,10 +536,13 @@ export function runImport(vaultBase, opts = {}) {
             turn.turnId, tx, vaultBase,
           );
         }
-        try {
-          updateSessionObservability({ vaultBase, sessionPath: existingNote, transcriptPath: t.path });
-        } catch { /* best-effort */ }
-        report.sessions.push({ sessionId: t.sessionId, turns: missing.length, repaired: true });
+        const observability = reconcileExistingObservability(t, existingNote, missing.length);
+        report.sessions.push({
+          sessionId: t.sessionId,
+          turns: missing.length,
+          repaired: true,
+          ...(observability ? { observability } : {}),
+        });
         report.repaired++;
         done++;
       } catch (error) {

package/hooks/session-identity.mjs

@@ -5,14 +5,49 @@ import {
   inspectTranscriptIdentityContent,
   resolveSessionIdentitySnapshot,
 } from '../packages/integrations/src/session-identity.mjs';
+import { readCodexRolloutMeta } from './codex-rollout-meta.mjs';
+
+function unknownTranscriptIdentity() {
+  return {
+    transcriptProvider: 'unknown',
+    provider: 'unknown',
+    canonicalConversationId: '',
+    transcriptId: '',
+    parentConversationId: '',
+  };
+}
+
+function inspectCodexMeta(meta, fallbackTranscriptId) {
+  return {
+    transcriptProvider: 'openai',
+    provider: 'codex',
+    canonicalConversationId: meta.session_id || meta.id || '',
+    transcriptId: meta.id || fallbackTranscriptId,
+    parentConversationId: meta.parent_thread_id || meta.forked_from_id || '',
+  };
+}
+
+function withoutCodexSessionMeta(content) {
+  return String(content || '').split('\n').filter((line) => {
+    try { return JSON.parse(line)?.type !== 'session_meta'; } catch { return true; }
+  }).join('\n');
+}
 
 export function inspectTranscriptIdentity(transcriptPath) {
-  const content = transcriptPath && existsSync(transcriptPath)
-    ? readFileSync(transcriptPath, 'utf-8')
-    : '';
-  return inspectTranscriptIdentityContent(content, {
-    fallbackTranscriptId: transcriptPath ? basename(transcriptPath, '.jsonl') : '',
+  const fallbackTranscriptId = transcriptPath ? basename(transcriptPath, '.jsonl') : '';
+  if (!transcriptPath || !existsSync(transcriptPath)) return unknownTranscriptIdentity();
+
+  const codexMeta = readCodexRolloutMeta(transcriptPath);
+  if (codexMeta.ok) return inspectCodexMeta(codexMeta.meta, fallbackTranscriptId);
+
+  // Claude JSONL has no session_meta header. Preserve its existing full-content inspection,
+  // but never reinterpret a later/misplaced Codex meta as the file identity.
+  let content;
+  try { content = readFileSync(transcriptPath, 'utf-8'); } catch { return unknownTranscriptIdentity(); }
+  const inspected = inspectTranscriptIdentityContent(withoutCodexSessionMeta(content), {
+    fallbackTranscriptId,
   });
+  return inspected.provider === 'claude' ? inspected : unknownTranscriptIdentity();
 }
 
 export function resolveSessionIdentity(vaultBase, input = {}, provider = detectProvider()) {

package/hooks/session-observability-lifecycle.mjs

@@ -0,0 +1,129 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { readCodexRolloutMeta } from './codex-rollout-meta.mjs';
+
+const stableHash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+
+function addTranscriptPath(paths, value) {
+  if (typeof value === 'string' && value.trim()) paths.add(value.trim());
+}
+
+function collectActivationPaths(paths, activations) {
+  if (!activations || typeof activations !== 'object') return;
+  const values = Array.isArray(activations) ? activations : Object.values(activations);
+  for (const activation of values) {
+    if (!activation || typeof activation !== 'object') continue;
+    addTranscriptPath(paths, activation.transcript_path);
+    for (const path of activation.transcript_paths || []) addTranscriptPath(paths, path);
+  }
+}
+
+function isCodexDescendant(meta) {
+  return Boolean(meta?.source && typeof meta.source === 'object' && meta.source.subagent);
+}
+
+// Resolve every transcript explicitly attached to the registry entry. Classification is
+// authoritative only when the rollout's first session_meta line can be read: filename and
+// directory layout are deliberately not used as subagent heuristics.
+export function resolveObservabilityRoots(entry, { readMeta = readCodexRolloutMeta } = {}) {
+  if (!entry || typeof entry !== 'object') {
+    return {
+      state: 'degraded',
+      rootPaths: [],
+      descendantPaths: [],
+      diagnostics: [{ code: 'MAIN_TRANSCRIPT_UNRESOLVED', count: 1 }],
+    };
+  }
+
+  const candidates = new Set();
+  addTranscriptPath(candidates, entry.transcript_path);
+  for (const path of entry.transcript_paths || []) addTranscriptPath(candidates, path);
+  collectActivationPaths(candidates, entry.activations);
+
+  const rootPaths = [];
+  const descendantPaths = [];
+  let unreadable = 0;
+  for (const path of [...candidates].sort((a, b) => a.localeCompare(b))) {
+    const result = readMeta(path);
+    if (!result?.ok) {
+      unreadable += 1;
+      continue;
+    }
+    if (isCodexDescendant(result.meta)) descendantPaths.push(path);
+    else rootPaths.push(path);
+  }
+
+  if (unreadable > 0) {
+    return {
+      state: 'degraded',
+      rootPaths,
+      descendantPaths,
+      diagnostics: [{ code: 'MAIN_TRANSCRIPT_UNRESOLVED', count: unreadable }],
+    };
+  }
+
+  return { state: 'complete', rootPaths, descendantPaths, diagnostics: [] };
+}
+
+function sameFrontier(left, right) {
+  return Boolean(left && right && JSON.stringify(left) === JSON.stringify(right));
+}
+
+export function assessObservabilityFreshness({
+  checkpoint,
+  runtimeState,
+  statSource = statSync,
+} = {}) {
+  if (!checkpoint) return { fresh: false, status: 'legacy', diagnostics: [] };
+  if (checkpoint.state === 'degraded') {
+    return {
+      fresh: false,
+      status: 'degraded',
+      diagnostics: checkpoint.diagnostics || [],
+    };
+  }
+  const manifest = runtimeState?.source_manifest;
+  if (!Array.isArray(manifest) || manifest.length === 0) {
+    return { fresh: false, status: 'manifest-unproven', diagnostics: [] };
+  }
+
+  const hashInput = [];
+  for (const source of manifest) {
+    if (!source || typeof source.path !== 'string' || typeof source.rolloutId !== 'string') {
+      return { fresh: false, status: 'manifest-unproven', diagnostics: [] };
+    }
+    let stat;
+    try { stat = statSource(source.path); } catch {
+      return {
+        fresh: false,
+        status: 'stale',
+        diagnostics: [{ code: 'STALE_FRONTIER', count: 1 }],
+      };
+    }
+    if (!stat.isFile() || stat.size !== Number(source.size)
+      || stat.mtimeMs !== Number(source.mtimeMs)) {
+      return {
+        fresh: false,
+        status: 'stale',
+        diagnostics: [{ code: 'STALE_FRONTIER', count: 1 }],
+      };
+    }
+    hashInput.push({ rolloutId: source.rolloutId, size: stat.size, mtimeMs: stat.mtimeMs });
+  }
+  hashInput.sort((left, right) =>
+    `${left.rolloutId}\u0000${left.size}\u0000${left.mtimeMs}`.localeCompare(
+      `${right.rolloutId}\u0000${right.size}\u0000${right.mtimeMs}`,
+    ));
+  const stale = stableHash(hashInput) !== checkpoint.frontier.source_manifest_hash
+    || !sameFrontier(runtimeState?.checkpoint_frontier, checkpoint.frontier)
+    || runtimeState?.observability_dirty !== false
+    || runtimeState?.observability_checkpoint_sequence !== runtimeState?.observability_signal_sequence
+    || runtimeState?.observability_checkpoint_sequence !== checkpoint.frontier.signal_sequence;
+  return stale
+    ? {
+      fresh: false,
+      status: 'stale',
+      diagnostics: [{ code: 'STALE_FRONTIER', count: 1 }],
+    }
+    : { fresh: true, status: 'fresh', diagnostics: [] };
+}