atris 3.63.0 → 3.65.0

package/commands/hire.js

@@ -0,0 +1,189 @@
+'use strict';
+
+// atris hire "<name>" --job "<idea>"   one call: member, inbox, allowance, nightly loop
+// atris hires                         the morning check-in: one line per hire, then its 24h / 7d scoreboard
+// Backend: POST /api/business/{id}/hire, GET /api/business/{id}/hires
+
+const { apiRequestJson } = require('../utils/api');
+const { NOT_LOGGED_IN } = require('../lib/developer-api');
+const {
+  parseArgs, businessOrSay, loginToken, errorText, relativeTime, dollars, clip,
+} = require('../lib/business-target');
+
+const HIRE_FLAGS = { switches: ['outreach'], values: ['job', 'budget', 'schedule', 'timezone'] };
+
+function hireHelp(log = console.log) {
+  log(`usage: atris hire "<name>" --job "<idea>" [--budget 50] [--outreach] [--schedule nightly] [--business <slug>] [--json]
+
+hire an agent in one step. it gets a name, a job, its own email inbox,
+a monthly spending allowance, and a work loop that runs overnight.
+
+  --job       the idea it works on, in plain words (required)
+  --budget    most it may ask you to approve per month, in dollars (default 0 = no spending)
+              you still approve every purchase yourself
+  --outreach  mark it as doing outreach (recorded; it uses a normal inbox for now)
+  --schedule  nightly (default, 2 AM your time), hourly, or a cron like "0 3 * * *"
+  --timezone  defaults to this computer's timezone
+  --business  which business; defaults to the business folder you are in
+
+running it again with the same name is safe: you get the same hire back,
+and anything missing (like the inbox) is filled in. --budget changes the allowance.
+
+then each morning: atris hires`);
+}
+
+function hiresHelp(log = console.log) {
+  log(`usage: atris hires [--business <slug>] [--json]
+
+the morning check-in: one line per hire with its email in the last day,
+what it spent this month, and what its last overnight run did. under it,
+its scoreboard for the last 24 hours and 7 days: emails sent, how many got
+a reply from a person, bounces, and spend.`);
+}
+
+function localTimezone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || '';
+  } catch {
+    return '';
+  }
+}
+
+function renderHire(data = {}, now = Date.now()) {
+  const m = data.member || {};
+  const lines = [data.created ? `Hired ${m.name}.` : `${m.name} was already hired. Same hire, nothing duplicated.`];
+  if (m.job) lines.push(`Job: ${clip(m.job, 200)}`);
+  if (data.inbox && data.inbox.address) lines.push(`Inbox: ${data.inbox.address}`);
+  const a = data.allowance || {};
+  lines.push(Number(a.monthly_usd) > 0
+    ? `Allowance: ${dollars(a.monthly_usd)} a month. You still approve every purchase.`
+    : 'Allowance: none. It cannot ask to spend money.');
+  if (a.note) lines.push(`  ${a.note}`);
+  const s = data.schedule || {};
+  let when = s.label ? `Works ${s.label}.` : 'Works on its schedule.';
+  if (s.enabled === false) when += ' Asleep right now.';
+  else if (data.next_run_at) when += ` First run ${relativeTime(data.next_run_at, now)}.`;
+  lines.push(when);
+  if (data.outreach && data.outreach.requested) lines.push(`Outreach: ${data.outreach.note || 'recorded.'}`);
+  lines.push('', 'Check in each morning: atris hires');
+  return lines.join('\n');
+}
+
+function hireLine(h = {}, now = Date.now()) {
+  const parts = [];
+  if (h.status && h.status !== 'active') {
+    const why = { needs_inbox: 'paused, no inbox yet', needs_allowance: 'paused, allowance not set up', setting_up: 'still setting up',
+      pending_schedule: 'set up, nightly work not switched on yet (run the same hire again)' };
+    parts.push(why[h.status] || `paused (${h.status})`);
+  }
+  const mail = h.emails_last_24h;
+  if (mail) parts.push(`sent ${mail.sent}, got ${mail.received} emails today`);
+  else parts.push('no inbox');
+  const a = h.allowance || {};
+  if (Number(a.monthly_usd) > 0) {
+    parts.push(a.spent_this_month_usd == null
+      ? `${dollars(a.monthly_usd)} a month`
+      : `spent ${dollars(a.spent_this_month_usd)} of ${dollars(a.monthly_usd)}`);
+  }
+  if (h.last_run_at) {
+    const result = h.last_result ? `: ${clip(h.last_result, 80)}` : '';
+    parts.push(`last ran ${relativeTime(h.last_run_at, now)}${result}`);
+  } else if (h.schedule && h.schedule.enabled === false) {
+    parts.push('asleep, has not run');
+  } else if (h.next_run_at) {
+    parts.push(`first run ${relativeTime(h.next_run_at, now)}`);
+  } else {
+    parts.push('has not run yet');
+  }
+  return `${h.name}: ${parts.join(' · ')}`;
+}
+
+function windowText(label, w) {
+  if (!w || w.sent == null) return '';
+  const replies = Number(w.replies) || 0;
+  const value = w.reply_rate == null || w.reply_rate === '' ? NaN : Number(w.reply_rate);
+  const rate = Number.isFinite(value) ? ` (${Math.round(value * 100)}%)` : '';
+  const parts = [`sent ${w.sent}`, `${replies} ${replies === 1 ? 'reply' : 'replies'}${rate}`,
+    `${Number(w.bounces) || 0} bounced`];
+  if (w.spend_cents != null) parts.push(`spent ${dollars(Number(w.spend_cents) / 100)}`);
+  return `${label}: ${parts.join(', ')}`;
+}
+
+// The second line under a hire: how its mail is landing. Empty for an older backend.
+function scoreLine(board, now = Date.now()) {
+  if (!board) return '';
+  const parts = [windowText('last 24h', board.last_24h), windowText('last 7 days', board.last_7d)].filter(Boolean);
+  if (!parts.length) return '';
+  if (board.last_action_at) parts.push(`last action ${relativeTime(board.last_action_at, now)}`);
+  if (board.capped) parts.push('counts cover only the newest mail');
+  return `  ${parts.join(' · ')}`;
+}
+
+function renderHires(data = {}, now = Date.now()) {
+  const rows = Array.isArray(data.hires) ? data.hires : [];
+  if (!rows.length) return 'No hires yet. Start one: atris hire "Maya" --job "grow the newsletter"';
+  return rows.map((h) => [hireLine(h, now), scoreLine(h.scoreboard, now)].filter(Boolean).join('\n')).join('\n');
+}
+
+function io(deps) {
+  return { log: deps.log || console.log, err: deps.err || console.error };
+}
+
+async function hireCommand(args = [], deps = {}) {
+  const out = io(deps);
+  const { flags, pos, error } = parseArgs(args, HIRE_FLAGS);
+  if (flags.help || pos[0] === 'help') { hireHelp(out.log); return 0; }
+  if (error) { out.err(`${error}. see: atris hire --help`); return 1; }
+
+  const name = pos.join(' ').trim();
+  const job = typeof flags.job === 'string' ? flags.job.trim() : '';
+  if (!name) { out.err('give the hire a name: atris hire "Maya" --job "<idea>"'); return 1; }
+  if (!job) { out.err('give the hire a job: --job "<the idea to grow>"'); return 1; }
+  const body = { name, job, outreach: flags.outreach === true };
+  if (flags.budget != null) {
+    const budget = Number(flags.budget);
+    if (!Number.isInteger(budget) || budget < 0 || budget > 1000) {
+      out.err('--budget must be whole dollars from 0 to 1000');
+      return 1;
+    }
+    body.monthly_allowance_usd = budget;
+  }
+  if (typeof flags.schedule === 'string') body.schedule = flags.schedule;
+  const tz = typeof flags.timezone === 'string' ? flags.timezone : (deps.timezone || localTimezone());
+  if (tz) body.timezone = tz;
+
+  const business = businessOrSay(flags, deps, out.err);
+  if (!business) return 1;
+  const token = await loginToken(deps);
+  if (!token) { out.err(NOT_LOGGED_IN); return 1; }
+
+  const request = deps.apiRequestJson || apiRequestJson;
+  const result = await request(`/business/${encodeURIComponent(business.id)}/hire`, {
+    method: 'POST', token, body, timeoutMs: 60000, retries: 0,
+  });
+  if (!result || !result.ok) { out.err(`Could not hire ${name}: ${errorText(result)}`); return 1; }
+  if (flags.json) out.log(JSON.stringify(result.data));
+  else out.log(renderHire(result.data, deps.now ? deps.now() : Date.now()));
+  return 0;
+}
+
+async function hiresCommand(args = [], deps = {}) {
+  const out = io(deps);
+  const { flags, pos, error } = parseArgs(args, {});
+  if (flags.help || pos[0] === 'help') { hiresHelp(out.log); return 0; }
+  if (error) { out.err(`${error}. see: atris hires --help`); return 1; }
+  if (pos.length) { out.err(`atris hires takes no other words (got "${pos[0]}"). see: atris hires --help`); return 1; }
+  const business = businessOrSay(flags, deps, out.err);
+  if (!business) return 1;
+  const token = await loginToken(deps);
+  if (!token) { out.err(NOT_LOGGED_IN); return 1; }
+
+  const request = deps.apiRequestJson || apiRequestJson;
+  const result = await request(`/business/${encodeURIComponent(business.id)}/hires`, { method: 'GET', token });
+  if (!result || !result.ok) { out.err(`Could not load hires: ${errorText(result)}`); return 1; }
+  if (flags.json) out.log(JSON.stringify(result.data));
+  else out.log(renderHires(result.data, deps.now ? deps.now() : Date.now()));
+  return 0;
+}
+
+module.exports = { hireCommand, hiresCommand, renderHire, renderHires, hireLine, scoreLine };

package/commands/improve.js

@@ -18,10 +18,13 @@
  * fallback, and scorecard writes can all be faked in tests.
  */
 
+const crypto = require('crypto');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const gitSpawn = require('../lib/git-spawn');
+const ignoredCache = require('../lib/ignored-cache');
 const { apiRequestJson, getApiBaseUrl } = require('../utils/api');
 const { loadCredentials } = require('../utils/auth');
 const pulse = require('../lib/pulse');
@@ -1085,8 +1088,9 @@ function parseRevisionsArgs(argv = []) {
   return opts;
 }
 
-function gitLines(cwdRoot, gitArgs) {
-  const r = spawnSync('git', gitArgs, { cwd: cwdRoot, encoding: 'utf8' });
+// Through the module object so tests can count git spawns with a spy.
+function gitLines(cwdRoot, gitArgs, { input, maxBuffer } = {}) {
+  const r = gitSpawn.runGit(gitArgs, { cwd: cwdRoot, check: false, input, maxBuffer });
   if (r.status !== 0) {
     const err = new Error(String(r.stderr || `git ${gitArgs[0]} exited ${r.status}`).trim());
     err.gitFailed = true;
@@ -1095,17 +1099,129 @@ function gitLines(cwdRoot, gitArgs) {
   return String(r.stdout || '');
 }
 
+// File names come back NUL-separated and never quoted, whatever core.quotePath
+// says, so a name reads the same fresh from git and from the saved cache.
+const NAME_ARGS = ['-c', 'core.quotePath=false'];
+
+function splitNames(out) {
+  return String(out || '').split('\0').filter(Boolean);
+}
+
 /**
  * Files changed by one commit. Merge commits are attributed by their
  * first-parent diff (what the merge actually brought onto the mainline);
  * plain commits use diff-tree. Root commits list their initial files.
+ * The rename choice is spelled out so a user's diff.renames setting cannot
+ * change the lists: merges find renames (git diff's default), plain commits
+ * do not (diff-tree's default).
  */
 function commitFiles(cwdRoot, commit) {
   const parents = commit.parents;
   const out = parents.length >= 2
-    ? gitLines(cwdRoot, ['diff', '--name-only', `${commit.hash}^1`, commit.hash])
-    : gitLines(cwdRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', '--root', commit.hash]);
-  return out.split('\n').map((line) => line.trim()).filter(Boolean);
+    ? gitLines(cwdRoot, [...NAME_ARGS, 'diff', '--name-only', '--find-renames', '-z', `${commit.hash}^1`, commit.hash])
+    : gitLines(cwdRoot, [...NAME_ARGS, 'diff-tree', '--no-commit-id', '--name-only', '--no-renames', '-z', '-r', '--root', commit.hash]);
+  return splitNames(out);
+}
+
+/**
+ * Files changed by many plain commits in one git process: the same diff-tree
+ * per-commit call above, fed every hash on stdin. --always prints the hash
+ * even for an empty commit. Raw output frames every file as a ':'-led status
+ * field followed by its path, so a path is never mistaken for a commit hash,
+ * even a path spelled exactly like the next one.
+ */
+function plainCommitFiles(cwdRoot, commits) {
+  const found = new Map(commits.map((commit) => [commit.hash, []]));
+  if (!commits.length) return found;
+  const hashes = commits.map((commit) => commit.hash);
+  const out = gitLines(cwdRoot, [...NAME_ARGS, 'diff-tree', '--stdin', '--always', '--raw', '--no-renames', '-z', '-r', '--root'], {
+    input: `${hashes.join('\n')}\n`,
+    // Many commits' lists in one reply; the per-commit calls each had 1MB.
+    maxBuffer: Math.max(1, hashes.length) * 1024 * 1024,
+  });
+  const fields = splitNames(out);
+  let current = null;
+  for (let i = 0; i < fields.length; i++) {
+    const field = fields[i];
+    if (field.startsWith(':')) {
+      // Status field; with --no-renames exactly one path follows it.
+      if (current && i + 1 < fields.length) current.push(fields[i + 1]);
+      i += 1;
+    } else {
+      current = found.get(field) || null;
+    }
+  }
+  return found;
+}
+
+// Where git keeps state shared by every checkout of this repo (a linked
+// worktree points at its main repo). null when it cannot be found on disk.
+function gitCommonDir(root) {
+  if (process.env.GIT_DIR || process.env.GIT_COMMON_DIR) return null;
+  let dir = path.resolve(root);
+  for (;;) {
+    const dotGit = path.join(dir, '.git');
+    let stat = null;
+    try { stat = fs.statSync(dotGit); } catch { stat = null; }
+    if (stat && stat.isDirectory()) return dotGit;
+    if (stat && stat.isFile()) {
+      const match = fs.readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+)$/m);
+      if (!match) return null;
+      const gitDir = path.resolve(dir, match[1].trim());
+      try {
+        return path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim());
+      } catch {
+        return gitDir;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// A shallow clone cuts history at boundary commits, and those commits list
+// different files once the history is fetched. The saved lists are only good
+// for the shallow state they were read under; null means do not cache.
+function shallowStamp(root) {
+  const common = gitCommonDir(root);
+  if (!common) return null;
+  try {
+    return crypto.createHash('sha1').update(fs.readFileSync(path.join(common, 'shallow'))).digest('hex');
+  } catch (error) {
+    return error.code === 'ENOENT' ? 'full' : null;
+  }
+}
+
+// A commit's file list never changes, so it is saved by hash in the ignored
+// .atris/cache and the gauge (shown on every boot) only asks git about commits
+// it has not seen. Hashes this read used come first; older ones stay until the
+// cap, so a 7-day boot read and a 14-day report read do not evict each other.
+const REVISION_FILES_CACHE = 'revision-files.json';
+const REVISION_FILES_CACHE_MAX = 5000;
+
+function loadRevisionFilesCache(root) {
+  const shallow = ignoredCache.cacheEnabled(root) ? shallowStamp(root) : null;
+  const cache = { root, shallow, entries: {}, used: {}, dirty: false, writable: Boolean(shallow) };
+  if (!cache.writable) return cache;
+  const parsed = ignoredCache.readCacheJson(root, REVISION_FILES_CACHE);
+  if (parsed && parsed.version === 1 && parsed.shallow === shallow && parsed.entries && typeof parsed.entries === 'object') {
+    cache.entries = parsed.entries;
+  }
+  return cache;
+}
+
+function saveRevisionFilesCache(cache) {
+  if (!cache.writable || !cache.dirty) return;
+  const entries = { ...cache.used };
+  let count = Object.keys(entries).length;
+  for (const [hash, files] of Object.entries(cache.entries)) {
+    if (count >= REVISION_FILES_CACHE_MAX) break;
+    if (entries[hash] || !Array.isArray(files)) continue;
+    entries[hash] = files;
+    count += 1;
+  }
+  ignoredCache.writeCacheJson(cache.root, REVISION_FILES_CACHE, { version: 1, shallow: cache.shallow, entries });
 }
 
 /**
@@ -1150,10 +1266,27 @@ function collectRevisionSignals(root, options = {}) {
   // commits count as revision signals.
   const humans = commits.filter((c) => !c.isAgent && c.parents.length < 2);
 
-  const filesCache = new Map();
+  // Every landing's files are needed, and a human commit's only when it falls
+  // inside some landing's window. Plain commits missing from the cache are
+  // read in one batch; merges keep their own first-parent diff.
+  const cache = loadRevisionFilesCache(root);
+  const needed = [...landings, ...humans.filter((human) => landings.some((landing) => human.ms > landing.ms && human.ms <= landing.ms + REVISION_WINDOW_MS))];
+  const missing = [];
+  for (const commit of needed) {
+    const hit = cache.entries[commit.hash];
+    if (Array.isArray(hit)) cache.used[commit.hash] = hit;
+    else if (commit.parents.length < 2) missing.push(commit);
+  }
+  for (const [hash, files] of plainCommitFiles(root, missing)) {
+    cache.used[hash] = files;
+    cache.dirty = true;
+  }
   const filesOf = (commit) => {
-    if (!filesCache.has(commit.hash)) filesCache.set(commit.hash, commitFiles(root, commit));
-    return filesCache.get(commit.hash);
+    if (!cache.used[commit.hash]) {
+      cache.used[commit.hash] = commitFiles(root, commit);
+      cache.dirty = true;
+    }
+    return cache.used[commit.hash];
   };
 
   const revisions = [];
@@ -1177,6 +1310,7 @@ function collectRevisionSignals(root, options = {}) {
       });
     }
   }
+  saveRevisionFilesCache(cache);
 
   return {
     schema: REVISIONS_SCHEMA,

package/commands/integrations.js

@@ -33,11 +33,12 @@ const {
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { stateHome } = require('../lib/state-home');
 const readline = require('readline');
 const { spawnSync } = require('child_process');
 const { sleepSync } = require('../lib/sleep-sync');
 
-const CALENDAR_CACHE_PATH = path.join(os.homedir(), '.atris', 'calendar-events-cache.json');
+const CALENDAR_CACHE_PATH = path.join(stateHome(), '.atris', 'calendar-events-cache.json');
 const GMAIL_CONNECT_POLL_MS = 3000;
 const GMAIL_CONNECT_TIMEOUT_MS = 3 * 60 * 1000;
 const GMAIL_SEND_USAGE = 'usage: atris gmail send <to> <subject> <body...> [--body-file <path>] [--account <id>]';
@@ -182,7 +183,7 @@ function parseGmailVerdictsArgs(args = []) {
 
 function gmailAccountStatePath() {
   return process.env.ATRIS_GMAIL_ACCOUNT_FILE
-    || path.join(os.homedir(), '.atris', 'gmail-account.json');
+    || path.join(stateHome(), '.atris', 'gmail-account.json');
 }
 
 function readGmailStickyAccount() {
@@ -1794,7 +1795,7 @@ function normalizeContactLabel(value) {
 }
 
 function imessageLookupCachePath() {
-  return path.join(os.homedir(), '.atris', 'cache', 'imessage-contacts.json');
+  return path.join(stateHome(), '.atris', 'cache', 'imessage-contacts.json');
 }
 
 function readImessageLookupCache() {

package/commands/loops.js

@@ -13,6 +13,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { stateHome } = require('../lib/state-home');
 const { execSync, spawnSync } = require('child_process');
 
 const MAX_LOG_AGE_DAYS = 14;
@@ -26,7 +27,7 @@ const SCAFFOLD_FILES = [
 ];
 
 function heartbeatDir() {
-  return process.env.ATRIS_HEARTBEAT_DIR || path.join(os.homedir(), '.atris', 'heartbeat');
+  return process.env.ATRIS_HEARTBEAT_DIR || path.join(stateHome(), '.atris', 'heartbeat');
 }
 
 function readJson(filePath, fallback) {

package/commands/mail.js

@@ -0,0 +1,163 @@
+'use strict';
+
+// atris mail inboxes | read <inbox> | send <inbox> --to --subject --body
+// Your agents' own email inboxes (the @atrismail.com ones), not your Gmail.
+// For Gmail use `atris gmail`. Backend: /api/business/{id}/mail/...
+
+const readline = require('readline');
+const { apiRequestJson } = require('../utils/api');
+const { NOT_LOGGED_IN } = require('../lib/developer-api');
+const {
+  parseArgs, businessOrSay, loginToken, errorText, clip,
+} = require('../lib/business-target');
+
+// The only flags each subcommand takes (plus --help, --json, --business).
+const MAIL_FLAGS = {
+  inboxes: {},
+  read: { values: ['limit'] },
+  send: { switches: ['yes', 'dry_run'], values: ['to', 'subject', 'body'] },
+};
+const ALL_MAIL_FLAGS = { switches: ['yes', 'dry_run'], values: ['limit', 'to', 'subject', 'body'] };
+
+function mailHelp(log = console.log) {
+  log(`usage: atris mail inboxes [--business <slug>] [--json]
+       atris mail read <inbox> [--limit 10] [--json]
+       atris mail send <inbox> --to <address> --subject "<subject>" --body "<text>" [--yes] [--dry-run]
+
+your agents' own email inboxes (not your Gmail; for that use atris gmail).
+<inbox> is the address, the part before the @, or the inbox id.
+
+  inboxes   list every agent inbox in this business
+  read      newest messages first (--limit 1 to 200, default 10)
+  send      send one email from an agent inbox. asks before sending unless --yes.
+            --dry-run prints the email and sends nothing.
+            unknown flags are refused, so a typo never sends anything.`);
+}
+
+function toList(value) {
+  if (Array.isArray(value)) return value.map(String);
+  if (typeof value === 'string' && value.trim().startsWith('[')) {
+    try { return JSON.parse(value).map(String); } catch { /* fall through */ }
+  }
+  return value ? [String(value)] : [];
+}
+
+function renderInboxes(rows = []) {
+  if (!rows.length) return 'No agent inboxes yet. Hiring an agent makes one: atris hire "<name>" --job "<idea>"';
+  return rows.map((r) => `${r.email_address}${r.display_name ? `  (${r.display_name})` : ''}`).join('\n');
+}
+
+function renderMessages(inbox, rows = []) {
+  if (!rows.length) return `No mail in ${inbox.email_address} yet.`;
+  const lines = [];
+  for (const m of rows) {
+    const when = String(m.created_at || '').slice(0, 16).replace('T', ' ');
+    const out = m.direction === 'outbound';
+    const who = out ? `to ${toList(m.to_addresses).join(', ')}` : `from ${m.from_address || '?'}`;
+    lines.push(`${when}  ${out ? 'sent' : 'got '}  ${who}`);
+    lines.push(`  ${clip(m.subject || '(no subject)', 100)}`);
+    const body = clip(m.body_text || '', 160);
+    if (body) lines.push(`  ${body}`);
+  }
+  return lines.join('\n');
+}
+
+// address, local part, or id -> the inbox row
+function findInbox(rows, wanted) {
+  const w = String(wanted || '').trim().toLowerCase();
+  if (!w) return null;
+  return rows.find((r) => String(r.id).toLowerCase() === w)
+    || rows.find((r) => String(r.email_address || '').toLowerCase() === w)
+    || rows.find((r) => String(r.email_address || '').toLowerCase().split('@')[0] === w)
+    || null;
+}
+
+function askYesNo(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
+    });
+  });
+}
+
+async function mailCommand(args = [], deps = {}) {
+  const out = { log: deps.log || console.log, err: deps.err || console.error };
+  const { flags, pos } = parseArgs(args, ALL_MAIL_FLAGS);
+  const sub = pos[0];
+  if (flags.help || !sub || sub === 'help') { mailHelp(out.log); return sub || flags.help ? 0 : 1; }
+  if (!MAIL_FLAGS[sub]) {
+    out.err(`unknown mail command: ${sub}. try: atris mail inboxes | read | send`);
+    return 1;
+  }
+  // Checked against this subcommand's own flags, before any request: an
+  // unknown or mistyped flag on send must never turn into a real email.
+  const { error } = parseArgs(args, MAIL_FLAGS[sub]);
+  if (error) { out.err(`${error}. see: atris mail --help`); return 1; }
+  const words = sub === 'inboxes' ? 1 : 2;
+  if (pos.length > words) {
+    out.err(`atris mail ${sub} got an extra word: "${pos[words]}". put text in quotes, like --body "hi there"`);
+    return 1;
+  }
+
+  const business = businessOrSay(flags, deps, out.err);
+  if (!business) return 1;
+  const token = await loginToken(deps);
+  if (!token) { out.err(NOT_LOGGED_IN); return 1; }
+  const request = deps.apiRequestJson || apiRequestJson;
+  const base = `/business/${encodeURIComponent(business.id)}/mail`;
+
+  const listed = await request(`${base}/inboxes`, { method: 'GET', token });
+  if (!listed || !listed.ok) { out.err(`Could not load inboxes: ${errorText(listed)}`); return 1; }
+  const inboxes = Array.isArray(listed.data) ? listed.data : [];
+
+  if (sub === 'inboxes') {
+    out.log(flags.json ? JSON.stringify(inboxes) : renderInboxes(inboxes));
+    return 0;
+  }
+
+  if (!pos[1]) { out.err(`which inbox? atris mail ${sub} <inbox>`); return 1; }
+  const inbox = findInbox(inboxes, pos[1]);
+  if (!inbox) { out.err(`No inbox matches "${pos[1]}". See them all: atris mail inboxes`); return 1; }
+
+  if (sub === 'read') {
+    const limit = flags.limit == null ? 10 : Number(flags.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) { out.err('--limit must be a number from 1 to 200'); return 1; }
+    const res = await request(`${base}/inboxes/${encodeURIComponent(inbox.id)}/messages?limit=${limit}`, { method: 'GET', token });
+    if (!res || !res.ok) { out.err(`Could not read ${inbox.email_address}: ${errorText(res)}`); return 1; }
+    const rows = Array.isArray(res.data) ? res.data : [];
+    out.log(flags.json ? JSON.stringify(rows) : renderMessages(inbox, rows));
+    return 0;
+  }
+
+  // send
+  const to = typeof flags.to === 'string' ? flags.to.trim() : '';
+  const subject = typeof flags.subject === 'string' ? flags.subject : '';
+  const text = typeof flags.body === 'string' ? flags.body : '';
+  if (!to || !subject || !text) { out.err('send needs --to, --subject, and --body'); return 1; }
+  const preview = `From:    ${inbox.email_address}\nTo:      ${to}\nSubject: ${subject}\n\n${text}\n`;
+  if (flags.dry_run === true) {
+    out.log(`${preview}\nDry run: nothing was sent.`);
+    return 0;
+  }
+  // Only a bare --yes (or -y) skips the question; the parser refuses --yes=<anything>.
+  if (flags.yes !== true) {
+    out.log(preview);
+    const ok = await (deps.confirm || askYesNo)('Send this email? (y/N) ');
+    if (!ok) {
+      out.log(process.stdin.isTTY || deps.confirm ? 'Not sent.' : 'Not sent. Add --yes to send without asking.');
+      return 1;
+    }
+  }
+  const res = await request(`${base}/inboxes/${encodeURIComponent(inbox.id)}/messages/send`, {
+    method: 'POST', token, body: { to, subject, text }, retries: 0, timeoutMs: 30000,
+  });
+  if (!res || !res.ok) { out.err(`Not sent: ${errorText(res)}`); return 1; }
+  if (flags.json) out.log(JSON.stringify(res.data));
+  else out.log(`Sent from ${inbox.email_address} to ${to}.`);
+  return 0;
+}
+
+module.exports = { mailCommand, findInbox, renderInboxes, renderMessages };