thumbgate 1.28.4 → 1.29.2

package/scripts/human-escalation.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Human Escalation Queue
+ *
+ * Agents may request or inspect escalation, but approval decisions require an
+ * explicit human actor identity distinct from the requesting agent. Events are
+ * append-only so every transition remains auditable.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { getFeedbackPaths } = require('./feedback-paths');
+
+const ESCALATIONS_FILE = 'human-escalations.jsonl';
+const MAX_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
+const DECISIONS = new Set(['approved', 'rejected', 'cancelled']);
+
+function getEscalationsPath(options = {}) {
+  return path.join(getFeedbackPaths(options).FEEDBACK_DIR, ESCALATIONS_FILE);
+}
+
+function requestEscalation(input = {}, options = {}) {
+  const now = options.now || new Date();
+  const taskId = requiredString(input.taskId, 'taskId');
+  const reason = requiredString(input.reason, 'reason');
+  const requester = requiredIdentity(input.requester, 'requester');
+  const evidence = stringArray(input.evidence);
+  if (evidence.length === 0) throw escalationError('evidence must contain at least one item');
+  const severity = input.severity || 'medium';
+  if (!SEVERITIES.has(severity)) throw escalationError(`severity must be one of ${Array.from(SEVERITIES).join(', ')}`);
+  const ttlMs = Math.min(MAX_TTL_MS, Math.max(1, finiteNumber(input.ttlMs, DEFAULT_TTL_MS)));
+  const idempotencyKey = requiredString(input.idempotencyKey || taskId, 'idempotencyKey');
+  const existing = listEscalations(options).find((entry) => entry.idempotencyKey === idempotencyKey);
+
+  const request = {
+    escalationId: input.escalationId || `esc_${crypto.randomUUID()}`,
+    idempotencyKey,
+    taskId,
+    reason,
+    severity,
+    requester,
+    evidence,
+    requestedAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+    status: 'pending',
+    eventType: 'requested',
+  };
+  request.eventHash = eventHash(request);
+
+  if (existing) {
+    if (eventComparableHash(existing) !== eventComparableHash(request)) {
+      const error = escalationError(`conflicting request for idempotency key '${idempotencyKey}'`);
+      error.code = 'THUMBGATE_IDEMPOTENCY_CONFLICT';
+      throw error;
+    }
+    return { recorded: false, duplicate: true, escalation: existing };
+  }
+
+  appendEvent(request, options);
+  return { recorded: true, duplicate: false, escalation: request };
+}
+
+function decideEscalation(input = {}, options = {}) {
+  const escalationId = requiredString(input.escalationId, 'escalationId');
+  const decision = requiredString(input.decision, 'decision');
+  if (!DECISIONS.has(decision)) throw escalationError(`decision must be one of ${Array.from(DECISIONS).join(', ')}`);
+  if (Object.hasOwn(input, 'actor')) {
+    throw escalationError('decision actor is derived from the authenticated reviewer and must not be supplied by the caller');
+  }
+  const actor = requiredIdentity(options.authenticatedActor, 'authenticatedActor');
+  if (actor.kind !== 'human') throw escalationError('authenticatedActor.kind must be human');
+  const reason = requiredString(input.reason, 'reason');
+  const current = getEscalation(escalationId, options);
+  if (!current) throw escalationError(`unknown escalation '${escalationId}'`);
+  if (current.status !== 'pending') throw escalationError(`escalation '${escalationId}' is already ${current.status}`);
+  if (sameIdentity(current.requester, actor)) throw escalationError('requester cannot decide their own escalation');
+
+  const now = options.now || new Date();
+  const event = {
+    escalationId,
+    taskId: current.taskId,
+    status: decision,
+    eventType: 'decided',
+    decision,
+    actor,
+    reason,
+    decidedAt: now.toISOString(),
+  };
+  event.eventHash = eventHash(event);
+  appendEvent(event, options);
+  return { recorded: true, escalation: { ...current, ...event } };
+}
+
+function listEscalations(options = {}) {
+  const events = readEvents(options);
+  const byId = new Map();
+  for (const event of events) {
+    const current = byId.get(event.escalationId) || {};
+    byId.set(event.escalationId, { ...current, ...event });
+  }
+
+  const nowMs = (options.now || new Date()).getTime();
+  const rows = Array.from(byId.values()).map((entry) => {
+    if (entry.status === 'pending' && Date.parse(entry.expiresAt) <= nowMs) {
+      return { ...entry, status: 'expired' };
+    }
+    return entry;
+  });
+  const status = options.status;
+  return rows
+    .filter((entry) => !status || entry.status === status)
+    .sort((a, b) => Date.parse(b.requestedAt || b.decidedAt) - Date.parse(a.requestedAt || a.decidedAt));
+}
+
+function getEscalation(escalationId, options = {}) {
+  return listEscalations(options).find((entry) => entry.escalationId === escalationId) || null;
+}
+
+function calculateEscalationMetrics(escalations = [], now = new Date()) {
+  const rows = escalations.filter(Boolean);
+  const decided = rows.filter((entry) => ['approved', 'rejected'].includes(entry.status));
+  const decisionLatencies = decided
+    .map((entry) => Date.parse(entry.decidedAt) - Date.parse(entry.requestedAt))
+    .filter((value) => Number.isFinite(value) && value >= 0);
+  const overdue = rows.filter((entry) => entry.status === 'pending' && Date.parse(entry.expiresAt) <= now.getTime());
+  return {
+    generatedAt: now.toISOString(),
+    sampleSize: rows.length,
+    evidenceStatus: rows.length ? 'measured' : 'insufficient_evidence',
+    pending: rows.filter((entry) => entry.status === 'pending').length,
+    approved: rows.filter((entry) => entry.status === 'approved').length,
+    rejected: rows.filter((entry) => entry.status === 'rejected').length,
+    expired: rows.filter((entry) => entry.status === 'expired').length,
+    overdue: overdue.length,
+    medianDecisionLatencyMs: percentile(decisionLatencies, 0.5),
+    p95DecisionLatencyMs: percentile(decisionLatencies, 0.95),
+  };
+}
+
+function readEvents(options = {}) {
+  const inputPath = options.inputPath ? path.resolve(options.inputPath) : getEscalationsPath(options);
+  let raw = '';
+  try {
+    raw = fs.readFileSync(inputPath, 'utf8');
+  } catch {
+    return [];
+  }
+  return raw.split('\n').map((line) => line.trim()).filter(Boolean).flatMap((line) => {
+    try {
+      return [JSON.parse(line)];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function appendEvent(event, options) {
+  const outputPath = getEscalationsPath(options);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.appendFileSync(outputPath, `${JSON.stringify(event)}\n`, 'utf8');
+}
+
+function requiredIdentity(value, field) {
+  if (!value || typeof value !== 'object') throw escalationError(`${field} identity is required`);
+  const identity = {
+    id: requiredString(value.id, `${field}.id`),
+    kind: requiredString(value.kind, `${field}.kind`),
+  };
+  const displayName = optionalString(value.displayName);
+  if (displayName) identity.displayName = displayName;
+  return identity;
+}
+
+function requiredString(value, field) {
+  const clean = String(value ?? '').trim();
+  if (!clean) throw escalationError(`${field} is required`);
+  return clean;
+}
+
+function optionalString(value) {
+  const clean = String(value ?? '').trim();
+  return clean || undefined;
+}
+
+function stringArray(value) {
+  return Array.isArray(value) ? value.map((entry) => String(entry).trim()).filter(Boolean) : [];
+}
+
+function finiteNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function sameIdentity(a, b) {
+  return a?.kind === b?.kind && a?.id === b?.id;
+}
+
+function eventHash(event) {
+  return crypto.createHash('sha256').update(stableStringify(event)).digest('hex');
+}
+
+function eventComparableHash(event) {
+  const comparable = {
+    idempotencyKey: event.idempotencyKey,
+    taskId: event.taskId,
+    reason: event.reason,
+    severity: event.severity,
+    requester: event.requester,
+    evidence: event.evidence,
+  };
+  return crypto.createHash('sha256').update(stableStringify(comparable)).digest('hex');
+}
+
+function stableStringify(value) {
+  if (!value || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort((left, right) => left.localeCompare(right));
+  const properties = keys.map((key) => [
+    JSON.stringify(key),
+    stableStringify(value[key]),
+  ].join(':'));
+  return ['{', properties.join(','), '}'].join('');
+}
+
+function percentile(values, quantile) {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.max(0, Math.ceil(sorted.length * quantile) - 1);
+  return sorted[index];
+}
+
+function escalationError(message) {
+  const error = new Error(`Invalid human escalation: ${message}`);
+  error.code = 'THUMBGATE_ESCALATION_INVALID';
+  return error;
+}
+
+function isCliInvocation() {
+  return Boolean(process.argv[1]) && path.resolve(process.argv[1]) === __filename;
+}
+
+if (isCliInvocation()) {
+  const command = process.argv[2] || 'metrics';
+  const escalations = listEscalations();
+  if (command === 'list') console.log(JSON.stringify(escalations, null, 2));
+  else if (command === 'metrics') console.log(JSON.stringify(calculateEscalationMetrics(escalations), null, 2));
+  else {
+    console.error('Usage: human-escalation.js [list|metrics]');
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  calculateEscalationMetrics,
+  decideEscalation,
+  getEscalation,
+  getEscalationsPath,
+  listEscalations,
+  requestEscalation,
+};

package/scripts/hybrid-feedback-context.js

@@ -151,13 +151,14 @@ function isHookPromptEnvelope(context) {
         parsed.transcriptPath
       )
     );
-  } catch (_) {
+  } catch {
+    // Not JSON — by definition not a hook envelope.
     return false;
   }
 }
 
 function patternContext(entry) {
-  const context = entry && entry.context ? String(entry.context) : '';
+  const context = entry?.context ? String(entry.context) : '';
   if (!context) return '';
   const hasExplicitFeedback = Boolean(
     entry.whatWentWrong ||
@@ -189,48 +190,6 @@ function isAutomatedFeedback(entry) {
 }
 
 
-function isHookPromptEnvelope(context) {
-  if (!context || typeof context !== 'string') return false;
-  try {
-    const parsed = JSON.parse(context);
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
-    return Boolean(
-      parsed.prompt &&
-      (
-        parsed.hookEventName ||
-        parsed.hook_event_name ||
-        parsed.workspaceRoot ||
-        parsed.workspace_root ||
-        parsed.session_id ||
-        parsed.sessionId ||
-        parsed.transcript_path ||
-        parsed.transcriptPath
-      )
-    );
-  } catch (_) {
-    return false;
-  }
-}
-
-function patternContext(entry) {
-  const context = entry && entry.context ? String(entry.context) : '';
-  if (!context) return '';
-  const hasExplicitFeedback = Boolean(
-    entry.whatWentWrong ||
-    entry.what_went_wrong ||
-    entry.whatToChange ||
-    entry.what_to_change ||
-    entry.failureType ||
-    (Array.isArray(entry.tags) && entry.tags.length > 0) ||
-    entry.structuredRule
-  );
-  if (isHookPromptEnvelope(context) && !hasExplicitFeedback) return '';
-  if (isHookPromptEnvelope(context) && hasExplicitFeedback) {
-    return '';
-  }
-  return context;
-}
-
 /**
  * Extract ms from a timestamp value. Returns 0 on failure.
  */
@@ -494,14 +453,94 @@ function buildAdditionalContext(state, constraints, maxChars) {
  * @param {string[]} words - keyword list from a pattern
  * @returns {boolean}
  */
+// Callers hand us the pending action in several shapes: a plain command string, an object,
+// or a JSON envelope like {"toolName":…,"command":…,"filePath":…,"affectedFiles":[…]}.
+// Matching over the raw JSON meant the envelope's own KEY NAMES were part of the haystack,
+// so the tokens "files", "command", "tool", "name" and "path" were present on every single
+// evaluation. With a two-hit block threshold, any guard whose keywords included two such
+// common words blocked every action regardless of what that action was. Match on the VALUES
+// only — the guard should key on the action, never on how we happened to serialize it.
+// normalize() runs text through sanitizeFeedbackText(), which exists to reject hook
+// TRANSPORT PAYLOADS and path-dominated blobs from human FEEDBACK. That is the wrong filter
+// for the pending action we are matching against: a real action is frequently just a command
+// plus a list of file paths, which sanitizeFeedbackText() discards wholesale as a "path blob",
+// leaving an empty haystack and silently matching nothing. Apply only the redactions here.
+function normalizeActionText(text) {
+  if (!text || typeof text !== 'string') return '';
+  return text
+    .replace(/\/Users\/[^\s/]+/g, '/Users/redacted')
+    .replace(/:\d{4,5}\b/g, ':PORT')
+    .toLowerCase()
+    .trim();
+}
+
+function buildMatchHaystack(input) {
+  if (input == null) return '';
+  let value = input;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!(trimmed.startsWith('{') || trimmed.startsWith('['))) return value;
+    try {
+      value = JSON.parse(trimmed);
+    } catch {
+      return value;
+    }
+  }
+  if (typeof value !== 'object') return String(value);
+
+  const parts = [];
+  const seen = new Set();
+  const walk = (node, depth) => {
+    if (node == null || depth > 6) return;
+    if (typeof node === 'object') {
+      if (seen.has(node)) return;
+      seen.add(node);
+      for (const child of Array.isArray(node) ? node : Object.values(node)) walk(child, depth + 1);
+      return;
+    }
+    if (typeof node === 'boolean') return; // "true"/"false" are structure, not content
+    parts.push(String(node));
+  };
+  walk(value, 0);
+  return parts.join(' ');
+}
+
+// A guard word is "specific" when it is a compound identifier — keywords() preserves `-` and
+// `_`, so a token like "generated-cache" or "tool_registry" survives intact and is almost
+// always lifted from a real command, path or symbol rather than from prose. One such token
+// is strong evidence on its own.
+//
+// Deliberately NOT keyed on length: ordinary English words ("deployment", "permission",
+// "everything") are long but common, and letting one of them carry a block on its own would
+// over-block. Those still require a second corroborating hit.
+function isSpecificKeyword(word) {
+  return /[-_]/.test(word);
+}
+
+// Whole-word matching: a bare includes() let "app" hit "apps/", "application" and "happen".
+// Boundaries are non-alphanumerics, so path and punctuation separators still delimit tokens
+// (`src/jobs/queue.js` matches the word "jobs").
+function containsWholeWord(haystack, word) {
+  const escaped = String(word).replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+  try {
+    return new RegExp(`(?:^|[^a-z0-9])${escaped}(?:[^a-z0-9]|$)`, 'i').test(haystack);
+  } catch {
+    return haystack.includes(word);
+  }
+}
+
 function hasTwoKeywordHits(normalizedInput, words) {
   if (!normalizedInput || !words || words.length === 0) return false;
   let hits = 0;
+  const seen = new Set();
   for (const word of words) {
-    if (normalizedInput.includes(word)) {
-      hits++;
-      if (hits >= 2) return true;
-    }
+    if (!word || seen.has(word)) continue;
+    seen.add(word);
+    if (!containsWholeWord(normalizedInput, word)) continue;
+    // A specific compound/long token carries a match on its own; generic words need two.
+    if (isSpecificKeyword(word)) return true;
+    hits++;
+    if (hits >= 2) return true;
   }
   return false;
 }
@@ -614,7 +653,7 @@ function evaluateCompiledGuards(artifact, toolName, toolInput) {
     return { mode: 'allow', reason: '', source: 'compiled' };
   }
 
-  const normInput = normalize(toolInput || '');
+  const normInput = normalizeActionText(buildMatchHaystack(toolInput));
   const normTool = (toolName || '').toLowerCase();
 
   for (const guard of artifact.guards) {
@@ -656,7 +695,7 @@ function evaluateCompiledGuards(artifact, toolName, toolInput) {
  * @returns {{ mode: string, reason: string, source: string }}
  */
 function evaluatePretoolFromState(state, toolName, toolInput) {
-  const normInput = normalize(toolInput || '');
+  const normInput = normalizeActionText(buildMatchHaystack(toolInput));
   const normTool = (toolName || '').toLowerCase();
 
   for (const pattern of state.recurringNegativePatterns || []) {
@@ -824,6 +863,10 @@ module.exports = {
   keywords,
   hashText,
   hasTwoKeywordHits,
+  buildMatchHaystack,
+  normalizeActionText,
+  isSpecificKeyword,
+  containsWholeWord,
   readJsonl,
   getHybridPaths,
   PATHS,

package/scripts/jsonl-window.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const fs = require('node:fs');
+
+/**
+ * Read recent JSONL rows since `sinceMs`, scanning at most maxBytes from EOF.
+ * Avoids loading multi-MB ledgers entirely into memory (export timeout fix).
+ */
+function readJsonlSinceTail(filePath, {
+  sinceMs = 0,
+  limit = 1000,
+  maxBytes = 8 * 1024 * 1024,
+  timestampKeys = ['timestamp', 'receivedAt', 'ts', 'createdAt'],
+} = {}) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return { rows: [], totalAfterSince: 0, truncated: false, scannedBytes: 0 };
+  }
+
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return { rows: [], totalAfterSince: 0, truncated: false, scannedBytes: 0 };
+  }
+
+  const size = stat.size || 0;
+  if (size === 0) {
+    return { rows: [], totalAfterSince: 0, truncated: false, scannedBytes: 0 };
+  }
+
+  const scanBytes = Math.min(size, Math.max(64 * 1024, maxBytes));
+  const start = Math.max(0, size - scanBytes);
+  let buf;
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      buf = Buffer.alloc(scanBytes);
+      fs.readSync(fd, buf, 0, scanBytes, start);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return { rows: [], totalAfterSince: 0, truncated: false, scannedBytes: 0 };
+  }
+
+  let text = buf.toString('utf8');
+  // If we started mid-file, drop the partial first line.
+  if (start > 0) {
+    const nl = text.indexOf('\n');
+    text = nl >= 0 ? text.slice(nl + 1) : '';
+  }
+
+  const matched = [];
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    let parsed = NaN;
+    for (const key of timestampKeys) {
+      const raw = obj && obj[key];
+      if (raw == null) continue;
+      parsed = typeof raw === 'number' ? raw : Date.parse(raw);
+      if (Number.isFinite(parsed)) break;
+    }
+    // Preserve since filter: only include rows with a parseable timestamp
+    // inside the window. Legacy/malformed lines without timestamps must not
+    // inflate totalAfterSince or journey summaries.
+    if (Number.isFinite(parsed) && parsed >= sinceMs) {
+      matched.push(obj);
+    }
+  }
+
+  const totalAfterSince = matched.length;
+  const rows = matched.slice(-Math.max(1, limit));
+  return {
+    rows,
+    totalAfterSince,
+    truncated: totalAfterSince > rows.length || start > 0,
+    scannedBytes: scanBytes,
+  };
+}
+
+module.exports = {
+  readJsonlSinceTail,
+};

package/scripts/judge-reward-function.js

@@ -12,6 +12,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { validateStructuredOutput } = require('./tool-contract-validator');
 
 const DEFAULT_CRITERIA = [
   {
@@ -117,15 +118,19 @@ function buildCompositeReward(sample = {}, options = {}) {
   }
 
   const judge = runJudgeSafely(sample, options.judge);
-  const judgeScore = judge.ok ? judge.score : 0.5;
-  const score = round((deterministic.score * 0.65) + (judgeScore * 0.35));
+  const score = judge.ok
+    ? round((deterministic.score * 0.65) + (judge.score * 0.35))
+    : deterministic.score;
   return {
     score,
-    label: rewardLabel(score),
+    label: judge.ok ? rewardLabel(score) : 'deterministic_only',
     deterministic,
     judge,
-    failureMode: judge.ok ? [] : ['judge_error_neutral_reward'],
-    recommendation: rewardRecommendation(score),
+    scoringMode: judge.ok ? 'deterministic_plus_llm_judge' : 'deterministic_only',
+    failureMode: judge.ok ? [] : [judge.available ? 'judge_error' : 'judge_unavailable'],
+    recommendation: judge.ok
+      ? rewardRecommendation(score)
+      : 'Use deterministic results only; do not represent unavailable judge evidence as a neutral judgment.',
   };
 }
 
@@ -148,7 +153,8 @@ function buildPreferenceJudgment(a, b, options = {}) {
 function buildJudgeReadinessReport(samples = [], options = {}) {
   const rewards = samples.map((sample) => buildCompositeReward(sample, options));
   const blocked = rewards.filter((reward) => reward.label === 'deterministic_block');
-  const neutralFallbacks = rewards.filter((reward) => reward.failureMode.includes('judge_error_neutral_reward'));
+  const neutralFallbacks = rewards.filter((reward) =>
+    reward.failureMode.includes('judge_error') || reward.failureMode.includes('judge_unavailable'));
   return {
     generatedAt: new Date().toISOString(),
     samples: samples.length,
@@ -186,7 +192,7 @@ function measureJudgeConsistency(samples = [], judge = null, options = {}) {
 
 function evaluateCriterion(id, prediction, sample, { requiresJson }) {
   if (id === 'schema_valid') {
-    return evaluateSchemaCriterion(prediction, requiresJson);
+    return evaluateSchemaCriterion(prediction, requiresJson, sample.outputSchema);
   }
   if (id === 'grounded_evidence') {
     return hasGroundedEvidence(prediction);
@@ -203,14 +209,17 @@ function evaluateCriterion(id, prediction, sample, { requiresJson }) {
   return true;
 }
 
-function evaluateSchemaCriterion(prediction, requiresJson) {
+function evaluateSchemaCriterion(prediction, requiresJson, outputSchema) {
   if (!requiresJson) return true;
-  try {
-    JSON.parse(prediction);
-    return true;
-  } catch {
-    return false;
+  if (!outputSchema) {
+    try {
+      JSON.parse(prediction);
+      return true;
+    } catch {
+      return false;
+    }
   }
+  return validateStructuredOutput(prediction, outputSchema).valid;
 }
 
 function hasGroundedEvidence(prediction) {
@@ -253,9 +262,10 @@ function buildCriterionReason(id, pass) {
 function runJudgeSafely(sample, judge) {
   if (typeof judge !== 'function') {
     return {
-      ok: true,
-      score: 0.5,
-      rationale: 'No external judge configured; deterministic checks carried the reward.',
+      ok: false,
+      available: false,
+      score: null,
+      rationale: 'No external judge configured; only deterministic checks are evidence.',
       raw: null,
     };
   }
@@ -264,6 +274,7 @@ function runJudgeSafely(sample, judge) {
     const score = clamp(Number(result.score ?? result), 0, 1);
     return {
       ok: true,
+      available: true,
       score,
       rationale: result.rationale || 'Judge returned a bounded score.',
       raw: result,
@@ -271,8 +282,9 @@ function runJudgeSafely(sample, judge) {
   } catch (err) {
     return {
       ok: false,
-      score: 0.5,
-      rationale: `Judge failed; returned neutral reward. ${err.message}`,
+      available: true,
+      score: null,
+      rationale: `Judge failed; deterministic checks remain authoritative. ${err.message}`,
       raw: null,
     };
   }

package/scripts/lesson-embedding-index.js

@@ -99,16 +99,12 @@ function isEmbedderAvailable() {
     const cfg = resolveGeminiEmbeddingConfig();
     if (cfg && cfg.enabled && cfg.apiKey) return true;
   } catch { /* policy module unavailable */ }
-  // Local transformers path
-  try {
-    require.resolve('@huggingface/transformers');
-    return true;
-  } catch { /* not installed */ }
-  return false;
+  // The zero-dependency feature-hash provider is always available locally.
+  return true;
 }
 
 function defaultEmbedder() {
-  // Lazy: do not pull in LanceDB/transformers at module require time.
+  // Lazy: do not pull in LanceDB or optional embedding providers at module require time.
   const { embed } = require('./vector-store');
   return embed;
 }