thumbgate 1.5.4 → 1.6.0

package/scripts/dashboard.js

@@ -26,6 +26,7 @@ const { computeDecisionMetrics } = require('./decision-journal');
 const PROJECT_ROOT = path.join(__dirname, '..');
 const DEFAULT_GATES_PATH = path.join(PROJECT_ROOT, 'config', 'gates', 'default.json');
 const LANDING_PAGE_PATH = path.join(PROJECT_ROOT, 'public', 'index.html');
+const DASHBOARD_REVIEW_STATE_FILE = 'dashboard-review-state.json';
 
 // ---------------------------------------------------------------------------
 // Data readers
@@ -72,6 +73,225 @@ function toLocalDayKey(value) {
   return `${year}-${month}-${day}`;
 }
 
+function getDashboardReviewStatePath(feedbackDir) {
+  return path.join(feedbackDir, DASHBOARD_REVIEW_STATE_FILE);
+}
+
+function inferProjectRootFromFeedbackDir(feedbackDir) {
+  if (!feedbackDir) return null;
+  const resolved = path.resolve(feedbackDir);
+  return path.basename(resolved) === '.thumbgate' ? path.dirname(resolved) : null;
+}
+
+function resolveGitDir(projectRoot) {
+  const gitPath = path.join(projectRoot, '.git');
+  if (!fs.existsSync(gitPath)) return null;
+  const stat = fs.statSync(gitPath);
+  if (stat.isDirectory()) return gitPath;
+  // Worktree / submodule: .git is a file like "gitdir: /path/to/real/gitdir".
+  // Parse with startsWith+slice — no regex, so no ReDoS surface (S5852).
+  if (stat.isFile()) {
+    const contents = fs.readFileSync(gitPath, 'utf8').trim();
+    const prefix = 'gitdir:';
+    if (!contents.startsWith(prefix)) return null;
+    const target = contents.slice(prefix.length).trim();
+    if (!target) return null;
+    const resolved = path.isAbsolute(target)
+      ? target
+      : path.resolve(projectRoot, target);
+    return fs.existsSync(resolved) ? resolved : null;
+  }
+  return null;
+}
+
+function readGitHead(projectRoot) {
+  if (!projectRoot) return null;
+  const gitDir = resolveGitDir(projectRoot);
+  if (!gitDir) return null;
+  try {
+    // Read .git/HEAD directly instead of spawning `git rev-parse HEAD`.
+    // Avoids S4036 (PATH-resolved binary) and is faster: no subprocess.
+    const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+    if (!head) return null;
+    // Detached HEAD: the file contains the raw SHA.
+    if (/^[0-9a-f]{40}$/i.test(head)) return head;
+    // Symbolic ref: "ref: refs/heads/<branch>" — resolve the ref file.
+    // Parse with startsWith+slice — no regex, so no ReDoS surface (S5852).
+    const refPrefix = 'ref:';
+    if (!head.startsWith(refPrefix)) return null;
+    const refName = head.slice(refPrefix.length).trim();
+    if (!refName) return null;
+    // For worktrees, the commondir points to the main .git. Refs may live
+    // there rather than in the per-worktree gitdir.
+    const commonDirFile = path.join(gitDir, 'commondir');
+    let commonDir = gitDir;
+    if (fs.existsSync(commonDirFile)) {
+      const rel = fs.readFileSync(commonDirFile, 'utf8').trim();
+      commonDir = path.isAbsolute(rel) ? rel : path.resolve(gitDir, rel);
+    }
+    for (const base of [gitDir, commonDir]) {
+      const refPath = path.join(base, refName);
+      if (fs.existsSync(refPath)) {
+        const sha = fs.readFileSync(refPath, 'utf8').trim();
+        if (/^[0-9a-f]{40}$/i.test(sha)) return sha;
+      }
+    }
+    // Packed refs fallback.
+    const packed = path.join(commonDir, 'packed-refs');
+    if (!fs.existsSync(packed)) return null;
+    const lines = fs.readFileSync(packed, 'utf8').split(/\r?\n/);
+    for (const line of lines) {
+      if (line.startsWith('#') || line.startsWith('^')) continue;
+      const [sha, ref] = line.split(/\s+/);
+      if (ref === refName && /^[0-9a-f]{40}$/i.test(sha)) return sha;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function findLatestTimestamp(entries) {
+  return entries.reduce((latest, entry) => {
+    const timestamp = normalizeText(entry && entry.timestamp);
+    if (!timestamp) return latest;
+    if (!latest) return timestamp;
+    return new Date(timestamp).getTime() > new Date(latest).getTime() ? timestamp : latest;
+  }, null);
+}
+
+function buildReviewSnapshot(feedbackDir, options = {}) {
+  const feedbackEntries = Array.isArray(options.feedbackEntries)
+    ? options.feedbackEntries
+    : readJSONL(path.join(feedbackDir, 'feedback-log.jsonl'));
+  const memoryEntries = Array.isArray(options.memoryEntries)
+    ? options.memoryEntries
+    : readJSONL(path.join(feedbackDir, 'memory-log.jsonl'));
+  const auditEntries = Array.isArray(options.auditEntries)
+    ? options.auditEntries
+    : readJSONL(path.join(feedbackDir, AUDIT_LOG_FILENAME));
+  const projectRoot = options.projectRoot === undefined
+    ? inferProjectRootFromFeedbackDir(feedbackDir)
+    : options.projectRoot;
+
+  return {
+    reviewedAt: options.reviewedAt || new Date().toISOString(),
+    feedbackCount: feedbackEntries.length,
+    positiveCount: feedbackEntries.filter((entry) => entry.signal === 'positive').length,
+    negativeCount: feedbackEntries.filter((entry) => entry.signal === 'negative').length,
+    lessonCount: memoryEntries.length,
+    blockedCount: auditEntries.filter((entry) => entry && entry.decision === 'deny').length,
+    warnedCount: auditEntries.filter((entry) => entry && entry.decision === 'warn').length,
+    latestFeedbackAt: findLatestTimestamp(feedbackEntries),
+    latestLessonAt: findLatestTimestamp(memoryEntries),
+    gitHead: readGitHead(projectRoot),
+  };
+}
+
+function readDashboardReviewState(feedbackDir) {
+  return readJsonFile(getDashboardReviewStatePath(feedbackDir));
+}
+
+function writeDashboardReviewState(feedbackDir, snapshot) {
+  fs.mkdirSync(feedbackDir, { recursive: true });
+  fs.writeFileSync(getDashboardReviewStatePath(feedbackDir), `${JSON.stringify(snapshot, null, 2)}\n`);
+  return snapshot;
+}
+
+function selectLatestRecord(entries, mapper) {
+  let latest = null;
+  let latestTime = -Infinity;
+  for (const entry of entries) {
+    const timestamp = normalizeText(entry && entry.timestamp);
+    if (!timestamp) continue;
+    const currentTime = new Date(timestamp).getTime();
+    if (Number.isNaN(currentTime) || currentTime < latestTime) continue;
+    latest = mapper(entry);
+    latestTime = currentTime;
+  }
+  return latest;
+}
+
+function summarizeReviewDelta(feedbackEntries, memoryEntries, auditEntries, baseline, currentSnapshot) {
+  const noBaselineSummary = {
+    hasBaseline: false,
+    reviewedAt: null,
+    previousHead: null,
+    currentHead: currentSnapshot.gitHead || null,
+    feedbackAdded: feedbackEntries.length,
+    negativeAdded: feedbackEntries.filter((entry) => entry.signal === 'negative').length,
+    lessonsAdded: memoryEntries.length,
+    blocksAdded: auditEntries.filter((entry) => entry && entry.decision === 'deny').length,
+    warnsAdded: auditEntries.filter((entry) => entry && entry.decision === 'warn').length,
+    headline: 'No review checkpoint yet. Mark the current dashboard as reviewed to start seeing only new changes.',
+    latestFeedback: selectLatestRecord(feedbackEntries, (entry) => ({
+      title: pickFirstText(entry.title, entry.context, entry.whatWentWrong, entry.whatWorked) || 'Feedback event',
+      timestamp: entry.timestamp,
+      signal: entry.signal || null,
+    })),
+    latestLesson: selectLatestRecord(memoryEntries, (entry) => ({
+      title: pickFirstText(entry.title, entry.content) || 'Lesson event',
+      timestamp: entry.timestamp,
+      category: entry.category || null,
+    })),
+  };
+
+  if (!baseline || !baseline.reviewedAt) return noBaselineSummary;
+
+  const reviewedAtMs = new Date(baseline.reviewedAt).getTime();
+  if (!Number.isFinite(reviewedAtMs)) return noBaselineSummary;
+
+  const isAfterBaseline = (entry) => {
+    const timestamp = entry && entry.timestamp ? new Date(entry.timestamp).getTime() : NaN;
+    return Number.isFinite(timestamp) && timestamp > reviewedAtMs;
+  };
+  const newFeedback = feedbackEntries.filter(isAfterBaseline);
+  const newLessons = memoryEntries.filter(isAfterBaseline);
+  const newAudit = auditEntries.filter(isAfterBaseline);
+  const reviewFeedback = newFeedback.some((entry) => entry.signal === 'negative')
+    ? newFeedback.filter((entry) => entry.signal === 'negative')
+    : newFeedback;
+  const feedbackAdded = newFeedback.length;
+  const negativeAdded = newFeedback.filter((entry) => entry.signal === 'negative').length;
+  const lessonsAdded = newLessons.length;
+  const blocksAdded = newAudit.filter((entry) => entry && entry.decision === 'deny').length;
+  const warnsAdded = newAudit.filter((entry) => entry && entry.decision === 'warn').length;
+  let headline = 'No new review activity since your last checkpoint.';
+
+  if (feedbackAdded || lessonsAdded || blocksAdded || warnsAdded) {
+    const parts = [];
+    if (feedbackAdded) parts.push(`${feedbackAdded} feedback event${feedbackAdded === 1 ? '' : 's'}`);
+    if (negativeAdded) parts.push(`${negativeAdded} negative`);
+    if (lessonsAdded) parts.push(`${lessonsAdded} lesson${lessonsAdded === 1 ? '' : 's'}`);
+    if (blocksAdded) parts.push(`${blocksAdded} gate block${blocksAdded === 1 ? '' : 's'}`);
+    if (warnsAdded) parts.push(`${warnsAdded} warning${warnsAdded === 1 ? '' : 's'}`);
+    headline = `Since your last review: ${parts.join(' · ')}.`;
+  }
+
+  return {
+    hasBaseline: true,
+    reviewedAt: baseline.reviewedAt,
+    previousHead: baseline.gitHead || null,
+    currentHead: currentSnapshot.gitHead || null,
+    feedbackAdded,
+    negativeAdded,
+    lessonsAdded,
+    blocksAdded,
+    warnsAdded,
+    headline,
+    latestFeedback: selectLatestRecord(reviewFeedback, (entry) => ({
+      title: pickFirstText(entry.title, entry.context, entry.whatWentWrong, entry.whatWorked) || 'Feedback event',
+      timestamp: entry.timestamp,
+      signal: entry.signal || null,
+    })),
+    latestLesson: selectLatestRecord(newLessons, (entry) => ({
+      title: pickFirstText(entry.title, entry.content) || 'Lesson event',
+      timestamp: entry.timestamp,
+      category: entry.category || null,
+    })),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Approval rate + trend
 // ---------------------------------------------------------------------------
@@ -904,6 +1124,17 @@ function generateDashboard(feedbackDir, options = {}) {
   const diagnosticLogPath = path.join(feedbackDir, 'diagnostic-log.jsonl');
   const entries = collectAllFeedbackEntries(feedbackDir);
   const diagnosticEntries = readJSONL(diagnosticLogPath);
+  const memoryEntries = readJSONL(path.join(feedbackDir, 'memory-log.jsonl'));
+  const auditEntries = readJSONL(path.join(feedbackDir, AUDIT_LOG_FILENAME));
+  const reviewBaseline = options.reviewBaseline === undefined
+    ? readDashboardReviewState(feedbackDir)
+    : options.reviewBaseline;
+  const reviewSnapshot = buildReviewSnapshot(feedbackDir, {
+    feedbackEntries: entries,
+    memoryEntries,
+    auditEntries,
+    reviewedAt: options.now || new Date().toISOString(),
+  });
   const billingSummary = options.billingSummary || getBillingSummary(analyticsWindow);
 
   const approval = computeApprovalStats(entries);
@@ -971,6 +1202,18 @@ function generateDashboard(feedbackDir, options = {}) {
   const feedbackTimeSeries = computeFeedbackTimeSeries(entries, 30);
   const lessonPipeline = computeLessonPipeline(feedbackDir, entries, gateStats);
 
+  // Estimated token savings — computed from gate blocked counts using the
+  // conservative methodology in scripts/token-savings.js. This is the ONLY
+  // place "$ saved" appears that's backed by real gate-block data; the landing
+  // page hero uses a hardcoded sample number disclosed as "Sample".
+  let tokenSavings = null;
+  try {
+    const { computeTokenSavings } = require('./token-savings');
+    tokenSavings = computeTokenSavings({
+      blockedCalls: Number(gateStats.blocked) || 0,
+    });
+  } catch { /* module missing — skip */ }
+
   // Merge lesson counts into feedbackTimeSeries days
   for (const day of feedbackTimeSeries.days) {
     day.lessons = lessonPipeline.lessonsByDay.get(day.dayKey) || 0;
@@ -988,6 +1231,7 @@ function generateDashboard(feedbackDir, options = {}) {
     gateStats,
     team,
   });
+  const reviewDelta = summarizeReviewDelta(entries, memoryEntries, auditEntries, reviewBaseline, reviewSnapshot);
 
   return {
     operational: {
@@ -1017,7 +1261,9 @@ function generateDashboard(feedbackDir, options = {}) {
     templateLibrary,
     liveMetrics,
     predictive,
+    reviewDelta,
     feedbackTimeSeries,
+    tokenSavings,
     lessonPipeline: {
       stages: lessonPipeline.stages,
       rates: lessonPipeline.rates,
@@ -1287,6 +1533,9 @@ function printDashboard(data) {
 
 module.exports = {
   generateDashboard,
+  buildReviewSnapshot,
+  readDashboardReviewState,
+  writeDashboardReviewState,
   printDashboard,
   computeApprovalStats,
   computeDecisionMetrics,

package/scripts/gates-engine.js

@@ -1518,6 +1518,146 @@ function buildBehavioralContext() {
   }
 }
 
+/**
+ * Build "recent mistakes" context by reading the tail of memory-log.jsonl.
+ * Surfaces the 3 most recent negative-signal memories (captured via
+ * capture_feedback) as a reminder on EVERY tool call — even when semantic
+ * retrieval returns nothing and there are no recurring patterns yet.
+ *
+ * This plugs the cold-start gap: a mistake captured seconds ago should
+ * surface on the very next tool call, not wait for the recurring-pattern
+ * threshold (≥2 occurrences) that buildBehavioralContext requires.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.maxAgeMs=86400000] - Only include memories from the last 24h by default
+ * @param {number} [options.limit=3]
+ * @returns {string|null}
+ */
+function buildRecentCorrectiveActionsContext(options = {}) {
+  const maxAgeMs = typeof options.maxAgeMs === 'number' ? options.maxAgeMs : 24 * 60 * 60 * 1000;
+  const limit = typeof options.limit === 'number' ? options.limit : 3;
+
+  let resolveFeedbackDir;
+  try {
+    ({ resolveFeedbackDir } = require('./feedback-paths'));
+  } catch {
+    return null;
+  }
+
+  let feedbackDir;
+  try {
+    feedbackDir = resolveFeedbackDir({});
+  } catch {
+    return null;
+  }
+
+  const memoryLogPath = path.join(feedbackDir, 'memory-log.jsonl');
+  if (!fs.existsSync(memoryLogPath)) return null;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(memoryLogPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const lines = raw.split('\n').filter(Boolean);
+  if (lines.length === 0) return null;
+
+  const cutoff = Date.now() - maxAgeMs;
+  const recent = [];
+
+  // Walk from the tail backwards so we get the newest entries first
+  for (let i = lines.length - 1; i >= 0 && recent.length < limit; i--) {
+    try {
+      const entry = JSON.parse(lines[i]);
+      if (entry.category !== 'error' && entry.category !== 'learning') continue;
+      const ts = entry.timestamp ? Date.parse(entry.timestamp) : NaN;
+      if (!Number.isFinite(ts) || ts < cutoff) continue;
+      recent.push(entry);
+    } catch {
+      // skip malformed line
+    }
+  }
+
+  if (recent.length === 0) return null;
+
+  const formatted = recent.map((m) => {
+    const title = String(m.title || '').replace(/^MISTAKE:\s*/, '').slice(0, 140);
+    const content = String(m.content || '');
+    const avoidMatch = content.match(/How to avoid:\s*([^\n]+)/i);
+    const advice = avoidMatch ? avoidMatch[1].trim().slice(0, 220) : null;
+    return advice ? `  • ${title}\n    → ${advice}` : `  • ${title}`;
+  });
+
+  return `[ThumbGate] Recent mistakes (last 24h) — do NOT repeat:\n${formatted.join('\n')}`;
+}
+
+/**
+ * Build per-action lesson context: retrieve semantically-relevant lessons for this
+ * specific tool call and inject the top negative ones into hook output so the agent
+ * sees its past mistakes BEFORE executing the action (not after).
+ *
+ * This is the enforcement mechanism that turns ThumbGate from a passive log into an
+ * active governor. Without this, lessons stay in the DB and never get surfaced at
+ * decision time — so the agent repeats mistakes.
+ */
+function buildRelevantLessonContext(toolName, toolInput) {
+  if (!toolName) return null;
+
+  let retrieveRelevantLessons;
+  try {
+    ({ retrieveRelevantLessons } = require('./lesson-retrieval'));
+  } catch {
+    return null;
+  }
+
+  // Extract a searchable action context from the tool input
+  const actionContext = extractActionContext(toolName, toolInput);
+  if (!actionContext) return null;
+
+  try {
+    const lessons = retrieveRelevantLessons(toolName, actionContext, { maxResults: 3 });
+    // retrieveRelevantLessons already filters at relevanceScore > 0.1 internally;
+    // any negative lesson that survives retrieval is relevant enough to surface.
+    const negative = lessons.filter((l) => l.signal === 'negative');
+    if (negative.length === 0) return null;
+
+    const formatted = negative.map((l) => {
+      const title = (l.title || '').replace(/^MISTAKE:\s*/, '').slice(0, 140);
+      const advice = extractAvoidanceAdvice(l.content);
+      return advice ? `  • ${title}\n    → ${advice}` : `  • ${title}`;
+    });
+
+    return `[ThumbGate] Past mistakes relevant to this action — read before proceeding:\n${formatted.join('\n')}`;
+  } catch {
+    return null;
+  }
+}
+
+function extractActionContext(toolName, toolInput) {
+  if (!toolInput) return toolName;
+  const parts = [toolName];
+  if (toolInput.command) parts.push(String(toolInput.command).slice(0, 400));
+  if (toolInput.file_path) parts.push(String(toolInput.file_path));
+  if (toolInput.description) parts.push(String(toolInput.description).slice(0, 200));
+  if (toolInput.prompt) parts.push(String(toolInput.prompt).slice(0, 400));
+  if (toolInput.pattern) parts.push(String(toolInput.pattern).slice(0, 200));
+  return parts.filter(Boolean).join(' ');
+}
+
+function extractAvoidanceAdvice(content) {
+  if (!content) return null;
+  // Extract the "How to avoid:" section if present
+  const match = content.match(/How to avoid:\s*([^\n]+)/i);
+  if (match) return match[1].trim().slice(0, 220);
+  return null;
+}
+
+function mergeContextStrings(...ctxs) {
+  return ctxs.filter((c) => typeof c === 'string' && c.length > 0).join('\n\n') || null;
+}
+
 async function runAsync(input) {
   const secretGuard = evaluateSecretGuard(input);
   if (secretGuard) {
@@ -1545,7 +1685,10 @@ async function runAsync(input) {
   }
 
   const behavioralContext = buildBehavioralContext();
-  return formatOutput(result, behavioralContext);
+  const lessonContext = buildRelevantLessonContext(toolName, toolInput);
+  const recentContext = buildRecentCorrectiveActionsContext();
+  const combinedContext = mergeContextStrings(lessonContext, recentContext, behavioralContext);
+  return formatOutput(result, combinedContext);
 }
 
 function run(input) {
@@ -1575,7 +1718,10 @@ function run(input) {
   }
 
   const behavioralContext = buildBehavioralContext();
-  return formatOutput(result, behavioralContext);
+  const lessonContext = buildRelevantLessonContext(toolName, toolInput);
+  const recentContext = buildRecentCorrectiveActionsContext();
+  const combinedContext = mergeContextStrings(lessonContext, recentContext, behavioralContext);
+  return formatOutput(result, combinedContext);
 }
 
 // ---------------------------------------------------------------------------
@@ -1796,6 +1942,11 @@ module.exports = {
   PROTECTED_APPROVAL_TTL_MS,
   DEFAULT_PROTECTED_FILE_GLOBS,
   buildBehavioralContext,
+  buildRecentCorrectiveActionsContext,
+  buildRelevantLessonContext,
+  extractActionContext,
+  extractAvoidanceAdvice,
+  mergeContextStrings,
   isHighRiskAction,
 };
 

package/scripts/hook-runtime.js

@@ -44,10 +44,25 @@ function resolveCliBaseCommand() {
   return publishedCliShellCommand(version);
 }
 
+function resolveCodexCliBaseCommand() {
+  const version = packageVersion();
+  if (publishedHookCommandsAvailable(version)) {
+    return publishedCliShellCommand('latest', [], { preferInstalled: false });
+  }
+  if (isSourceCheckout(PKG_ROOT)) {
+    return `node ${shellQuote(path.join(PKG_ROOT, 'bin', 'cli.js'))}`;
+  }
+  return publishedCliShellCommand('latest', [], { preferInstalled: false });
+}
+
 function buildPortableHookCommand(subcommand) {
   return `${resolveCliBaseCommand()} ${subcommand}`;
 }
 
+function buildCodexPortableHookCommand(subcommand) {
+  return `${resolveCodexCliBaseCommand()} ${subcommand}`;
+}
+
 function preToolHookCommand() {
   return buildPortableHookCommand('gate-check');
 }
@@ -68,12 +83,39 @@ function statuslineCommand() {
   return buildPortableHookCommand('statusline-render');
 }
 
+function codexPreToolHookCommand() {
+  return buildCodexPortableHookCommand('gate-check');
+}
+
+function codexUserPromptHookCommand() {
+  return buildCodexPortableHookCommand('hook-auto-capture');
+}
+
+function codexSessionStartHookCommand() {
+  return buildCodexPortableHookCommand('session-start');
+}
+
+function codexCacheUpdateHookCommand() {
+  return buildCodexPortableHookCommand('cache-update');
+}
+
+function codexStatuslineCommand() {
+  return buildCodexPortableHookCommand('statusline-render');
+}
+
 module.exports = {
   buildPortableHookCommand,
+  buildCodexPortableHookCommand,
   cacheUpdateHookCommand,
+  codexCacheUpdateHookCommand,
+  codexPreToolHookCommand,
+  codexSessionStartHookCommand,
+  codexStatuslineCommand,
+  codexUserPromptHookCommand,
   packageVersion,
   publishedHookCommandsAvailable,
   preToolHookCommand,
+  resolveCodexCliBaseCommand,
   resolveCliBaseCommand,
   sessionStartHookCommand,
   statuslineCommand,

package/scripts/llm-client.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 'use strict';
 
+const { runStep } = require('./durability/step');
+
 const MODELS = {
   FAST: 'claude-haiku-4-5-20251001',
   SMART: 'claude-sonnet-4-6',
@@ -33,25 +35,38 @@ function stripCodeFences(text) {
   return fenced ? fenced[1].trim() : text.trim();
 }
 
+// Anthropic SDK throws errors with a `.status` field for HTTP failures.
+// Our defaultClassify already reads `.status`, so 429/5xx retry and 4xx
+// (bad request / unauthorized / not-found) bail immediately — which is
+// what we want: there is no point retrying a malformed prompt or a
+// revoked API key.
 async function callClaude({ systemPrompt, userPrompt, model, maxTokens } = {}) {
   const client = getClient();
   if (!client) return null;
 
   try {
-    const response = await client.messages.create({
-      model: model || DEFAULT_MODEL,
-      max_tokens: maxTokens || DEFAULT_MAX_TOKENS,
-      system: systemPrompt || undefined,
-      messages: [{ role: 'user', content: userPrompt }],
-    });
+    const text = await runStep('llm.callClaude', {
+      retries: 2,
+      logger: (msg) => console.warn(msg),
+    }, async () => {
+      const response = await client.messages.create({
+        model: model || DEFAULT_MODEL,
+        max_tokens: maxTokens || DEFAULT_MAX_TOKENS,
+        system: systemPrompt || undefined,
+        messages: [{ role: 'user', content: userPrompt }],
+      });
 
-    const text = response.content
-      .filter((b) => b.type === 'text')
-      .map((b) => b.text)
-      .join('');
+      return response.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('');
+    });
 
     return stripCodeFences(text);
   } catch {
+    // Preserve the original callClaude contract — callers expect `null` on
+    // failure, not an exception. runStep already logged retry attempts,
+    // so the permanent failure is visible in logs.
     return null;
   }
 }

package/scripts/mailer/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+/**
+ * scripts/mailer/index.js — public entry point for the mailer module.
+ */
+
+const { sendEmail, sendTrialWelcomeEmail, renderTrialWelcomeBodies } = require('./resend-mailer');
+
+module.exports = {
+  sendEmail,
+  sendTrialWelcomeEmail,
+  renderTrialWelcomeBodies,
+};