atris 3.68.1 → 3.68.2

package/bin/atris.js

@@ -6,6 +6,17 @@ process.on('unhandledRejection', (err) => {
   process.exit(1);
 });
 
+// node:sqlite (task state) ships unflagged in Node 22.13. On older Node the
+// first require crashes with ERR_UNKNOWN_BUILTIN_MODULE before any help prints.
+{
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 13)) {
+    console.error(`atris needs Node 22.13 or newer. this is Node ${process.versions.node}.`);
+    console.error('upgrade from https://nodejs.org, then run atris again.');
+    process.exit(1);
+  }
+}
+
 const fs = require('fs');
 const path = require('path');
 const { exec, spawnSync } = require('child_process');
@@ -67,9 +78,14 @@ const {
   isBareAtrisFlag,
   isFirstTalkLine,
   isLeftoverVerbLook,
+  isWhatsNextLine,
   listUserVisibleWork,
+  loadLocalTasks,
   personName,
   renderFirstTalk,
+  renderWhatsNextAsk,
+  firstTalkBuilder,
+  shippedHumanStarter,
   shouldAutoInitFresh,
 } = require('../lib/first-minute');
 
@@ -501,6 +517,7 @@ function showHelpShort() {
   console.log('  atris later "..."                remember without a room');
   console.log('  atris guide "..."                translate your words');
   console.log('  atris do                         work already here');
+  console.log('  atris done                       land what your agent built');
   console.log('  atris spaceship                  Keep working for a few hours');
   console.log('  atris autopilot                  Keep working until you stop');
   console.log('  atris mission                    the one goal');
@@ -512,6 +529,7 @@ function helpCatalog() {
   return [
     { name: 'init', summary: 'scaffold atris/ in this project', json: false, interactive_risk: 'medium' },
     { name: 'guide', summary: 'translate plain english into the right atris move', json: true, interactive_risk: 'none' },
+    { name: 'done', summary: 'land what your coding agent built: check, accept, sign', json: true, interactive_risk: 'low' },
     { name: 'task', summary: 'local task plane: new, claim, ready, accept', json: true, interactive_risk: 'low' },
     { name: 'review', summary: 'validate work and capture learnings', json: false, interactive_risk: 'low' },
     { name: 'recap', summary: 'spoken recap of what your team did', json: true, interactive_risk: 'low' },
@@ -532,6 +550,7 @@ function showHelpAll() {
   console.log('  atris later "..."                remember without a room');
   console.log('  atris guide "..."                translate your words');
   console.log('  atris do                         work already here');
+  console.log('  atris done                       land what your agent built');
   console.log('  atris spaceship                  Keep working for a few hours');
   console.log('  atris autopilot                  Keep working until you stop');
   console.log('  atris mission                    the one goal');
@@ -1430,7 +1449,7 @@ async function interactiveEntry(userInput, options = {}) {
       return 0;
     }
     console.log('');
-    console.log(renderFirstTalk({ person: who, folder: room, starter }));
+    console.log(renderFirstTalk({ person: who, folder: room, starter, builder: firstTalkBuilder() }));
     return 0;
   }
 
@@ -1519,6 +1538,23 @@ async function interactiveEntry(userInput, options = {}) {
   // Placeholder or missing MAP is already a first-minute job. Do not send the
   // operator to a rewrite lobby, and do not treat `test` as a new first task.
   if (mapStatus !== 'ready') {
+    // A person who already shipped their first want here can say the next one.
+    // It becomes their new task, the same way the first one did.
+    const nextWant = String(userInput || '').trim();
+    const shipped = nextWant && !options.asJson ? shippedHumanStarter(loadLocalTasks(workspaceDir)) : null;
+    if (shipped && !isLeftoverVerbLook(nextWant) && !isFlagLikeAnswer(nextWant) && !isAtrisMetaQuestion(nextWant)) {
+      const who = personName();
+      const room = folderName(workspaceDir);
+      console.log('');
+      if (isWhatsNextLine(nextWant) || isFirstTalkLine(nextWant)) {
+        console.log(renderWhatsNextAsk({ person: who, task: shipped, folder: room }));
+        return 0;
+      }
+      saveContextProfile(workspaceDir, nextWant, { source: 'next_talk' });
+      const starter = createStarterTask(workspaceDir, nextWant);
+      console.log(renderFirstTalk({ person: who, folder: room, starter, builder: firstTalkBuilder() }));
+      return 0;
+    }
     const screenOptions = {
       root: workspaceDir,
       context,
@@ -2229,6 +2265,9 @@ if (command === 'guide') {
 } else if (command === 'later') {
   const laterCode = require('../commands/later').laterAtris(process.argv.slice(3));
   process.exit(Number.isInteger(laterCode) ? laterCode : 0);
+} else if (command === 'done') {
+  const doneCode = require('../commands/done').doneAtris(process.argv.slice(3));
+  process.exit(Number.isInteger(doneCode) ? doneCode : 0);
 } else if (command === 'activate') {
   const args = process.argv.slice(3);
   if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {

package/commands/done.js

@@ -0,0 +1,374 @@
+'use strict';
+
+// `atris done`: the one command a person runs after their coding agent built
+// the thing. It names what was built, lands it through the real task path
+// (`task ready --verify` then `task accept`, same gates agents face), and ends
+// with a short credits roll and the file to open.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { argsWantHelp } = require('../lib/noninteractive');
+const {
+  buildFirstMinute,
+  firstTalkBuildCommand,
+  firstTalkBuilder,
+  folderName,
+  humanStarterTask,
+  isFreshWorkspace,
+  listBuiltSince,
+  loadLocalTasks,
+  mainBuiltFile,
+  orderBuilt,
+  personName,
+  speakFirstMinute,
+  spokenBuiltList,
+  taskStartedAt,
+} = require('../lib/first-minute');
+
+const ATRIS_BIN = path.join(__dirname, '..', 'bin', 'atris.js');
+const DONE_SCHEMA = 'atris.one_lap.v1';
+
+// What a page has, in plain words, for the first tag found.
+const HTML_MARKS = [
+  ['<form', 'the form'],
+  ['<h1', 'the heading'],
+  ['<title', 'the page title'],
+  ['<main', 'the main section'],
+  ['<body', 'the page body'],
+  ['<html', 'the page'],
+];
+
+function doneUsage() {
+  return 'Usage: atris done [<task>] [--json]';
+}
+
+function shQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function spokenTitle(task) {
+  return String((task && task.title) || 'this').replace(/\s+/g, ' ').trim().replace(/[.,;:!?]+$/g, '');
+}
+
+function readHead(root, file) {
+  try {
+    const buf = fs.readFileSync(path.join(root, file));
+    return buf.subarray(0, 65536);
+  } catch {
+    return null;
+  }
+}
+
+// A check that fails when the built file is gone or no longer holds what was
+// built, so it clears the weak-verifier and empty-folder gates honestly.
+function verifierFor(root, files) {
+  const ordered = orderBuilt(files);
+  for (const file of ordered) {
+    const head = readHead(root, file);
+    if (!head || !head.length || head.includes(0)) continue;
+    const text = head.toString('utf8');
+    if (/\.html?$/i.test(file)) {
+      const lower = text.toLowerCase();
+      const mark = HTML_MARKS.find(([tag]) => lower.includes(tag));
+      if (mark) {
+        return {
+          command: `grep -qi ${shQuote(mark[0])} ${shQuote(file)}`,
+          plain: `${file} has ${mark[1]}`,
+          file,
+        };
+      }
+    }
+    const word = (text.match(/[A-Za-z][A-Za-z0-9_-]{3,}/) || [])[0];
+    if (word) {
+      return {
+        command: `grep -qF ${shQuote(word)} ${shQuote(file)}`,
+        plain: `${file} says "${word}"`,
+        file,
+      };
+    }
+  }
+  const file = ordered.find((name) => {
+    const head = readHead(root, name);
+    return head && head.length;
+  });
+  if (!file) return null;
+  return {
+    command: `grep -qa . ${shQuote(file)}`,
+    plain: `${file} is there and not empty`,
+    file,
+  };
+}
+
+// One sentence the ready gate accepts: what the person can do now and why.
+function resultSentence(task) {
+  const { explainResult } = require('../lib/autoland');
+  const title = spokenTitle(task).replace(/[.!?]/g, '').slice(0, 100).trim();
+  const candidates = [
+    `You can now open ${title} and use it yourself, so it is real instead of only a plan.`,
+    'You can now open what you asked for here and use it yourself, so it is real instead of only a plan.',
+  ];
+  return candidates.find((line) => explainResult(line, { allowCommandMention: true }).ok) || candidates[1];
+}
+
+function openCommand(file) {
+  const target = /^[\w./-]+$/.test(file) ? file : shQuote(file);
+  if (process.platform === 'darwin') return `open ${target}`;
+  if (process.platform === 'win32') return `start ${target}`;
+  return `xdg-open ${target}`;
+}
+
+function buildCommandFor(task, builder) {
+  const pick = builder !== undefined ? builder : firstTalkBuilder();
+  // Test runners skip the machine probe; name the default builder so the line stays runnable.
+  return firstTalkBuildCommand(pick === undefined ? 'claude' : pick, spokenTitle(task));
+}
+
+function taskRefOf(task) {
+  return String((task && (task.display_id || task.legacy_ref || task.id)) || '').trim();
+}
+
+function findTask(tasks, ref) {
+  const want = String(ref || '').trim().toLowerCase();
+  if (!want) return null;
+  return tasks.find((task) => [task.display_id, task.legacy_ref, task.id]
+    .some((value) => value && String(value).toLowerCase() === want))
+    || tasks.find((task) => task.id && String(task.id).toLowerCase().startsWith(want))
+    || null;
+}
+
+function pickTask(tasks, person) {
+  const starter = humanStarterTask(tasks, person);
+  if (starter) return starter;
+  const who = String(person || '').trim();
+  const mine = tasks
+    .filter((task) => (task.status === 'claimed' || task.status === 'review')
+      && (!who || String(task.claimed_by || '') === who))
+    .sort((a, b) => Number(b.updated_at || 0) - Number(a.updated_at || 0));
+  return mine[0] || null;
+}
+
+function runAtris(root, args) {
+  const result = spawnSync(process.execPath, [ATRIS_BIN, ...args], {
+    cwd: root,
+    env: process.env,
+    encoding: 'utf8',
+    timeout: 240000,
+  });
+  let json = null;
+  try {
+    json = JSON.parse(String(result.stdout || '').trim());
+  } catch {
+    json = null;
+  }
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: String(result.stdout || ''),
+    stderr: String(result.stderr || ''),
+    json,
+  };
+}
+
+function failureLine(step) {
+  const text = `${step.stderr}\n${step.stdout}`;
+  if (step.json && (step.json.detail || step.json.reason)) {
+    return String(step.json.detail || step.json.reason).split('\n')[0];
+  }
+  const line = text.split('\n').map((s) => s.trim()).find(Boolean);
+  return line || `exit ${step.status}`;
+}
+
+function liveTask(root, id) {
+  try {
+    const taskDb = require('../lib/task-db');
+    const db = taskDb.open();
+    return taskDb.getTask(db, id);
+  } catch {
+    return null;
+  }
+}
+
+function receiptFromProof(proof) {
+  const match = String(proof || '').match(/Receipt:\s*(\S+\.json)/);
+  return match ? match[1] : '';
+}
+
+// The receipt is the record. Say on it that the person who owned this work
+// accepted it themselves, through `atris done`.
+function stampOwnerAccept(root, receiptPath, { owner, actor }) {
+  if (!receiptPath) return false;
+  const file = path.resolve(root, receiptPath);
+  try {
+    const receipt = JSON.parse(fs.readFileSync(file, 'utf8'));
+    receipt.accepted = {
+      by: actor || owner || null,
+      owner: owner || null,
+      self_accepted: true,
+      via: 'atris done',
+      note: 'the human owner accepted their own work',
+      at: new Date().toISOString(),
+    };
+    fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function renderCredits({ title, built, checked, receipt, next }) {
+  return [
+    '',
+    `  ${title}`,
+    '',
+    `  built     ${spokenBuiltList(built)}`,
+    `  checked   ${checked}, passed`,
+    `  signed    ${receipt || 'the task record'}`,
+    '',
+    `next: ${next}`,
+  ].join('\n');
+}
+
+function emit(asJson, log, payload, text) {
+  if (asJson) log(JSON.stringify(payload, null, 2));
+  else log(text);
+}
+
+function doneAtris(args = process.argv.slice(3), {
+  root = process.cwd(),
+  log = console.log,
+  builder,
+} = {}) {
+  const list = Array.isArray(args) ? args : [];
+  if (argsWantHelp(list)) {
+    log(doneUsage());
+    return 0;
+  }
+  const asJson = list.includes('--json');
+  const ref = list.find((arg) => !String(arg).startsWith('-')) || '';
+
+  if (isFreshWorkspace(root)) {
+    return speakFirstMinute({ root, fresh: true, asJson, log });
+  }
+
+  const person = personName();
+  const tasks = loadLocalTasks(root);
+  const task = ref ? findTask(tasks, ref) : pickTask(tasks, person);
+
+  if (!task) {
+    const minute = buildFirstMinute({ root, builder });
+    const reason = ref ? `nothing here is called ${ref}` : 'nothing of yours is in progress here';
+    // Already shipped: say so, the same way bare atris does.
+    const text = !ref && minute.shipped ? `\n${minute.text}` : `\n${reason}.\n\nnext: ${minute.nextCommand}`;
+    emit(asJson, log, {
+      schema: DONE_SCHEMA,
+      ok: false,
+      status: 'stuck',
+      reason,
+      next_action: minute.nextCommand,
+    }, text);
+    return asJson ? 2 : 0;
+  }
+
+  const title = spokenTitle(task);
+  if (task.status === 'done') {
+    emit(asJson, log, {
+      schema: DONE_SCHEMA,
+      ok: true,
+      status: 'already_done',
+      reason: `${title} is already done`,
+      next_action: buildFirstMinute({ root, builder }).nextCommand,
+    }, `\n${title} is already done.\n\nnext: ${buildFirstMinute({ root, builder }).nextCommand}`);
+    return 0;
+  }
+  if (!['open', 'claimed', 'review'].includes(task.status)) {
+    emit(asJson, log, {
+      schema: DONE_SCHEMA,
+      ok: false,
+      status: 'stuck',
+      reason: `${title} is ${task.status}`,
+      next_action: `atris task show ${taskRefOf(task)}`,
+    }, `\n${title} is ${task.status}.\n\nnext: atris task show ${taskRefOf(task)}`);
+    return asJson ? 2 : 0;
+  }
+
+  const built = orderBuilt(listBuiltSince(root, taskStartedAt(task)));
+  if (!built.length) {
+    const next = buildCommandFor(task, builder);
+    emit(asJson, log, {
+      schema: DONE_SCHEMA,
+      ok: true,
+      status: 'nothing_new',
+      reason: `nothing new here since you started ${title}`,
+      task: { display_id: task.display_id || null, title: task.title },
+      built: [],
+      next_action: next,
+    }, `\nnothing new here since you started ${title}.\n\nnext: ${next}`);
+    return 0;
+  }
+
+  const verify = verifierFor(root, built);
+  const fail = (reason, next) => {
+    emit(asJson, log, {
+      schema: DONE_SCHEMA,
+      ok: false,
+      status: 'stuck',
+      reason,
+      task: { display_id: task.display_id || null, title: task.title },
+      built,
+      next_action: next,
+    }, `\n${title} has new work, but ${reason}.\n\nnext: ${next}`);
+    return 1;
+  };
+  if (!verify) return fail('nothing built has content to check yet', buildCommandFor(task, builder));
+
+  let current = liveTask(root, task.id) || task;
+  if (current.status !== 'review') {
+    const ready = runAtris(root, [
+      'task', 'ready', task.id,
+      '--verify', verify.command,
+      '--result', resultSentence(task),
+      '--json',
+    ]);
+    if (!ready.ok) {
+      return fail(`the check did not pass (${failureLine(ready)})`, `atris task show ${taskRefOf(task)}`);
+    }
+    current = liveTask(root, task.id) || current;
+  }
+  const receipt = receiptFromProof(current && current.metadata && current.metadata.latest_agent_proof);
+
+  const accept = runAtris(root, ['task', 'accept', task.id, '--json']);
+  if (!accept.ok) {
+    const why = failureLine(accept);
+    const waiting = /agent_proof_only|cannot accept/i.test(`${why} ${accept.stderr} ${accept.stdout}`);
+    return fail(
+      waiting ? 'it is checked and waiting on a person to accept it' : `accept did not go through (${why})`,
+      `atris task accept ${taskRefOf(task)}`,
+    );
+  }
+  const actor = (accept.json && accept.json.episode && (accept.json.episode.actor || accept.json.episode.reviewer)) || '';
+  const stamped = stampOwnerAccept(root, receipt, { owner: task.claimed_by || person, actor });
+
+  const main = mainBuiltFile(built);
+  const next = openCommand(main);
+  emit(asJson, log, {
+    schema: DONE_SCHEMA,
+    ok: true,
+    status: 'done',
+    reason: `${title} is done`,
+    task: { display_id: task.display_id || null, title: task.title },
+    built,
+    checked: { command: verify.command, plain: verify.plain, passed: true },
+    receipt: receipt || null,
+    owner_accepted: stamped,
+    next_action: next,
+  }, renderCredits({ title, built, checked: verify.plain, receipt, next }));
+  return 0;
+}
+
+module.exports = {
+  doneAtris,
+  resultSentence,
+  verifierFor,
+  openCommand,
+};

package/commands/workflow.js

@@ -83,7 +83,7 @@ function reviewSoftTitle(title, maxWords = 5) {
 
 function isHumanDeskNext(command) {
   const text = String(command || '');
-  return /^atris do\b/.test(text) || /^atris task (?:claim|show|ready|accept)\b/.test(text);
+  return /^atris do\b/.test(text) || /^atris done\b/.test(text) || /^atris task (?:claim|show|ready|accept)\b/.test(text);
 }
 
 function loadReviewTasks(root = process.cwd()) {

package/lib/falsifier-probe.js

@@ -47,10 +47,16 @@ function probeVerifierCanFail({ command, runner, tmpRoot } = {}) {
   const dir = fs.mkdtempSync(path.join(tmpRoot || os.tmpdir(), 'atris-falsifier-probe-'));
   try {
     const run = runner || spawnSync;
+    // A probe that inherits a test-runner context joins the outer runner as a
+    // child and exits 0 without running anything, so every check would look
+    // like it cannot fail. Same strip as verifyCommandEnv.
+    const env = { ...process.env };
+    delete env.NODE_TEST_CONTEXT;
     const result = run('bash', ['-lc', cmd], {
       cwd: dir,
       encoding: 'utf8',
       timeout: PROBE_TIMEOUT_MS,
+      env,
     });
     if (result.error) {
       const timedOut = /ETIMEDOUT/i.test(String(result.error.code || result.error.message || ''));

package/lib/first-minute.js

@@ -272,6 +272,25 @@ function taskNextCommand(tasks, person) {
   return picked.command;
 }
 
+// A person's first talk mints an onboarding task in their own words. That task
+// is the human's thing; the init seed ("Generate MAP.md, ...") is agent setup.
+function isHumanStarter(task) {
+  const metadata = (task && task.metadata) || {};
+  return Boolean(task) && (metadata.source === 'context_gatherer' || task.tag === 'onboarding');
+}
+
+function isInitSeedTask(task) {
+  return Boolean(task && task.metadata && task.metadata.source === 'init_seed');
+}
+
+// In a room a person started by talking, the open init seed is not their next
+// step. Agents still find it on the task plane; the human screens skip it.
+function withoutSeedForHumans(tasks) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  if (!list.some(isHumanStarter)) return list;
+  return list.filter((task) => !(isInitSeedTask(task) && task.status === 'open'));
+}
+
 function pickNext({
   tasks = [],
   missions = [],
@@ -281,6 +300,7 @@ function pickNext({
   inboxCount = 0,
   wipCount = 0,
 } = {}) {
+  tasks = withoutSeedForHumans(tasks);
   const reviews = (Array.isArray(tasks) ? tasks : []).filter((task) => task && task.status === 'review');
   const certified = newest(reviews.filter(isCertifiedReview));
   if (certified) return { task: certified, command: taskCommand(certified, person) };
@@ -361,6 +381,94 @@ function spokenVisibleNames(files) {
   return names.sort((a, b) => a.localeCompare(b));
 }
 
+const BUILT_SKIP_DIRS = new Set(['atris', 'node_modules']);
+const BUILT_MAX_FILES = 500;
+const BUILT_MAX_DEPTH = 6;
+
+function toMs(value) {
+  if (value == null || value === '') return 0;
+  const n = Number(value);
+  if (Number.isFinite(n)) return n;
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function taskStartedAt(task) {
+  return toMs(task && task.claimed_at) || toMs(task && task.created_at);
+}
+
+// Files a person can see that were written after `sinceMs`: what their coding
+// agent built. atris/, .atris/, node_modules, and dotfiles are not the work.
+function listBuiltSince(root = process.cwd(), sinceMs = 0) {
+  const base = path.resolve(root || '.');
+  const since = Number(sinceMs) || 0;
+  const found = [];
+  let seen = 0;
+  const walk = (dir, rel, depth) => {
+    if (depth > BUILT_MAX_DEPTH || seen >= BUILT_MAX_FILES) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (seen >= BUILT_MAX_FILES) return;
+      const name = entry.name;
+      if (!isUserVisibleName(name) || name === LATER_NOTE_FILE) continue;
+      if (depth === 0 && BUILT_SKIP_DIRS.has(name)) continue;
+      if (name === 'node_modules') continue;
+      const full = path.join(dir, name);
+      const relPath = rel ? `${rel}/${name}` : name;
+      if (entry.isDirectory()) {
+        walk(full, relPath, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      seen += 1;
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.mtimeMs >= since) found.push(relPath);
+    }
+  };
+  walk(base, '', 0);
+  return found.sort((a, b) => a.localeCompare(b));
+}
+
+// The thing to open: an index.html (shallowest first), else the first file.
+function mainBuiltFile(files) {
+  const list = Array.isArray(files) ? files : [];
+  const pages = list
+    .filter((file) => /(^|\/)index\.html?$/i.test(file))
+    .sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b));
+  return pages[0] || list[0] || '';
+}
+
+function orderBuilt(files) {
+  const list = Array.isArray(files) ? [...files] : [];
+  const main = mainBuiltFile(list);
+  if (!main) return list;
+  return [main, ...list.filter((file) => file !== main)];
+}
+
+function spokenBuiltList(files, max = 3) {
+  const list = orderBuilt(files);
+  if (list.length <= max) return list.join(', ');
+  return `${list.slice(0, max).join(', ')} and ${list.length - max} more`;
+}
+
+function humanStarterTask(tasks, person = '', { statuses = ['claimed', 'review'] } = {}) {
+  const list = (Array.isArray(tasks) ? tasks : [])
+    .filter((task) => isHumanStarter(task) && statuses.includes(task.status));
+  const who = String(person || '').trim();
+  const mine = who ? list.filter((task) => String(task.claimed_by || '') === who) : [];
+  return newest(mine.length ? mine : list);
+}
+
 function spokenCommitSubject(value) {
   const text = clip(value, 72);
   if (text.endsWith('...')) return text;
@@ -619,13 +727,85 @@ function firstTalkJson({ starter = null, person = '', folder = 'this folder' } =
   };
 }
 
-function renderFirstTalk({ person = '', folder = 'this folder', starter = null } = {}) {
+// First talk only saves the want as a task. Say so, and make the one next step
+// the local coding agent that builds it, so a new person is never told work
+// exists when none does. Test runners get no probe (machine-independent output).
+const FIRST_TALK_BUILDERS = ['claude', 'codex', 'cursor-agent'];
+const FIRST_TALK_INSTALL = 'npm install -g @anthropic-ai/claude-code';
+
+function firstTalkBuilder(probe = (bin) => spawnSync('sh', ['-c', `command -v ${bin}`], { encoding: 'utf8' })) {
+  if (process.env.NODE_TEST_CONTEXT && arguments.length === 0) return undefined;
+  for (const bin of FIRST_TALK_BUILDERS) {
+    const result = probe(bin);
+    if (result && result.status === 0 && String(result.stdout || '').trim()) return bin;
+  }
+  return null;
+}
+
+function firstTalkBuildCommand(builder, want) {
+  if (builder === undefined) return '';
+  if (!builder) return FIRST_TALK_INSTALL;
+  const text = String(want || '').replace(/\s+/g, ' ').trim().replace(/(["\\$`])/g, '\\$1');
+  return `${builder} "${text}"`;
+}
+
+function renderFirstTalk({ person = '', folder = 'this folder', starter = null, builder } = {}) {
   const room = folder || 'this folder';
   const title = spokenStarterTitle(starter && starter.title, room);
+  const build = firstTalkBuildCommand(builder, (starter && starter.title) || title);
   return [
-    `${greet(person)}${title} is ready.`,
+    `${greet(person)}${title} is started. nothing is built yet.`,
     '',
-    `next: ${firstTalkNext({ starter, person, folder: room })}`,
+    `next: ${build || firstTalkNext({ starter, person, folder: room })}`,
+  ].join('\n');
+}
+
+const WHATS_NEXT_COMMAND = 'atris "what\'s next?"';
+
+function isWhatsNextLine(value) {
+  const text = String(value || '')
+    .trim()
+    .replace(/^atris\s+/i, '')
+    .replace(/^["']+|["']+$/g, '')
+    .toLowerCase()
+    .replace(/[?.!]+$/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return /^(what'?s|what is) next$/.test(text) || text === 'what next';
+}
+
+function starterTitle(task, folder = 'this folder') {
+  return spokenStarterTitle(clip(task && task.title, 80), folder);
+}
+
+function renderStarterNewWork({ person = '', task = null, files = [], folder = 'this folder' } = {}) {
+  return [
+    `${greet(person)}${starterTitle(task, folder)} has new work: ${spokenBuiltList(files)}.`,
+    '',
+    'next: atris done',
+  ].join('\n');
+}
+
+// The human's first want is landed and nothing else of theirs is live.
+function shippedHumanStarter(tasks) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  if (list.some((task) => isHumanStarter(task) && isActionableTask(task))) return null;
+  return newest(list.filter((task) => isHumanStarter(task) && task.status === 'done'));
+}
+
+function renderStarterShipped({ person = '', task = null, folder = 'this folder' } = {}) {
+  return [
+    `${greet(person)}you already shipped ${starterTitle(task, folder)}.`,
+    '',
+    `next: ${WHATS_NEXT_COMMAND}`,
+  ].join('\n');
+}
+
+function renderWhatsNextAsk({ person = '', task = null, folder = 'this folder' } = {}) {
+  return [
+    `${greet(person)}${starterTitle(task, folder)} is shipped. say the next thing you want here, in your own words.`,
+    '',
+    'next: atris "<the next thing you want>"',
   ].join('\n');
 }
 
@@ -694,6 +874,7 @@ function buildFirstMinute({
   dirty,
   branch,
   later,
+  builder,
 } = {}) {
   const who = person != null ? person : personName();
   const room = folder != null ? folder : folderName(root);
@@ -718,8 +899,16 @@ function buildFirstMinute({
     };
   }
   const tasks = loadLocalTasks(root);
-  const todoBacklog = titlesFromTodoSection(root, 'Backlog');
-  const todoWip = titlesFromTodoSection(root, 'In Progress');
+  // The rendered TODO.md still lists the init seed; in a person's room it is
+  // not their waiting work either.
+  const seedTitles = tasks.some(isHumanStarter)
+    ? new Set(tasks.filter(isInitSeedTask).map((task) => String(task.title || '').trim().toLowerCase()))
+    : null;
+  const notSeed = (titles) => (titles && seedTitles
+    ? titles.filter((title) => !seedTitles.has(String(title || '').trim().toLowerCase()))
+    : titles);
+  const todoBacklog = notSeed(titlesFromTodoSection(root, 'Backlog'));
+  const todoWip = notSeed(titlesFromTodoSection(root, 'In Progress'));
   const backlogCount = todoBacklog
     ? todoBacklog.length
     : (Array.isArray(context.backlogTasks) ? context.backlogTasks.length : 0);
@@ -749,6 +938,55 @@ function buildFirstMinute({
     wipCount,
     inboxCount,
   });
+  // The person's own first want, claimed: if their coding agent built
+  // something since, the next step is `atris done`. If nothing is built yet,
+  // the next step is the builder, not a task-plane ready line.
+  if (picked.task && picked.task.status === 'claimed' && isHumanStarter(picked.task)) {
+    const built = listBuiltSince(root, taskStartedAt(picked.task));
+    if (built.length) {
+      return {
+        kind: 'workspace',
+        text: renderStarterNewWork({ person: who, task: picked.task, files: built, folder: room }),
+        nextCommand: 'atris done',
+        task: picked.task,
+        recap,
+        starter: true,
+        built,
+      };
+    }
+    const build = firstTalkBuildCommand(
+      builder !== undefined ? builder : firstTalkBuilder(),
+      picked.task.title,
+    );
+    if (build) {
+      return {
+        kind: 'workspace',
+        text: renderWorkspace({
+          person: who,
+          folder: room,
+          task: picked.task,
+          recap,
+          nextCommand: build,
+          liveWork,
+        }),
+        nextCommand: build,
+        task: picked.task,
+        recap,
+        starter: true,
+      };
+    }
+  }
+  const shipped = !picked.task && !picked.mission && !liveWork ? shippedHumanStarter(tasks) : null;
+  if (shipped) {
+    return {
+      kind: 'workspace',
+      text: renderStarterShipped({ person: who, task: shipped, folder: room }),
+      nextCommand: WHATS_NEXT_COMMAND,
+      task: null,
+      recap,
+      shipped,
+    };
+  }
   return {
     kind: 'workspace',
     text: renderWorkspace({
@@ -863,7 +1101,8 @@ function spokenWinReason(text) {
 
 function isKeepWorkingMinute(minute) {
   const next = String((minute && minute.nextCommand) || '');
-  if (next === 'atris do') return true;
+  if (next === 'atris do' || next === 'atris done') return true;
+  if (minute && (minute.starter || minute.shipped)) return true;
   return isClaimedKeepWorkingCommand(next);
 }
 
@@ -913,12 +1152,24 @@ module.exports = {
   isCertifiedReview,
   isFirstTalkLine,
   isFreshWorkspace,
+  isWhatsNextLine,
+  humanStarterTask,
+  listBuiltSince,
+  mainBuiltFile,
+  orderBuilt,
+  shippedHumanStarter,
+  spokenBuiltList,
+  taskStartedAt,
+  loadLocalTasks,
+  firstTalkBuildCommand,
+  renderWhatsNextAsk,
   isLeftoverVerbLook,
   isTaskNextLook,
   listUserVisibleWork,
   personName,
   pickNext,
   renderFirstTalk,
+  firstTalkBuilder,
   renderLaterRemember,
   spokenLaterNote,
   visibleWorkTitle,

package/lib/known-commands.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const knownCommands = ['init', 'guide', 'doctor', 'doc-health', 'install', 'workspace', 'log', 'logs', 'later', 'wish', 'ask', 'approve', 'stop', 'ready', 'check', 'drill', 'dream', 'now', 'goal', 'wtf', 'founder', 'orb', 'radar', 'who', 'stream', 'ctop', 'launchpad', 'status', 'analytics', 'revisions', 'visualize', 'brain', 'brainstorm', 'autopilot', 'run', 'plan', 'do', 'review', 'release',
+const knownCommands = ['init', 'guide', 'doctor', 'doc-health', 'install', 'workspace', 'log', 'logs', 'later', 'done', 'wish', 'ask', 'approve', 'stop', 'ready', 'check', 'drill', 'dream', 'now', 'goal', 'wtf', 'founder', 'orb', 'radar', 'who', 'stream', 'ctop', 'launchpad', 'status', 'analytics', 'revisions', 'visualize', 'brain', 'brainstorm', 'autopilot', 'run', 'plan', 'do', 'review', 'release',
                        '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', 'tree', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'watch', 'cloud', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube', 'x-search',
                        '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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.68.1",
+  "version": "3.68.2",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "main": "bin/atris.js",
   "bin": {
@@ -101,5 +101,8 @@
   "bugs": {
     "url": "https://github.com/atrislabs/atris/issues"
   },
-  "homepage": "https://github.com/atrislabs/atris#readme"
+  "homepage": "https://github.com/atrislabs/atris#readme",
+  "engines": {
+    "node": ">=22.13"
+  }
 }

package/utils/backend-root.js

@@ -24,6 +24,10 @@ function resolveBackendRoot(cwd = process.cwd()) {
 
   const sibling = path.resolve(workspace, '..', 'atrisos-backend');
   if (fs.existsSync(sibling) && fs.statSync(sibling).isDirectory()) return sibling;
+  // Test children inherit NODE_TEST_CONTEXT: do not discover the developer's
+  // backend beside this CLI install unless a test explicitly opts in.
+  const installSibling = process.env.ATRIS_BACKEND_INSTALL_SIBLING;
+  if (installSibling === '0' || (process.env.NODE_TEST_CONTEXT && installSibling !== '1')) return null;
   const installedSibling = path.resolve(__dirname, '..', '..', 'atrisos-backend');
   return fs.existsSync(installedSibling) && fs.statSync(installedSibling).isDirectory() ? installedSibling : null;
 }