atris 3.57.4 → 3.58.6

package/commands/workflow.js

@@ -19,6 +19,7 @@ const { startFirstTalk } = require('../lib/context-gatherer');
 const { isNonInteractive } = require('../lib/noninteractive');
 const { loadContext } = require('../lib/state-detection');
 const { buildToolResultBody } = require('../lib/tool-result-encode');
+const { commitReviewLearning } = require('./learn');
 
 function wrapWorkflowText(text, width = 76) {
   const normalized = String(text || '').replace(/\s+/g, ' ').trim();
@@ -612,7 +613,7 @@ async function planAtris(userInput = null) {
 
   if (showFactory) {
   console.log('┌─────────────────────────────────────────────────────────────┐');
-  console.log('│ Atris Plan — Navigator Agent Activated                      │');
+  console.log('│ Atris Plan - Navigator Agent Activated                     │');
   console.log('└─────────────────────────────────────────────────────────────┘');
   console.log('');
 
@@ -641,7 +642,7 @@ async function planAtris(userInput = null) {
   console.log(`- Navigator spec: ${navigatorPath || 'atris/team/navigator/MEMBER.md (missing)'}`);
   console.log(`- Persona: ${personaFileRef || 'atris/PERSONA.md (missing)'}`);
   const mapDisplay = mapFileRef
-    ? `${mapFileRef}${mapIsPlaceholder ? ' (placeholder — generate first)' : ''}`
+    ? `${mapFileRef}${mapIsPlaceholder ? ' (placeholder, generate first)' : ''}`
     : 'atris/MAP.md (missing)';
   console.log(`- MAP: ${mapDisplay}`);
   console.log(`- TODO: ${taskSourcePath || 'atris/TODO.md (missing)'}`);
@@ -710,11 +711,12 @@ async function planAtris(userInput = null) {
     console.log('');
   }
   console.log('Workflow:');
-  console.log('1) ASCII visualize + wait for approval');
+  console.log('1) ASCII visualize; use existing approval for this scope, otherwise wait for approval');
   console.log('2) Run the Confidence Gate before writing tasks');
   printConfidenceGate('   ');
-  console.log('3) Write tasks to atris/TODO.md under ## Backlog');
-  console.log('   Format: - **T#:** Description [explore|execute]');
+  console.log('3) Create each task in the live task plane: `atris task add "<title>" --tag <tag>`, then `atris task plan <id> --goal ... --exit ... --proof-needed ...`');
+  console.log('   Keep a delegated owner: `atris task delegate "<title>" --to <member>`; plan keeps that owner unless you pass --owner');
+  console.log('   atris/TODO.md is a generated view: never hand-edit it, regenerate with `atris task render --out atris/TODO.md`');
   console.log('4) Log to atris/team/navigator/logs/YYYY-MM-DD.md');
   console.log('   (Task, Delivered, User reaction, Pattern)');
   if (atris2Mode) {
@@ -783,7 +785,7 @@ async function planAtris(userInput = null) {
     userPrompt += `Your job (execute these steps):\n\n`;
     userPrompt += `STEP 1: Generate ASCII visualizations for user approval\n`;
     userPrompt += `   Create diagrams showing architecture, flows, schemas, UI/UX.\n`;
-    userPrompt += `   SHOW these diagrams and wait for approval before proceeding.\n\n`;
+    userPrompt += `   SHOW these diagrams; use existing approval for this scope, otherwise wait for approval before proceeding.\n\n`;
     userPrompt += `STEP 2: Run the Confidence Gate before writing tasks\n`;
     userPrompt += confidenceGatePrompt('plan') + `\n\n`;
     userPrompt += `STEP 3: Break approved ideas into concrete tasks\n`;
@@ -799,7 +801,7 @@ async function planAtris(userInput = null) {
     userPrompt += `STEP 5: Log to your journal\n`;
     userPrompt += `   - Write to atris/team/navigator/logs/YYYY-MM-DD.md\n`;
     userPrompt += `   - Include: Task, Delivered, User reaction, Pattern\n`;
-    userPrompt += `   - Your journal is how you learn — record what worked\n\n`;
+    userPrompt += `   - Your journal is how you learn, so record what worked\n\n`;
     userPrompt += `Start planning now. Read MAP.md for file references.`;
 
     console.log('');
@@ -866,6 +868,73 @@ async function planAtris(userInput = null) {
   // Prompt mode continues with existing output (already logged above)
 }
 
+// Both executor surfaces require the exact live record before any work.
+// The rendered list omits raw instructions and cannot select the mission.
+function executorDispatchForTask(task) {
+  const metadata = task && task.metadata || {};
+  return {
+    taskId: task && task.id || '',
+    owner: metadata.assigned_to || task && task.claimed_by || metadata.stage_owner || '',
+    goalId: metadata.goal_id || '',
+    missionId: metadata.mission_id || '',
+    objective: metadata.task_goal || metadata.goal_objective || metadata.stage_goal || '',
+    workspaceRoot: task && task.workspace_root || '',
+  };
+}
+
+function validateExecutorDispatch(expected = {}, task) {
+  if (!expected.taskId || !expected.owner || (!expected.goalId && !expected.missionId && !expected.objective)) {
+    return { ok: false, reason: 'missing task, owner, or mission in dispatch' };
+  }
+  const actual = executorDispatchForTask(task);
+  if (!task || ['taskId', 'owner', 'goalId', 'missionId', 'objective', 'workspaceRoot']
+    .some(key => (expected[key] || '') !== (actual[key] || ''))) {
+    return { ok: false, reason: 'task, owner, or mission changed since dispatch' };
+  }
+  if (!['open', 'claimed'].includes(task.status)
+    || (task.status === 'claimed' && task.claimed_by !== expected.owner)) {
+    return { ok: false, reason: 'task is inactive or claimed by another owner' };
+  }
+  return { ok: true };
+}
+
+function executorTaskHandoff({ taskId = '', owner = '', goalId = '', missionId = '', objective = '' } = {}) {
+  const ref = taskId || '<task-id>';
+  const expected = JSON.stringify({ taskId: taskId || null, owner: owner || null, goalId: goalId || null, missionId: missionId || null, objective: objective || null });
+  return `Expected dispatch: ${expected}. Before claiming or editing, run \`atris task show ${ref} --json\` for the exact current dispatched task. If the expected task ID, owner, or mission is missing, stop; no edits are allowed. Do not select another displayed row. Check the ID, current mission, active status (open or claimed by the same owner), and functional owner against these expected values. Refuse a stale or mismatched task. Read the raw metadata, requirements, events, and verify command for exact paths, flags, and engine/model instructions; the explanation and rendered TODO are summaries only. Then claim that same task with \`atris task claim ${ref} --as <task-owner>\`, using its recorded functional owner and keeping the engine separate.`;
+}
+
+// The executor prompt sent to a backend agent in --execute mode. Kept as a
+// pure function so the emitted instructions can be tested without a network:
+// the agent claims and finishes work through the live task plane, and treats
+// atris/TODO.md as a generated view it never hand-edits.
+function executorAgentPrompt({ filteredTasks = '', taskSource = 'atris/TODO.md', context = 'UNKNOWN', taskId = '', owner = '', goalId = '', missionId = '', objective = '' } = {}) {
+  let userPrompt = `⚠️ CRITICAL: Execute tasks NOW. Use file tools to edit code, terminal to run commands.\n\n`;
+  userPrompt += `You are the Executor. Get it done, precisely, following instructions perfectly.\n\n`;
+
+  if (filteredTasks) {
+    userPrompt += `## REFERENCE TASK SUMMARIES (generated view from ${taskSource}; live truth is \`atris task list\`):\n${filteredTasks}\n\n`;
+  } else {
+    userPrompt += `## TASKS TO EXECUTE:\n(No tasks found - run \`atris task list\` for the live task plane)\n\n`;
+  }
+
+  userPrompt += `Your process (EXECUTE these steps):\n`;
+  userPrompt += `1. ${executorTaskHandoff({ taskId, owner, goalId, missionId, objective })}\n`;
+  userPrompt += `2. For this task: Show ASCII visualization first (especially complex changes)\n`;
+  userPrompt += `3. Run the Confidence Gate before editing\n`;
+  userPrompt += confidenceGatePrompt('do') + `\n`;
+  userPrompt += `4. Execute task: Use file edit tools, terminal commands, etc.\n`;
+  userPrompt += `5. Before completion, rerun the gate against proof and residual risk\n`;
+  userPrompt += `6. Send it to review: \`atris task ready <id> --proof "<commands run>"\`; a human accepts. Never hand-edit TODO.md; \`atris task render --out atris/TODO.md\` regenerates it\n`;
+  userPrompt += `7. Log to atris/team/executor/logs/YYYY-MM-DD.md\n`;
+  userPrompt += `   (Task, Delivered, Errors hit, Learned)\n`;
+  userPrompt += `8. Use MAP.md to navigate codebase\n\n`;
+  userPrompt += `DO NOT just describe what you would do - actually edit files and execute commands!\n`;
+  userPrompt += `Context: ${context}\n`;
+  userPrompt += `Start only the dispatched task after the raw-record check.`;
+  return userPrompt;
+}
+
 async function doAtris() {
   const { loadConfig } = require('../utils/config');
   const { loadCredentials, ensureValidCredentials } = require('../utils/auth');
@@ -1044,7 +1113,7 @@ async function doAtris() {
     console.log(`- Executor spec: ${executorPath || 'atris/team/executor/MEMBER.md (missing)'}`);
     console.log(`- Persona: ${personaFileRef || 'atris/PERSONA.md (missing)'}`);
     const mapDisplay = mapPath
-      ? `${mapPath}${mapIsPlaceholder ? ' (placeholder — generate first)' : ''}`
+      ? `${mapPath}${mapIsPlaceholder ? ' (placeholder, generate first)' : ''}`
       : 'atris/MAP.md (missing)';
     console.log(`- MAP: ${mapDisplay}`);
     console.log(`- TODO: ${taskSourcePath || 'atris/TODO.md (missing)'}`);
@@ -1097,17 +1166,17 @@ async function doAtris() {
       console.log('');
     }
     console.log('Workflow:');
-    console.log('1) Read atris/TODO.md — claim next unclaimed Backlog task');
-    console.log('   Move to ## In Progress: add "Claimed by: executor at YYYY-MM-DD HH:MM"');
+    console.log(`1) ${executorTaskHandoff(executorDispatchForTask(firstMinute && firstMinute.task))}`);
+    console.log('   The live task plane is truth; never hand-edit TODO.md to claim or move work');
     console.log('2) Run the Confidence Gate against the task before editing');
     printConfidenceGate('   ');
     console.log('3) Execute step-by-step. Run tests as you go.');
     console.log('4) Before completion, rerun the gate against proof and residual risk');
-    console.log('5) When done, move task to ## Completed');
+    console.log('5) When done, send it to review: `atris task ready <id> --proof "<commands run>"`; a human accepts, then `atris task render --out atris/TODO.md` refreshes the view');
     console.log('6) Log to atris/team/executor/logs/YYYY-MM-DD.md');
     console.log('   (Task, Delivered, Errors hit, Learned)');
     console.log('');
-    console.log('⛔ Do NOT plan — just execute what\'s written.');
+    console.log('⛔ Do NOT plan, just execute what\'s written.');
     console.log('');
 
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
@@ -1146,6 +1215,10 @@ async function doAtris() {
 
   // Check execution mode
   if (executionMode === 'agent') {
+    // Bind edit permission to the selected live task, not its rendered summary.
+    const dispatch = executorDispatchForTask(firstMinute && firstMinute.task);
+    const dispatchCheck = validateExecutorDispatch(dispatch, firstMinute && firstMinute.task);
+    if (!dispatchCheck.ok) throw new Error(`executor dispatch refused: ${dispatchCheck.reason}`);
     // Agent mode: execute via backend API
     if (!config.agent_id) {
       throw new Error('No agent selected. Run "atris agent" first.');
@@ -1175,29 +1248,11 @@ async function doAtris() {
     }
 
     // Build user prompt with context
-    let userPrompt = `⚠️ CRITICAL: Execute tasks NOW. Use file tools to edit code, terminal to run commands.\n\n`;
-    userPrompt += `You are the Executor. Get it done, precisely, following instructions perfectly.\n\n`;
-
-    if (filteredTasks) {
-      userPrompt += `## TASKS TO EXECUTE (from ${taskSource}):\n${filteredTasks}\n\n`;
-    } else {
-      userPrompt += `## TASKS TO EXECUTE:\n(No tasks found - check TODO.md)\n\n`;
-    }
-
-    userPrompt += `Your process (EXECUTE these steps):\n`;
-    userPrompt += `1. Read tasks from TODO.md (shown above)\n`;
-    userPrompt += `2. For each task: Show ASCII visualization first (especially complex changes)\n`;
-    userPrompt += `3. Run the Confidence Gate before editing\n`;
-    userPrompt += confidenceGatePrompt('do') + `\n`;
-    userPrompt += `4. Execute task: Use file edit tools, terminal commands, etc.\n`;
-    userPrompt += `5. Before completion, rerun the gate against proof and residual risk\n`;
-    userPrompt += `6. Move task to ## Completed in TODO.md\n`;
-    userPrompt += `7. Log to atris/team/executor/logs/YYYY-MM-DD.md\n`;
-    userPrompt += `   (Task, Delivered, Errors hit, Learned)\n`;
-    userPrompt += `8. Use MAP.md to navigate codebase\n\n`;
-    userPrompt += `DO NOT just describe what you would do - actually edit files and execute commands!\n`;
-    userPrompt += `Context: ${context}\n`;
-    userPrompt += `Start executing tasks now.`;
+    const taskDb = require('../lib/task-db');
+    const liveTask = taskDb.getTask(taskDb.open(), dispatch.taskId);
+    const currentDispatchCheck = validateExecutorDispatch(dispatch, liveTask);
+    if (!currentDispatchCheck.ok) throw new Error(`executor dispatch refused: ${currentDispatchCheck.reason}`);
+    const userPrompt = executorAgentPrompt({ filteredTasks, taskSource, context, ...dispatch });
 
     console.log('');
     console.log('🤖 AGENT MODE: Executing via backend API...');
@@ -1417,13 +1472,13 @@ async function reviewAtris() {
   }
 
   const mapDisplay = mapPath
-    ? `${mapPath}${mapIsPlaceholder ? ' (placeholder — generate first)' : ''}`
+    ? `${mapPath}${mapIsPlaceholder ? ' (placeholder, generate first)' : ''}`
     : 'atris/MAP.md (missing)';
 
   if (showFull) {
     console.log('');
     console.log('┌─────────────────────────────────────────────────────────────┐');
-    console.log('│ Atris Review — Validator Agent Activated                    │');
+    console.log('│ Atris Review - Validator Agent Activated                   │');
     console.log('└─────────────────────────────────────────────────────────────┘');
     console.log('');
 
@@ -1594,7 +1649,7 @@ async function reviewAtris() {
     userPrompt += `  • Verify everything works\n`;
     userPrompt += `  • Find all plausible loopholes; patch them or name residual risk\n`;
     userPrompt += `  • Test thoroughly (unless user says no)\n`;
-    userPrompt += `  • Confirm active task state is clean — no unresolved Backlog/In Progress/Blocked rows for reviewed work.\n`;
+    userPrompt += `  • Confirm active task state is clean, with no unresolved Backlog/In Progress/Blocked rows for reviewed work.\n`;
     userPrompt += `    If durable task state changed, regenerate the readable view with \`atris task render --out atris/TODO.md\`.\n`;
     userPrompt += `    Do not hand-delete rendered completed history; if a task fails, move or mark it blocked with a note.\n`;
     userPrompt += `  • Log to atris/team/validator/logs/YYYY-MM-DD.md\n`;
@@ -1718,7 +1773,7 @@ async function reviewAtris() {
         if (fs.existsSync(logFile)) {
           let journalContent = fs.readFileSync(logFile, 'utf8');
           const timestamp = new Date().toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false });
-          const learning = `- ${timestamp} — ${answer.trim()}`;
+          const learning = `- ${timestamp} \u2014 ${answer.trim()}`;
 
           // Find or create ## Notes section
           if (journalContent.includes('## Notes')) {
@@ -1732,17 +1787,12 @@ async function reviewAtris() {
           console.log(`✓ Logged to journal: ${learning}`);
         }
 
-        // Also log to structured learnings (if learnings module exists)
         try {
-          const { addLearning } = require('../lib/learnings');
-          const insight = answer.trim();
-          // Auto-classify: starts with "don't" or "never" or "avoid" → pitfall, else pattern
-          const type = /^(don't|never|avoid|watch out|careful)/i.test(insight) ? 'pitfall' : 'pattern';
-          const key = insight.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).slice(0, 4).join('-');
-          addLearning({ type, key, insight, confidence: 7, source: 'review', files: [] });
-          console.log(`✓ Saved to learnings: [7/10] ${type}/${key}`);
+          commitReviewLearning(answer.trim(), {
+            cwd: process.cwd(),
+          });
         } catch {
-          // learnings module not available — skip silently
+          // learnings module not available, so skip silently
         }
       }
 
@@ -1844,6 +1894,9 @@ module.exports = {
   doAtris,
   reviewAtris,
   renderReviewMinute,
+  executorAgentPrompt,
+  executorDispatchForTask,
+  validateExecutorDispatch,
   executeAgentSDKFast,
   makeCloudExecutor,
   postToolResult

package/commands/worktree.js

@@ -939,7 +939,7 @@ function guard(args) {
     return 2;
   }
   // Conductor plumbing (worktree metadata, the fleet prompt written for this very
-  // engine, runtime scratch, the brief ledger) must not count as dirt — otherwise the
+  // engine, runtime scratch, the brief ledger) must not count as dirt, otherwise the
   // harness blocks the engine with the harness's own files.
   const counts = statusCounts(root, { ignoreUntracked: isConductorArtifact });
   if (counts && (counts.staged || counts.unstaged || counts.untracked) && !hasFlag(args, '--allow-dirty')) {

package/commands/write.js

@@ -1,14 +1,14 @@
-// atris write — guided writing sessions (plan-do-review for prose).
+// atris write: guided writing sessions (plan-do-review for prose).
 //
 // The contract: the human types every word of the draft. Atris structures the
 // session (outline beats with states), tracks progress against the plan, and
 // reviews against the taste gate (writing policy + slop detector). It NEVER
-// writes or rewrites prose — review output is suggestions, not edits.
+// writes or rewrites prose. Review output is suggestions, not edits.
 //
 // Session = a folder of plain markdown, so the same files open in the web and
 // desktop editors with no extra format:
 //   atris/writing/<slug>/plan.md    outline beats: [ ] empty, [~] drafted, [x] passed
-//   atris/writing/<slug>/draft.md   the piece — human-only territory
+//   atris/writing/<slug>/draft.md   the piece, human-only territory
 //
 // Usage:
 //   atris write start "<topic>" [--dump "raw ideas"] [--beats "a | b | c"]
@@ -17,7 +17,7 @@
 //   atris write pass <n> [slug]   mark beat n passed (human calls it, not the AI)
 //   atris write list              list sessions
 //
-// Zero external deps (Node built-ins only) — repo contract.
+// Zero external deps (Node built-ins only). Repo contract.
 
 const fs = require('fs');
 const path = require('path');
@@ -212,7 +212,7 @@ function review(argv, root = process.cwd()) {
     console.log(`  ⚠ ${empty.length} beat${empty.length === 1 ? '' : 's'} still empty: ${empty.map((b) => b.title).join(', ')}`);
   }
   if (findings.length) {
-    console.log(`\n  slop tells (fix them yourself — atris never edits your draft):`);
+    console.log(`\n  slop tells (fix them yourself, atris never edits your draft):`);
     for (const f of findings) console.log(`  ✗ draft.md:${f.line}  ${f.rule.padEnd(16)} ${f.why}`);
   } else {
     console.log(`  ✓ slop scan clean`);
@@ -235,7 +235,7 @@ function pass(argv, root = process.cwd()) {
   const beat = plan.beats.find((b) => b.n === n);
   if (!beat) { console.error(`  no beat ${n} in ${slug}`); return 2; }
   const counts = draftWordCounts(slug, plan.beats, root);
-  if ((counts.get(n) || 0) === 0) { console.error(`  beat ${n} "${beat.title}" has no words yet — write it first`); return 2; }
+  if ((counts.get(n) || 0) === 0) { console.error(`  beat ${n} "${beat.title}" has no words yet, write it first`); return 2; }
   beat.state = 'x';
   writePlanStates(slug, plan.beats, root);
   console.log(`  ● passed: ${n}. ${beat.title}`);
@@ -370,17 +370,17 @@ function coach(argv, root = process.cwd()) {
 
 function help() {
   console.log(`
-  atris write — guided writing sessions (you write every word; atris structures + reviews)
+  atris write: guided writing sessions (you write every word; atris structures + reviews)
 
     atris write                   the coach: knows where you are, gets you going
     atris write start "<topic>" [--dump "..."] [--beats "a | b | c"]
     atris write coach [slug]      the coach: cheers your best line, asks the next question (--offline for no-LLM)
     atris write status [slug]     progress against the outline (beats landed)
     atris write review [slug]     taste gate: slop scan + writing-policy passes (read-only)
-    atris write pass <n> [slug]   mark beat n passed — the human calls it
+    atris write pass <n> [slug]   mark beat n passed, the human calls it
     atris write list              all sessions
 
-  sessions are plain markdown in atris/writing/<slug>/ — the same files open
+  sessions are plain markdown in atris/writing/<slug>/, the same files open
   in the web and desktop editors. atris never writes or edits your draft.
 `);
   return 0;

package/commands/x-search.js

@@ -11,6 +11,8 @@ const {
   extractTeachMechanisms,
   isThinTeachLesson,
   TEACH_THIN_REFUSE,
+  printLearnerCheckGate,
+  proveSavedLearnerBaseline,
 } = require('./youtube');
 
 const DEFAULT_TIMEOUT_MS = 120000;
@@ -27,10 +29,10 @@ function showXSearchHelp(output = console.log, commandName = 'atris x-search') {
   output('');
   output(`Search X/Twitter via Atris (${COST_HINT}).`);
   output('Requires login. Same auth path as atris youtube process.');
-  output('Prints to stdout. Rich ephemeral prints one apply next-step (no files).');
+  output('Prints to stdout. Rich ephemeral prints one apply next-step, then hands off to atris youtube search (no files).');
   output('--save files a brief only when the result is rich.');
   output('unsave deletes the filed brief, apply stub, and matching experiment pack (no paid calls).');
-  output('Empty or failed search refunds the credits.');
+  output('Empty or failed search prints credits refunded only when the server marks a refund.');
   output('');
   output('Options:');
   output('  --limit <n>         Max results hint (search only)');
@@ -221,7 +223,9 @@ function parseUnsaveArgs(argv = []) {
   const options = {
     mode: 'unsave',
     help: false,
+    json: false,
     source: null,
+    sources: [],
   };
 
   if (args.length === 0 || ['help', '--help', '-h'].includes(args[0])) {
@@ -236,19 +240,20 @@ function parseUnsaveArgs(argv = []) {
     const arg = args[i];
     if (arg === '--help' || arg === '-h' || arg === 'help') {
       options.help = true;
+    } else if (arg === '--json') {
+      options.json = true;
     } else if (arg === '--unsave') {
       continue;
     } else if (arg.startsWith('-')) {
       throw new Error(`Unknown option: ${arg}`);
-    } else if (!options.source) {
-      options.source = arg;
     } else {
-      throw new Error(`Unexpected argument: ${arg}`);
+      options.sources.push(arg);
+      if (!options.source) options.source = arg;
     }
   }
 
   if (options.help) return options;
-  if (!options.source) throw new Error('usage: atris x-search unsave <query-or-source>');
+  if (!options.sources.length) throw new Error('usage: atris x-search unsave <query-or-source>');
   return options;
 }
 
@@ -322,9 +327,8 @@ function xSearchCredits(data) {
   return { used, remaining, refunded };
 }
 
-function creditsWereRefunded(credits) {
+function creditsRefundedExplicitly(credits) {
   if (!credits) return false;
-  if (credits.used === 0) return true;
   if (credits.refunded === true) return true;
   return typeof credits.refunded === 'number' && credits.refunded > 0;
 }
@@ -334,7 +338,7 @@ function formatCreditsLines(credits) {
   if (credits.used !== undefined || credits.remaining !== undefined) {
     lines.push(`Credits: ${credits.used !== undefined ? credits.used : '?'} used, ${credits.remaining !== undefined ? credits.remaining : '?'} remaining`);
   }
-  if (creditsWereRefunded(credits)) {
+  if (creditsRefundedExplicitly(credits)) {
     lines.push('credits refunded');
   }
   return lines;
@@ -349,7 +353,7 @@ function xSearchFailureError(result) {
         ? ' xAI is unavailable; retry in a few seconds.'
         : '';
   const credits = xSearchCredits(result.data);
-  const refundHint = result.status === 502 && creditsWereRefunded(credits)
+  const refundHint = result.status === 502 && creditsRefundedExplicitly(credits)
     ? ' credits refunded.'
     : '';
   const lines = [`X search failed (${result.status}): ${resultErrorText(result)}.${hint}${refundHint}`];
@@ -387,6 +391,12 @@ async function runXSearch(options, deps = {}) {
       forceMint: true,
     });
     if (remint?.ok && remint.token) {
+      if (!options.json) {
+        const print = typeof deps.output === 'function' ? deps.output : () => {};
+        for (const line of formatCreditsLines(xSearchCredits(result.data))) {
+          print(line);
+        }
+      }
       auth = remint;
       result = await call(auth.token);
     }
@@ -403,6 +413,21 @@ function xSearchApplySource(options) {
   return options?.query;
 }
 
+function quoteYoutubeSearchQuery(source) {
+  return `"${String(source || '').replace(/"/g, '')}"`;
+}
+
+function printYoutubeSearchNext(source, output) {
+  if (!source) return;
+  output(`next: atris youtube search ${quoteYoutubeSearchQuery(source)}`);
+}
+
+const EMPTY_YOUTUBE_SEARCH_NEXT = 'next: atris youtube search " "';
+
+function printEmptyYoutubeSearchNext(output) {
+  output(EMPTY_YOUTUBE_SEARCH_NEXT);
+}
+
 function xSearchApplyRel(source) {
   return applyGate.applySidecarRel('x-search', applyGate.applySlug(source));
 }
@@ -509,10 +534,34 @@ function unsaveXSearch(target, deps = {}) {
   return 0;
 }
 
+function unsaveTargets(options) {
+  if (Array.isArray(options?.sources) && options.sources.length) return options.sources;
+  const single = options?.source || options?.query;
+  return single ? [single] : [];
+}
+
+function runXSearchUnsave(options, deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const targets = unsaveTargets(options);
+  if (!targets.length) {
+    output('usage: atris x-search unsave <query-or-source>');
+    return 2;
+  }
+  let code = 0;
+  for (const target of targets) {
+    const status = unsaveXSearch(target, deps);
+    if (status !== 0) code = status;
+  }
+  if (code === 0 && options.json !== true && deps.json !== true) {
+    printEmptyYoutubeSearchNext(output);
+  }
+  return code;
+}
+
 function saveRichXSearch({ cwd, source, text, now } = {}) {
   const lesson = xSearchLessonFromText(text);
   if (isThinTeachLesson(lesson)) {
-    return { thin: true, brief: null, packRel: null };
+    return { thin: true, brief: null, packRel: null, lesson };
   }
   const brief = fileXSearchBrief({ cwd, source, text, now });
   const packRel = fileTeachExperiment({
@@ -521,19 +570,20 @@ function saveRichXSearch({ cwd, source, text, now } = {}) {
     slug: source ? xSearchExperimentSlug(source) : null,
     applyRel: source ? xSearchApplyRel(source) : null,
   });
-  return { thin: false, brief, packRel };
+  return { thin: false, brief, packRel, lesson };
 }
 
 function ensureXSearchApply({ cwd, source, packRel, now, output } = {}) {
   const pack = packRel || (source ? xSearchExperimentRel(source) : null);
+  const slug = pack ? path.basename(pack) : null;
   return applyGate.ensureApply({
     cwd,
     source,
     rel: source ? xSearchApplyRel(source) : null,
     now,
     output,
-    incompleteMessage: pack
-      ? `next: apply ${pack}. keep only if measure.py moves 0→1`
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
       : APPLY_NEXT_MESSAGE,
     required: false,
     change: pack ? `apply ${pack}` : undefined,
@@ -598,7 +648,7 @@ async function xSearchCommand(argv = process.argv.slice(3), deps = {}) {
   }
 
   if (options.mode === 'unsave' || options.unsave) {
-    return unsaveXSearch(options.source || options.query, deps);
+    return runXSearchUnsave(options, deps);
   }
 
   let status = 0;
@@ -611,11 +661,19 @@ async function xSearchCommand(argv = process.argv.slice(3), deps = {}) {
       output(hasResults ? formatXSearchResult(data) : formatEmptyXSearchResult(data));
     }
     if (!hasResults) {
+      if (
+        !options.json
+        && !options.save
+        && !creditsRefundedExplicitly(xSearchCredits(data))
+      ) {
+        printEmptyYoutubeSearchNext(output);
+      }
       status = 2;
     } else if (options.save) {
       const source = xSearchApplySource(options);
+      const cwd = deps.cwd || process.cwd();
       const saved = saveRichXSearch({
-        cwd: deps.cwd || process.cwd(),
+        cwd,
         source,
         text: xSearchContent(data),
         now: deps.applyNow || deps.now,
@@ -625,21 +683,34 @@ async function xSearchCommand(argv = process.argv.slice(3), deps = {}) {
         status = 2;
       } else {
         const ensureApply = deps.ensureApply || ensureXSearchApply;
-        status = ensureApply({
-          cwd: deps.cwd || process.cwd(),
+        const applyCode = ensureApply({
+          cwd,
           source,
           packRel: saved.packRel,
           now: deps.applyNow || deps.now,
           output,
         });
+        if (deps.ensureApply) {
+          status = applyCode;
+        } else {
+          const baseline = proveSavedLearnerBaseline({
+            cwd,
+            applyRel: source ? xSearchApplyRel(source) : null,
+            lesson: saved.lesson,
+            output,
+            json: options.json === true,
+          });
+          status = baseline !== 0 ? baseline : applyCode;
+        }
       }
     } else {
-      if (
-        !options.json
-        && !isThinTeachLesson(xSearchLessonFromText(xSearchContent(data)))
-      ) {
+      const lesson = xSearchLessonFromText(xSearchContent(data));
+      const json = options.json === true;
+      if (!json && !isThinTeachLesson(lesson)) {
         applyGate.hintEphemeralApply(output, 'x-search');
       }
+      printLearnerCheckGate(output, lesson, { includeCheck: true, json });
+      if (!json) printYoutubeSearchNext(xSearchApplySource(options), output);
       status = 0;
     }
   } catch (err) {

package/commands/xp.js

@@ -6,6 +6,7 @@ const path = require('path');
 const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 const { hasFlag: hasExactFlag } = require('../lib/arg-parser');
+const { treeHashFor } = require('../lib/tree-hash');
 
 const DEFAULT_GRAPH_DAYS = 365;
 const MAX_SYNC_GRAPH_DAYS = 370;
@@ -22,7 +23,7 @@ const CODEX_STATE_FILE = path.join(os.homedir(), '.codex', 'state_5.sqlite');
 
 // Default single-workspace XP root. Local XP reads task_episodes.jsonl (written
 // by task-db at the resolved workspace root) and writes its projection beside
-// it, so the `--workspace` default must resolve the same shared root — otherwise
+// it, so the `--workspace` default must resolve the same shared root, otherwise
 // `xp --local` from a subdir (e.g. backend/) read the wrong/empty episodes and
 // split the projection into a nested .atris. Explicit --workspace still wins;
 // the multi-root roster path (discoverCareerXpWorkspaces) is untouched. Falls
@@ -908,7 +909,7 @@ function readTaskEpisodeTail(episodePath, cursorPath, options = {}) {
   }
 }
 
-function receiptFromTaskEpisode(episode) {
+function receiptFromTaskEpisode(episode, treeHash) {
   const episodeId = episode?.episode_id;
   const label = episode?.rl?.label;
   const rejected = label === 'rework_requested' || label === 'rejected';
@@ -924,6 +925,7 @@ function receiptFromTaskEpisode(episode) {
 
   return {
     schema: 'atris.career_xp_receipt.v1',
+    tree_hash: treeHash,
     receipt_id: `task_review:${episodeId}${rejected ? ':rejected' : ''}`,
     source: 'atris-cli',
     source_type: 'task_review',
@@ -1071,10 +1073,11 @@ function collectLocalXpProjectionState(args = [], { write = true } = {}) {
     && fileSize(episodePath) > 0
     && fileSize(receiptsPath) === 0;
   const tail = readTaskEpisodeTail(episodePath, cursorPath, { forceReset: replayFromStart });
+  const treeHash = write && tail.episodes.length ? treeHashFor(workspace) : null;
   const seen = new Set(existingChain.receipts.map(receipt => receipt.receipt_id).filter(Boolean));
   let previousHash = existingChain.integrity.head_hash || null;
   const newReceipts = tail.episodes
-    .map(receiptFromTaskEpisode)
+    .map((episode) => receiptFromTaskEpisode(episode, treeHash))
     .filter(Boolean)
     .filter((receipt) => {
       if (seen.has(receipt.receipt_id)) return false;