atris 3.45.1 → 3.46.1

package/lib/ci-runner.js

@@ -0,0 +1,396 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const https = require('node:https');
+const { spawn, spawnSync } = require('node:child_process');
+
+const RUNNER_VERSION = '2.336.0';
+const GITHUB_API_VERSION = '2026-03-10';
+
+function usageFilePath(home = os.homedir()) {
+  return path.join(home, '.atris', 'ci', 'usage.jsonl');
+}
+
+function appendUsageLine(file, line) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, line, 'utf8');
+}
+
+function clockDate(clock) {
+  const value = clock();
+  const date = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(date.getTime())) throw new Error('ci usage clock returned an invalid time');
+  return date;
+}
+
+function runnerAssetName(platform, arch, version = RUNNER_VERSION) {
+  const platformNames = { darwin: 'osx', linux: 'linux' };
+  const archNames = { x64: 'x64', arm64: 'arm64' };
+  const runnerPlatform = platformNames[platform];
+  const runnerArch = archNames[arch];
+  if (!runnerPlatform || !runnerArch) {
+    throw new Error(`unsupported runner platform: ${platform}/${arch}`);
+  }
+  return `actions-runner-${runnerPlatform}-${runnerArch}-${version}.tar.gz`;
+}
+
+function parseRepo(value) {
+  if (typeof value !== 'string') throw new Error('--repo owner/name is required');
+  const parts = value.trim().split('/');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error('--repo must use owner/name');
+  }
+  const [owner, repo] = parts;
+  const validOwner = /^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/i;
+  const validRepo = /^[a-z0-9_.-]{1,100}$/i;
+  if (!validOwner.test(owner) || !validRepo.test(repo) || repo === '.' || repo === '..') {
+    throw new Error('--repo must use a valid owner/name');
+  }
+  return { owner, repo, slug: `${owner}/${repo}` };
+}
+
+function parseRunnerArgs(argv) {
+  const options = { label: null, once: false };
+  let repoValue = null;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--repo') {
+      if (repoValue !== null) throw new Error('--repo may only be set once');
+      repoValue = argv[index + 1];
+      if (!repoValue || repoValue.startsWith('--')) throw new Error('--repo owner/name is required');
+      index += 1;
+    } else if (arg === '--label') {
+      if (options.label !== null) throw new Error('--label may only be set once');
+      options.label = argv[index + 1];
+      if (!options.label || options.label.startsWith('--')) throw new Error('--label name is required');
+      if (!/^[a-z0-9_.-]+$/i.test(options.label)) {
+        throw new Error('--label must contain only letters, numbers, dots, underscores, or hyphens');
+      }
+      index += 1;
+    } else if (arg === '--once') {
+      if (options.once) throw new Error('--once may only be set once');
+      options.once = true;
+    } else {
+      throw new Error(`unknown ci runner option: ${arg}`);
+    }
+  }
+
+  return { repo: parseRepo(repoValue), label: options.label, once: options.once };
+}
+
+function parseUsageArgs(argv) {
+  let repo = null;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg !== '--repo') throw new Error(`unknown ci usage option: ${arg}`);
+    if (repo !== null) throw new Error('--repo may only be set once');
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error('--repo owner/name is required');
+    repo = parseRepo(value).slug;
+    index += 1;
+  }
+
+  return { repo };
+}
+
+function readUsageRecords(file = usageFilePath(), readFile = fs.readFileSync) {
+  let content;
+  try {
+    content = readFile(file, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return [];
+    throw error;
+  }
+
+  return String(content)
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function summarizeUsage(records, options = {}) {
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  if (!Number.isFinite(now.getTime())) throw new Error('ci usage clock returned an invalid time');
+  const month = now.toISOString().slice(0, 7);
+  const selected = records.filter((record) => (
+    record
+    && typeof record.repo === 'string'
+    && record.repo.length > 0
+    && (!options.repo || record.repo === options.repo)
+    && Number.isFinite(Date.parse(record.started_at))
+    && Number.isFinite(Number(record.duration_seconds))
+    && Number(record.duration_seconds) >= 0
+  ));
+  const repos = new Map();
+  let totalMinutes = 0;
+  let monthMinutes = 0;
+
+  for (const record of selected) {
+    const minutes = Math.ceil(Number(record.duration_seconds) / 60);
+    totalMinutes += minutes;
+    if (new Date(record.started_at).toISOString().slice(0, 7) === month) monthMinutes += minutes;
+    const repo = repos.get(record.repo) || { repo: record.repo, jobs: 0, minutes: 0 };
+    repo.jobs += 1;
+    repo.minutes += minutes;
+    repos.set(record.repo, repo);
+  }
+
+  return {
+    totalJobs: selected.length,
+    totalMinutes,
+    monthMinutes,
+    repos: [...repos.values()].sort((left, right) => left.repo.localeCompare(right.repo)),
+  };
+}
+
+function formatUsageSummary(summary) {
+  if (summary.totalJobs === 0) return 'no build minutes recorded yet';
+  return [
+    `total jobs: ${summary.totalJobs}`,
+    `total minutes: ${summary.totalMinutes}`,
+    `minutes this month: ${summary.monthMinutes}`,
+    'per repo:',
+    ...summary.repos.map((repo) => (
+      `${repo.repo}: ${repo.jobs} ${repo.jobs === 1 ? 'job' : 'jobs'}, `
+      + `${repo.minutes} ${repo.minutes === 1 ? 'minute' : 'minutes'}`
+    )),
+  ].join('\n');
+}
+
+function buildJitConfigRequest(repo, label, runnerName) {
+  const labels = label && label !== 'atris' ? ['atris', label] : ['atris'];
+  return {
+    path: `/repos/${repo.owner}/${repo.repo}/actions/runners/generate-jitconfig`,
+    body: {
+      name: runnerName,
+      runner_group_id: 1,
+      labels,
+      work_folder: '_work',
+    },
+  };
+}
+
+function resolveGithubToken(env = process.env, run = spawnSync) {
+  const envToken = String(env.GITHUB_TOKEN || '').trim();
+  if (envToken) return envToken;
+  const result = run('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  const ghToken = result && result.status === 0 ? String(result.stdout || '').trim() : '';
+  if (ghToken) return ghToken;
+  throw new Error('github token required: set GITHUB_TOKEN or run gh auth login');
+}
+
+function requestJson(options, body, request = https.request) {
+  return new Promise((resolve, reject) => {
+    const req = request(options, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed = {};
+        try {
+          parsed = raw ? JSON.parse(raw) : {};
+        } catch {
+          reject(new Error('github returned an unreadable response'));
+          return;
+        }
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          const message = String(parsed.message || `github request failed with status ${response.statusCode}`)
+            .replace(/\s+/g, ' ')
+            .trim();
+          reject(new Error(message.toLowerCase()));
+          return;
+        }
+        resolve(parsed);
+      });
+    });
+    req.on('error', reject);
+    req.end(body);
+  });
+}
+
+async function generateJitConfig(token, repo, label, runnerName, request = https.request) {
+  const spec = buildJitConfigRequest(repo, label, runnerName);
+  const body = JSON.stringify(spec.body);
+  const response = await requestJson({
+    hostname: 'api.github.com',
+    path: spec.path,
+    method: 'POST',
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'User-Agent': 'atris-ci-runner',
+      'X-GitHub-Api-Version': GITHUB_API_VERSION,
+    },
+  }, body, request);
+  if (!response.encoded_jit_config) throw new Error('github did not return a runner configuration');
+  return response.encoded_jit_config;
+}
+
+function downloadFile(url, destination, get = https.get, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const request = get(url, { headers: { 'User-Agent': 'atris-ci-runner' } }, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        if (redirectsLeft === 0) {
+          reject(new Error('runner download followed too many redirects'));
+          return;
+        }
+        const nextUrl = new URL(response.headers.location, url);
+        if (nextUrl.protocol !== 'https:') {
+          reject(new Error('runner download redirected outside https'));
+          return;
+        }
+        downloadFile(nextUrl.toString(), destination, get, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`runner download failed with status ${response.statusCode}`));
+        return;
+      }
+      const output = fs.createWriteStream(destination);
+      output.on('error', reject);
+      response.on('error', reject);
+      output.on('finish', () => output.close(resolve));
+      response.pipe(output);
+    });
+    request.on('error', reject);
+  });
+}
+
+async function ensureRunner(options = {}) {
+  const version = options.version || RUNNER_VERSION;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const home = options.home || os.homedir();
+  const log = options.log || console.log;
+  const asset = runnerAssetName(platform, arch, version);
+  const runnerPlatform = platform === 'darwin' ? 'osx' : platform;
+  const runnerDir = path.join(home, '.atris', 'ci', version, `${runnerPlatform}-${arch}`);
+  const runScript = path.join(runnerDir, 'run.sh');
+  if (fs.existsSync(runScript)) return runnerDir;
+
+  const cacheDir = path.join(home, '.atris', 'ci');
+  const archive = path.join(cacheDir, asset);
+  fs.mkdirSync(runnerDir, { recursive: true });
+  if (!fs.existsSync(archive)) {
+    const partial = `${archive}.download-${process.pid}`;
+    log(`downloading github actions runner ${version}`);
+    try {
+      await (options.download || downloadFile)(
+        `https://github.com/actions/runner/releases/download/v${version}/${asset}`,
+        partial,
+      );
+      fs.renameSync(partial, archive);
+    } catch (error) {
+      fs.rmSync(partial, { force: true });
+      throw error;
+    }
+  }
+
+  const extract = (options.spawnSync || spawnSync)('tar', ['-xzf', archive, '-C', runnerDir], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (extract.error || extract.status !== 0) {
+    const detail = String(extract.stderr || extract.error?.message || 'tar failed').replace(/\s+/g, ' ').trim();
+    throw new Error(`could not extract github actions runner: ${detail.toLowerCase()}`);
+  }
+  if (!fs.existsSync(runScript)) throw new Error('github actions runner archive did not contain run.sh');
+  fs.chmodSync(runScript, 0o755);
+  return runnerDir;
+}
+
+function runWorker(runnerDir, jitConfig, start = spawn) {
+  return new Promise((resolve, reject) => {
+    const child = start('./run.sh', ['--jitconfig', jitConfig], {
+      cwd: runnerDir,
+      env: process.env,
+      stdio: 'inherit',
+    });
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (code === 0) {
+        resolve();
+      } else if (signal) {
+        reject(new Error(`github actions runner stopped with signal ${signal}`));
+      } else {
+        reject(new Error(`github actions runner exited with code ${code}`));
+      }
+    });
+  });
+}
+
+async function runJobLoop(options, dependencies = {}) {
+  const mint = dependencies.generateJitConfig || generateJitConfig;
+  const startWorker = dependencies.runWorker || runWorker;
+  const shouldContinue = dependencies.shouldContinue || ((state) => !state.once);
+  const log = dependencies.log || console.log;
+  const clock = dependencies.clock || (() => new Date());
+  const file = dependencies.usagePath || usageFilePath();
+  const appendUsage = dependencies.appendUsage || appendUsageLine;
+  let completedJobs = 0;
+
+  while (true) {
+    const runnerName = `${options.runnerName}-${completedJobs + 1}`;
+    const jitConfig = await mint(options.token, options.repo, options.label, runnerName);
+    log(`worker ready, waiting for jobs on ${options.repo.slug}`);
+    const startedAt = clockDate(clock);
+    let workerError = null;
+    try {
+      await startWorker(options.runnerDir, jitConfig);
+    } catch (error) {
+      workerError = error;
+    } finally {
+      const finishedAt = clockDate(clock);
+      const durationSeconds = Math.max(0, Math.ceil((finishedAt.getTime() - startedAt.getTime()) / 1000));
+      const line = `${JSON.stringify({
+        repo: options.repo.slug,
+        started_at: startedAt.toISOString(),
+        duration_seconds: durationSeconds,
+      })}\n`;
+      await appendUsage(file, line);
+    }
+    if (workerError) throw workerError;
+    completedJobs += 1;
+    if (!shouldContinue({ once: options.once, completedJobs })) return completedJobs;
+  }
+}
+
+async function runCiRunner(options, dependencies = {}) {
+  const token = (dependencies.resolveGithubToken || resolveGithubToken)();
+  const runnerDir = await (dependencies.ensureRunner || ensureRunner)({ log: dependencies.log });
+  const host = String((dependencies.hostname || os.hostname)()).toLowerCase().replace(/[^a-z0-9-]+/g, '-');
+  return runJobLoop({
+    ...options,
+    token,
+    runnerDir,
+    runnerName: `atris-${host || 'worker'}-${process.pid}`,
+  }, dependencies);
+}
+
+module.exports = {
+  buildJitConfigRequest,
+  formatUsageSummary,
+  parseRunnerArgs,
+  parseUsageArgs,
+  readUsageRecords,
+  runCiRunner,
+  runJobLoop,
+  runnerAssetName,
+  summarizeUsage,
+  usageFilePath,
+};

package/lib/engine-validate.js

@@ -14,6 +14,8 @@ const DEFAULT_REFEREE_ENGINE = 'haiku';
 const VALIDATION_SCHEMA = 'atris.engine_validate_verdict.v1';
 const VALID_VERDICTS = new Set(['pass', 'fail', 'unsure']);
 const MODEL_SELECTING_REFEREES = new Set(['claude', 'fable', 'haiku', 'codex', 'cursor', 'devin', 'grok']);
+// Three receipt checks per hourly tick keep the cheap referee spend negligible.
+const MAX_AUTOMATIC_VALIDATIONS_PER_TICK = 3;
 
 function validateUsage() {
   return [
@@ -254,6 +256,127 @@ function relativePath(root, filePath) {
   return path.relative(root, filePath) || path.basename(filePath);
 }
 
+function validationSourceKey(root, source) {
+  const sourcePath = path.isAbsolute(source) ? source : path.resolve(root, source);
+  return relativePath(root, sourcePath).split(path.sep).join('/');
+}
+
+function automaticValidationCandidates(root, fsModule = fs) {
+  const covered = new Set(readValidationRows(root, fsModule)
+    .filter((row) => row && row.source_receipt && VALID_VERDICTS.has(row.verdict))
+    .map((row) => validationSourceKey(root, row.source_receipt)));
+  const summary = {
+    scanned: 0,
+    skipped_covered: 0,
+    skipped_status: 0,
+    skipped_no_answers: 0,
+  };
+  const runsDir = path.join(root, 'atris', 'runs');
+  let names;
+  try {
+    names = fsModule.readdirSync(runsDir)
+      .filter((name) => /^engine-ask-.+[.]json$/.test(name));
+  } catch {
+    return { candidates: [], summary };
+  }
+
+  const candidates = [];
+  for (const name of names) {
+    const receiptPath = path.join(runsDir, name);
+    let receipt;
+    let stat;
+    try {
+      receipt = readAskReceipt(receiptPath, fsModule);
+      stat = fsModule.statSync(receiptPath);
+    } catch {
+      continue;
+    }
+    summary.scanned += 1;
+    if (receipt.status !== 'completed') {
+      summary.skipped_status += 1;
+      continue;
+    }
+    const answered = receipt.answers.filter((answer) => answer.status === 'answered');
+    if (!answered.length) {
+      summary.skipped_no_answers += 1;
+      continue;
+    }
+    const sourceReceipt = validationSourceKey(root, receiptPath);
+    if (covered.has(sourceReceipt)) {
+      summary.skipped_covered += 1;
+      continue;
+    }
+    const gradeable = answered.filter((answer) => {
+      const worker = canonicalEngineName(answer.engine) || String(answer.engine || '').trim();
+      return worker !== DEFAULT_REFEREE_ENGINE;
+    });
+    const skipped = answered.filter((answer) => !gradeable.includes(answer));
+    candidates.push({
+      receiptPath,
+      sourceReceipt,
+      timeMs: receiptTimeMs(receipt, stat),
+      gradeable,
+      skipped,
+    });
+  }
+  candidates.sort((left, right) => right.timeMs - left.timeMs
+    || right.receiptPath.localeCompare(left.receiptPath));
+  return { candidates, summary };
+}
+
+async function validateRecentAskReceipts(root, deps = {}) {
+  const fsModule = deps.fs || fs;
+  const selected = automaticValidationCandidates(root, fsModule);
+  const summary = {
+    ...selected.summary,
+    attempted_receipts: 0,
+    graded_receipts: 0,
+    graded_answers: 0,
+    skipped_self_grade: 0,
+    failures: 0,
+    notes: [],
+  };
+  const candidates = [];
+  for (const candidate of selected.candidates) {
+    if (candidate.skipped.length) {
+      summary.skipped_self_grade += candidate.skipped.length;
+      for (const answer of candidate.skipped) {
+        const label = String(answer.label || answer.engine || 'haiku answer').trim();
+        summary.notes.push(`skipped ${label} from ${candidate.sourceReceipt}: judge never equals worker.`);
+      }
+    }
+    if (candidate.gradeable.length) candidates.push(candidate);
+  }
+
+  const validateReceipt = deps.validateReceipt || runEngineValidateCommand;
+  for (const candidate of candidates.slice(0, MAX_AUTOMATIC_VALIDATIONS_PER_TICK)) {
+    summary.attempted_receipts += 1;
+    let code;
+    try {
+      code = await validateReceipt([candidate.receiptPath], root, {
+        fs: fsModule,
+        now: deps.now,
+        concurrency: deps.concurrency,
+        timeoutMs: deps.timeoutMs,
+        executeAskJob: deps.executeAskJob,
+        skipMatchingWorker: true,
+        log: deps.validationLog || (() => {}),
+        error: deps.validationError || (() => {}),
+      });
+    } catch (error) {
+      code = 1;
+      summary.notes.push(`validation failed for ${candidate.sourceReceipt}: ${String(error && error.message || error)}`);
+    }
+    if (code === 0) {
+      summary.graded_receipts += 1;
+      summary.graded_answers += candidate.gradeable.length;
+    } else {
+      summary.failures += 1;
+    }
+  }
+  return summary;
+}
+
 async function runEngineValidateCommand(args = [], root = process.cwd(), deps = {}) {
   const log = deps.log || console.log;
   const errorLog = deps.error || console.error;
@@ -286,11 +409,25 @@ async function runEngineValidateCommand(args = [], root = process.cwd(), deps =
     errorLog(`engine validate: ${error.message}`);
     return 2;
   }
-  const answered = source.receipt.answers.filter((answer) => answer.status === 'answered');
+  let answered = source.receipt.answers.filter((answer) => answer.status === 'answered');
   if (!answered.length) {
     errorLog('engine validate: the ask receipt has no answered entries');
     return 2;
   }
+  const skipped = [];
+  if (deps.skipMatchingWorker) {
+    answered = answered.filter((answer) => {
+      const workerEngine = canonicalEngineName(answer.engine) || String(answer.engine || '').trim();
+      if (workerEngine !== parsed.refereeEngine) return true;
+      skipped.push({
+        answer_label: String(answer.label || ''),
+        worker_engine: String(answer.engine || ''),
+        reason: 'judge never equals worker',
+      });
+      return false;
+    });
+    if (!answered.length) return 0;
+  }
   for (const answer of answered) {
     const workerEngine = canonicalEngineName(answer.engine) || String(answer.engine || '').trim();
     if (!workerEngine) {
@@ -348,6 +485,7 @@ async function runEngineValidateCommand(args = [], root = process.cwd(), deps =
     referee_engine: parsed.refereeEngine,
     referee_model: model,
     verdicts,
+    ...(skipped.length ? { skipped } : {}),
     duration_ms: verdicts.reduce((sum, verdict) => sum + verdict.duration_ms, 0),
     at,
   };
@@ -375,8 +513,10 @@ async function runEngineValidateCommand(args = [], root = process.cwd(), deps =
 }
 
 module.exports = {
+  MAX_AUTOMATIC_VALIDATIONS_PER_TICK,
   VALIDATION_SCHEMA,
   parseRefereeOutput,
   resolveAskReceipt,
   runEngineValidateCommand,
+  validateRecentAskReceipts,
 };

package/lib/known-commands.js

@@ -4,7 +4,7 @@ const knownCommands = ['init', 'log', 'logs', 'wish', 'ask', 'approve', 'stop',
                        'activate', '_activate', 'agent', 'team', 'chat', 'fast', 'ax', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
                        'clean', 'close', 'harvest', 'verify', 'recover', 'search', 'scout', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'taste', 'teach', 'plugin', 'experiments', 'bench', 'router', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'watch', 'cloud', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube',
                        'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'decide', 'agents', 'probe', 'worktree', 'land', 'caretaker', 'autoland', 'drive', 'aeo', 'slop', 'voice', 'strings', 'write', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'study', 'rainmaker', 'xp', 'play', 'gm', 'game', 'x', 'recap', 'report', 'signup', 'clarity', 'interview', 'meet', 'moves', 'unknowns', 'avail', 'sync-checkout',
-                       'github', 'vercel', 'supabase', 'linear', 'stripe', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
+                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'pack', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet', 'fleet-report', 'loops', 'self-improve', 'compile', 'spaceship', 'truth', 'sign', 'engine', 'engines', 'feed', 'brief'];
 
 // Damerau-Levenshtein edit distance between two short strings. Counts an

package/lib/task-db.js

@@ -30,6 +30,7 @@ const { DatabaseSync } = require('node:sqlite');
 const reviewIntegrity = require('./review-integrity');
 const { isDecisionTask } = require('./task-decision');
 const { parseVerifyCommand } = require('./auto-accept-certified');
+const { taskExplanation } = require('./task-explanation');
 
 const DEFAULT_DB_PATH = path.join(os.homedir(), '.atris', 'tasks.db');
 const TASK_EPISODES_FILE = path.join('.atris', 'state', 'task_episodes.jsonl');
@@ -384,13 +385,21 @@ function taskDisplayRefMap(rows) {
   return map;
 }
 
-function taskCreationMetadata(metadata) {
+// One chokepoint every production addTask caller passes through, so a task
+// created by mission, play, business, gm, lesson, the context gatherer, the
+// self-drive lane, the CLI, or the board API all carry the same plain-language
+// first layer. Explicit fields from the caller are kept verbatim; the rest get
+// an honest derived default recorded as such.
+function taskCreationMetadata(metadata, { title, tag } = {}) {
   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';
   }
+  if (!next.explanation || typeof next.explanation !== 'object') {
+    next.explanation = taskExplanation({ title, tag, metadata: next });
+  }
   return next;
 }
 
@@ -408,7 +417,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);
+  const taskMetadata = taskCreationMetadata(metadata, { title: String(title).trim(), tag: tag || null });
   withBusyRetry(() => db.prepare(`
     INSERT INTO tasks (id, title, status, tag, workspace_root, source_key,
                        claimed_by, claimed_at, created_at, updated_at, metadata)
@@ -2052,6 +2061,9 @@ function taskProjection(db, {
         id: row.id,
         ...(refById.get(row.id) || {}),
         title: row.title,
+        // First layer, ahead of the detail. Legacy rows with no stored
+        // explanation get the same three fields derived here.
+        explanation: taskExplanation(row),
         result: row.metadata && row.metadata.result || null,
         status: row.status,
         tag: row.tag,
@@ -2130,7 +2142,14 @@ function appendSection(lines, name, rows) {
     // 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}${decision}`);
+    const explanation = taskExplanation(row);
+    // The plain face leads. The exact original title remains immediately below
+    // it so old TODO-only projects and deep inspection keep full fidelity.
+    lines.push(`- **[${displayRef}]** ${explanation.what_changes}${tag}${decision}`);
+    lines.push(`  **Why it matters:** ${explanation.why_it_matters}`);
+    lines.push(`  **Done looks like:** ${explanation.done_looks_like}`);
+    lines.push(`  **Approve or change:** \`atris task show ${displayRef}\` shows the actions allowed by the current plan and proof checks.`);
+    lines.push(`  **Technical details:** ${row.title}`);
     if (row.claimed_by && row.status === 'claimed') lines.push(`  **Claimed by:** ${row.claimed_by}`);
     if (meta.verify) lines.push(`  **Verify:** ${meta.verify}`);
   }