atris 3.82.23 → 3.82.25

package/bin/atris.js

@@ -153,7 +153,8 @@ const dryRunRequested = updateArgs.includes('--dry-run');
 const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER || helpRequested || jsonRequested);
 // Local-only commands make no registry call and start no background install.
 // sentinel prints its own one-line notice at the end of the run instead.
-if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update', 'mcp', 'recap', '99', 'sentinel', 'login'].includes(updateCommand)))) {
+// listen is polled by scripts every minute and its stdout is read by them.
+if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update', 'mcp', 'recap', '99', 'sentinel', 'login', 'listen'].includes(updateCommand)))) {
   updateCheckPromise = checkForUpdates()
     .then((updateInfo) => {
       if (updateInfo) {
@@ -722,7 +723,7 @@ function showHelpAll() {
   console.log('  pull       - Pull journals + member data from cloud');
   console.log('  push       - Push workspace files to cloud');
   console.log('  memory     - Your Atris memory for any agent: show, search, remember, notebook; pull/push a laptop copy');
-  console.log('  sync-checkout - fetch and fast-forward a clean current branch');
+  console.log('  sync-checkout - fetch and fast-forward the current branch (--backup saves edits first)');
   console.log('  zen        - make this repo calm and current, keeping everything (--check to only look)');
   console.log('  cloud      - Delete cloud files not present locally (cloud clean --dry-run|--yes)');
   console.log('  live       - Keep a business brain fresh (doctor, pull, watch, push)');
@@ -788,6 +789,7 @@ function showHelpAll() {
   console.log('  hires      - Morning check-in: one line per hire (mail, spend, last run)');
   console.log('  mail       - Your agents\' own inboxes: list, read, send (not Gmail)');
   console.log('  channel    - The team\'s shared channels: read, post, claim, done (atris channel <name>)');
+  console.log('  listen     - A team member\'s inbox: what was sent to it, then mark it handled (atris listen --as <member>)');
   console.log('  design     - Extract a site design system, check brand adherence, search brands');
   console.log('  mcp        - Run the atris MCP server (stdio) for Claude Desktop and Cursor');
   console.log('');
@@ -2586,6 +2588,11 @@ if (command === 'guide') {
   Promise.resolve().then(() => require('../commands/channel').channelCommand(process.argv.slice(3)))
     .then((code) => exitAfterStdoutDrain(typeof code === 'number' ? code : 0))
     .catch((err) => { console.error(String(err.message || err).replace(/\s+/g, ' ')); process.exit(1); });
+} else if (command === 'listen') {
+  // A team member's inbox on the team board. Exits 0 new, 1 nothing new, 2 error.
+  Promise.resolve().then(() => require('../commands/listen').listenCommand(process.argv.slice(3)))
+    .then((code) => exitAfterStdoutDrain(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(String(err.message || err).replace(/\s+/g, ' ')); process.exit(2); });
 } else if (command === 'transactions') {
   Promise.resolve().then(() => require('../commands/transactions').transactionsCommand(process.argv.slice(3)))
     .then((code) => exitAfterStdoutDrain(typeof code === 'number' ? code : 0))

package/commands/autopilot.js

@@ -190,7 +190,7 @@ async function suggestNextTask(cwd, skipped = new Set(), { auto = false, problem
     ? { unhealable: [] }
     : healBrokenMapRefs(cwd, atrisDir, true); // dry-run
   if (unhealable.length > 0 && !skipped.has('fix-map-refs')) {
-    const sample = unhealable.slice(0, 3).map(r => `${r.file}:${r.line}`).join(', ');
+    const sample = unhealable.slice(0, 3).map(r => (r.line == null ? r.file : `${r.file}:${r.line}`)).join(', ');
     suggestions.push({
       task: `Fix ${unhealable.length} broken reference${unhealable.length > 1 ? 's' : ''} in MAP.md`,
       why: `These file:line references point to code that moved or was deleted: ${sample}. MAP.md is the navigation, it needs to be accurate.`,

package/commands/channel.js

@@ -5,12 +5,10 @@
 // the sign-in they already have. Backend: /api/swarlo/{business}/... (the
 // business may be its slug or its id; the server takes both).
 
-const fs = require('fs');
-const path = require('path');
 const { apiRequestJson } = require('../utils/api');
-const { NOT_LOGGED_IN, oneLine } = require('../lib/developer-api');
+const { NOT_LOGGED_IN } = require('../lib/developer-api');
 const { parseArgs, loginToken, relativeTime, clip } = require('../lib/business-target');
-const { stateHome } = require('../lib/state-home');
+const { resolveChannelBusiness, boardWhy, memberName, lookupMember } = require('../lib/team-board');
 
 // Words that are verbs here, so no channel can be called one of them.
 const REPORTS = ['done', 'failed', 'blocked'];
@@ -43,60 +41,6 @@ the team's channels on the hosted Atris server, shared by every agent on every
 computer. uses your existing sign-in (atris login).`);
 }
 
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
-}
-
-function registeredBusinesses(homeDir) {
-  const raw = readJson(path.join(homeDir, '.atris', 'businesses.json'));
-  if (!raw || typeof raw !== 'object') return [];
-  return Object.entries(raw)
-    .filter(([, b]) => b && typeof b === 'object' && b.business_id)
-    .map(([key, b]) => ({ id: String(b.business_id), slug: String(b.slug || key), name: String(b.name || b.slug || key) }));
-}
-
-function boundBusiness(startDir) {
-  let dir = path.resolve(startDir);
-  for (;;) {
-    const parsed = readJson(path.join(dir, '.atris', 'business.json'));
-    if (parsed && parsed.business_id) {
-      const slug = String(parsed.slug || parsed.name || parsed.business_id);
-      return { id: String(parsed.business_id), slug, name: String(parsed.name || slug) };
-    }
-    const up = path.dirname(dir);
-    if (up === dir) return null;
-    dir = up;
-  }
-}
-
-const PICK = 'add --business <slug>, set ATRIS_BUSINESS=<slug>, or run inside a business folder';
-
-// Which business, in order: --business, ATRIS_BUSINESS, the nearest
-// .atris/business.json, then the only one in ~/.atris/businesses.json.
-// A slug is looked up locally; one this computer does not know goes to the
-// server as is. Returns { id, slug, name } or { error }.
-function resolveChannelBusiness(flags = {}, deps = {}) {
-  const env = deps.env || process.env;
-  const known = registeredBusinesses(deps.homeDir || stateHome());
-  const lookup = (value) => known.find((b) => b.slug === value || b.id === value)
-    || { id: value, slug: value, name: value };
-
-  if (Object.prototype.hasOwnProperty.call(flags, 'business')) {
-    const given = typeof flags.business === 'string' ? flags.business.trim() : '';
-    if (!given) return { error: '--business needs a business slug' };
-    return lookup(given);
-  }
-  const fromEnv = String(env.ATRIS_BUSINESS || '').trim();
-  if (fromEnv) return lookup(fromEnv);
-  const bound = boundBusiness(deps.cwd || process.cwd());
-  if (bound) return bound;
-  if (known.length === 1) return known[0];
-  if (!known.length) return { error: `no business picked: ${PICK}.` };
-  const names = known.map((b) => b.slug);
-  const shown = names.length > 8 ? `${names.slice(0, 8).join(', ')}, and ${names.length - 8} more` : names.join(', ');
-  return { error: `more than one business on this computer (${shown}): ${PICK}.` };
-}
-
 function postLine(post, now, width = 400) {
   const who = clip(post.member_name || 'someone', 18);
   const when = relativeTime(post.created_at, now) || '';
@@ -144,14 +88,7 @@ async function channelCommand(args = [], deps = {}) {
   const request = deps.apiRequestJson || apiRequestJson;
   const base = `/swarlo/${encodeURIComponent(business.id)}`;
   const call = (route, options = {}) => request(`${base}${route}`, { method: 'GET', ...options, token });
-  const why = (res) => {
-    if (!res) return 'no answer from the server';
-    const detail = res.data && (res.data.detail || res.data.error);
-    if (res.status === 401) return 'your sign-in was refused. run: atris login';
-    if (res.status === 403) return `you are not on ${business.slug}'s team`;
-    if (res.status === 404 && detail === 'Business not found') return `no business called "${business.slug}"`;
-    return oneLine(detail || res.error || `request failed (${res.status})`);
-  };
+  const why = (res) => boardWhy(res, business);
   const say = (res) => log(JSON.stringify(res.data));
   const channelList = async () => {
     const res = await call('/channels');
@@ -200,14 +137,14 @@ async function channelCommand(args = [], deps = {}) {
   // member that cannot be found stops the write; it never falls back to you.
   const writes = (verb && verb !== 'list') || (name && text);
   const env = deps.env || process.env;
-  const asWho = String((typeof flags.as === 'string' ? flags.as : env.ATRIS_AGENT) || '').trim().replace(/^@/, '').toLowerCase();
+  const asWho = memberName(flags, env);
   let member = null;
   if (writes && asWho) {
-    const res = await request(`/business/${encodeURIComponent(business.id)}/team/${encodeURIComponent(asWho)}`, { method: 'GET', token });
-    if (res && res.status === 404) { err(`no member called "${asWho}" in ${business.slug}, so nothing was sent. check the name, or leave off --as to post as yourself`); return 1; }
-    if (!res || !res.ok) { err(`could not look up member "${asWho}", so nothing was sent: ${why(res)}`); return 1; }
-    if (!res.data || !res.data.agent_id) { err(`member "${asWho}" in ${business.slug} has no agent id, so nothing was sent`); return 1; }
-    member = { id: String(res.data.agent_id), name: String(res.data.name || asWho) };
+    const found = await lookupMember(request, business, asWho, token);
+    if (found.missing) { err(`no member called "${asWho}" in ${business.slug}, so nothing was sent. check the name, or leave off --as to post as yourself`); return 1; }
+    if (found.failed !== undefined) { err(`could not look up member "${asWho}", so nothing was sent: ${why(found.failed)}`); return 1; }
+    if (found.noId) { err(`member "${asWho}" in ${business.slug} has no agent id, so nothing was sent`); return 1; }
+    member = found.member;
   }
   const signed = (body) => (member ? { ...body, agent_id: member.id } : body);
   const byline = member ? ` as ${member.name}` : '';

package/commands/clean.js

@@ -46,8 +46,10 @@ function cleanAtris(options = {}) {
   results.staleTasks = staleTasks;
 
   // 2. Find and HEAL broken MAP.md references
-  const { healed, unhealable, replacements } = healBrokenMapRefs(cwd, atrisDir, options.dryRun);
+  const { healed, unhealable, replacements, checked = 0, skipped = 0 } = healBrokenMapRefs(cwd, atrisDir, options.dryRun);
   results.healedRefs = healed;
+  results.checkedRefs = checked;
+  results.skippedRefs = skipped;
   results.healedRefDetails = replacements;
   results.unhealableRefs = unhealable;
 
@@ -108,9 +110,10 @@ function cleanAtris(options = {}) {
   }
 
   // Healed refs
+  const countText = refCountText(checked, skipped);
   if (healed > 0) {
-    const verb = options.dryRun ? 'Would heal' : 'Healed';
-    console.log(`✓ ${verb} ${healed} MAP.md ${healed === 1 ? 'reference' : 'references'}`);
+    const verb = options.dryRun ? 'would heal' : 'healed';
+    console.log(`✓ ${verb} ${healed} MAP.md ${healed === 1 ? 'reference' : 'references'} (${countText})`);
     (results.healedRefDetails || []).slice(0, 3).forEach(ref => {
       console.log(`   • ${ref.old} -> ${ref.new}${ref.symbol ? ` (${ref.symbol})` : ''}`);
     });
@@ -121,16 +124,18 @@ function cleanAtris(options = {}) {
 
   // Unhealable refs
   if (unhealable.length > 0) {
-    console.log(`⚠ ${unhealable.length} MAP.md ${unhealable.length === 1 ? 'ref' : 'refs'} couldn't be healed:`);
+    console.log(`⚠ ${unhealable.length} MAP.md ${unhealable.length === 1 ? 'ref' : 'refs'} couldn't be healed (${countText}):`);
     unhealable.slice(0, 3).forEach(ref => {
-      console.log(`   • ${ref.file}:${ref.line}: ${ref.reason}`);
+      console.log(`   • ${unhealableLine(ref)}`);
     });
     if (unhealable.length > 3) {
       console.log(`   ... and ${unhealable.length - 3} more`);
     }
     console.log('');
+  } else if (checked === 0) {
+    console.log(`○ ${countText}, nothing to validate`);
   } else if (healed === 0) {
-    console.log('✓ All MAP.md refs valid');
+    console.log(`✓ all MAP.md refs valid (${countText})`);
   }
 
   // Repo-local map scripts
@@ -274,6 +279,8 @@ function cleanResultPayload(results, options = {}, cwd = process.cwd()) {
         items: results.staleTasks,
       },
       map_refs: {
+        checked_count: results.checkedRefs || 0,
+        skipped_count: results.skippedRefs || 0,
         healed_count: results.healedRefs,
         verb: options.dryRun ? 'would_heal' : 'healed',
         items: results.healedRefDetails || [],
@@ -375,14 +382,28 @@ function mapNoteFiles(atrisDir) {
   return files.filter((file) => { try { return fs.statSync(file).isFile(); } catch { return false; } });
 }
 
+function refCountText(checked, skipped) {
+  const noun = checked === 1 ? 'ref' : 'refs';
+  const other = skipped > 0 ? `, skipped ${skipped} ${skipped === 1 ? 'path' : 'paths'} (other projects or git-ignored)` : '';
+  return `checked ${checked} ${noun}${other}`;
+}
+
+function unhealableLine(ref) {
+  // A plain path has no line of its own. Say where in the map it was written.
+  if (ref.plain) return `${ref.file}: ${ref.reason} (${ref.map}:${ref.mapLine})`;
+  return `${ref.file}:${ref.line}: ${ref.reason}`;
+}
+
 function healBrokenMapRefs(cwd, atrisDir, dryRun = false, homeDir = os.homedir()) {
   const mapFile = path.join(atrisDir, 'MAP.md');
-  if (!fs.existsSync(mapFile)) return { healed: 0, unhealable: [] };
+  if (!fs.existsSync(mapFile)) return { healed: 0, unhealable: [], checked: 0, skipped: 0 };
   const result = healMapFileRefs(cwd, mapFile, dryRun, homeDir);
   for (const notesFile of mapNoteFiles(atrisDir)) {
     const notes = healMapFileRefs(cwd, notesFile, dryRun, homeDir);
     const map = path.relative(cwd, notesFile).split(path.sep).join('/');
     result.healed += notes.healed;
+    result.checked += notes.checked;
+    result.skipped += notes.skipped;
     result.unhealable = [...result.unhealable, ...notes.unhealable.map((entry) => ({ ...entry, map }))];
     result.replacements = [...(result.replacements || []), ...notes.replacements.map((entry) => ({ ...entry, map }))];
   }
@@ -394,6 +415,7 @@ function healMapFileRefs(cwd, mapFile, dryRun, homeDir) {
   let mapContent = fs.readFileSync(mapFile, 'utf8');
   const unhealable = [];
   let healed = 0;
+  let checked = 0;
 
   // Match both `file.js:123` and `file.js:123-456` with surrounding context
   // [^\S\n] = horizontal whitespace only (no newlines)
@@ -437,6 +459,7 @@ function healMapFileRefs(cwd, mapFile, dryRun, homeDir) {
     const backtickAfter = match[6] || '';
     const contextPart = match[8] || '';
 
+    checked++;
     const file = readFileCached(filePath);
     if (!file) {
       unhealable.push({ file: filePath, line: startLine, reason: 'File not found' });
@@ -497,6 +520,11 @@ function healMapFileRefs(cwd, mapFile, dryRun, homeDir) {
     }
   }
 
+  // Plain backticked paths with no line number. Report only, never rewrite.
+  const plain = checkPlainMapPaths(cwd, mapFile, mapContent);
+  checked += plain.checked;
+  unhealable.push(...plain.unhealable);
+
   // Apply replacements
   if (!dryRun && replacements.length > 0) {
     for (const r of replacements) {
@@ -505,7 +533,111 @@ function healMapFileRefs(cwd, mapFile, dryRun, homeDir) {
     fs.writeFileSync(mapFile, mapContent);
   }
 
-  return { healed, unhealable, replacements };
+  return { healed, unhealable, replacements, checked, skipped: plain.skipped };
+}
+
+// `folder/file.ext` with a slash and no `:line` suffix. The closing backtick must
+// follow the extension. That keeps `file.js:12` and `file.jsonl` from matching here.
+const PLAIN_PATH_PATTERN = /`((?:\.\.?\/)*[A-Za-z0-9_@.\-]+(?:\/[A-Za-z0-9_@.\-]+)+\.(?:js|ts|py|go|rs|rb|java|c|cpp|h|hpp|md|json|yaml|yml))`/g;
+
+// A plain path can be written from the project root, the map's own folder, or any
+// folder between them. Each of those is a base the path is resolved against.
+function plainPathBases(root, mapFile) {
+  const bases = [root];
+  let dir = path.dirname(path.resolve(mapFile));
+  while (dir.startsWith(root + path.sep)) {
+    bases.push(dir);
+    dir = path.dirname(dir);
+  }
+  return bases;
+}
+
+function insideRoot(root, target) {
+  return target === root || target.startsWith(root + path.sep);
+}
+
+// Fenced code blocks hold examples, not navigation. Blank their lines, keeping
+// every line number. The plain-path pass then never reads them.
+function maskFencedBlocks(content) {
+  let fence = null;
+  return content.split('\n').map((line) => {
+    const opener = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence) {
+      if (opener && opener[1][0] === fence.char && opener[1].length >= fence.length && opener[2].trim() === '') fence = null;
+      return '';
+    }
+    if (opener && !(opener[1][0] === '`' && opener[2].includes('`'))) {
+      fence = { char: opener[1][0], length: opener[1].length };
+      return '';
+    }
+    return line;
+  }).join('\n');
+}
+
+function isDirectory(target) {
+  try { return fs.statSync(target).isDirectory(); } catch { return false; }
+}
+
+// Runtime files (state folders, logs) are written by the tools and are not in a
+// fresh checkout. Paths the repo's own ignore rules cover are not dead refs.
+function gitIgnoredPaths(cwd, paths) {
+  if (paths.length === 0) return new Set();
+  const out = spawnSync('git', ['check-ignore', '--no-index', '--stdin'], {
+    cwd, input: paths.join('\n'), encoding: 'utf8',
+  });
+  if (out.status !== 0 && out.status !== 1) return new Set();
+  return new Set(String(out.stdout).split('\n').filter(Boolean));
+}
+
+// The first folder of a path, checked in the place it was resolved against. A path
+// that climbs out of its base is judged by its first folder under the project root.
+function firstFolderExists(root, base, target) {
+  let anchor = base;
+  let from = path.relative(base, target);
+  if (from === '..' || from.startsWith('..' + path.sep)) {
+    anchor = root;
+    from = path.relative(root, target);
+  }
+  const parts = from.split(path.sep);
+  return parts.length > 1 && isDirectory(path.join(anchor, parts[0]));
+}
+
+function checkPlainMapPaths(cwd, mapFile, content) {
+  const root = path.resolve(cwd);
+  const map = path.relative(root, path.resolve(mapFile)).split(path.sep).join('/');
+  const bases = plainPathBases(root, mapFile);
+  const scanned = maskFencedBlocks(content);
+  const seen = new Set();
+  const missing = [];
+  let checked = 0;
+  let skipped = 0;
+  const pattern = new RegExp(PLAIN_PATH_PATTERN.source, 'g');
+  let match;
+  while ((match = pattern.exec(scanned)) !== null) {
+    const rel = match[1];
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    // Anything that resolves outside the project belongs to another project.
+    const candidates = bases
+      .map((base) => ({ base, target: path.resolve(base, rel) }))
+      .filter((candidate) => insideRoot(root, candidate.target));
+    if (candidates.some((candidate) => fs.existsSync(candidate.target))) { checked++; continue; }
+    // A path whose first folder is in none of its bases belongs to another project.
+    const here = candidates
+      .filter((candidate) => firstFolderExists(root, candidate.base, candidate.target))
+      .map((candidate) => path.relative(root, candidate.target).split(path.sep).join('/'));
+    if (here.length === 0) { skipped++; continue; }
+    const mapLine = scanned.slice(0, match.index).split('\n').length;
+    missing.push({ rel, mapLine, here });
+  }
+  const ignored = gitIgnoredPaths(root, missing.flatMap((entry) => entry.here));
+  const unhealable = [];
+  for (const { rel, mapLine, here } of missing) {
+    if (here.every((candidate) => ignored.has(candidate))) { skipped++; continue; }
+    checked++;
+    unhealable.push({ file: rel, line: null, mapLine, map, reason: 'missing file', plain: true });
+  }
+  return { checked, skipped, unhealable };
 }
 
 /**
@@ -851,6 +983,7 @@ module.exports = {
   cleanResultPayload,
   findStaleTasks,
   healBrokenMapRefs,
+  unhealableLine,
   findStalePages,
   checkPageStaleness
 };

package/commands/listen.js

@@ -0,0 +1,196 @@
+'use strict';
+
+// atris listen: a team member's inbox on the team board. Shows what was sent
+// to that member (mentions, replies, tasks) that it has not marked handled.
+// Backend: GET /api/swarlo/{business}/inbox and POST .../inbox/ack.
+//
+// Exit codes are for scripts: 0 something new, 1 nothing new, 2 error.
+//   if atris listen --as walsh --json > new.json; then ...; fi
+
+const { apiRequestJson } = require('../utils/api');
+const { NOT_LOGGED_IN, oneLine } = require('../lib/developer-api');
+const { parseArgs, relativeTime, clip } = require('../lib/business-target');
+const { resolveChannelBusiness, boardWhy, memberName, lookupMember } = require('../lib/team-board');
+
+const FLAGS = { switches: ['watch'], values: ['as', 'limit', 'ack'] };
+const NEW = 0;
+const NOTHING = 1;
+const FAILED = 2;
+const WATCH_MS = 30000;
+const SERVER_MAX = 50;
+// Scripts run this every minute: each request gives up after 10 seconds and
+// is never retried, so one run cannot outlast the next.
+const QUICK = { timeoutMs: 10000, retries: 0 };
+const WHOLE = /^[1-9]\d*$/;
+
+// The sign-in token, or { error }. A token from ATRIS_TOKEN or one that is
+// not near expiry is used as is: the inbox request's own 401 is the check,
+// which saves a round trip per run. Anything else (expired, unknown expiry,
+// an agent client) goes through the full check. When that check fails for a
+// reason other than "never signed in", say the real reason.
+async function listenToken(deps, request) {
+  if (deps.token) return { token: deps.token };
+  if (!deps.ensureCredentials) {
+    const auth = require('../utils/auth');
+    const { isAgentClientCredential } = require('../utils/agent-client');
+    const creds = auth.readActiveCredentials();
+    const fresh = creds && creds.token && !isAgentClientCredential(creds)
+      && (creds.source === 'env' || (auth.getTokenExpiryEpochSeconds(creds.token) && !auth.shouldRefreshToken(creds.token)));
+    if (fresh) return { token: creds.token };
+  }
+  const ensure = deps.ensureCredentials
+    || (() => require('../utils/auth').ensureValidCredentials((p, o = {}) => request(p, { ...o, ...QUICK })));
+  let auth;
+  try { auth = await ensure(); } catch (e) { return { error: `could not check your sign-in: ${oneLine((e && e.message) || e)}` }; }
+  if (auth && !auth.error && auth.credentials && auth.credentials.token) return { token: auth.credentials.token };
+  if (!auth || auth.error === 'not_logged_in') return { error: NOT_LOGGED_IN };
+  return { error: `could not check your sign-in: ${oneLine(auth.detail || auth.error)}. if this keeps happening, run: atris login` };
+}
+
+function listenHelp(log = console.log) {
+  log(`usage: atris listen --as <member>                 what was sent to that member, oldest first
+       atris listen --as <member> --ack <number>  mark everything up to that number handled
+       atris listen --as <member> --watch         keep checking every 30 seconds (Ctrl-C to stop)
+
+options:
+  --as <member>       whose inbox (else ATRIS_AGENT)
+  --business <slug>   which business (else ATRIS_BUSINESS, this folder's business, or your only one)
+  --limit <n>         how many to show, 1 to 50 (default 20)
+  --json              the server's reply as is
+
+exits 0 when something is new, 1 when nothing is, 2 on an error, so a script
+can run: if atris listen --as walsh --json > new.json; then ...; fi
+--watch never marks anything handled. uses your existing sign-in (atris login).`);
+}
+
+// Oldest first, whatever order the server sent.
+function bySeq(items) {
+  return items.slice().sort((a, b) => Number(a.seq) - Number(b.seq));
+}
+
+function itemLines(items, now) {
+  const rows = items.map((it) => ({
+    channel: `#${clip(it.channel || '?', 20)}`,
+    who: clip(it.author_name || it.author_id || 'someone', 18),
+    when: relativeTime(it.created_at, now) || '',
+    text: `[${it.reason || 'note'}] ${clip(it.content || '', 200)}`,
+  }));
+  const w = (key) => Math.max(...rows.map((r) => r[key].length));
+  const wc = w('channel'); const ww = w('who'); const wt = w('when');
+  return rows.map((r) => `${r.channel.padEnd(wc)}  ${r.who.padEnd(ww)}  ${r.when.padEnd(wt)}  ${r.text}`);
+}
+
+async function listenCommand(args = [], deps = {}) {
+  let secret = '';
+  const hide = (line) => (secret ? String(line).split(secret).join('[hidden]') : String(line));
+  const log = (line) => (deps.log || console.log)(hide(line));
+  const err = (line) => (deps.err || console.error)(hide(line));
+  const clock = () => (deps.now ? deps.now() : Date.now());
+  const env = deps.env || process.env;
+
+  const { flags, pos, error } = parseArgs(args, FLAGS);
+  if (flags.help || pos[0] === 'help') { listenHelp(log); return 0; }
+  if (error) { err(`${error}. see: atris listen --help`); return FAILED; }
+  if (pos.length) { err(`atris listen takes no other words. to name the member: atris listen --as ${pos[0].replace(/^@/, '')}`); return FAILED; }
+
+  const who = memberName(flags, env);
+  if (!who) { err('say who is listening: atris listen --as <member>'); return FAILED; }
+  const limit = flags.limit == null ? 20 : (WHOLE.test(flags.limit) ? Number(flags.limit) : NaN);
+  if (!(limit >= 1 && limit <= SERVER_MAX)) { err('--limit takes a whole number from 1 to 50'); return FAILED; }
+  const ack = flags.ack == null ? null : (WHOLE.test(flags.ack) ? Number(flags.ack) : NaN);
+  if (ack !== null && !Number.isSafeInteger(ack)) { err(`--ack takes the number shown on the last line, like: atris listen --as ${who} --ack 42`); return FAILED; }
+  if (ack !== null && flags.watch) { err('--ack and --watch do not go together: --watch never marks anything handled'); return FAILED; }
+
+  const business = resolveChannelBusiness(flags, deps);
+  if (business.error) { err(business.error); return FAILED; }
+  const raw = deps.apiRequestJson || apiRequestJson;
+  const request = (p, o = {}) => raw(p, { ...o, ...QUICK });
+  const signIn = await listenToken(deps, raw);
+  if (signIn.error) { err(signIn.error); return FAILED; }
+  const token = signIn.token;
+  secret = token;
+
+  const why = (res) => boardWhy(res, business);
+  const found = await lookupMember(request, business, who, token);
+  if (found.missing) { err(`no member called "${who}" in ${business.slug}, so nothing was checked. check the spelling of the name`); return FAILED; }
+  if (found.failed !== undefined) { err(`could not look up member "${who}": ${why(found.failed)}`); return FAILED; }
+  if (found.noId) { err(`member "${who}" in ${business.slug} has no agent id, so it has no inbox`); return FAILED; }
+  const member = found.member;
+
+  const base = `/swarlo/${encodeURIComponent(business.id)}/inbox`;
+  const inboxWhy = (res) => (res && res.status === 404 && res.data && res.data.detail === 'Not Found'
+    ? 'this server has no inboxes yet; the update may still be rolling out'
+    : why(res));
+  // The same command again, so the hint is copyable as is.
+  const again = `atris listen --as ${who}${Object.prototype.hasOwnProperty.call(flags, 'business') ? ` --business ${business.slug}` : ''}`;
+
+  if (ack !== null) {
+    const res = await request(`${base}/ack`, { method: 'POST', token, body: { agent_id: member.id, seq: ack } });
+    if (!res || !res.ok) { err(`could not mark ${member.name}'s inbox handled: ${inboxWhy(res)}`); return FAILED; }
+    if (flags.json) { log(JSON.stringify(res.data)); return 0; }
+    const upTo = Number(res.data && res.data.read_up_to);
+    if (Number.isFinite(upTo) && upTo > ack) log(`${member.name}'s inbox was already handled up to ${upTo}; nothing changed.`);
+    else log(`marked handled for ${member.name}, up to ${Number.isFinite(upTo) ? upTo : ack}.`);
+    return 0;
+  }
+
+  const fetchInbox = async () => {
+    // --watch asks for the most the server gives, since it never marks
+    // anything handled and would otherwise keep seeing the same oldest few.
+    const n = flags.watch ? SERVER_MAX : limit;
+    const res = await request(`${base}?agent_id=${encodeURIComponent(member.id)}&limit=${n}`, { method: 'GET', token });
+    if (!res || !res.ok) return { failed: inboxWhy(res), res };
+    if (!res.data || !Array.isArray(res.data.items)) return { failed: 'the server answered without an items list' };
+    return { data: res.data, items: bySeq(res.data.items) };
+  };
+
+  if (!flags.watch) {
+    const got = await fetchInbox();
+    if (got.failed) { err(`could not read ${member.name}'s inbox: ${got.failed}`); return FAILED; }
+    if (flags.json) { log(JSON.stringify(got.data)); return got.items.length ? NEW : NOTHING; }
+    if (!got.items.length) { log(`nothing new for ${member.name}.`); return NOTHING; }
+    for (const line of itemLines(got.items, clock())) log(line);
+    if (got.items.length >= limit) log(`showing the oldest ${got.items.length}; more are waiting after these are handled.`);
+    log(`mark handled: ${again} --ack ${got.items[got.items.length - 1].seq}`);
+    return NEW;
+  }
+
+  // --watch: for a person at a terminal. Prints only items it has not shown
+  // yet and never marks anything handled. Errors that retrying cannot fix
+  // (sign-in, access, no such business) stop it; the rest wait for the next round.
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const keepGoing = deps.keepGoing || (() => true);
+  // stderr, so --watch --json leaves nothing but items on stdout.
+  if (!deps.sleep) process.once('SIGINT', () => { (deps.err || console.error)('stopped listening.'); process.exit(0); });
+  if (!flags.json) log(`listening for ${member.name} in ${business.slug}. checks every 30 seconds; Ctrl-C to stop.`);
+  let shown = -Infinity;
+  let first = true;
+  let full = false;
+  for (;;) {
+    const got = await fetchInbox();
+    if (got.failed) {
+      err(`could not read ${member.name}'s inbox: ${got.failed}`);
+      if (got.res && [401, 403, 404].includes(got.res.status)) return FAILED;
+    } else {
+      const fresh = got.items.filter((it) => Number(it.seq) > shown);
+      if (fresh.length) {
+        if (flags.json) for (const it of fresh) log(JSON.stringify(it));
+        else for (const line of itemLines(fresh, clock())) log(line);
+        shown = Math.max(shown, ...fresh.map((it) => Number(it.seq)));
+        if (!flags.json) log(`mark handled: ${again} --ack ${shown}`);
+      } else if (first && !flags.json) {
+        log(`nothing new for ${member.name} yet.`);
+      }
+      // The server gives the oldest 50 unhandled; newer ones stay hidden
+      // until some are marked handled. Say so once, not every round.
+      const nowFull = got.items.length >= SERVER_MAX;
+      if (nowFull && !full) (flags.json ? err : log)(`${SERVER_MAX}+ waiting for ${member.name}; newer ones show after these are marked handled: ${again} --ack ${shown}`);
+      full = nowFull;
+    }
+    first = false;
+    if (!keepGoing()) return 0;
+    await sleep(deps.intervalMs || WATCH_MS);
+  }
+}
+
+module.exports = { listenCommand };

package/commands/sync-checkout.js

@@ -1,5 +1,9 @@
 'use strict';
 
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
 const {
   runGit,
   trackedTreeIsClean,
@@ -10,19 +14,80 @@ function refuse(message) {
   return 1;
 }
 
+function pad(value) {
+  return String(value).padStart(2, '0');
+}
+
+// 2026-11-12-134655, local time, so a backup sorts and reads like a date.
+function backupStamp(date = new Date()) {
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+  ].join('-') + `-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+// Saves the checkout's tracked edits as a patch under ~/.atris/backups/<repo>/.
+// Untracked files are only listed (in a sibling .untracked.txt), never copied.
+// Returns { patchPath, untrackedPath } or null when nothing could be saved.
+function writeBackup(cwd) {
+  const topResult = runGit(['rev-parse', '--show-toplevel'], cwd);
+  const top = topResult.status === 0 ? topResult.stdout.trim() : cwd;
+  const repoName = path.basename(top) || 'checkout';
+
+  const dir = path.join(os.homedir(), '.atris', 'backups', repoName);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const stamp = backupStamp();
+  let patchPath = null;
+  for (let attempt = 0; attempt < 100 && !patchPath; attempt += 1) {
+    const candidate = path.join(dir, `${stamp}${attempt === 0 ? '' : `-${attempt}`}.patch`);
+    if (!fs.existsSync(candidate)) patchPath = candidate;
+  }
+  if (!patchPath) return null;
+
+  // Diff against HEAD so staged and unstaged edits land in one patch. Git
+  // writes the file itself, so the bytes are exact even for odd encodings.
+  const diffResult = runGit(
+    ['diff', 'HEAD', '--binary', '--no-color', '--no-ext-diff', `--output=${patchPath}`],
+    cwd
+  );
+  const written = diffResult.status === 0 && fs.existsSync(patchPath) && fs.statSync(patchPath).size > 0;
+  if (!written) {
+    fs.rmSync(patchPath, { force: true });
+    return null;
+  }
+
+  const untrackedResult = runGit(['ls-files', '--others', '--exclude-standard'], top);
+  const untracked = untrackedResult.status === 0
+    ? untrackedResult.stdout.split('\n').filter(Boolean)
+    : [];
+  let untrackedPath = null;
+  if (untracked.length > 0) {
+    untrackedPath = patchPath.replace(/\.patch$/, '.untracked.txt');
+    fs.writeFileSync(untrackedPath, `${untracked.join('\n')}\n`);
+  }
+
+  return { patchPath, untrackedPath };
+}
+
 function syncCheckoutCommand(args = [], cwd = process.cwd()) {
   if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
-    console.log('usage: atris sync-checkout.');
+    console.log('usage: atris sync-checkout [--backup].');
     return 0;
   }
+  const backup = args.includes('--backup');
 
   const branchResult = runGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);
   if (branchResult.status !== 0) {
     return refuse('this checkout is not on a git branch; sync-checkout refused to touch it.');
   }
 
-  if (!trackedTreeIsClean(cwd)) {
-    return refuse('this checkout has tracked changes; sync-checkout refused to touch it.');
+  const dirty = !trackedTreeIsClean(cwd);
+  if (dirty && !backup) {
+    console.log('this checkout has tracked changes; sync-checkout refused to touch it.');
+    console.log('run: atris sync-checkout --backup   (saves your edits as a patch, then syncs)');
+    return 1;
   }
 
   const upstreamResult = runGit(
@@ -39,6 +104,39 @@ function syncCheckoutCommand(args = [], cwd = process.cwd()) {
     return refuse('this checkout could not sync because git fetch failed.');
   }
 
+  if (dirty) {
+    // Check the sync can succeed before touching anything, so a sync that
+    // was never going to work does not cost anyone their edits.
+    const canFastForward = runGit(['merge-base', '--is-ancestor', 'HEAD', '@{upstream}'], cwd);
+    if (canFastForward.status !== 0) {
+      return refuse('this checkout could not fast-forward; sync-checkout refused to change it.');
+    }
+    const behindResult = runGit(['rev-list', '--count', 'HEAD..@{upstream}'], cwd);
+    if (behindResult.status === 0 && behindResult.stdout.trim() === '0') {
+      console.log(`this checkout is up to date with ${upstream}; your edits were left in place.`);
+      return 0;
+    }
+
+    let saved;
+    try {
+      saved = writeBackup(cwd);
+    } catch (error) {
+      saved = null;
+    }
+    if (!saved) {
+      return refuse('could not save your edits as a patch; sync-checkout refused to touch it.');
+    }
+    const resetResult = runGit(['reset', '--hard', '--quiet', 'HEAD'], cwd);
+    if (resetResult.status !== 0) {
+      return refuse(`could not set your edits aside; they are saved at ${saved.patchPath}`);
+    }
+    console.log(`saved your edits to ${saved.patchPath}`);
+    if (saved.untrackedPath) {
+      console.log(`untracked files were left in place; their names are in ${saved.untrackedPath}`);
+    }
+    console.log(`to restore them: git apply ${saved.patchPath}`);
+  }
+
   const mergeResult = runGit(['merge', '--ff-only', '@{upstream}'], cwd);
   if (mergeResult.status !== 0) {
     return refuse('this checkout could not fast-forward; sync-checkout refused to change it.');

package/commands/task.js

@@ -9000,6 +9000,38 @@ function appendRelabelArchivedJournalReceipt(workspaceRoot, { actor, count, ids
   return logPath;
 }
 
+// --work-root <path>, or ATRIS_WORK_ROOT only when the flag is absent. Nothing named gives
+// undefined. The job then records the main folder's commit as before. A flag that is present
+// but empty is an error, never a quiet fall back to the env var. A relative path resolves
+// from the current folder. The folder must be a real checkout with a commit, because that
+// commit is what the job records.
+function readyWorkRoot(args) {
+  const at = args.indexOf('--work-root');
+  let named;
+  if (at !== -1) {
+    named = String(args[at + 1] === undefined ? '' : args[at + 1]).trim();
+    if (!named) {
+      console.error('work root is empty');
+      process.exit(1);
+    }
+  } else {
+    named = String(process.env.ATRIS_WORK_ROOT || '').trim();
+  }
+  if (!named) return undefined;
+  const resolved = path.resolve(named);
+  let isDir = false;
+  try { isDir = fs.statSync(resolved).isDirectory(); } catch (_) { isDir = false; }
+  if (!isDir) {
+    console.error(`work root not found: ${resolved}`);
+    process.exit(1);
+  }
+  if (!getTaskDb().workspaceHead(resolved)) {
+    console.error(`work root has no git commit: ${resolved}`);
+    process.exit(1);
+  }
+  return resolved;
+}
+
 function cmdReady(args) {
   const pos = positional(args);
   const id = pos[0];
@@ -9007,9 +9039,12 @@ function cmdReady(args) {
   const verifyFlag = flag(args, '--verify');
   const resultFlag = textFlag(args, ['--result']);
   if (!id || (!proofFlag && !verifyFlag && !resultFlag)) {
-    console.log('Usage: atris task ready <id> --proof "..." --result "<sentence>"');
+    console.log('Usage: atris task ready <id> --proof "..." --result "<sentence>" [--work-root <path>] (the copy you built in; ATRIS_WORK_ROOT is the fallback; a relative path resolves from the current folder)');
     process.exit(2);
   }
+  // The copy the builder actually built in. Its commit is the one the job records.
+  // Without it the job records the main folder's commit, as before.
+  const workRoot = readyWorkRoot(args);
   // Two ways to prove: --proof "<note>" (claimed, pattern-checked) or
   // --verify "<command>" which actually RUNS the command and gates ready on exit 0.
   // If --proof names npm test, node --test, or git diff --check, this process
@@ -9041,12 +9076,54 @@ function cmdReady(args) {
     proof = proof.trim() ? `${proof.trim()} ${attested}` : attested;
   }
   const verifyAutoCertifyAllowed = !usedVerify || isAutoCertifyVerifyCommandAllowed(verifyFlag);
+  const landing = landingFlags(args);
+  // What this process can refuse from the flags and the task alone is refused before the verifier
+  // runs. Wording or a name the gate would turn away never costs a test run. The verifier's own
+  // wording, the actor, the task lookup and the landing sentence only need the flags and the task
+  // row. Without --verify nothing slow comes first. The actor, task and landing checks then keep
+  // their place after the proof checks below.
+  let readyTarget = null;
+  const resolveReadyTarget = () => {
+    if (readyTarget) return readyTarget;
+    guardExplicitActor('atris task ready', flag(args, '--as'));
+    const taskDb = getTaskDb();
+    const db = taskDb.open();
+    const taskId = requireTaskId(taskDb, db, id, 'atris task ready');
+    const beforeTask = taskDetail(taskDb, db, taskId);
+    requireExplicitLandingDayOnePm('atris task ready', landing, beforeTask && beforeTask.title);
+    readyTarget = { taskDb, db, taskId, beforeTask };
+    return readyTarget;
+  };
+  // The start of the proof written once the verifier passes. It is built from the flags alone. A
+  // proof that names a command the verifier did not run is refused before the verifier runs. The
+  // command's output and the receipt path follow it. Then the same check runs again on the whole
+  // proof.
+  const verifiedLead = usedVerify
+    ? `[verified] \`${verifyFlag}\` passed (exit 0)${proof.trim() ? `, ${proof.trim()}` : ''}`
+    : '';
+  if (usedVerify) {
+    if (!hasFlag(args, '--no-falsify-check')) {
+      const { classifyVerifier } = require('../lib/verifier-quality');
+      const quality = classifyVerifier(verifyFlag);
+      if (!quality.ok) {
+        console.error(`atris task ready: weak verifier, ${quality.reason}`);
+        console.error(`  command: ${verifyFlag}`);
+        console.error('  allowlisted examples: node --test, npm test, git diff --check, node --check, rg <symbol>');
+        console.error('  or pass --no-falsify-check to accept anyway.');
+        process.exit(1);
+      }
+    }
+    requireRanNamedProofCommand('atris task ready', verifiedLead, usedVerify);
+    resolveReadyTarget();
+  }
   if (usedVerify) {
     // Run the verifier once and write a receipt (pass or fail) so the review
     // gate in lib/receipt-evidence.js can validate the exact path named in
     // the proof, not just trust the prose.
     const { writeTaskReceipt } = require('../lib/task-receipt');
-    const receipt = writeTaskReceipt({ taskId: id, command: verifyFlag, root: process.cwd() });
+    // The check runs in the copy the work was built in. Its receipt still lands under the
+    // folder ready ran from, because that is where a reviewer looks for the path in the proof.
+    const receipt = writeTaskReceipt({ taskId: id, command: verifyFlag, root: workRoot || process.cwd(), receiptRoot: process.cwd() });
     if (!receipt.passed) {
       const detail = receipt.exit != null ? ` (exit ${receipt.exit})` : (receipt.signal ? ` (signal ${receipt.signal})` : '');
       console.error(`atris task ready: verifier failed${detail}: ${verifyFlag}`);
@@ -9060,15 +9137,6 @@ function cmdReady(args) {
     // this codebase fails there, and one that passes anywhere passes there too.
     if (!hasFlag(args, '--no-falsify-check')) {
       const { probeVerifierCanFail } = require('../lib/falsifier-probe');
-      const { classifyVerifier } = require('../lib/verifier-quality');
-      const quality = classifyVerifier(verifyFlag);
-      if (!quality.ok) {
-        console.error(`atris task ready: weak verifier, ${quality.reason}`);
-        console.error(`  command: ${verifyFlag}`);
-        console.error('  allowlisted examples: node --test, npm test, git diff --check, node --check, rg <symbol>');
-        console.error('  or pass --no-falsify-check to accept anyway.');
-        process.exit(1);
-      }
       const probe = probeVerifierCanFail({ command: verifyFlag });
       if (probe.probed && probe.canFail === false) {
         console.error(`atris task ready: this check cannot fail, ${probe.reason}`);
@@ -9078,8 +9146,7 @@ function cmdReady(args) {
       }
       if (!probe.probed && !wantsJson(args)) console.log(`  ${probe.reason}`);
     }
-    const base = proof.trim();
-    proof = `[verified] \`${verifyFlag}\` passed (exit 0)${base ? `, ${base}` : ''}${receipt.output ? `\n${receipt.output}` : ''}\nReceipt: ${receipt.receiptPath}`;
+    proof = `${verifiedLead}${receipt.output ? `\n${receipt.output}` : ''}\nReceipt: ${receipt.receiptPath}`;
     if (!wantsJson(args)) console.log(`✓ verified: \`${verifyFlag}\` exited 0 (receipt ${receipt.receiptPath})`);
   }
   if (!proof) {
@@ -9090,9 +9157,7 @@ function cmdReady(args) {
   requireRanNamedProofCommand('atris task ready', proof, usedVerify);
   const lesson = flag(args, '--lesson') || '';
   const nextTaskInput = normalizeReviewNextTaskInput(typeof flag(args, '--next') === 'string' ? flag(args, '--next') : '');
-  const landing = landingFlags(args);
   const merge = readyMergeFlags(args);
-  guardExplicitActor('atris task ready', flag(args, '--as'));
   const actor = String(flag(args, '--as') || DEFAULT_OWNER);
   // The others who built the work with --as, by name, comma apart: a flight that ran for a member
   // hands in under the member's name and names the engines that ran here. Only a hand-in uses it.
@@ -9109,18 +9174,19 @@ function cmdReady(args) {
     files: textFlag(args, ['--files']),
     commands: textFlag(args, ['--commands', '--command']),
   };
-  const taskDb = getTaskDb();
-  const db = taskDb.open();
-  const taskId = requireTaskId(taskDb, db, id, 'atris task ready');
-  const beforeTask = taskDetail(taskDb, db, taskId);
-  requireExplicitLandingDayOnePm('atris task ready', landing, beforeTask && beforeTask.title);
+  const { taskDb, db, taskId } = resolveReadyTarget();
+  // The verifier may have run for a while. The task is read again after it. Without one, nothing
+  // elapsed and the read from the checks above stands. The landing sentence is checked against the
+  // refreshed title too, since a verifier can rename the task.
+  const beforeTask = usedVerify ? taskDetail(taskDb, db, taskId) : readyTarget.beforeTask;
+  if (usedVerify) requireExplicitLandingDayOnePm('atris task ready', landing, beforeTask && beforeTask.title);
   const missionXpIssue = missionXpEndToEndProofIssue(beforeTask, proof, taskDb.workspaceRoot());
   if (missionXpIssue) {
     failTask('atris task ready', MISSION_XP_END_TO_END_REASON, missionXpIssue);
   }
   const readyPolicyTask = {
     ...beforeTask,
-    workspace_root: process.cwd(),
+    workspace_root: workRoot || process.cwd(),
     metadata: {
       ...(beforeTask && beforeTask.metadata || {}),
       ...(resultFields.files ? { changed_files: resultFields.files } : {}),
@@ -9145,6 +9211,7 @@ function cmdReady(args) {
     merge,
     result: resultSentence,
     builtWith,
+    workRoot,
   });
   if (!result.ready) {
     console.error(`ready failed: ${result.reason}`);
@@ -12235,7 +12302,7 @@ async function run(args) {
   // `task ready --help` is a help request, not a run. Ready mutates
   // review state, so never list or ready just to show usage.
   if (sub === 'ready' && argsWantHelp(raw.slice(1))) {
-    console.log('Usage: atris task ready <id> --proof "..." --result "<sentence>"');
+    console.log('Usage: atris task ready <id> --proof "..." --result "<sentence>" [--work-root <path>] (the copy you built in; ATRIS_WORK_ROOT is the fallback; a relative path resolves from the current folder)');
     return;
   }
   // `task step --help` is a help request, not a run. Step mutates

package/commands/worktree.js

@@ -60,6 +60,7 @@ const {
   repoRoot,
   restoreRegeneratedAdapterChurn,
   runCommand,
+  runShipNets,
   runGit,
   runShipHealthCheck,
   scheduleShippedCopyRemoval,
@@ -186,13 +187,15 @@ function startWorktree(args) {
 }
 
 function shipHelp() {
-  console.log('Usage: atris worktree ship --message "<commit>" --verify "<cmd>" [--merge] [--target <ref>] [--local]');
+  console.log('Usage: atris worktree ship --message "<commit>" --verify "<cmd>" [--merge] [--target <ref>] [--local] [--skip-nets]');
   console.log('');
   console.log('  --target <ref>  override the default landing target (default: branch atris-base, else origin default branch)');
   console.log('  --local         merge into the local primary checkout instead of pushing and opening a PR');
   console.log('  protected-lane tasks (billing, money, deploy, feedback, ...) can be pushed for review without --merge;');
   console.log('  landing one with --merge or --local needs --allow-denied-lane on written order');
   console.log('  --no-map-refresh  skip the automatic refresh of moved map line references');
+  console.log('  --skip-nets     skip the repo hygiene tests that run before --verify (or set ATRIS_SHIP_SKIP_NETS=1)');
+  console.log('  nets run first: repo-hygiene, no-hardcoded-home-paths and map-refs-accurate, for repos that have them; a failure stops the ship before the push');
   console.log('  --keep-copy     keep this build copy; by default it is removed once the work lands or is pushed');
   console.log('  unstaged regenerated adapter files are skipped unless staged first or named in --message');
   console.log('  recommended flight verify: npm run test:fast && node --test <focused files>');
@@ -293,6 +296,9 @@ function shipWorktree(args) {
     refreshMovedMapRefs(root, args);
   }
 
+  const nets = runShipNets(root, { verify, skip: hasFlag(args, '--skip-nets'), dryRun });
+  if (!nets.ok) return 1;
+
   if (verify) {
     const beforeVerify = dryRun ? [] : statusSnapshot(root);
     console.log(`verify: ${verify}`);
@@ -619,6 +625,7 @@ function guide() {
   console.log('4. Ship only from the isolated worktree:');
   console.log('   atris worktree ship --message "<commit>" --verify "<cmd>" --merge [--target <ref>]');
   console.log('   --target <ref> overrides the default landing target (default: branch atris-base, else origin default branch)');
+  console.log('   ship runs the repo hygiene nets first (repo-hygiene, no-hardcoded-home-paths, map-refs-accurate); --skip-nets or ATRIS_SHIP_SKIP_NETS=1 skips them');
   console.log('   recommended verify: npm run test:fast && node --test <focused files>');
   console.log('');
   console.log('5. Cleanup is part of creation, shipping, and the sweep; run it directly any time:');
@@ -645,10 +652,11 @@ function help() {
   console.log('    --force         start even when another recent flight shares a task word');
   console.log('    --former-task   the task\'s older name; a branch left unfinished under it is named, never resumed');
   console.log('    --no-deps       do not clone node_modules from a matching install');
-  console.log('  atris worktree ship --message "<commit>" --verify "<cmd>" [--merge] [--target <ref>] [--local]');
+  console.log('  atris worktree ship --message "<commit>" --verify "<cmd>" [--merge] [--target <ref>] [--local] [--skip-nets]');
   console.log('    --target <ref>  override the default landing target (default: branch atris-base, else origin default branch)');
   console.log('    --local         merge into the local primary checkout instead of pushing and opening a PR');
   console.log('    --no-map-refresh  skip the automatic refresh of moved map line references');
+  console.log('    --skip-nets     skip the repo hygiene tests that run before --verify; they run first by default');
   console.log('    --keep-copy     keep this build copy after it ships');
   console.log('    recommended verify: npm run test:fast && node --test <focused files>');
   console.log('  atris worktree status');

package/lib/known-commands.js

@@ -4,7 +4,7 @@ const knownCommands = ['init', 'guide', 'doctor', 'doc-health', 'install', 'work
                        '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', 'campaign', 'agents', 'probe', 'worktree', 'land', 'caretaker', 'autoland', 'drive', 'aeo', 'slop', 'voice', 'strings', 'write', 'security-review', 'secure', 'sentinel', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'study', 'rainmaker', 'xp', 'play', 'gm', 'game', 'x', 'recap', 'report', 'signup', 'clarity', 'interview', 'meet', 'moves', 'unknowns', 'avail', 'scoreboard', 'growth', 'scorecard', 'rating', 'sync-checkout', 'zen',
-                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'memory', 'balance', 'film', 'usage', 'spend', 'api-key', 'agent-client', 'topup', 'buy', 'transactions', 'hire', 'hires', 'mail', 'channel', 'design', 'mcp', 'gmail', 'google', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
+                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'memory', 'balance', 'film', 'usage', 'spend', 'api-key', 'agent-client', 'topup', 'buy', 'transactions', 'hire', 'hires', 'mail', 'channel', 'listen', 'design', 'mcp', 'gmail', 'google', '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', 'link', 'playbook', 'feed', 'brief', 'social', 'host', 'people', 'follow', 'unfollow', 'friends', 'msg', 'inbox', 'invite', 'join', 'rsi', 'pay', 'trust'];
 
 // Damerau-Levenshtein edit distance between two short strings. Counts an

package/lib/roster-swap.js

@@ -174,11 +174,15 @@ function jobScope(state, key) {
   return state.machine && state.machine.path ? 'machine' : 'project';
 }
 
+// A member belongs to one project, so a member no file names yet goes in that
+// project's own atris/ROSTER.md when it has one; only a project without one
+// falls back to the all-projects roster.
 function teamScope(state, member) {
   for (const scope of reg.ROSTER_LAYERS) {
     const team = state[scope] && Array.isArray(state[scope].team) ? state[scope].team : [];
     if (team.some((line) => line.member === member)) return scope;
   }
+  if (state.project && state.project.format === 'markdown') return 'project';
   return state.machine && state.machine.path ? 'machine' : 'project';
 }
 

package/lib/task-core.js

@@ -125,8 +125,9 @@ atris task - durable local task state (SQLite, gitignored)
   atris task continue-work <id>           Create/reuse a certified Review follow-up task
   atris task say <id> "<message>"         Add context to a task
   atris task chat <id> "<message>" [--goal "..."]  Refine a task chat + working goal
-  atris task ready <id> --proof "..." --result "<sentence>"
+  atris task ready <id> --proof "..." --result "<sentence>" [--work-root <path>]
                                            Agent proof ready; native goal can complete
+                                           --work-root names the copy you built in and the job records that copy's commit; ATRIS_WORK_ROOT is the fallback and a relative path resolves from the current folder
   atris task ready <id> --verify "<cmd>" --result "<sentence>"
                                            Run <cmd>; only ready if it exits 0 (executed proof)
                                            Writes atris/runs/ receipt (pass or fail); that local pass is enough proof

package/lib/task-db.js

@@ -3247,6 +3247,7 @@ function withBusyRetry(fn, attempts = 8) {
 
 module.exports = {
   open,
+  workspaceHead,
   withBusyRetry,
   isBusyError,
   close,

package/lib/task-receipt.js

@@ -54,7 +54,10 @@ function verifyTimeoutMs() {
 // Runs `command` for `taskId`, writes atris/runs/<date>-task-<id>-<time>.json,
 // and returns { ok, passed, receiptPath, exit, signal, output }. `ok` mirrors
 // `passed`, kept as a separate field so callers reading either name work.
-function writeTaskReceipt({ taskId, command, root = process.cwd(), runner } = {}) {
+// The command runs in `root`. The receipt file goes under `receiptRoot`, which
+// is `root` unless the caller built in another copy and wants the receipt left
+// where a reviewer looks for it.
+function writeTaskReceipt({ taskId, command, root = process.cwd(), receiptRoot = root, runner } = {}) {
   const cmd = String(command || '').trim();
   if (!taskId) return { ok: false, passed: false, reason: 'task_id_required' };
   if (!cmd) return { ok: false, passed: false, reason: 'verify_command_required' };
@@ -83,7 +86,7 @@ function writeTaskReceipt({ taskId, command, root = process.cwd(), runner } = {}
     : '';
   const output = tailText(`${result.stdout || ''}${result.stderr || ''}${diagnostic}`);
   const passed = !result.error && result.status === 0;
-  const dir = runsDir(root);
+  const dir = runsDir(receiptRoot);
   fs.mkdirSync(dir, { recursive: true });
   const now = new Date();
   // Local calendar day for the file name; toISOString() is the UTC day,
@@ -91,13 +94,15 @@ function writeTaskReceipt({ taskId, command, root = process.cwd(), runner } = {}
   const date = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
   const safeTime = now.toISOString().replace(/[:.]/g, '-');
   const receiptFile = path.join(dir, `${date}-task-${slugifyTaskId(taskId)}-${safeTime}.json`);
-  const receiptPath = path.relative(root, receiptFile);
+  const receiptPath = path.relative(receiptRoot, receiptFile);
   const receipt = {
     schema: 'atris.task_receipt.v1',
     task_id: String(taskId),
     command: cmd,
     at: now.toISOString(),
     commit: gitCommitHash(root),
+    work_root: path.resolve(root),
+    receipt_root: path.resolve(receiptRoot),
     result: {
       passed,
       exit: result.status,

package/lib/team-board.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// Shared plumbing for the team board on the hosted server (`atris channel`,
+// `atris listen`): which business, the plain reason a request failed, and the
+// member name -> agent id lookup. HTTP client only; routes live in the backend.
+
+const fs = require('fs');
+const path = require('path');
+const { oneLine } = require('./developer-api');
+const { stateHome } = require('./state-home');
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function registeredBusinesses(homeDir) {
+  const raw = readJson(path.join(homeDir, '.atris', 'businesses.json'));
+  if (!raw || typeof raw !== 'object') return [];
+  return Object.entries(raw)
+    .filter(([, b]) => b && typeof b === 'object' && b.business_id)
+    .map(([key, b]) => ({ id: String(b.business_id), slug: String(b.slug || key), name: String(b.name || b.slug || key) }));
+}
+
+function boundBusiness(startDir) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    const parsed = readJson(path.join(dir, '.atris', 'business.json'));
+    if (parsed && parsed.business_id) {
+      const slug = String(parsed.slug || parsed.name || parsed.business_id);
+      return { id: String(parsed.business_id), slug, name: String(parsed.name || slug) };
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+const PICK = 'add --business <slug>, set ATRIS_BUSINESS=<slug>, or run inside a business folder';
+
+// Which business, in order: --business, ATRIS_BUSINESS, the nearest
+// .atris/business.json, then the only one in ~/.atris/businesses.json.
+// A slug is looked up locally; one this computer does not know goes to the
+// server as is. Returns { id, slug, name } or { error }.
+function resolveChannelBusiness(flags = {}, deps = {}) {
+  const env = deps.env || process.env;
+  const known = registeredBusinesses(deps.homeDir || stateHome());
+  const lookup = (value) => known.find((b) => b.slug === value || b.id === value)
+    || { id: value, slug: value, name: value };
+
+  if (Object.prototype.hasOwnProperty.call(flags, 'business')) {
+    const given = typeof flags.business === 'string' ? flags.business.trim() : '';
+    if (!given) return { error: '--business needs a business slug' };
+    return lookup(given);
+  }
+  const fromEnv = String(env.ATRIS_BUSINESS || '').trim();
+  if (fromEnv) return lookup(fromEnv);
+  const bound = boundBusiness(deps.cwd || process.cwd());
+  if (bound) return bound;
+  if (known.length === 1) return known[0];
+  if (!known.length) return { error: `no business picked: ${PICK}.` };
+  const names = known.map((b) => b.slug);
+  const shown = names.length > 8 ? `${names.slice(0, 8).join(', ')}, and ${names.length - 8} more` : names.join(', ');
+  return { error: `more than one business on this computer (${shown}): ${PICK}.` };
+}
+
+// One plain line on why a board request failed.
+function boardWhy(res, business) {
+  if (!res) return 'no answer from the server';
+  const detail = res.data && (res.data.detail || res.data.error);
+  if (res.status === 401) return 'your sign-in was refused. run: atris login';
+  if (res.status === 403) return `you are not on ${business.slug}'s team`;
+  if (res.status === 404 && detail === 'Business not found') return `no business called "${business.slug}"`;
+  return oneLine(detail || res.error || `request failed (${res.status})`);
+}
+
+// The member named by --as, else ATRIS_AGENT: lowercased, no leading @.
+function memberName(flags = {}, env = process.env) {
+  return String((typeof flags.as === 'string' ? flags.as : env.ATRIS_AGENT) || '').trim().replace(/^@/, '').toLowerCase();
+}
+
+// The server's words for "no such member" ("Agent not found: walsh"). Any
+// other 404, like "Business not found", is a different problem.
+const MEMBER_MISSING = /\b(agent|member) not found\b/i;
+
+// Member name -> { member: { id, name } }, or { missing: true }, { failed: res },
+// or { noId: true }. The caller words the error for its own command.
+// `options` adds request settings, like a shorter timeout.
+async function lookupMember(request, business, name, token, options = {}) {
+  const res = await request(`/business/${encodeURIComponent(business.id)}/team/${encodeURIComponent(name)}`, { method: 'GET', ...options, token });
+  const detail = res && res.data && (res.data.detail || res.data.error);
+  if (res && res.status === 404 && MEMBER_MISSING.test(String(detail || ''))) return { missing: true };
+  if (!res || !res.ok) return { failed: res };
+  if (!res.data || !res.data.agent_id) return { noId: true };
+  return { member: { id: String(res.data.agent_id), name: String(res.data.name || name) } };
+}
+
+module.exports = { resolveChannelBusiness, boardWhy, memberName, lookupMember };

package/lib/worktree-core.js

@@ -906,6 +906,53 @@ function refreshMovedMapRefs(root, args = []) {
   }
 }
 
+// The repo checks that failed CI for seven builders in three days. Ship runs
+// them itself so the failure shows up before the push, not after a CI round trip.
+const SHIP_NET_FILES = [
+  'test/repo-hygiene.test.js',
+  'test/no-hardcoded-home-paths.test.js',
+  'test/map-refs-accurate.test.js',
+];
+
+function shipNets(root) {
+  return SHIP_NET_FILES.filter((file) => fs.existsSync(path.join(root, file)));
+}
+
+// Runs the nets once, before the caller's --verify. A net the verify command
+// already names by its exact path is dropped so it does not run twice. Returns { ok, ran, files }.
+function runShipNets(root, { verify = '', skip = false, dryRun = false, env = process.env } = {}) {
+  if (skip || env.ATRIS_SHIP_SKIP_NETS === '1') {
+    console.log(`nets: skipped (${skip ? '--skip-nets' : 'ATRIS_SHIP_SKIP_NETS=1'})`);
+    return { ok: true, ran: false, files: [] };
+  }
+  const present = shipNets(root);
+  if (!present.length) {
+    console.log('nets: none in this repo');
+    return { ok: true, ran: false, files: [] };
+  }
+  // Whole whitespace-separated tokens only: the exact path, or the same path with ./ in front.
+  const named = new Set(String(verify || '').split(/\s+/).map((token) => token.replace(/^(['"])(.*)\1$/, '$2')));
+  const files = present.filter((file) => !named.has(file) && !named.has(`./${file}`));
+  if (!files.length) {
+    console.log('nets: covered by --verify');
+    return { ok: true, ran: false, files: [] };
+  }
+  console.log(`nets: node --test ${files.join(' ')}`);
+  if (dryRun) {
+    console.log('nets: skipped (dry-run)');
+    return { ok: true, ran: false, files };
+  }
+  // A ship started from inside a test run must still get a real runner.
+  const childEnv = { ...env };
+  delete childEnv.NODE_TEST_CONTEXT;
+  const result = spawnSync(process.execPath, ['--test', ...files], { cwd: root, stdio: 'inherit', env: childEnv });
+  if (result.error || result.status !== 0) {
+    console.error('nets: failed, fix before shipping');
+    return { ok: false, ran: true, files };
+  }
+  return { ok: true, ran: true, files };
+}
+
 const SHIP_SETTLE_MS = 10 * 60 * 1000;
 const SHIP_REAP_POLL_MS = 60 * 1000;
 const SHIP_REAP_GIVE_UP_MS = 6 * 60 * 60 * 1000;
@@ -2014,9 +2061,11 @@ module.exports = {
   runCommand,
   runGit,
   runShipHealthCheck,
+  runShipNets,
   scheduleShippedCopyRemoval,
   shellQuote,
   shipMergeRecord,
+  shipNets,
   shippedCopyRemovalPlan,
   slugify,
   stamp,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.82.23",
+  "version": "3.82.25",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof. project memory your coding agents share across sessions.",
   "mcpName": "io.github.atrislabs/atris",
   "main": "bin/atris.js",