thumbgate 1.30.0 → 1.34.0

package/scripts/skill-packs.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { registerPreventionRules } = require('./contextfs');
+const SKILL_PACKS_DIR = path.join(__dirname, '..', 'config', 'skill-packs');
+const BUILTIN_PACKS = {
+  'stripe-integration': { name: 'stripe-integration', description: 'Stripe API best practices', triggers: ['stripe', 'payment', 'checkout', 'subscription', 'webhook signature', 'credit card', 'card number'], rules: ['ALWAYS use idempotency keys on PaymentIntent creation to prevent duplicate charges.', 'NEVER log or store raw card numbers — use Stripe tokens or PaymentMethod IDs.', 'ALWAYS verify webhook signatures with stripe.webhooks.constructEvent() before processing.', 'Use Checkout Sessions instead of raw PaymentIntents for new integrations.', 'ALWAYS handle payment_intent.succeeded AND payment_intent.payment_failed webhooks.'], packTemplate: { namespaces: ['memoryError', 'memoryLearning', 'rules'], maxItems: 8, maxChars: 6000, queryPrefix: 'stripe payment checkout webhook idempotency' } },
+  'railway-deploy': { name: 'railway-deploy', description: 'Railway deployment best practices', triggers: ['railway', 'deploy', 'dockerfile', 'health check'], rules: ['ALWAYS verify /health endpoint returns new version after deploy.', 'NEVER say "deployed" without curling the health endpoint and showing version match.', 'ALWAYS check Railway build logs for warnings even when deploy succeeds.', 'Use RAILWAY_VOLUME_MOUNT_PATH for persistent data.', 'ALWAYS wait 2-5 minutes after merge before verifying.'], packTemplate: { namespaces: ['memoryError', 'memoryLearning', 'rules'], maxItems: 8, maxChars: 6000, queryPrefix: 'railway deploy health version dockerfile' } },
+  'database-migration': { name: 'database-migration', description: 'Database migration best practices', triggers: ['migration', 'prisma', 'sqlite', 'schema', 'alter table'], rules: ['ALWAYS back up the database before running destructive migrations.', 'NEVER drop columns in production without verifying no code references them.', 'ALWAYS run migrations against a test database first.', 'Use reversible migrations — every up() should have a corresponding down().', 'ALWAYS check for pending migrations before deploying new code.'], packTemplate: { namespaces: ['memoryError', 'rules'], maxItems: 6, maxChars: 5000, queryPrefix: 'migration database schema prisma sqlite' } },
+  'database-agent-safety': {
+    name: 'database-agent-safety',
+    description: 'Pre-action checks for AI agents before they touch production databases.',
+    triggers: ['database', 'postgres', 'mysql', 'sql', 'migration', 'prisma', 'rails db:migrate', 'drop table', 'truncate', 'production database'],
+    rules: [
+      'NEVER allow an autonomous agent to run DROP, TRUNCATE, DROP SCHEMA, or DROP DATABASE without explicit human approval and rollback evidence.',
+      'ALWAYS require a backup, snapshot, or reversible rollback plan before production schema migrations.',
+      'NEVER run UPDATE or DELETE without a restrictive WHERE clause; WHERE 1=1 and WHERE TRUE are not restrictive.',
+      'ALWAYS require dry-run or EXPLAIN evidence before production writes, migrations, or high-cardinality queries.',
+      'NEVER let agents create roles, alter roles, or grant broad privileges in a live database.',
+      'ALWAYS treat database work as a pre-action approval boundary, not a post-hoc review item.',
+    ],
+    packTemplate: {
+      namespaces: ['memoryError', 'memoryLearning', 'rules'],
+      maxItems: 8,
+      maxChars: 6000,
+      queryPrefix: 'database postgres mysql sql migration production drop truncate rollback backup explain',
+    },
+  },
+};
+const registry = new Map(); for (const [id, p] of Object.entries(BUILTIN_PACKS)) registry.set(id, p);
+function ensurePacksDir() { if (!fs.existsSync(SKILL_PACKS_DIR)) fs.mkdirSync(SKILL_PACKS_DIR, { recursive: true }); }
+function registerSkillPack(pack) { if (!pack.name) throw new Error('Skill pack requires a name'); if (!Array.isArray(pack.rules) || pack.rules.length === 0) throw new Error('Skill pack requires at least one rule'); const n = { name: pack.name, description: pack.description || '', triggers: Array.isArray(pack.triggers) ? pack.triggers : [], rules: pack.rules, packTemplate: pack.packTemplate || null, registeredAt: new Date().toISOString() }; registry.set(n.name, n); ensurePacksDir(); fs.writeFileSync(path.join(SKILL_PACKS_DIR, `${n.name}.json`), JSON.stringify(n, null, 2) + '\n'); return n; }
+function loadSkillPacksFromDisk() { ensurePacksDir(); for (const f of fs.readdirSync(SKILL_PACKS_DIR).filter((x) => x.endsWith('.json'))) { try { const p = JSON.parse(fs.readFileSync(path.join(SKILL_PACKS_DIR, f), 'utf-8')); if (p.name) registry.set(p.name, p); } catch { /* skip */ } } }
+function listSkillPacks() { loadSkillPacksFromDisk(); return Array.from(registry.values()).map((p) => ({ name: p.name, description: p.description, triggers: p.triggers, ruleCount: p.rules.length, hasPackTemplate: !!p.packTemplate })); }
+function getSkillPack(name) { loadSkillPacksFromDisk(); return registry.get(name) || null; }
+function matchTokens(value) {
+  return String(value || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length >= 3);
+}
+function matchSkillPacks(query) {
+  const tokens = matchTokens(query);
+  if (tokens.length === 0) return [];
+  loadSkillPacksFromDisk();
+  const scored = [];
+  for (const pack of registry.values()) {
+    let score = 0;
+    for (const trigger of pack.triggers) {
+      for (const triggerToken of matchTokens(trigger)) {
+        const matched = tokens.some((queryToken) => (
+          queryToken === triggerToken
+          || (
+            Math.min(queryToken.length, triggerToken.length) >= 4
+            && (queryToken.includes(triggerToken) || triggerToken.includes(queryToken))
+          )
+        ));
+        if (matched) score += 1;
+      }
+    }
+    if (score > 0) scored.push({ pack, score });
+  }
+  return scored.sort((a, b) => b.score - a.score).map((entry) => entry.pack);
+}
+function installSkillPackRules(name) { const pack = getSkillPack(name); if (!pack) throw new Error(`Skill pack not found: "${name}"`); return registerPreventionRules([`# Skill Pack: ${pack.name}`, '', pack.description || '', '', ...pack.rules.map((r, i) => `${i + 1}. ${r}`)].join('\n'), { skillPack: pack.name }); }
+// ---------------------------------------------------------------------------
+// L3 Resource Loading (ADK progressive disclosure)
+// ---------------------------------------------------------------------------
+
+const RESOURCES_DIR_NAME = 'references';
+
+/**
+ * Load an L3 resource file for a skill pack.
+ * Resources live in config/skill-packs/{pack-name}/references/{filename}.
+ */
+function loadSkillResource(packName, resourceName) {
+  const resDir = path.join(SKILL_PACKS_DIR, packName, RESOURCES_DIR_NAME);
+  const resPath = path.join(resDir, resourceName);
+  if (!fs.existsSync(resPath)) return null;
+  return { name: resourceName, path: resPath, content: fs.readFileSync(resPath, 'utf-8'), sizeBytes: fs.statSync(resPath).size };
+}
+
+/**
+ * List available L3 resources for a skill pack.
+ */
+function listSkillResources(packName) {
+  const resDir = path.join(SKILL_PACKS_DIR, packName, RESOURCES_DIR_NAME);
+  if (!fs.existsSync(resDir)) return [];
+  return fs.readdirSync(resDir).filter((f) => !f.startsWith('.')).map((f) => {
+    const fp = path.join(resDir, f);
+    return { name: f, sizeBytes: fs.statSync(fp).size };
+  });
+}
+
+/**
+ * Add an L3 resource file to a skill pack.
+ */
+function addSkillResource(packName, resourceName, content) {
+  const resDir = path.join(SKILL_PACKS_DIR, packName, RESOURCES_DIR_NAME);
+  ensurePacksDir();
+  if (!fs.existsSync(resDir)) fs.mkdirSync(resDir, { recursive: true });
+  const resPath = path.join(resDir, resourceName);
+  fs.writeFileSync(resPath, content);
+  return { name: resourceName, path: resPath, sizeBytes: Buffer.byteLength(content) };
+}
+
+// ---------------------------------------------------------------------------
+// Skill Factory — agent-driven skill generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-generate a skill pack from recurring failure patterns.
+ * Uses distilled lessons to propose rules for a new domain.
+ *
+ * @param {Object} opts
+ * @param {string} opts.domain - Domain name (e.g., 'graphql-api')
+ * @param {Array} opts.lessons - Array of lesson strings from history distiller
+ * @param {string} [opts.description] - Pack description
+ * @param {Array} [opts.triggers] - Trigger keywords
+ * @returns {Object} The created skill pack
+ */
+function generateSkillPack({ domain, lessons, description, triggers } = {}) {
+  if (!domain) throw new Error('Skill factory requires a domain name');
+  if (!Array.isArray(lessons) || lessons.length === 0) throw new Error('Skill factory requires at least one lesson');
+
+  // Convert lessons into NEVER/ALWAYS rules
+  const rules = lessons.map((lesson) => {
+    const l = String(lesson).trim();
+    if (/^(NEVER|ALWAYS|DO NOT|MUST)/i.test(l)) return l;
+    if (/fail|error|broke|wrong|bug|crash/i.test(l)) return `NEVER ${l.replace(/^(avoid|don'?t|stop)\s*/i, '').trim()}`;
+    return `ALWAYS ${l.replace(/^(repeat|keep|continue)\s*/i, '').trim()}`;
+  });
+
+  // Infer triggers from domain + lesson content
+  const inferredTriggers = triggers || [domain, ...domain.split('-').filter((t) => t.length > 2)];
+
+  return registerSkillPack({
+    name: domain,
+    description: description || `Auto-generated skill pack for ${domain} from ${lessons.length} lessons`,
+    triggers: inferredTriggers,
+    rules,
+    packTemplate: { namespaces: ['memoryError', 'memoryLearning', 'rules'], maxItems: 8, maxChars: 6000, queryPrefix: inferredTriggers.join(' ') },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Token-Efficient Progressive Disclosure Metrics
+// ---------------------------------------------------------------------------
+
+/**
+ * Measure token cost of each disclosure level for a skill pack.
+ * Helps agents decide which packs to load.
+ */
+function measureSkillTokens(packName) {
+  const pack = getSkillPack(packName);
+  if (!pack) return null;
+
+  // L1: metadata only (~name + description + triggers)
+  const l1Text = `${pack.name}: ${pack.description} [${(pack.triggers || []).join(', ')}]`;
+  const l1Chars = l1Text.length;
+
+  // L2: full rules
+  const l2Text = pack.rules.join('\n');
+  const l2Chars = l2Text.length;
+
+  // L3: resources
+  const resources = listSkillResources(packName);
+  const l3Chars = resources.reduce((sum, r) => sum + r.sizeBytes, 0);
+
+  const totalChars = l1Chars + l2Chars + l3Chars;
+
+  return {
+    packName,
+    l1: { chars: l1Chars, estimatedTokens: Math.ceil(l1Chars / 4) },
+    l2: { chars: l2Chars, estimatedTokens: Math.ceil(l2Chars / 4), ruleCount: pack.rules.length },
+    l3: { chars: l3Chars, estimatedTokens: Math.ceil(l3Chars / 4), resourceCount: resources.length },
+    total: { chars: totalChars, estimatedTokens: Math.ceil(totalChars / 4) },
+    disclosureSavings: totalChars > 0 ? Math.round((1 - l1Chars / totalChars) * 100) : 0,
+  };
+}
+
+module.exports = { BUILTIN_PACKS, registerSkillPack, listSkillPacks, getSkillPack, matchSkillPacks, installSkillPackRules, SKILL_PACKS_DIR, loadSkillResource, listSkillResources, addSkillResource, generateSkillPack, measureSkillTokens };

package/scripts/slow-loop.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createSchedule } = require('./schedule-manager');
+const { resolveFeedbackDir } = require('./feedback-paths');
+
+const IDLE_THRESHOLD_MINUTES = 30;
+const SLOW_LOOP_STATE_FILE = 'slow-loop-state.json';
+
+function getStatePath() {
+  return path.join(resolveFeedbackDir(), SLOW_LOOP_STATE_FILE);
+}
+
+function loadState() {
+  const p = getStatePath();
+  if (!fs.existsSync(p)) return { lastExportAt: null, exportCount: 0, lastIdleCheckAt: null, totalPairsExported: 0 };
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return { lastExportAt: null, exportCount: 0, lastIdleCheckAt: null, totalPairsExported: 0 }; }
+}
+
+function saveState(state) {
+  const p = getStatePath();
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(state, null, 2) + '\n');
+}
+
+function isIdle({ thresholdMinutes = IDLE_THRESHOLD_MINUTES } = {}) {
+  const feedbackDir = resolveFeedbackDir();
+  const logPath = path.join(feedbackDir, 'feedback-log.jsonl');
+  if (!fs.existsSync(logPath)) return true;
+  try {
+    const stats = fs.statSync(logPath);
+    const minutesSinceModified = (Date.now() - stats.mtimeMs) / (1000 * 60);
+    return minutesSinceModified >= thresholdMinutes;
+  } catch { return true; }
+}
+
+function runSlowLoop({ thresholdMinutes = IDLE_THRESHOLD_MINUTES, force = false } = {}) {
+  const state = loadState();
+  const idle = force || isIdle({ thresholdMinutes });
+  if (!idle) { state.lastIdleCheckAt = new Date().toISOString(); saveState(state); return { action: 'skipped', reason: 'system not idle', idle: false, state }; }
+
+  const feedbackDir = resolveFeedbackDir();
+  const logPath = path.join(feedbackDir, 'feedback-log.jsonl');
+  let newEntries = 0;
+  if (fs.existsSync(logPath)) {
+    const totalEntries = fs.readFileSync(logPath, 'utf-8').trim().split('\n').filter(Boolean).length;
+    newEntries = totalEntries - (state.lastFeedbackCount || 0);
+    state.lastFeedbackCount = totalEntries;
+  }
+  if (newEntries <= 0 && !force) { state.lastIdleCheckAt = new Date().toISOString(); saveState(state); return { action: 'skipped', reason: 'no new feedback since last export', idle: true, newEntries: 0, state }; }
+
+  let dpoResult = null;
+  try { const { exportDpoPairs } = require('./feedback-loop'); dpoResult = exportDpoPairs(); } catch (err) { dpoResult = { error: err.message, pairsExported: 0 }; }
+
+  const pairsExported = dpoResult && dpoResult.pairs ? dpoResult.pairs.length : (dpoResult && dpoResult.pairsExported) || 0;
+  state.lastExportAt = new Date().toISOString();
+  state.exportCount = (state.exportCount || 0) + 1;
+  state.totalPairsExported = (state.totalPairsExported || 0) + pairsExported;
+  state.lastIdleCheckAt = new Date().toISOString();
+  saveState(state);
+  return { action: 'exported', idle: true, newEntries, pairsExported, totalExports: state.exportCount, totalPairsExported: state.totalPairsExported, exportedAt: state.lastExportAt, state };
+}
+
+function createSlowLoopSchedule({ schedule = 'hourly', thresholdMinutes = IDLE_THRESHOLD_MINUTES } = {}) {
+  const command = [`const sl = require(${JSON.stringify(__filename)});`, `const result = sl.runSlowLoop(${JSON.stringify({ thresholdMinutes })});`, 'process.stdout.write(JSON.stringify(result, null, 2) + "\\n");'].join(' ');
+  return createSchedule({ id: 'thumbgate-slow-loop', name: 'ThumbGate Slow Loop (DPO Export)', description: `Idle-time DPO export, runs ${schedule}`, schedule, command });
+}
+
+module.exports = { isIdle, runSlowLoop, createSlowLoopSchedule, loadState, getStatePath };

package/scripts/statusline-links.js

@@ -109,7 +109,7 @@ function launchLocalServer(options = {}) {
 
   const child = spawn(
     process.execPath,
-    [path.join(PKG_ROOT, 'bin', 'cli.js'), 'start-api'],
+    [path.join(PKG_ROOT, 'src', 'api', 'server.js')],
     {
       cwd: projectDir,
       env: childEnv,

package/scripts/statusline.sh

@@ -21,7 +21,14 @@ PROJECT_CWD="${PROJECT_CWD:-}"
 if [ -n "$PROJECT_CWD" ] && [ -d "$PROJECT_CWD" ]; then
   export THUMBGATE_PROJECT_DIR="$PROJECT_CWD"
   if [ -z "${THUMBGATE_FEEDBACK_DIR:-}" ]; then
-    export THUMBGATE_FEEDBACK_DIR="${PROJECT_CWD}/.claude/memory/feedback"
+    THUMBGATE_FEEDBACK_DIR="$(node -e '
+      const { resolveFeedbackDir } = require(process.argv[1]);
+      process.stdout.write(resolveFeedbackDir({
+        projectDir: process.env.THUMBGATE_PROJECT_DIR,
+        env: process.env,
+      }));
+    ' "${SCRIPT_DIR}/feedback-paths.js" 2>/dev/null)"
+    export THUMBGATE_FEEDBACK_DIR="${THUMBGATE_FEEDBACK_DIR:-${PROJECT_CWD}/.thumbgate}"
   fi
 fi
 

package/scripts/telemetry-analytics.js

@@ -419,7 +419,15 @@ function classifyTelemetryAudience(entry = {}, raw = {}) {
 }
 
 function sanitizeTelemetryPayload(payload = {}, headers = {}) {
-  const raw = payload && typeof payload === 'object' ? payload : {};
+  const envelope = payload && typeof payload === 'object' ? payload : {};
+  const nestedProps = envelope.props
+    && typeof envelope.props === 'object'
+    && !Array.isArray(envelope.props)
+    ? envelope.props
+    : {};
+  // Browser analytics libraries conventionally wrap event properties in
+  // `props`. Flatten that envelope while letting explicit top-level fields win.
+  const raw = { ...nestedProps, ...envelope };
   const clientType = inferClientType(raw);
   const eventType = inferEventType(raw, clientType);
   const source = pickFirstText(raw.source, raw.utmSource, clientType === 'cli' ? 'cli' : 'direct');
@@ -471,6 +479,10 @@ function sanitizeTelemetryPayload(payload = {}, headers = {}) {
     ctaId: pickFirstText(raw.ctaId),
     ctaPlacement: pickFirstText(raw.ctaPlacement),
     planId: pickFirstText(raw.planId),
+    segment: pickFirstText(raw.segment, raw.buyerSegment, raw.campaignVariant, raw.variant),
+    experimentId: pickFirstText(raw.experimentId, raw.experiment, raw.utmCampaign),
+    value: normalizeInteger(raw.value),
+    currency: pickFirstText(raw.currency),
     linkSlug: pickFirstText(raw.linkSlug, raw.destinationSlug),
     destinationPath: pickFirstText(raw.destinationPath),
     pipelineStatus: pickFirstText(raw.pipelineStatus, raw.workflowSprintStatus, raw.status),

package/scripts/thumbgate-search.js

@@ -8,6 +8,7 @@ const {
 } = require('./filesystem-search');
 const {
   searchImportedDocuments,
+  searchImportedDocumentsAsync,
 } = require('./document-intake');
 
 const VALID_SOURCES = ['all', 'feedback', 'context', 'rules', 'documents'];
@@ -139,9 +140,25 @@ function mapDocumentResult(record) {
     proposalCount: safeArray(record.proposals).length,
     matchedTemplateIds: safeArray(record.matchedTemplateIds),
     sourceFormat: record.sourceFormat || null,
+    matchedChunks: safeArray(record._matchedChunks),
+    retrieval: record._retrieval || null,
   };
 }
 
+async function getDocumentResultsAsync(query, limit, feedbackDir, options = {}) {
+  const documents = await searchImportedDocumentsAsync({
+    query,
+    limit,
+    feedbackDir,
+    metadataFilters: options.metadataFilters,
+    queryRewrite: options.queryRewrite,
+    embedder: options.embedder,
+    embedderId: options.embedderId,
+    accessContext: options.accessContext,
+  });
+  return documents.map(mapDocumentResult);
+}
+
 function sortResults(results) {
   return [...results].sort((left, right) => {
     if ((right.score || 0) !== (left.score || 0)) {
@@ -154,7 +171,7 @@ function sortResults(results) {
 function extractFeedbackId(str) {
   if (!str) return null;
   const match = str.match(/fb[_-]\d+[_-][a-z0-9]+/i);
-  return match ? match[0].replace(/-/g, '_').toLowerCase() : null;
+  return match ? match[0].replaceAll('-', '_').toLowerCase() : null;
 }
 
 function deduplicateResults(results) {
@@ -227,11 +244,23 @@ function getRuleResults(query, limit, feedbackDir) {
   return searchPreventionRulesSync(query, limit, { feedbackDir }).map(mapRuleResult);
 }
 
-function getDocumentResults(query, limit, feedbackDir) {
-  return searchImportedDocuments({ query, limit, feedbackDir }).map(mapDocumentResult);
+function getDocumentResults(query, limit, feedbackDir, accessContext) {
+  return searchImportedDocuments({
+    query,
+    limit,
+    feedbackDir,
+    accessContext,
+  }).map(mapDocumentResult);
 }
 
-function searchThumbgate({ query, source = 'all', limit = 10, signal = null, feedbackDir = null } = {}) {
+function searchThumbgate({
+  query,
+  source = 'all',
+  limit = 10,
+  signal = null,
+  feedbackDir = null,
+  accessContext = null,
+} = {}) {
   const trimmedQuery = String(query || '').trim();
   if (!trimmedQuery) {
     throw new Error('query is required');
@@ -254,14 +283,14 @@ function searchThumbgate({ query, source = 'all', limit = 10, signal = null, fee
     const raw = getRuleResults(trimmedQuery, fetchLimit, feedbackDir);
     results = deduplicateResults(raw).slice(0, normalizedLimit);
   } else if (normalizedSource === 'documents') {
-    const raw = getDocumentResults(trimmedQuery, fetchLimit, feedbackDir);
+    const raw = getDocumentResults(trimmedQuery, fetchLimit, feedbackDir, accessContext);
     results = deduplicateResults(raw).slice(0, normalizedLimit);
   } else {
     const combined = [
       ...getFeedbackResults(trimmedQuery, fetchLimit, normalizedSignal, feedbackDir),
       ...getContextResults(trimmedQuery, fetchLimit, feedbackDir),
       ...getRuleResults(trimmedQuery, fetchLimit, feedbackDir),
-      ...getDocumentResults(trimmedQuery, fetchLimit, feedbackDir),
+      ...getDocumentResults(trimmedQuery, fetchLimit, feedbackDir, accessContext),
     ];
     results = deduplicateResults(sortResults(combined)).slice(0, normalizedLimit);
   }
@@ -278,9 +307,72 @@ function searchThumbgate({ query, source = 'all', limit = 10, signal = null, fee
   };
 }
 
+async function searchThumbgateAsync({
+  query,
+  source = 'all',
+  limit = 10,
+  signal = null,
+  feedbackDir = null,
+  metadataFilters = null,
+  queryRewrite = true,
+  embedder,
+  embedderId,
+  accessContext = null,
+} = {}) {
+  const trimmedQuery = String(query || '').trim();
+  if (!trimmedQuery) throw new Error('query is required');
+  const normalizedSource = normalizeSource(source);
+  const normalizedSignal = normalizeSignal(signal);
+  const normalizedLimit = normalizeLimit(limit);
+  const fetchLimit = Math.max(100, normalizedLimit * 5);
+  const documentOptions = {
+    metadataFilters,
+    queryRewrite,
+    embedder,
+    embedderId,
+    accessContext,
+  };
+
+  let results;
+  if (normalizedSource === 'documents') {
+    results = deduplicateResults(
+      await getDocumentResultsAsync(trimmedQuery, fetchLimit, feedbackDir, documentOptions),
+    ).slice(0, normalizedLimit);
+  } else if (normalizedSource === 'all') {
+    const combined = [
+      ...getFeedbackResults(trimmedQuery, fetchLimit, normalizedSignal, feedbackDir),
+      ...getContextResults(trimmedQuery, fetchLimit, feedbackDir),
+      ...getRuleResults(trimmedQuery, fetchLimit, feedbackDir),
+      ...await getDocumentResultsAsync(trimmedQuery, fetchLimit, feedbackDir, documentOptions),
+    ];
+    results = deduplicateResults(sortResults(combined)).slice(0, normalizedLimit);
+  } else {
+    return searchThumbgate({
+      query: trimmedQuery,
+      source: normalizedSource,
+      limit: normalizedLimit,
+      signal: normalizedSignal,
+      feedbackDir,
+      accessContext,
+    });
+  }
+
+  return {
+    query: trimmedQuery,
+    source: normalizedSource,
+    signal: normalizedSignal,
+    limit: normalizedLimit,
+    engine: 'hybrid-parent-child',
+    returned: results.length,
+    total: results.length,
+    results,
+  };
+}
+
 module.exports = {
   VALID_SOURCES,
   normalizeSearchSource: normalizeSource,
   normalizeSearchSignal: normalizeSignal,
   searchThumbgate,
+  searchThumbgateAsync,
 };

package/scripts/tier-budget-guard.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * Hard cost + latency budgets for model tier routing.
+ *
+ * Complements FrontierBudget (session token cap) with:
+ *   - per-request max cost (cents)
+ *   - per-request max latency budget (ms) for planning/degrade
+ *   - max frontier invocations per day (process-local counter)
+ *
+ * Env (optional):
+ *   THUMBGATE_MAX_COST_CENTS_PER_REQUEST
+ *   THUMBGATE_MAX_LATENCY_MS
+ *   THUMBGATE_MAX_FRONTIER_PER_DAY
+ */
+
+const { TIERS, classifyTask, FrontierBudget } = require('./model-tier-router');
+
+const DEFAULTS = Object.freeze({
+  maxCostCentsPerRequest: 25, // $0.25
+  maxLatencyMs: 30_000,
+  maxFrontierPerDay: 50,
+});
+
+/** @type {Map<string, number>} dayKey → frontier invocation count */
+const frontierDayCounts = new Map();
+
+function dayKey(now = Date.now()) {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function readEnvNumber(name, fallback) {
+  const raw = process.env[name];
+  if (raw == null || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function getBudgetConfig(overrides = {}) {
+  return {
+    maxCostCentsPerRequest: overrides.maxCostCentsPerRequest
+      ?? readEnvNumber('THUMBGATE_MAX_COST_CENTS_PER_REQUEST', DEFAULTS.maxCostCentsPerRequest),
+    maxLatencyMs: overrides.maxLatencyMs
+      ?? readEnvNumber('THUMBGATE_MAX_LATENCY_MS', DEFAULTS.maxLatencyMs),
+    maxFrontierPerDay: overrides.maxFrontierPerDay
+      ?? readEnvNumber('THUMBGATE_MAX_FRONTIER_PER_DAY', DEFAULTS.maxFrontierPerDay),
+  };
+}
+
+/**
+ * Estimate request cost cents from tier + token budget.
+ * @param {string} tier
+ * @param {number} estimatedTokens
+ */
+function estimateTierCostCents(tier, estimatedTokens = 4000) {
+  const t = TIERS[tier] || TIERS.mini;
+  // Base: ~$3/M input + $15/M out blended as ~$6/M total for coding
+  const basePerM = 6;
+  const usd = (estimatedTokens / 1e6) * basePerM * (t.costMultiplier ?? 1);
+  return Number((usd * 100).toFixed(4));
+}
+
+/**
+ * Enforce hard budgets on a classification result.
+ *
+ * @param {object} task — same shape as classifyTask
+ * @param {object} [options]
+ * @param {object} [options.classification] — precomputed classifyTask result
+ * @param {FrontierBudget} [options.frontierBudget]
+ * @param {number} [options.estimatedTokens]
+ * @param {number} [options.nowMs]
+ * @returns {{
+ *   allowed: boolean,
+ *   tier: string,
+ *   action: 'allow'|'degrade'|'deny',
+ *   reasons: string[],
+ *   classification: object,
+ *   estimatedCostCents: number,
+ *   budget: object,
+ * }}
+ */
+function enforceTierBudgets(task = {}, options = {}) {
+  const config = getBudgetConfig(options);
+  const classification = options.classification || classifyTask(task);
+  let tier = classification.tier;
+  const reasons = [];
+  const estimatedTokens = Number(options.estimatedTokens) || 4000;
+  let estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+  let action = 'allow';
+
+  // Daily frontier cap (process-local)
+  if (tier === 'frontier') {
+    const key = dayKey(options.nowMs);
+    const used = frontierDayCounts.get(key) || 0;
+    if (used >= config.maxFrontierPerDay) {
+      reasons.push(`frontier_daily_cap:${used}/${config.maxFrontierPerDay}`);
+      tier = 'mini';
+      action = 'degrade';
+      estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+    }
+  }
+
+  // Per-request cost cap → degrade tier then deny if still over
+  if (estimatedCostCents > config.maxCostCentsPerRequest) {
+    if (tier === 'frontier') {
+      reasons.push(`cost_over_cap_degrade:${estimatedCostCents}>${config.maxCostCentsPerRequest}`);
+      tier = 'mini';
+      action = 'degrade';
+      estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+    }
+  }
+  if (estimatedCostCents > config.maxCostCentsPerRequest && tier !== 'nano' && tier !== 'localFrontier') {
+    reasons.push(`cost_over_cap_degrade_nano:${estimatedCostCents}>${config.maxCostCentsPerRequest}`);
+    tier = 'nano';
+    action = 'degrade';
+    estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+  }
+  if (estimatedCostCents > config.maxCostCentsPerRequest && (TIERS[tier]?.costMultiplier || 0) > 0) {
+    reasons.push(`cost_deny:${estimatedCostCents}>${config.maxCostCentsPerRequest}`);
+    action = 'deny';
+  }
+
+  // Session frontier token budget
+  const frontierBudget = options.frontierBudget || null;
+  if (frontierBudget && tier === 'frontier' && typeof frontierBudget.canSpend === 'function') {
+    const check = frontierBudget.canSpend(estimatedTokens, task.reason || classification.reason || 'routed_frontier');
+    if (!check.allowed) {
+      reasons.push(`frontier_session_budget:${check.reason}`);
+      tier = 'mini';
+      action = action === 'deny' ? 'deny' : 'degrade';
+      estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+    }
+  }
+
+  // Latency budget is advisory for planning (caller may still enforce timeouts)
+  if (Number(task.expectedLatencyMs) > config.maxLatencyMs) {
+    reasons.push(`latency_budget_exceeded_plan:${task.expectedLatencyMs}>${config.maxLatencyMs}`);
+    if (tier === 'frontier') {
+      tier = 'mini';
+      action = action === 'deny' ? 'deny' : 'degrade';
+    }
+  }
+
+  const allowed = action !== 'deny';
+  return {
+    allowed,
+    tier,
+    action,
+    reasons,
+    classification,
+    estimatedCostCents,
+    budget: {
+      ...config,
+      estimatedTokens,
+    },
+  };
+}
+
+/**
+ * Record a frontier invocation against the daily counter (call only when actually used).
+ */
+function recordFrontierInvocation(nowMs = Date.now()) {
+  const key = dayKey(nowMs);
+  frontierDayCounts.set(key, (frontierDayCounts.get(key) || 0) + 1);
+  return frontierDayCounts.get(key);
+}
+
+/** Test helper */
+function _resetFrontierDayCounts() {
+  frontierDayCounts.clear();
+}
+
+function getFrontierDayUsage(nowMs = Date.now()) {
+  const key = dayKey(nowMs);
+  return { day: key, count: frontierDayCounts.get(key) || 0 };
+}
+
+module.exports = {
+  DEFAULTS,
+  getBudgetConfig,
+  estimateTierCostCents,
+  enforceTierBudgets,
+  recordFrontierInvocation,
+  getFrontierDayUsage,
+  _resetFrontierDayCounts,
+};