thumbgate 1.27.20 → 1.28.1

package/scripts/feedback-loop.js

@@ -7,6 +7,7 @@
  *   -> compute analytics -> generate prevention rules
  */
 
+const crypto = require('node:crypto');
 const fs = require('fs');
 const path = require('path');
 const { loadOptionalModule } = require('./private-core-boundary');
@@ -19,6 +20,7 @@ const {
 const {
   buildClarificationMessage,
   isGenericFeedbackText,
+  normalizeFeedbackText,
 } = require('./feedback-quality');
 const {
   buildRubricEvaluation,
@@ -55,6 +57,10 @@ const {
 }));
 
 const AUDIT_TRAIL_TAG = 'audit-trail';
+const FEEDBACK_EVENT_DEDUPE_WINDOW_MS = 30 * 1000;
+const FEEDBACK_EVENT_CLAIM_STALE_MS = 60 * 1000;
+const FEEDBACK_EVENT_CLAIM_WAIT_MS = 15 * 1000;
+const FEEDBACK_EVENT_CLAIM_POLL_MS = 25;
 
 /**
  * Anonymous fire-and-forget CLI feedback telemetry.
@@ -631,6 +637,269 @@ function normalizeSignal(signal) {
   return null;
 }
 
+function hashFeedbackSourcePart(value) {
+  const text = String(value || '').trim();
+  if (!text) return null;
+  return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+function parseFeedbackSourceTimestamp(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value > 1e12 ? value : value * 1000;
+  }
+  const text = String(value || '').trim();
+  if (!text) return Date.now();
+  if (/^\d+$/.test(text)) {
+    const numeric = Number(text);
+    return numeric > 1e12 ? numeric : numeric * 1000;
+  }
+  const parsed = Date.parse(text);
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+/**
+ * Build a privacy-preserving identity for one external thumbs event.
+ * Raw session, prompt, and project identifiers are hashed before persistence.
+ * A prompt ID wins when present so two distinct prompts with identical text are
+ * still separate events; otherwise the session + project + text fingerprint is
+ * deduplicated inside a short capture window.
+ */
+function buildFeedbackSourceIdentity(input = {}) {
+  const signal = normalizeSignal(input.signal);
+  const normalizedText = normalizeFeedbackText(input.promptText || input.context);
+  if (!signal || !normalizedText) return null;
+
+  const sessionHash = hashFeedbackSourcePart(input.sessionId);
+  const promptIdHash = hashFeedbackSourcePart(input.promptId);
+  const projectHash = hashFeedbackSourcePart(input.projectDir || input.project);
+  if (!sessionHash && !promptIdHash) return null;
+
+  const textHash = hashFeedbackSourcePart(normalizedText);
+  const discriminator = promptIdHash
+    ? `prompt:${sessionHash || ''}:${projectHash || ''}:${promptIdHash}`
+    : `content:${sessionHash || ''}:${projectHash || ''}:${textHash}`;
+  const eventHash = hashFeedbackSourcePart(['v1', signal, discriminator].join(':'));
+  const key = `fev_${eventHash}`;
+
+  return {
+    key,
+    signal,
+    normalizedText,
+    sessionHash,
+    promptIdHash,
+    projectHash,
+    eventTimestampMs: parseFeedbackSourceTimestamp(input.timestamp),
+    source: String(input.source || 'external').replace(/[^a-z0-9._-]/gi, '-').slice(0, 64),
+  };
+}
+
+function normalizeFeedbackSourceIdentity(identity, params = {}) {
+  if (!identity || typeof identity !== 'object' || typeof identity.key !== 'string') return null;
+  const signal = normalizeSignal(params.signal || identity.signal);
+  const normalizedText = normalizeFeedbackText(
+    identity.normalizedText || params.context || params.whatWentWrong || params.whatWorked,
+  );
+  if (!signal || !normalizedText) return null;
+
+  return {
+    key: `fev_${hashFeedbackSourcePart(identity.key)}`,
+    signal,
+    normalizedText,
+    sessionHash: hashFeedbackSourcePart(identity.sessionHash),
+    promptIdHash: hashFeedbackSourcePart(identity.promptIdHash),
+    projectHash: hashFeedbackSourcePart(identity.projectHash),
+    eventTimestampMs: parseFeedbackSourceTimestamp(identity.eventTimestampMs),
+    source: String(identity.source || 'external').replace(/[^a-z0-9._-]/gi, '-').slice(0, 64),
+  };
+}
+
+function publicFeedbackSourceMetadata(identity) {
+  if (!identity) return null;
+  return {
+    key: identity.key,
+    sessionHash: identity.sessionHash,
+    promptIdHash: identity.promptIdHash,
+    projectHash: identity.projectHash,
+    source: identity.source,
+    timestamp: new Date(identity.eventTimestampMs).toISOString(),
+  };
+}
+
+function readClaimState(claimPath) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(claimPath, 'state.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeClaimState(claimPath, state) {
+  const target = path.join(claimPath, 'state.json');
+  const temporary = path.join(claimPath, `state.${process.pid}.${Date.now()}.tmp`);
+  fs.writeFileSync(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, target);
+}
+
+function sleepSync(milliseconds) {
+  const signal = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(signal, 0, 0, milliseconds);
+}
+
+function replaceStaleClaim(claimPath) {
+  const nonce = crypto.randomBytes(4).toString('hex');
+  const stalePath = `${claimPath}.stale-${process.pid}-${Date.now()}-${nonce}`;
+  try {
+    fs.renameSync(claimPath, stalePath);
+    fs.rmSync(stalePath, { recursive: true, force: true });
+    return true;
+  } catch (error) {
+    if (error && (error.code === 'ENOENT' || error.code === 'EEXIST')) return false;
+    throw error;
+  }
+}
+
+function waitForClaimCompletion(claimPath, deadlineMs) {
+  let state = readClaimState(claimPath);
+  while ((!state || state.status === 'pending') && Date.now() < deadlineMs) {
+    sleepSync(FEEDBACK_EVENT_CLAIM_POLL_MS);
+    state = readClaimState(claimPath);
+  }
+  return state;
+}
+
+function findRecordById(filePath, id) {
+  if (!id) return null;
+  const entries = readJSONL(filePath, { maxLines: 500 });
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    if (entries[index]?.id === id) return entries[index];
+  }
+  return null;
+}
+
+function duplicateCaptureResult(receipt, paths, options = {}) {
+  const feedbackEvent = findRecordById(paths.FEEDBACK_LOG_PATH, receipt?.feedbackId);
+  const memoryRecord = findRecordById(paths.MEMORY_LOG_PATH, receipt?.memoryId);
+  return {
+    accepted: Boolean(receipt?.accepted),
+    signalLogged: Boolean(receipt?.signalLogged),
+    duplicate: true,
+    pending: Boolean(options.pending),
+    status: options.pending ? 'duplicate_in_progress' : 'duplicate',
+    reason: options.pending ? 'source_event_capture_in_progress' : 'source_event_already_captured',
+    message: options.pending
+      ? 'Equivalent feedback is already being captured.'
+      : 'This feedback event was already captured; no counters or lessons were changed.',
+    feedbackEvent: feedbackEvent || (receipt?.feedbackId ? { id: receipt.feedbackId } : null),
+    memoryRecord: memoryRecord || (receipt?.memoryId ? { id: receipt.memoryId } : null),
+  };
+}
+
+function sourceHashMatches(expected, actual) {
+  return !expected || !actual || expected === actual;
+}
+
+function isDuplicateFeedbackEntry(entry, identity) {
+  if (!entry || entry.signal !== identity.signal) return false;
+  if (normalizeFeedbackText(entry.submittedContext || entry.context) !== identity.normalizedText) return false;
+
+  const sourceEvent = entry.sourceEvent || {};
+  if (!sourceHashMatches(identity.sessionHash, sourceEvent.sessionHash)) return false;
+  if (!sourceHashMatches(identity.projectHash, sourceEvent.projectHash)) return false;
+  if (!sourceHashMatches(identity.promptIdHash, sourceEvent.promptIdHash)) return false;
+  if (identity.promptIdHash && sourceEvent.promptIdHash === identity.promptIdHash) return true;
+
+  const timestamp = parseFeedbackSourceTimestamp(sourceEvent.timestamp || entry.timestamp);
+  return Math.abs(identity.eventTimestampMs - timestamp) <= FEEDBACK_EVENT_DEDUPE_WINDOW_MS;
+}
+
+function receiptFromFeedbackEntry(entry, paths) {
+  if (!entry) return null;
+  const memories = readJSONL(paths.MEMORY_LOG_PATH, { maxLines: 500 });
+  const memory = memories.find((candidate) => candidate?.sourceFeedbackId === entry.id);
+  return {
+    status: 'complete',
+    feedbackId: entry.id,
+    memoryId: memory?.id,
+    accepted: entry.actionType !== 'no-action'
+      && (!Array.isArray(entry.validationIssues) || entry.validationIssues.length === 0),
+    signalLogged: true,
+    completedAtMs: Date.parse(entry.timestamp || '') || Date.now(),
+  };
+}
+
+function recentDuplicateReceipt(identity, paths) {
+  const entries = readJSONL(paths.FEEDBACK_LOG_PATH, { maxLines: 250 });
+  const entry = entries.findLast((candidate) => isDuplicateFeedbackEntry(candidate, identity));
+  return receiptFromFeedbackEntry(entry, paths);
+}
+
+function tryCreateFeedbackClaim(claimPath) {
+  try {
+    fs.mkdirSync(claimPath, { mode: 0o700 });
+    writeClaimState(claimPath, { status: 'pending', startedAtMs: Date.now() });
+    return { owned: true, claimPath };
+  } catch (error) {
+    if (error?.code === 'EEXIST') return null;
+    throw error;
+  }
+}
+
+function existingClaimResult(state, identity, paths) {
+  const stateTimestamp = Number(state?.completedAtMs || state?.startedAtMs || 0);
+  const ageMs = stateTimestamp > 0 ? Date.now() - stateTimestamp : 0;
+  if (state?.status === 'complete'
+    && (identity.promptIdHash || ageMs <= FEEDBACK_EVENT_DEDUPE_WINDOW_MS)) {
+    return duplicateCaptureResult(state, paths);
+  }
+  if (state?.status === 'pending' && ageMs <= FEEDBACK_EVENT_CLAIM_STALE_MS) {
+    return duplicateCaptureResult(state, paths, { pending: true });
+  }
+  return null;
+}
+
+function acquireFeedbackEventClaim(identity, paths) {
+  const recent = recentDuplicateReceipt(identity, paths);
+  if (recent) return { owned: false, result: duplicateCaptureResult(recent, paths) };
+
+  const claimsRoot = path.join(paths.FEEDBACK_DIR, '.feedback-event-claims');
+  const claimPath = path.join(claimsRoot, identity.key);
+  ensureDir(claimsRoot);
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const ownedClaim = tryCreateFeedbackClaim(claimPath);
+    if (ownedClaim) return ownedClaim;
+
+    const state = waitForClaimCompletion(claimPath, Date.now() + FEEDBACK_EVENT_CLAIM_WAIT_MS);
+    const duplicateResult = existingClaimResult(state, identity, paths);
+    if (duplicateResult) return { owned: false, result: duplicateResult };
+    if (!replaceStaleClaim(claimPath)) continue;
+  }
+
+  return {
+    owned: false,
+    result: duplicateCaptureResult(null, paths, { pending: true }),
+  };
+}
+
+function finalizeFeedbackEventClaim(claim, result) {
+  if (!claim?.owned) return;
+  writeClaimState(claim.claimPath, {
+    status: 'complete',
+    startedAtMs: Date.now(),
+    completedAtMs: Date.now(),
+    accepted: Boolean(result?.accepted),
+    signalLogged: Boolean(result?.signalLogged || result?.feedbackEvent),
+    feedbackId: result?.feedbackEvent?.id || null,
+    memoryId: result?.memoryRecord?.id || null,
+  });
+}
+
+function releaseFeedbackEventClaim(claim) {
+  if (claim?.owned && claim.claimPath) {
+    fs.rmSync(claim.claimPath, { recursive: true, force: true });
+  }
+}
+
 function parseOptionalObject(input, name) {
   if (input == null) return {};
   if (typeof input === 'object' && !Array.isArray(input)) return input;
@@ -1144,6 +1413,7 @@ function captureFeedback(params) {
     structuredRule: structuredRule || null,
     ...(reflection && { reflection }),
     gateAction: params.gateAction || null,
+    sourceEvent: publicFeedbackSourceMetadata(params.sourceEvent),
     timestamp: now,
   };
 
@@ -1567,6 +1837,24 @@ function captureFeedback(params) {
   return result;
 }
 
+function captureFeedbackIdempotent(params = {}) {
+  const paths = getFeedbackPaths();
+  const identity = normalizeFeedbackSourceIdentity(params.sourceEvent, params);
+  if (!identity) return captureFeedback(params);
+
+  const claim = acquireFeedbackEventClaim(identity, paths);
+  if (!claim.owned) return claim.result;
+
+  try {
+    const result = captureFeedback({ ...params, sourceEvent: identity });
+    finalizeFeedbackEventClaim(claim, result);
+    return result;
+  } catch (error) {
+    releaseFeedbackEventClaim(claim);
+    throw error;
+  }
+}
+
 function analyzeFeedback(logPath) {
   const { FEEDBACK_LOG_PATH } = getFeedbackPaths();
   const resolvedLogPath = logPath || FEEDBACK_LOG_PATH;
@@ -2200,7 +2488,8 @@ function buildCorrectiveActionsReminder(correctiveActions = []) {
 }
 
 module.exports = {
-  captureFeedback,
+  captureFeedback: captureFeedbackIdempotent,
+  buildFeedbackSourceIdentity,
   compactMemories,
   buildCorrectiveActionsReminder,
   analyzeFeedback,

package/scripts/feedback-quality.js

@@ -100,49 +100,48 @@ function isNearDownToken(token) {
 
 function detectFeedbackSignal(value) {
   const raw = String(value || '');
-  if (/[👎👎🏻👎🏼👎🏽👎🏾👎🏿]/u.test(raw)) return { signal: 'down', confidence: 'emoji', match: '👎' };
-  if (/[👍👍🏻👍🏼👍🏽👍🏾👍🏿]/u.test(raw)) return { signal: 'up', confidence: 'emoji', match: '👍' };
+  const leading = raw.trimStart();
+  if (/^["'`]/.test(leading)) return null;
+  if (/^👎(?:🏻|🏼|🏽|🏾|🏿)?/u.test(leading)) return { signal: 'down', confidence: 'emoji', match: '👎' };
+  if (/^👍(?:🏻|🏼|🏽|🏾|🏿)?/u.test(leading)) return { signal: 'up', confidence: 'emoji', match: '👍' };
 
   const normalized = normalizeFeedbackText(raw);
   if (!normalized) return null;
 
   const exactDown = [
-    /\bthumbs?\s*down\b/,
-    /\bthumbs?down\b/,
-    /\bthat failed\b/,
-    /\bit failed\b/,
-    /\bthat was wrong\b/,
-    /\bfix this\b/,
+    /^thumbs?\s*down\b/,
+    /^thumbs?down\b/,
+    /^that failed\b/,
+    /^it failed\b/,
+    /^that was wrong\b/,
   ];
   if (exactDown.some((pattern) => pattern.test(normalized))) {
     return { signal: 'down', confidence: 'exact', match: normalized };
   }
 
   const exactUp = [
-    /\bthumbs?\s*up\b/,
-    /\bthumbs?up\b/,
-    /\bthat worked\b/,
-    /\bit worked\b/,
-    /\blooks good\b/,
-    /\bgood job\b/,
-    /\bgood work\b/,
-    /\bnice work\b/,
-    /\bperfect\b/,
-    /\blgtm\b/,
+    /^thumbs?\s*up\b/,
+    /^thumbs?up\b/,
+    /^that worked\b/,
+    /^it worked\b/,
+    /^looks good\b/,
+    /^good job\b/,
+    /^good work\b/,
+    /^nice work\b/,
+    /^perfect\b/,
+    /^lgtm\b/,
   ];
   if (exactUp.some((pattern) => pattern.test(normalized))) {
     return { signal: 'up', confidence: 'exact', match: normalized };
   }
 
   const words = normalized.split(/\s+/).filter(Boolean);
-  for (let i = 0; i < words.length - 1; i++) {
-    if (!isNearThumbToken(words[i])) continue;
-    if (isNearDownToken(words[i + 1])) {
-      return { signal: 'down', confidence: 'fuzzy', match: `${words[i]} ${words[i + 1]}` };
-    }
-    if (isNearUpToken(words[i + 1])) {
-      return { signal: 'up', confidence: 'fuzzy', match: `${words[i]} ${words[i + 1]}` };
-    }
+  if (!isNearThumbToken(words[0])) return null;
+  if (isNearDownToken(words[1])) {
+    return { signal: 'down', confidence: 'fuzzy', match: `${words[0]} ${words[1]}` };
+  }
+  if (isNearUpToken(words[1])) {
+    return { signal: 'up', confidence: 'fuzzy', match: `${words[0]} ${words[1]}` };
   }
 
   return null;

package/scripts/feedback-sanitizer.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const crypto = require('crypto');
+const crypto = require('node:crypto');
 
 const TRANSPORT_KEYS = new Set([
   'hookeventname',
@@ -52,10 +52,136 @@ const TRANSPORT_WORDS = new Set([
   'json',
 ]);
 
+// Transport keys that distinguish hook/session envelopes from ordinary JSON
+// tool inputs. A JSON object is rejected only when it carries one of these
+// keys; valid inputs such as {"filePath":"AGENTS.md"} must remain searchable.
+const REJECT_SUBSTRINGS = [
+  'session_id',
+  'transcript_path',
+  'prompt_id',
+  'hook_event_name',
+];
+const REJECT_JSON_KEYS = new Set([
+  ...REJECT_SUBSTRINGS,
+  'sessionid',
+  'transcriptpath',
+  'promptid',
+  'hookeventname',
+]);
+
+// A token is treated as a filesystem-path fragment when it contains a path
+// separator, ends in a machine-file extension, or is a bare UUID.
+function isPathToken(token) {
+  if (!token) return false;
+  return (
+    token.includes('/') ||
+    token.includes('\\') ||
+    /\.(?:jsonl|json|log|sqlite|db)$/i.test(token) ||
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(token)
+  );
+}
+
+function parseJsonValue(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    return { ok: false, value: null };
+  }
+}
+
+function hasTransportJsonKey(text) {
+  const trimmed = String(text || '').trim();
+  if (!/^[[{]/.test(trimmed)) return false;
+  const parsedResult = parseJsonValue(trimmed);
+  if (!parsedResult.ok) return false;
+  const parsed = parsedResult.value;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
+  const keys = new Set(Object.keys(parsed).map((key) => key.toLowerCase()));
+  return [...keys].some((key) => REJECT_JSON_KEYS.has(key));
+}
+
+// Positive rejection guard. Returns true when `text` is a transport/metadata
+// blob that must never be stored as a lesson, because it:
+//   (a) is a JSON object carrying a hook/session transport key, OR
+//   (b) contains multiple known transport marker substrings, OR
+//   (c) is dominated by filesystem-path tokens.
+function looksLikeTransportBlob(text) {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return false;
+
+  if (hasTransportJsonKey(trimmed)) return true;
+
+  // Multiple marker names identify non-JSON transport residue. A human
+  // sentence that merely discusses `session_id` is not itself an envelope.
+  const lower = trimmed.toLowerCase();
+  const markerCount = REJECT_SUBSTRINGS.filter((marker) => lower.includes(marker)).length;
+  if (markerCount >= 2) return true;
+
+  // (b) Dominated by filesystem-path tokens.
+  const tokens = trimmed.split(/\s+/).filter(Boolean);
+  if (tokens.length > 0) {
+    const pathTokens = tokens.filter(isPathToken);
+    if (pathTokens.length > 0 && pathTokens.length / tokens.length > 0.5) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function firstStringField(record, names) {
+  for (const name of names) {
+    if (typeof record[name] === 'string' && record[name].trim()) return record[name].trim();
+    if (typeof record[name] === 'number' && Number.isFinite(record[name])) return String(record[name]);
+  }
+  return null;
+}
+
+/**
+ * Extract the human prompt plus the minimum source metadata needed to identify
+ * one hook event. Transcript paths and raw identifiers never enter lesson text;
+ * callers hash the source fields before persistence.
+ */
+function extractPromptEnvelope(rawStdin) {
+  const raw = typeof rawStdin === 'string' ? rawStdin : '';
+  const trimmed = raw.trim();
+  if (!trimmed) return { prompt: '' };
+
+  if (/^[[{]/.test(trimmed)) {
+    const parsedResult = parseJsonValue(trimmed);
+    if (!parsedResult.ok) return { prompt: trimmed };
+    const parsed = parsedResult.value;
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return {
+        prompt: typeof parsed.prompt === 'string' ? parsed.prompt.trim() : '',
+        sessionId: firstStringField(parsed, ['session_id', 'sessionId']),
+        promptId: firstStringField(parsed, ['prompt_id', 'promptId']),
+        projectDir: firstStringField(parsed, ['cwd', 'project', 'project_dir', 'projectDir']),
+        timestamp: firstStringField(parsed, ['timestamp', 'created_at', 'createdAt']),
+        hookEventName: firstStringField(parsed, ['hook_event_name', 'hookEventName']),
+      };
+    }
+    return { prompt: '' };
+  }
+
+  return { prompt: trimmed };
+}
+
+// Persist ONLY the human `.prompt` field from a hook transport envelope.
+function extractPromptText(rawStdin) {
+  return extractPromptEnvelope(rawStdin).prompt;
+}
+
 function stripEphemeralText(text) {
   if (!text || typeof text !== 'string') return '';
-  return String(text)
-    .replace(/["']?(?:hook_?event_?name|session_?id|transcript_?path|timestamp|created_?at|updated_?at|cwd|pid|process_?id|prompt_?id|trace_?id|request_?id|install_?id|visitor_?session_?id)["']?\s*[:=]\s*["']?[^"',}\]\s]+["']?/gi, ' ')
+  let stripped = String(text);
+  for (const key of TRANSPORT_KEYS) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+    const assignment = new RegExp(String.raw`["']?${escapedKey}["']?\s*[:=]\s*["']?[^"',}\]\s]+["']?`, 'gi');
+    stripped = stripped.replace(assignment, ' ');
+  }
+  return stripped
     .replace(/\/(?:private\/)?tmp\/[^\s"',}\]]+/gi, ' ')
     .replace(/\/var\/folders\/[^\s"',}\]]+/gi, ' ')
     .replace(/\/Users\/[^/\s]+\/\.(?:claude|codex|thumbgate)\/[^\s"',}\]]+/gi, ' ')
@@ -68,6 +194,10 @@ function stripEphemeralText(text) {
 }
 
 function transportWordsOnly(text) {
+  // Positive rejection first: JSON payloads, transport markers, and
+  // path-dominated blobs are always "transport only" regardless of the
+  // incidental non-transport words they contain.
+  if (looksLikeTransportBlob(text)) return true;
   const tokens = String(text || '')
     .toLowerCase()
     .replace(/[^a-z0-9_ -]/g, ' ')
@@ -78,6 +208,20 @@ function transportWordsOnly(text) {
 }
 
 function sanitizeFeedbackText(text) {
+  const raw = String(text || '').trim();
+  // A raw hook-stdin PAYLOAD — a pure JSON object carrying transport markers
+  // (session_id / transcript_path / prompt_id / hook_event_name) — is never a
+  // human lesson; reject it whole, even when it also carries a `prompt` field
+  // (that field is pulled out separately via extractPromptText). But do NOT
+  // reject content JSON that carries no transport markers (e.g. a tool input
+  // {"filePath":"…","reason":"…"}): it must survive so it can be matched against
+  // patterns. The discriminator is the marker, not JSON-ness.
+  if (hasTransportJsonKey(raw)) return '';
+  // Otherwise scrub ephemeral marker key:value pairs and volatile paths, then
+  // reject only if nothing substantive remains — so real feedback that arrives
+  // next to hook metadata keeps the sentence while the metadata is stripped, and
+  // space-separated marker residue / path-dominated blobs collapse to
+  // transport-only text and are dropped by transportWordsOnly().
   const stripped = stripEphemeralText(text)
     .replace(/\/Users\/[^\s/]+/g, '/Users/redacted')
     .replace(/\s+/g, ' ')
@@ -99,7 +243,11 @@ function actionFingerprint(parts) {
 
 module.exports = {
   TRANSPORT_WORDS,
+  REJECT_SUBSTRINGS,
   sanitizeFeedbackText,
   actionFingerprint,
   transportWordsOnly,
+  looksLikeTransportBlob,
+  extractPromptEnvelope,
+  extractPromptText,
 };