atris 3.38.0 → 3.41.0

package/lib/router-brain.js

@@ -6,6 +6,8 @@ const path = require('node:path');
 const DEFAULT_MIN_RECEIPTS = 3;
 const DEFAULT_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000;
 const DURATION_SCALE_MS = 60 * 1000;
+const STRETCH_ZONE_MIN = 0.6;
+const STRETCH_ZONE_MAX = 0.85;
 
 function objectValue(value) {
   return value && typeof value === 'object' ? value : null;
@@ -313,15 +315,56 @@ function rankEnginesDetailed(candidates, options = {}) {
       || fallbackOrder(left.candidate, left.index) - fallbackOrder(right.candidate, right.index)
       || candidateId(left.candidate).localeCompare(candidateId(right.candidate)))
     .map((entry) => entry.candidate);
+
+  const stretchPick = stretchZonePick(ranked.map((candidate) => ({
+    candidate,
+    predicted: statsByEngine.get(candidateId(candidate))?.verified_pass_rate ?? null,
+  })), options);
+  const finalRanked = stretchPick
+    ? [stretchPick, ...ranked.filter((candidate) => candidate !== stretchPick)]
+    : ranked;
   return {
-    candidates: ranked,
+    candidates: finalRanked,
     stats,
     task_type: taskType,
     used_track_record: true,
     thin_engines: [],
+    stretch_zone_pick: stretchPick ? candidateId(stretchPick) : null,
   };
 }
 
+function engineCost(candidate) {
+  const value = Number(candidate && typeof candidate === 'object' ? candidate.cost : NaN);
+  return Number.isFinite(value) && value >= 0 ? value : Number.POSITIVE_INFINITY;
+}
+
+// stretch zone rule for low-stakes lanes: land the cheapest engine whose
+// predicted success rate sits in the learnable band. entries are
+// { candidate, predicted } rows where predicted is a 0..1 rate or null.
+// returns the winning candidate, or null when nobody is in the band; the
+// caller then keeps the normal score order, whose top is the strongest
+// engine, which is the escalation path when every engine sits below the
+// band floor.
+function stretchZonePick(entries, options = {}) {
+  const lowStakes = options.lowStakes === true || normalizedLabel(options.stakes) === 'low';
+  if (!lowStakes) return null;
+  const rows = (Array.isArray(entries) ? entries : [])
+    .map((entry, index) => ({
+      candidate: entry && typeof entry === 'object' && 'candidate' in entry ? entry.candidate : entry,
+      predicted: entry && typeof entry === 'object' ? finiteNonnegative(entry.predicted) : null,
+      index,
+    }))
+    .filter((row) => row.candidate);
+  const inBand = rows
+    .filter((row) => row.predicted !== null && row.predicted <= 1
+      && row.predicted >= STRETCH_ZONE_MIN && row.predicted <= STRETCH_ZONE_MAX)
+    .sort((left, right) => engineCost(left.candidate) - engineCost(right.candidate)
+      || right.predicted - left.predicted
+      || fallbackOrder(left.candidate, left.index) - fallbackOrder(right.candidate, right.index)
+      || candidateId(left.candidate).localeCompare(candidateId(right.candidate)));
+  return inBand.length ? inBand[0].candidate : null;
+}
+
 function rankEngines(candidates, options = {}) {
   return rankEnginesDetailed(candidates, options).candidates;
 }
@@ -335,6 +378,10 @@ function routerPickExplanation(decision) {
     return `router picked ${engine} because ${taskType} track records are thin, so fallback order applies.`;
   }
   const stats = decision.stats.find((row) => row.engine === engine && row.task_type === taskType);
+  if (decision.stretch_zone_pick === engine) {
+    const predicted = stats ? stats.verified_pass_rate.toFixed(2) : 'unknown';
+    return `router picked ${engine} because the lane is low stakes and its predicted pass rate ${predicted} sits in the ${STRETCH_ZONE_MIN.toFixed(2)} to ${STRETCH_ZONE_MAX.toFixed(2)} stretch zone at the lowest cost.`;
+  }
   if (!stats) return `router picked ${engine} because it has the strongest ${taskType} track record.`;
   const passRate = (stats.verified_pass_rate * 100).toFixed(1);
   const duration = stats.median_duration_ms === null ? 'no duration' : `${Math.round(stats.median_duration_ms)} ms median`;
@@ -342,9 +389,12 @@ function routerPickExplanation(decision) {
 }
 
 module.exports = {
+  STRETCH_ZONE_MIN,
+  STRETCH_ZONE_MAX,
   loadRouterHistory,
   computeEngineTaskStats,
   rankEngines,
   rankEnginesDetailed,
   routerPickExplanation,
+  stretchZonePick,
 };

package/lib/runner-command.js

@@ -67,11 +67,6 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
     model: 'grok-4.5',
     commandTemplate: '{bin} --always-approve -p {prompt}',
   }),
-  hermes: Object.freeze({
-    bin: 'hermes',
-    model: '',
-    commandTemplate: '{bin} -p -- {prompt}',
-  }),
   droid: Object.freeze({
     bin: 'droid',
     model: '',
@@ -85,7 +80,6 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
 const RUNNER_PROFILE_ALIASES = Object.freeze({
   'atris2-fast': 'atris-fast',
   'atris-2-fast': 'atris-fast',
-  'hermes-agent': 'hermes',
 });
 
 // Back-compat surface: RUNNER_PROFILES still resolves every accepted name

package/lib/self-drive.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { openHumanAsks } = require('./mission-human-asks');
 
 const HUMAN_BLOCKING_REASONS = new Set(['auth-required', 'model-unavailable', 'rate-limit-exceeded-wall']);
 const OPEN_TASK_STATUSES = new Set(['open', 'claimed', 'review']);
@@ -154,10 +155,10 @@ function projectTasks(taskDb, db, workspaceRoot) {
 function handleMissionBlocker({ mission, stopReason, workspaceRoot, appendEvent }, injected = {}) {
   if (!mission || !mission.id) return { taskId: null, dispatched: false, engine: null, reason: 'missing mission' };
   const blockerClass = reasonClass(stopReason || mission.stop_reason || mission.last_tick_reason);
-  if (HUMAN_BLOCKING_REASONS.has(blockerClass) || (Array.isArray(mission.human_asks) && mission.human_asks.length)) {
+  if (HUMAN_BLOCKING_REASONS.has(blockerClass) || openHumanAsks(mission.human_asks).length) {
     return { taskId: null, dispatched: false, engine: null, reason: 'human-blocking' };
   }
-  if (['ready', 'complete'].includes(String(mission.status || '').toLowerCase())) {
+  if (['ready', 'complete', 'stopped'].includes(String(mission.status || '').toLowerCase())) {
     return { taskId: null, dispatched: false, engine: null, reason: 'stop condition met' };
   }
 
@@ -175,23 +176,53 @@ function handleMissionBlocker({ mission, stopReason, workspaceRoot, appendEvent
     return { taskId: taskRef(task), dispatched: false, engine: null, reason: 'existing blocker task' };
   }
 
+  const evidence = String(mission.receipt_path || mission.last_tick_reason || stopReason || blockerClass).trim();
+  const objective = String(mission.objective || mission.id).trim();
+  const fullStopReason = String(stopReason || blockerClass).trim();
+  const blockerMetadata = {
+    mission_id: mission.id,
+    mission_objective: objective,
+    mission_blocker_class: blockerClass,
+    stop_reason: fullStopReason,
+    evidence,
+  };
+  const latestClosed = matching
+    .filter(row => !OPEN_TASK_STATUSES.has(row.status))
+    .sort((a, b) => Number(b.updated_at || b.created_at || 0) - Number(a.updated_at || a.created_at || 0))[0];
+  if (latestClosed && typeof deps.taskDb.reopenTask === 'function') {
+    const reopened = deps.taskDb.reopenTask(db, {
+      id: latestClosed.id,
+      actor: 'self-drive',
+      reason: `mission blocker fired again: ${blockerClass}`,
+      metadata: blockerMetadata,
+    });
+    if (reopened.reopened) {
+      const refreshed = deps.taskDb.withTaskDisplayRefs(deps.taskDb.listTasks(db, { workspaceRoot: scopedRoot }));
+      task = refreshed.find(row => row.id === latestClosed.id) || reopened.row;
+      if (task && typeof deps.taskDb.noteTask === 'function') {
+        deps.taskDb.noteTask(db, {
+          id: task.id,
+          actor: 'self-drive',
+          content: `Mission blocker reopened.\nMission objective: ${objective}\nStop reason: ${fullStopReason}\nEvidence: ${evidence}`,
+        });
+      }
+      projectTasks(deps.taskDb, db, scopedRoot);
+      appendEvent?.('mission_blocker_task_reopened', {
+        task_id: taskRef(task),
+        stop_reason: fullStopReason,
+        blocker_class: blockerClass,
+      });
+    }
+  }
+
   if (!task) {
-    const evidence = String(mission.receipt_path || mission.last_tick_reason || stopReason || blockerClass).trim();
-    const objective = String(mission.objective || mission.id).trim();
-    const fullStopReason = String(stopReason || blockerClass).trim();
     const title = missionBlockerTitle(objective, fullStopReason);
     const created = deps.taskDb.addTask(db, {
       title,
       tag: 'mission-blocker',
       workspaceRoot: scopedRoot,
-      sourceKey: `mission-blocker:${mission.id}:${blockerClass}:${matching.length}`,
-      metadata: {
-        mission_id: mission.id,
-        mission_objective: objective,
-        mission_blocker_class: blockerClass,
-        stop_reason: fullStopReason,
-        evidence,
-      },
+      sourceKey: `mission-blocker:${mission.id}:${blockerClass}`,
+      metadata: blockerMetadata,
     });
     const refreshed = deps.taskDb.withTaskDisplayRefs(deps.taskDb.listTasks(db, { workspaceRoot: scopedRoot }));
     task = refreshed.find((row) => row.id === created.id) || deps.taskDb.getTask(db, created.id);

package/lib/task-db.js

@@ -28,6 +28,8 @@ const os = require('os');
 const crypto = require('crypto');
 const { DatabaseSync } = require('node:sqlite');
 const reviewIntegrity = require('./review-integrity');
+const { isDecisionTask } = require('./task-decision');
+const { parseVerifyCommand } = require('./auto-accept-certified');
 
 const DEFAULT_DB_PATH = path.join(os.homedir(), '.atris', 'tasks.db');
 const TASK_EPISODES_FILE = path.join('.atris', 'state', 'task_episodes.jsonl');
@@ -38,6 +40,8 @@ const PROJECTION_EVENT_LIMIT = 8;
 const PROJECTION_MESSAGE_LIMIT = 6;
 const PROJECTION_PAYLOAD_TEXT_LIMIT = 1000;
 const AGENT_CERTIFICATION_REVIEW_PASSES = 2;
+const OPEN_TASK_STATUSES = new Set(['open', 'claimed', 'review']);
+const TERMINAL_MISSION_STATUSES = new Set(['complete', 'stopped']);
 const TASK_REF_GENERIC_TOKENS = new Set(['app', 'atris', 'atrisos', 'project', 'repo', 'workspace']);
 const TASK_PLAN_TAGS = new Set([
   'agent',
@@ -380,6 +384,16 @@ function taskDisplayRefMap(rows) {
   return map;
 }
 
+function taskCreationMetadata(metadata) {
+  const next = metadata && typeof metadata === 'object' ? { ...metadata } : {};
+  const verify = typeof next.verify === 'string' ? next.verify.trim() : '';
+  if (!verify || verify.toLowerCase() === 'git diff --check') {
+    next.verification_status = 'degraded';
+    next.verification_degraded_reason = verify ? 'diff_only_verify' : 'missing_verify';
+  }
+  return next;
+}
+
 function addTask(db, { title, tag, workspaceRoot: ws, sourceKey: sk, metadata, status, claimedBy }) {
   if (!title || !String(title).trim()) throw new Error('title required');
   const now = Date.now();
@@ -394,6 +408,7 @@ function addTask(db, { title, tag, workspaceRoot: ws, sourceKey: sk, metadata, s
     ).get(ws, sk);
     if (existing) return { id: existing.id, inserted: false };
   }
+  const taskMetadata = taskCreationMetadata(metadata);
   withBusyRetry(() => db.prepare(`
     INSERT INTO tasks (id, title, status, tag, workspace_root, source_key,
                        claimed_by, claimed_at, created_at, updated_at, metadata)
@@ -409,7 +424,7 @@ function addTask(db, { title, tag, workspaceRoot: ws, sourceKey: sk, metadata, s
     claimedAt,
     now,
     now,
-    metadata ? JSON.stringify(metadata) : null,
+    JSON.stringify(taskMetadata),
   ));
   appendTaskEvent(db, {
     taskId: id,
@@ -421,7 +436,7 @@ function addTask(db, { title, tag, workspaceRoot: ws, sourceKey: sk, metadata, s
       tag: tag || null,
       status: taskStatus,
       source_key: sk || null,
-      metadata: metadata || null,
+      metadata: taskMetadata,
     },
   });
   return { id, inserted: true };
@@ -531,6 +546,72 @@ function releaseTask(db, { id, actor }) {
   return { released: true, row: updated, event };
 }
 
+function reopenTask(db, { id, actor, reason, metadata: metadataPatch } = {}) {
+  if (!id) throw new Error('id required');
+  const row = getTask(db, id);
+  if (!row) return { reopened: false, reason: 'not_found' };
+  if (OPEN_TASK_STATUSES.has(row.status)) return { reopened: false, reason: `already_${row.status}`, row };
+  if (!['done', 'failed', 'archived'].includes(row.status)) {
+    return { reopened: false, reason: `not_reopenable_${row.status}` };
+  }
+
+  const now = Math.max(Date.now(), Number(row.updated_at || 0) + 1);
+  const actorText = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
+  const reasonText = String(reason || 'reopened').trim();
+  const metadata = {
+    ...(row.metadata && typeof row.metadata === 'object' ? row.metadata : {}),
+    ...(metadataPatch && typeof metadataPatch === 'object' ? metadataPatch : {}),
+    reopened_at: new Date(now).toISOString(),
+    reopened_by: actorText,
+    reopened_from: row.status,
+    reopen_reason: reasonText,
+  };
+  for (const key of [
+    'accepted_at',
+    'accepted_by',
+    'agent_certification_policy',
+    'agent_certified',
+    'agent_certified_at',
+    'agent_certified_by',
+    'agent_review_actors',
+    'agent_review_pass_count',
+    'agent_reviewed_at',
+    'agent_reviewed_by',
+    'approval_status',
+    'archived_at',
+    'archived_by',
+    'archived_from',
+    'archived_reason',
+    'independent_review_by',
+    'latest_agent_lesson',
+    'latest_agent_next_task',
+    'latest_agent_proof',
+  ]) delete metadata[key];
+
+  const result = withBusyRetry(() => db.prepare(`
+    UPDATE tasks
+       SET status = 'open',
+           claimed_by = NULL,
+           claimed_at = NULL,
+           done_at = NULL,
+           updated_at = ?,
+           metadata = ?
+     WHERE id = ?
+       AND status = ?
+       AND updated_at = ?
+  `).run(now, JSON.stringify(metadata), id, row.status, row.updated_at));
+  if (result.changes !== 1) return { reopened: false, reason: 'stale_task_state' };
+  const updated = getTask(db, id);
+  const event = appendTaskEvent(db, {
+    taskId: id,
+    workspaceRoot: updated.workspace_root,
+    actor: actorText,
+    eventType: 'reopened',
+    payload: { previous_status: row.status, reason: reasonText },
+  });
+  return { reopened: true, event, row: updated };
+}
+
 function doneTask(db, { id, status, actor, allowReview = false, action, proof, autoAccepted = false } = {}) {
   if (!id) throw new Error('id required');
   const final = status || 'done';
@@ -570,6 +651,39 @@ function doneTask(db, { id, status, actor, allowReview = false, action, proof, a
   return { updated: false };
 }
 
+function reapMissionBlockerTasks(db, { workspaceRoot: ws, missions = [], actor } = {}) {
+  const missionById = new Map((Array.isArray(missions) ? missions : [])
+    .filter(mission => mission && mission.id)
+    .map(mission => [String(mission.id), mission]));
+  const candidates = listTasks(db, { workspaceRoot: ws || null, limit: null })
+    .filter(row => OPEN_TASK_STATUSES.has(row.status))
+    .filter(row => row.tag === 'mission-blocker')
+    .filter(row => row.metadata && row.metadata.mission_id && row.metadata.mission_blocker_class)
+    .map(row => ({ row, mission: missionById.get(String(row.metadata.mission_id)) }))
+    .filter(({ mission }) => mission && TERMINAL_MISSION_STATUSES.has(String(mission.status || '').toLowerCase()));
+  const closed = [];
+  for (const { row, mission } of candidates) {
+    const missionStatus = String(mission.status).toLowerCase();
+    const reason = `mission ${mission.id} is ${missionStatus}`;
+    const result = archiveTask(db, {
+      id: row.id,
+      actor,
+      reason,
+    });
+    if (!result.archived) continue;
+    closed.push({
+      task_id: row.id,
+      title: row.title,
+      previous_status: row.status,
+      mission_id: mission.id,
+      mission_status: missionStatus,
+      blocker_class: row.metadata.mission_blocker_class,
+      reason,
+    });
+  }
+  return { closed, count: closed.length };
+}
+
 // Distinct terminal status for housekeeping sweeps (duplicate loop-ticks,
 // off-roadmap backlog resets, synthetic-test cleanup). Never conflate this
 // with `failed` — 'failed' means the work itself did not succeed, 'archived'
@@ -1556,6 +1670,21 @@ function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, ca
     metadata.agent_reviewed_by = reviewer;
     if (proofText) metadata.latest_agent_proof = proofText;
     if (verifyText) {
+      // Gate at the write path, not just cmdReview: a verify the strict parser
+      // rejects can never be run by the hourly autoland recheck, so storing it
+      // silently parks the task on a human forever (observed 2026-07-31: five
+      // certified tasks stalled for days on unrunnable verifies stored by
+      // fleet lanes that bypass the command-layer gate).
+      const parsedVerify = parseVerifyCommand(verifyText);
+      if (!parsedVerify.ok) {
+        const error = new Error(
+          `verify command is not runnable by the hourly recheck (${parsedVerify.reason || 'verify_command_not_allowed'}); `
+          + 'use an allowlisted shape: cd backend && ../venv/bin/python -m pytest <file> -q, '
+          + 'test -s <artifact>, npm test, node --test <file>, tsc, or git diff --check',
+        );
+        error.reason = parsedVerify.reason || 'verify_command_not_allowed';
+        throw error;
+      }
       metadata.verify = verifyText;
       metadata.latest_agent_verify = verifyText;
     }
@@ -1997,8 +2126,11 @@ function appendSection(lines, name, rows) {
     const tag = [...new Set(tags.filter(Boolean).map(value => String(value).trim()).filter(Boolean))]
       .map(value => ` [${value}]`)
       .join('');
+    // Decision holds live in metadata.tags (or the primary tag). Surface them
+    // so a human judgment row never blends into ordinary work on the board.
+    const decision = isDecisionTask(row) ? ' [decision]' : '';
     const displayRef = meta.todo_id || row.display_id || row.id;
-    lines.push(`- **[${displayRef}]** ${row.title}${tag}`);
+    lines.push(`- **[${displayRef}]** ${row.title}${tag}${decision}`);
     if (row.claimed_by && row.status === 'claimed') lines.push(`  **Claimed by:** ${row.claimed_by}`);
     if (meta.verify) lines.push(`  **Verify:** ${meta.verify}`);
   }
@@ -2046,9 +2178,11 @@ module.exports = {
   listTasks,
   claimTask,
   releaseTask,
+  reopenTask,
   backlogTask,
   clearPlanTasks,
   doneTask,
+  reapMissionBlockerTasks,
   archiveTask,
   relabelArchivedTasks,
   readyTask,

package/lib/task-decision.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// Decision rows are human judgment calls, not agent work. Detect them from
+// tags already in the data (primary tag, tags[], metadata.tags). The live
+// marker is needs-human (CLI-879); decision is the same hold under a clearer
+// name. Autonomous pickers must refuse these; list renderers must show them.
+
+const DECISION_HOLD_TAGS = new Set([
+  'needs-human',
+  'needshuman',
+  'decision',
+]);
+
+const DECISION_MARKER = '[decision]';
+const DECISION_REFUSE_REASON = 'decision row: human judgment required';
+
+function normalizeDecisionTag(value) {
+  return String(value == null ? '' : value).trim().toLowerCase().replace(/_/g, '-');
+}
+
+function taskTagTokens(task) {
+  if (!task || typeof task !== 'object') return [];
+  const fromTags = Array.isArray(task.tags) ? task.tags : [];
+  const fromTag = task.tag ? [task.tag] : [];
+  const fromMeta = task.metadata && Array.isArray(task.metadata.tags) ? task.metadata.tags : [];
+  const fromTitle = (String(task.title || '').match(/#([a-z0-9-]+)/gi) || []).map((t) => t.slice(1));
+  return [...fromTag, ...fromTags, ...fromMeta, ...fromTitle]
+    .map(normalizeDecisionTag)
+    .filter(Boolean);
+}
+
+function isDecisionHoldTag(tag) {
+  return DECISION_HOLD_TAGS.has(normalizeDecisionTag(tag));
+}
+
+function isDecisionTask(task) {
+  return taskTagTokens(task).some(isDecisionHoldTag);
+}
+
+function decisionMarkerFor(task) {
+  return isDecisionTask(task) ? DECISION_MARKER : '';
+}
+
+module.exports = {
+  DECISION_REFUSE_REASON,
+  taskTagTokens,
+  isDecisionHoldTag,
+  isDecisionTask,
+  decisionMarkerFor,
+};

package/lib/taste-lessons.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VERDICTS = new Set(['keep', 'kill', 'more']);
+const SCOPES = new Set(['writing', 'design', 'code', 'any']);
+const STOP_WORDS = new Set([
+  'and', 'are', 'because', 'for', 'from', 'has', 'have', 'into', 'its', 'not', 'of', 'on', 'or',
+  'that', 'the', 'their', 'this', 'to', 'was', 'were', 'with', 'without', 'you', 'your',
+]);
+
+function tastePath(root) {
+  return path.join(root, 'atris', 'taste.json');
+}
+
+function readTaste(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(tastePath(root), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function slugify(subject) {
+  return String(subject || '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80)
+    .replace(/-+$/g, '');
+}
+
+function validEntry(entry) {
+  return entry
+    && typeof entry === 'object'
+    && VERDICTS.has(entry.verdict)
+    && typeof entry.subject === 'string'
+    && entry.subject.trim()
+    && typeof entry.why === 'string'
+    && entry.why.trim()
+    && SCOPES.has(entry.scope)
+    && typeof entry.added === 'string';
+}
+
+function entriesFrom(store) {
+  return Object.entries(store)
+    .filter(([, entry]) => validEntry(entry))
+    .map(([slug, entry]) => ({ slug, ...entry }));
+}
+
+function assertChoice(value, allowed, field) {
+  if (!allowed.has(value)) throw new Error(`${field} must be one of: ${[...allowed].join(', ')}`);
+}
+
+function addTaste({
+  verdict,
+  subject,
+  why,
+  scope = 'any',
+  example,
+  added,
+  root = process.cwd(),
+} = {}) {
+  const cleanVerdict = String(verdict || '').trim().toLowerCase();
+  const cleanSubject = String(subject || '').trim();
+  const cleanWhy = String(why || '').trim();
+  const cleanScope = String(scope || 'any').trim().toLowerCase();
+  const cleanExample = example === undefined ? '' : String(example).trim();
+  const cleanAdded = String(added || '').trim();
+
+  assertChoice(cleanVerdict, VERDICTS, 'verdict');
+  assertChoice(cleanScope, SCOPES, 'scope');
+  if (!cleanSubject) throw new Error('subject is required');
+  if (!cleanWhy) throw new Error('why is required');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(cleanAdded)) throw new Error('added must be an ISO date');
+
+  const baseSlug = slugify(cleanSubject);
+  if (!baseSlug) throw new Error('subject must contain letters or numbers');
+
+  const store = readTaste(root);
+  let slug = baseSlug;
+  let suffix = 2;
+  while (store[slug] && store[slug].subject !== cleanSubject) {
+    slug = `${baseSlug}-${suffix}`;
+    suffix += 1;
+  }
+
+  const entry = {
+    verdict: cleanVerdict,
+    subject: cleanSubject,
+    why: cleanWhy,
+    scope: cleanScope,
+    ...(cleanExample ? { example: cleanExample } : {}),
+    added: cleanAdded,
+  };
+  store[slug] = entry;
+
+  const file = tastePath(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+  return { slug, ...entry };
+}
+
+function listTaste({ root = process.cwd(), scope } = {}) {
+  const cleanScope = scope === undefined ? null : String(scope).trim().toLowerCase();
+  if (cleanScope) assertChoice(cleanScope, SCOPES, 'scope');
+  return entriesFrom(readTaste(root))
+    .filter((entry) => !cleanScope || cleanScope === 'any' || entry.scope === 'any' || entry.scope === cleanScope)
+    .sort((left, right) => right.added.localeCompare(left.added) || left.slug.localeCompare(right.slug));
+}
+
+function keywords(text) {
+  return [...new Set(String(text || '').toLowerCase().split(/[^a-z0-9]+/)
+    .filter((word) => word.length >= 3 && !STOP_WORDS.has(word)))];
+}
+
+function matchTaste({ briefText = '', scope = 'any', root = process.cwd() } = {}) {
+  const cleanScope = SCOPES.has(String(scope || '').toLowerCase())
+    ? String(scope).toLowerCase()
+    : 'any';
+  const briefWords = new Set(keywords(briefText));
+  if (!briefWords.size) return [];
+
+  const matches = [];
+  for (const entry of entriesFrom(readTaste(root))) {
+    if (cleanScope !== 'any' && entry.scope !== 'any' && entry.scope !== cleanScope) continue;
+
+    const subjectMatches = keywords(`${entry.slug} ${entry.subject}`).filter((word) => briefWords.has(word));
+    const whyMatches = keywords(entry.why).filter((word) => briefWords.has(word));
+    const exampleMatches = keywords(entry.example || '').filter((word) => briefWords.has(word));
+    const overlap = new Set([...subjectMatches, ...whyMatches, ...exampleMatches]);
+    if (!overlap.size) continue;
+
+    const scopeScore = entry.scope === cleanScope ? 10_000 : entry.scope === 'any' ? 5_000 : 0;
+    const score = scopeScore
+      + (subjectMatches.length * 300)
+      + (exampleMatches.length * 200)
+      + (whyMatches.length * 100)
+      + [...overlap].reduce((total, word) => total + word.length, 0);
+    matches.push({ ...entry, why_matched: `brief mentions ${[...overlap].join(', ')}`, score });
+  }
+
+  return matches
+    .sort((left, right) => right.score - left.score || left.slug.localeCompare(right.slug))
+    .slice(0, 5)
+    .map(({ score, ...entry }) => entry);
+}
+
+module.exports = { addTaste, listTaste, matchTaste };

package/lib/tool-result-encode.js

@@ -4,4 +4,20 @@ function encodeToolResult(result) {
   return Buffer.from(JSON.stringify(result), 'utf8').toString('base64');
 }
 
-module.exports = { encodeToolResult };
+function toolResultEncodingEnabled(env = process.env) {
+  return env.ATRIS_TOOL_RESULT_B64 !== '0';
+}
+
+function buildToolResultBody(callId, result, env = process.env) {
+  if (!toolResultEncodingEnabled(env)) {
+    return { call_id: callId, result };
+  }
+
+  return {
+    call_id: callId,
+    result: encodeToolResult(result),
+    output_encoding: 'base64',
+  };
+}
+
+module.exports = { buildToolResultBody, encodeToolResult, toolResultEncodingEnabled };