@dzhechkov/harness-core 0.7.12 → 0.8.2

package/src/native-dep-probe.ts

@@ -0,0 +1,118 @@
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+
+export type NativeDepState = 'usable' | 'absent' | 'unusable';
+
+export interface NativeDepVerdict {
+  readonly state: NativeDepState;
+  readonly pkg: string;
+  readonly reason?: string;
+  readonly path?: string;
+}
+
+const verdictCache = new Map<string, NativeDepVerdict>();
+const exerciseIds = new WeakMap<Function, string>();
+let nextExerciseId = 1;
+
+function exerciseIdentity(exercise: unknown): string {
+  if (typeof exercise !== 'function') return `invalid-${typeof exercise}`;
+  const existing = exerciseIds.get(exercise);
+  if (existing) return existing;
+  const identity = `function-${nextExerciseId++}`;
+  exerciseIds.set(exercise, identity);
+  return identity;
+}
+
+function formatError(error: unknown): string {
+  try {
+    const message = error instanceof Error ? error.message : String(error);
+    const oneLine = message.replace(/\s+/g, ' ').trim() || 'unknown error';
+    return oneLine.length > 400 ? `${oneLine.slice(0, 397)}...` : oneLine;
+  } catch {
+    return 'unknown error';
+  }
+}
+
+export function exerciseSqliteOpen(mod: unknown): void {
+  const defaultExport =
+    typeof mod === 'object' && mod !== null && 'default' in mod
+      ? (mod as { default: unknown }).default
+      : mod;
+  const Database = defaultExport as new (filename: string) => { close(): void };
+  const database = new Database(':memory:');
+  database.close();
+}
+
+export function probeNativeDep(
+  projectRoot: string,
+  pkg: string,
+  exercise?: (mod: unknown) => unknown,
+  exerciseId?: string,
+): NativeDepVerdict {
+  let cacheKey: string;
+  try {
+    const resolvedExerciseId =
+      exerciseId ?? (exercise === undefined ? undefined : exerciseIdentity(exercise));
+    cacheKey = `${resolve(projectRoot)}::${pkg}::${resolvedExerciseId ?? 'none'}`;
+  } catch {
+    return { state: 'absent', pkg };
+  }
+
+  const cached = verdictCache.get(cacheKey);
+  if (cached) return cached;
+
+  let resolvedPath: string;
+  let projectRequire: ReturnType<typeof createRequire>;
+  try {
+    projectRequire = createRequire(join(projectRoot, 'package.json'));
+    resolvedPath = projectRequire.resolve(pkg);
+  } catch {
+    const verdict: NativeDepVerdict = { state: 'absent', pkg };
+    verdictCache.set(cacheKey, verdict);
+    return verdict;
+  }
+
+  let verdict: NativeDepVerdict;
+  try {
+    const mod = projectRequire(resolvedPath);
+    const exerciseResult = exercise?.(mod);
+    const then =
+      exerciseResult !== null &&
+      (typeof exerciseResult === 'object' || typeof exerciseResult === 'function')
+        ? (exerciseResult as { then?: unknown }).then
+        : undefined;
+    if (typeof then === 'function') {
+      void Promise.resolve(exerciseResult).catch(() => {});
+      verdict = {
+        state: 'unusable',
+        pkg,
+        reason:
+          'exercise returned a promise; probeNativeDep is synchronous and cannot await it',
+        path: resolvedPath,
+      };
+    } else {
+      verdict = { state: 'usable', pkg, path: resolvedPath };
+    }
+  } catch (error) {
+    verdict = {
+      state: 'unusable',
+      pkg,
+      reason: formatError(error),
+      path: resolvedPath,
+    };
+  }
+
+  verdictCache.set(cacheKey, verdict);
+  return verdict;
+}
+
+export function describeNativeDep(verdict: NativeDepVerdict): string {
+  if (verdict.state === 'usable') return '';
+  if (verdict.state === 'absent') {
+    if (verdict.pkg === 'agentdb' || verdict.pkg === 'better-sqlite3') {
+      return `${verdict.pkg} not installed in project (run: dz setup --memory agentdb)`;
+    }
+    return `${verdict.pkg} not installed in project (run: npm i ${verdict.pkg})`;
+  }
+  return `${verdict.pkg} is installed at ${verdict.path ?? 'an unknown path'}, but its native part will not load on this Node: ${verdict.reason ?? 'unknown error'} (run: npm rebuild ${verdict.pkg})`;
+}

package/src/operations.ts

@@ -27,6 +27,7 @@ import {
   type HooksListHookMetadata,
   type ManagedEntry,
 } from './codex-hooks.js';
+import { sweepSkillDrift } from './skill-drift.js';
 import { generateCodexHelpers } from './codex-hooks-assets.js';
 import {
   classifyVetoProbe,
@@ -997,6 +998,40 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       detail: '.claude/mcp.json is NOT loaded by Claude Code — re-run dz setup to register agentdb in .mcp.json (project root)',
     });
   }
+  // 8x. agentdb MCP/writer store SEPARATION (ADR-001 agentdb-setup-shared-store-fix, 2026-08-26).
+  // A shared store is a measured data-loss path (2026-07-09: 5 of 20 samples zero bytes, 4 torn) —
+  // the same predicate setup.ts's `agentdb wiring` step uses, imported, never re-implemented.
+  // Deliberately OUTSIDE the `.dz/agentdb-writer.mjs` branch below: a registration can be wrong
+  // before any writer is deployed, and that is exactly when it is cheapest to fix.
+  const mcpConfigPath = join(root, '.mcp.json');
+  if (existsSync(mcpConfigPath)) {
+    try {
+      const { agentdbStoreSeparationProblem } = await import('./setup.js');
+      const mcp = JSON.parse(readFileSync(mcpConfigPath, 'utf-8')) as {
+        mcpServers?: Record<string, { env?: Record<string, string> }>;
+      };
+      const pinned = mcp.mcpServers?.['agentdb']?.env?.['AGENTDB_PATH'];
+      // Only speak when an agentdb server is actually registered — a project without one keeps
+      // its doctor output noise-free, exactly as before this check existed.
+      // A REGISTERED agentdb server with NO AGENTDB_PATH is not a quiet project — it is the
+      // protection DELETED. Without the pin the server resolves its store from its own cwd, which is
+      // exactly the unpinned arrangement that produced an empty orphan store in this repo. The first
+      // version of this check skipped that case, so removing the guard produced no finding at all
+      // (cross-family QE, Codex gpt-5.6-sol). Silence on a deleted protection is the failure mode
+      // this whole feature exists to end.
+      const registered = mcp.mcpServers?.['agentdb'] !== undefined;
+      if (registered && pinned === undefined) {
+        checks.push({
+          name: 'agentdb store separation',
+          ok: false,
+          detail: 'an agentdb MCP server is registered with NO AGENTDB_PATH — it will resolve its store from its own cwd, so nothing guarantees it stays off the session-hook writer store; re-run dz setup --memory agentdb',
+        });
+      } else if (pinned !== undefined) {
+        const problem = agentdbStoreSeparationProblem(root, pinned);
+        if (problem) checks.push({ name: 'agentdb store separation', ok: false, detail: problem });
+      }
+    } catch { /* doctor never throws on a diagnostic */ }
+  }
   // Flat dz hook entries (dz ≤0.3.43 emitted `{type,command}` without the matcher-group wrapper)
   // are silently IGNORED by Claude Code — the writer never fires. Detect and point at the fix.
   try {
@@ -1097,12 +1132,53 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
         checks.push({
           name: 'agentdb version drift',
           ok: false,
-          detail: `local agentdb@${localVer} != MCP pin ${pinned} (alpha schema drift risk on the shared DB) — re-run dz setup`,
+          detail: `local agentdb@${localVer} != MCP pin ${pinned} (alpha schema drift risk) — re-run dz setup`,
         });
       }
     } catch { /* either side absent — covered by other checks */ }
   }
 
+  // 8a-bis. DEV-TREE SKILL LAG — advisory, never blocking.
+  //
+  // The `no-skill-drift` HARD rule sweeps scope 'installs', which DELIBERATELY excludes the
+  // hand-edited `.claude/skills/` dev tree: those copies are allowed to lag a published bump, and
+  // holding them to byte-identity would make the gate red-on-arrival. That reasoning is sound and
+  // is NOT changed here.
+  //
+  // What was missing is that nobody SAW the lag. MEASURED 2026-08-26: `.claude/skills/idea2prd-manual`
+  // was a month behind its package copy — missing the entire v3 modernization that landed in
+  // 0.1.3/0.1.4 — and `.claude/skills/observability` had never received the 2026-08-24 tightening of
+  // its dashboard gate. Those dev copies are exactly what the agents in THIS repo read, so "legitimately
+  // lagging" quietly meant "the agents here have been running a stale skill for a month". A narrow
+  // gate plus zero visibility is how a lag becomes a silent regression.
+  //
+  // So: report the DIFFERENCE between the wide sweep and the gated one — i.e. only skills whose sole
+  // divergence is the dev tree. Never `ok:false` for a lag alone; the HARD rule keeps owning what
+  // blocks. `dz drift-check --all` remains the detailed view.
+  try {
+    const allowlist = ((): string[] => {
+      const ap = join(root, '.dz', 'drift-allowlist.json');
+      if (!existsSync(ap)) return [];
+      try {
+        const raw = JSON.parse(readFileSync(ap, 'utf8')) as unknown;
+        const arr = Array.isArray(raw) ? raw : Array.isArray((raw as { skills?: unknown })?.skills) ? (raw as { skills: unknown[] }).skills : [];
+        return arr.map((e) => (typeof e === 'string' ? e : (e as { name?: string })?.name)).filter((n): n is string => typeof n === 'string' && n.length > 0);
+      } catch { return []; }
+    })();
+    const wide = sweepSkillDrift(root, { scope: 'all', allowlist });
+    const gated = new Set(sweepSkillDrift(root, { scope: 'installs', allowlist }).drifted.map((d) => d.name));
+    // Only what the HARD rule does NOT already own: these differ ONLY because of the dev tree.
+    const devOnly = wide.drifted.filter((d) => !gated.has(d.name));
+    if (devOnly.length > 0) {
+      const names = devOnly.slice(0, 5).map((d) => `${d.name} (${d.driftFiles} file(s))`).join(', ');
+      checks.push({
+        name: 'dev-tree skill lag',
+        ok: true, // ADVISORY: the gated scope decides what blocks; this only makes the lag visible.
+        detail: `${devOnly.length} skill(s) differ ONLY in the .claude/skills dev tree: ${names}${devOnly.length > 5 ? ', …' : ''} — a dev copy may legitimately lag a published bump, but it is what the agents here READ, so a month-old copy is a silent regression. Inspect with: dz drift-check --all`,
+      });
+    }
+  } catch { /* doctor never throws on a diagnostic */ }
+
   // 8b. EVIDENCE-CHAIN INTEGRITY (feature event-chain, ADR-001). `.dz/recall-usage.jsonl` and
   // `.dz/guard-audit.jsonl` are what `dz compounding` and `dz guard promote` decide on; a rewrite
   // that loses or duplicates a record there is a wrong verdict with no symptom. Deliberately OUTSIDE

package/src/parser-safe-region.ts

@@ -0,0 +1,65 @@
+/**
+ * The `feature-adr.js` workflow's PARSER-SAFE REGION — the shared predicate, not a re-implementation.
+ *
+ * The Workflow runtime's parser is STRICTER than `node --check`: inside the routing block that runs
+ * from `const MODELS =` to `const ROUTER =` a template literal is a hard parse error, so no backtick
+ * may appear there. That constraint used to be enforced by a `not.toContain('`')` assertion written
+ * inline in one test (`feature-adr-model-routing.test.ts:142`), which proves only that the SHIPPED
+ * file is currently clean — delete the assertion and nothing goes red.
+ *
+ * ADR-001 / AM-1 asked for the other half: a guard that is PROVEN to fire on a real violation. Making
+ * the predicate a shared export is what buys that — the same function decides the shipped file and the
+ * deliberately mutated copy, so a test can inject one backtick into the region and watch it refuse.
+ * Deleting the guard now deletes the thing the mutation test calls.
+ *
+ * Pure and dependency-free: string in, verdict out. No file I/O, no process state.
+ *
+ * @packageDocumentation
+ */
+
+/** Opening marker of the parser-safe region (the first line of the inlined routing block). */
+export const PARSER_SAFE_REGION_START = 'const MODELS =';
+/** Closing marker of the parser-safe region (the first declaration after the routing block). */
+export const PARSER_SAFE_REGION_END = 'const ROUTER =';
+
+/** Why a source could not be cleared — `null` when the region is clean. */
+export type ParserSafeRegionRefusal =
+  /** a marker is missing or the two markers are out of order: the region cannot be located at all */
+  | 'region-not-found'
+  /** a backtick sits between the two markers — the Workflow parser rejects the file */
+  | 'backtick-in-region';
+
+export interface ParserSafeRegionVerdict {
+  /** true only when the region was LOCATED and contains no backtick. */
+  readonly ok: boolean;
+  /** the refusal reason, or `null` on a clean verdict. */
+  readonly refusal: ParserSafeRegionRefusal | null;
+  /** absolute character offset of the first offending backtick, or `null`. */
+  readonly index: number | null;
+  /** 1-based line number of the first offending backtick, or `null`. */
+  readonly line: number | null;
+}
+
+/**
+ * Decide whether `source` respects the parser-safe region.
+ *
+ * A source whose markers cannot be located is NOT quietly cleared — an unlocatable region is
+ * `region-not-found`, never `ok`. That asymmetry is deliberate: a refactor that moves or renames the
+ * markers must be loud, because a silently-skipped check is indistinguishable from a passing one.
+ */
+export function checkParserSafeRegion(source: string): ParserSafeRegionVerdict {
+  const start = source.indexOf(PARSER_SAFE_REGION_START);
+  const end = source.indexOf(PARSER_SAFE_REGION_END);
+  if (start === -1 || end === -1 || end <= start) {
+    return { ok: false, refusal: 'region-not-found', index: null, line: null };
+  }
+  const offset = source.slice(start, end).indexOf('`');
+  if (offset === -1) return { ok: true, refusal: null, index: null, line: null };
+  const index = start + offset;
+  return {
+    ok: false,
+    refusal: 'backtick-in-region',
+    index,
+    line: source.slice(0, index).split('\n').length,
+  };
+}

package/src/patterns.ts

@@ -31,6 +31,7 @@ import { resolveAgentdbPath } from './agentdb-index.js';
 import type { VectorEntry } from './vector-tier.js';
 import { rankLessonsByDelta, type LessonHistory } from './safla-delta.js';
 import { withStoreLock, withStoreLockSync, StoreLockTimeoutError, StoreLockCompromisedError } from './store-lock.js';
+import { describeNativeDep, exerciseSqliteOpen, probeNativeDep } from './native-dep-probe.js';
 
 /** A learned pattern as written by `dz teach` to `.dz/patterns.jsonl`. */
 export interface PatternRecord {
@@ -1272,7 +1273,11 @@ function countNoiseVectors(projectRoot: string): { removed: number; error?: stri
       db.close();
     }
   } catch (err) {
-    return { removed: 0, error: `vector mirror: ${err instanceof Error ? err.message : String(err)}` };
+    const verdict = probeNativeDep(projectRoot, 'better-sqlite3', exerciseSqliteOpen, 'sqlite-open');
+    const message = verdict.state === 'unusable'
+      ? describeNativeDep(verdict)
+      : err instanceof Error ? err.message : String(err);
+    return { removed: 0, error: `vector mirror: ${message}` };
   }
 }
 
@@ -1314,6 +1319,10 @@ function pruneNoiseVectors(projectRoot: string): { removed: number; error?: stri
       db.close();
     }
   } catch (err) {
+    const verdict = probeNativeDep(projectRoot, 'better-sqlite3', exerciseSqliteOpen, 'sqlite-open');
+    if (verdict.state === 'unusable') {
+      return { removed: 0, error: `vector mirror: ${describeNativeDep(verdict)}` };
+    }
     return { removed: 0, error: `vector prune failed: ${err instanceof Error ? err.message : String(err)}` };
   }
 }