atris 3.61.0 → 3.63.0

package/commands/buy.js

@@ -0,0 +1,242 @@
+'use strict';
+
+// atris buy: quote a purchase or trade, start the person's approval, check status.
+//
+//   atris buy quote --kind ticket --event-url <vividseats url> --quantity 2
+//   atris buy approve ord_<id> --pick 1 --delivery-email sam@example.com
+//   atris buy status ord_<id>
+//
+// Nothing is ever charged by this command. Approve only starts the human step:
+// a tap in their Link app, a payment page, or a reply to the confirm code Atris
+// texts to their own phone. The code never comes back to this command.
+
+const { apiRequestJson } = require('../utils/api');
+const { loadCredentials } = require('../utils/auth');
+const { NOT_LOGGED_IN, tokenFrom, oneLine, printResult } = require('../lib/developer-api');
+const { parseFlags, formatCents, untilText, errorFrom } = require('../lib/commerce');
+
+const KINDS = ['ticket', 'shop', 'trade', 'flight'];
+const NOTHING_CHARGED = 'Nothing is charged until the person approves it themselves.';
+const CONTROL_FLAGS = new Set(['json', 'help', 'intent', 'details']);
+const TRADE_CONFIRM = 'We texted you a confirm code. Reply to that text to place the trade.';
+
+function showBuyHelp(log = console.log) {
+  log(`usage: atris buy <quote|approve|status> [flags] [--json]
+
+get a real quote, then hand the person the approval step. nothing is charged
+until the person approves it themselves (Link app, payment page, or a text
+from their own phone).
+
+  atris buy quote --kind ticket|shop|trade|flight [fields] [--intent '<json>']
+  atris buy approve <id> [fields] [--details '<json>']
+  atris buy status <id>
+
+quote fields (flags, kebab-case is fine):
+  ticket  --event-url <vividseats.com url> --quantity N [--min-each-usd N] [--max-each-usd N]
+  shop    --query "<item>" | --url <product url>  [--quantity N]
+  trade   --side buy|sell --symbol VTI (--quantity N | --dollars N) [--order-type market|limit --limit-price N]
+  flight  not wired yet, quotes are refused
+
+approve fields:
+  ticket  --pick 1 --delivery-email you@example.com
+  shop    --delivery-email you@example.com [--options '<json>'] [--address '<json>'] [--accept-extras]
+  trade   none. Atris texts the person a confirm code; they reply to that text.
+
+examples:
+  atris buy quote --kind trade --side buy --symbol VTI --dollars 25
+  atris buy quote --intent '{"kind":"shop","query":"uniqlo supima crew tee navy"}'
+  atris buy approve ord_1234 --pick 1 --delivery-email sam@example.com
+  atris buy status ord_1234 --json`);
+}
+
+function fieldsFrom(flags) {
+  const out = {};
+  for (const [key, value] of Object.entries(flags)) {
+    if (!CONTROL_FLAGS.has(key)) out[key] = value;
+  }
+  return out;
+}
+
+function jsonFlag(flags, name) {
+  if (flags[name] == null) return { ok: true, value: {} };
+  const value = flags[name];
+  if (value && typeof value === 'object' && !Array.isArray(value)) return { ok: true, value };
+  return { ok: false, error: `--${name} must be a JSON object, like --${name} '{"kind":"shop","query":"navy tee"}'` };
+}
+
+function approvalLines(approval) {
+  if (!approval || typeof approval !== 'object') return [];
+  const lines = [];
+  // The backend sends trade confirm codes only to the person's own texts.
+  if (approval.how === 'text_confirm') return [TRADE_CONFIRM];
+  if (approval.url) {
+    const label = approval.how === 'connect_link' ? 'Connect Link first'
+      : approval.how === 'payment_page' ? 'Pay on this page'
+        : 'Approve in Link';
+    lines.push(`${label}: ${approval.url}`);
+  }
+  if (approval.text) lines.push(approval.text);
+  return lines;
+}
+
+function moneyLines(data) {
+  const lines = [];
+  if (data.total_cents != null) lines.push(`Total: ${formatCents(data.total_cents, data.currency)}`);
+  if (data.fee_cents != null) lines.push(`Atris fee: ${formatCents(data.fee_cents, data.currency)}`);
+  return lines;
+}
+
+function renderQuote(data = {}, now = Date.now()) {
+  const lines = [];
+  if (data.status !== 'quoted') return renderOutcome(data, now);
+  lines.push(data.summary || 'Quote ready.');
+  lines.push('');
+  lines.push(...moneyLines(data));
+  if (data.expires_at) lines.push(`Expires: ${data.expires_at} (${untilText(data.expires_at, now)})`);
+  if (data.id) lines.push(`Quote id: ${data.id}`);
+  if (data.product_url) lines.push(`Product: ${data.product_url}`);
+  const choices = data.options && typeof data.options === 'object' && !Array.isArray(data.options)
+    ? Object.entries(data.options) : [];
+  if (choices.length) {
+    lines.push('Choices:');
+    for (const [name, values] of choices) {
+      lines.push(`  ${name}: ${Array.isArray(values) ? values.join(', ') : oneLine(values)}`);
+    }
+  }
+  if (data.note) lines.push('', String(data.note));
+  lines.push('');
+  lines.push(NOTHING_CHARGED);
+  const approval = data.approval && data.approval.text ? data.approval.text : '';
+  if (approval) lines.push(approval);
+  if (data.id) {
+    const hints = data.approve_with && typeof data.approve_with === 'object'
+      ? Object.keys(data.approve_with).map((key) => `--${key.replace(/_/g, '-')} <${key}>`).join(' ')
+      : '';
+    lines.push(`Once they say yes: atris buy approve ${data.id}${hints ? ` ${hints}` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+function renderOutcome(data = {}, now = Date.now()) {
+  const lines = [];
+  const status = String(data.status || '');
+  if (status === 'pending_approval') {
+    lines.push(data.message || 'Waiting for the person to approve.');
+    lines.push('');
+    lines.push(...moneyLines(data));
+    if (data.expires_at) lines.push(`Expires: ${data.expires_at} (${untilText(data.expires_at, now)})`);
+    if (data.id) lines.push(`Id: ${data.id}`);
+    lines.push('');
+    lines.push('Next, the person does this themselves:');
+    for (const line of approvalLines(data.approval)) lines.push(`  ${line}`);
+    if (data.fee_card && data.fee_card.url) lines.push(`  Fee card: ${data.fee_card.url}`);
+    lines.push('');
+    lines.push('Nothing has been charged yet. Money moves only after the person acts themselves.');
+    if (data.id) lines.push(`Check it: atris buy status ${data.id}`);
+    return lines.join('\n');
+  }
+  if (status === 'needs_setup') {
+    lines.push(data.message || 'Setup needed first.');
+    for (const line of approvalLines(data.approval)) lines.push(`  ${line}`);
+    lines.push('Nothing was charged.');
+    return lines.join('\n');
+  }
+  if (status === 'needs_input') {
+    lines.push(data.message || 'More details needed.');
+    if (Array.isArray(data.fields) && data.fields.length) lines.push(`Needed: ${data.fields.join(', ')}`);
+    if (data.extra_usd != null) lines.push(`Extra: $${data.extra_usd}`);
+    if (data.total_usd != null) lines.push(`New total: $${data.total_usd}`);
+    lines.push('Nothing was charged.');
+    return lines.join('\n');
+  }
+  if (status === 'refused') {
+    lines.push(data.message || 'That did not go through.');
+    if (!/nothing was/i.test(String(data.message || ''))) lines.push('Nothing was charged.');
+    return lines.join('\n');
+  }
+  return data.message || oneLine(data);
+}
+
+function renderStatus(data = {}) {
+  const lines = [];
+  lines.push(`${data.id || ''}  ${data.kind || ''}  ${String(data.state || 'unknown').toUpperCase()}`.trim());
+  if (data.what) lines.push(`What: ${data.what}`);
+  if (data.amount_cents != null) lines.push(`Amount: ${formatCents(data.amount_cents, data.currency)}`);
+  if (data.when) lines.push(`When: ${data.when}`);
+  if (data.detail) lines.push(`Detail: ${data.detail}`);
+  if (data.counterparty) lines.push(`With: ${data.counterparty}`);
+  if (data.receipt_url) lines.push(`Receipt: ${data.receipt_url}`);
+  if (data.fee_payment_url) lines.push(`Pay the Atris fee: ${data.fee_payment_url}`);
+  const approval = approvalLines(data.approval);
+  if (approval.length) {
+    lines.push('Waiting on the person:');
+    for (const line of approval) lines.push(`  ${line}`);
+  }
+  if (data.state === 'unknown') lines.push('Money may have moved. Check the store or Robinhood app. Do not buy again to fix it.');
+  return lines.join('\n');
+}
+
+function buildRequest(sub, pos, flags) {
+  if (sub === 'quote') {
+    const base = jsonFlag(flags, 'intent');
+    if (!base.ok) return base;
+    const body = { ...base.value, ...fieldsFrom(flags) };
+    const kind = String(body.kind || '').toLowerCase();
+    if (!KINDS.includes(kind)) return { ok: false, error: `--kind must be one of ${KINDS.join(', ')}` };
+    body.kind = kind;
+    return { ok: true, path: '/commerce/quote', method: 'POST', body };
+  }
+  if (sub === 'approve' || sub === 'status') {
+    const id = String(pos[1] || '').trim();
+    if (!id) return { ok: false, error: `usage: atris buy ${sub} <id>` };
+    const path = `/commerce/${encodeURIComponent(id)}`;
+    if (sub === 'status') return { ok: true, path, method: 'GET' };
+    const base = jsonFlag(flags, 'details');
+    if (!base.ok) return base;
+    return { ok: true, path: `${path}/approve`, method: 'POST', body: { ...base.value, ...fieldsFrom(flags) } };
+  }
+  return { ok: false, error: 'usage: atris buy <quote|approve|status>. run: atris buy --help' };
+}
+
+async function buyCommand(args = [], deps = {}) {
+  const io = { log: deps.log || console.log, err: deps.err || console.error };
+  const { flags, pos } = parseFlags(args);
+  const sub = String(pos[0] || '').toLowerCase();
+  if (!sub || sub === 'help' || flags.help) {
+    showBuyHelp(io.log);
+    return 0;
+  }
+
+  const json = flags.json === true;
+  const fail = (error, status) => {
+    printResult({ json, ok: false, error, payload: { ok: false, error, ...(status ? { status } : {}) } }, io);
+    return 1;
+  };
+
+  const req = buildRequest(sub, pos, flags);
+  if (!req.ok) return fail(req.error);
+
+  const load = deps.loadCredentials || loadCredentials;
+  const request = deps.apiRequestJson || apiRequestJson;
+  const token = tokenFrom(load());
+  if (!token) return fail(NOT_LOGGED_IN);
+
+  try {
+    // No retries: a quote or approval must never be sent twice by accident.
+    const options = { method: req.method, token, retries: 0 };
+    if (req.body) options.body = req.body;
+    const result = await request(req.path, options);
+    if (!result || !result.ok) return fail(errorFrom(result), result && result.status);
+    const data = result.data || {};
+    const now = deps.now ? deps.now() : Date.now();
+    const text = sub === 'quote' ? renderQuote(data, now)
+      : sub === 'approve' ? renderOutcome(data, now)
+        : renderStatus(data);
+    printResult({ json, ok: true, text, payload: { ok: true, ...data } }, io);
+    return 0;
+  } catch (error) {
+    return fail(oneLine(error && error.message));
+  }
+}
+
+module.exports = { buyCommand };

package/commands/engine.js

@@ -11,8 +11,8 @@
 //   atris engine roster confirm  renew every dated worker for 30 days
 //   atris engine roster session [clear]  this shell's own changes
 //   atris engine roster --available  tools and models on this machine
-//   atris engine assign <job> <tool> [--like <kind>] [--model <m>] [--effort <level>] [--max "20 min"] [--backup "<tool> [model]"] [--days <n>] [--add] [--session | --everywhere]
-//   atris engine assign <job> --remove <tool> | --clear [--session | --everywhere]
+//   atris engine assign <job> <tool> [--like <kind>] [--model <m>] [--effort <level>] [--max "20 min"] [--prep <job>] [--backup "<tool> [model]"] [--days <n>] [--add] [--session | --everywhere]
+//   atris engine assign <job> --promote "<tool> [model]" | --remove <tool> | --clear [--session | --everywhere]
 //   jobs are open-ended: search, build, review, or your own ("small build")
 //   atris engine cursor     make cursor the default engine here
 //   atris engine reset      back to the house default (atris-fast)
@@ -36,6 +36,8 @@ const { parseScopeFlag } = require('../lib/cli-scope');
 const { isFreshWorkspace, speakFirstMinute } = require('../lib/first-minute');
 const { teamRosterView } = require('../lib/member-engine');
 const { engineRunsView, availableModels } = require('../lib/roster-models');
+const { readRosterRuns, workerRuns, summarizeRuns, recentRuns, renderRunLine, DEFAULT_DAYS: RUN_DAYS } = require('../lib/roster-runs');
+const { attachSuggestions } = require('../lib/roster-suggest');
 const {
   ENGINE_ROLES,
   ENGINE_JOBS,
@@ -70,6 +72,8 @@ const {
   requireEngineBin,
   engineDoctorReport,
   engineFailureHealthStatus,
+  engineReadyAt,
+  coolingView,
   setEngineOverrides,
   setEngineHealth,
 } = require('../lib/engine-registry');
@@ -144,7 +148,7 @@ function resolveDefaultEngine(root = process.cwd()) {
   if (saved) return { name: saved, source: 'saved' };
   const ready = new Set(
     engineRegistryView(root)
-      .filter((engine) => engine.health && engine.health.status === 'ready')
+      .filter((engine) => engineReadyAt(engine))
       .map((engine) => engine.id)
   );
   if (ready.has(HOUSE_ENGINE)) return { name: HOUSE_ENGINE, source: 'house' };
@@ -941,7 +945,7 @@ function printRoster(root, { scope = 'workspace' } = {}) {
   const list = roster(root);
   const scoped = scope === 'global'
     ? list
-    : list.filter((engine) => engine.installed || engine.default || engine.health.status === 'ready');
+    : list.filter((engine) => engine.installed || engine.default || ['ready', 'cooling'].includes(engine.health.status));
   const found = scoped.filter((e) => e.installed).length;
   const current = resolveDefaultEngine(root);
   console.log('');
@@ -954,6 +958,7 @@ function printRoster(root, { scope = 'workspace' } = {}) {
     console.log(`  ${mark} ${engine.id.padEnd(12)} ${state.padEnd(13)} ${engine.tier.padEnd(4)} ${roles}`);
     const details = [`models: ${engine.models.join(', ')}`];
     if (engine.duty) details.push(`duty: ${engine.duty}`);
+    if (engine.health.status === 'cooling') details.push(coolingView(engine).text);
     console.log(`      ${details.join('   ')}`);
   }
   if (scope !== 'global' && list.length > scoped.length) {
@@ -1001,17 +1006,21 @@ function workerRow(step, index, leadIndex) {
   const { worker } = step;
   const runs = worker.error ? null : engineRunsView(worker.engine, { model: worker.model || '', effort: worker.effort || '' });
   const status = index === leadIndex ? 'leads' : step.skip ? 'skipped' : 'backup';
-  const why = step.skip === 'bad line' ? `bad line: ${worker.error}` : step.skip ? WORKER_SKIP_WORDS[step.skip] : '';
+  const why = step.skip === 'bad line' ? `bad line: ${worker.error}`
+    : step.skip === 'cooling' && step.cooling ? step.cooling.text
+      : step.skip ? WORKER_SKIP_WORDS[step.skip] : '';
   return {
     engine: worker.engine || null,
     model: worker.model || null,
     effort: worker.effort || null,
     max_seconds: Number(worker.max_seconds) > 0 ? Number(worker.max_seconds) : null,
+    prep: worker.prep ? rosterJobLabel(worker.prep) : null,
     until: worker.until || null,
     line: worker.line || null,
     ...(worker.error ? { text: worker.text || '' } : {}),
     status,
     why,
+    ...(step.cooling ? { cooling_until: step.cooling.until, cooling_reason: step.cooling.reason } : {}),
     runs,
   };
 }
@@ -1039,7 +1048,8 @@ function jobRosterRow(job, role, root, state, registry, now, key = role) {
   const status = !pick ? 'router'
     : first && first.step.skip === 'expired' ? 'expired'
       : first && leadIndex === first.index ? 'picked'
-        : 'not ready';
+        : first && first.step.skip === 'cooling' ? 'cooling'
+          : 'not ready';
   const lead = leadIndex === -1 ? 'none'
     : first && leadIndex === first.index ? 'first'
       : good[1] && leadIndex === good[1].index ? 'backup'
@@ -1066,12 +1076,15 @@ function jobRosterRow(job, role, root, state, registry, now, key = role) {
     model: resolved.engine && resolved.engine.roster_model ? resolved.engine.roster_model : null,
     effort: resolved.engine && resolved.engine.roster_effort ? resolved.engine.roster_effort : null,
     max_seconds: pick && Number(pick.max_seconds) > 0 ? Number(pick.max_seconds) : null,
+    prep: first && first.step.worker.prep ? rosterJobLabel(first.step.worker.prep) : null,
+    backup_prep: good[1] && good[1].step.worker.prep ? rosterJobLabel(good[1].step.worker.prep) : null,
     runs: runs || nowRuns,
     backup_runs: runsOf(good[1]),
     now_runs: nowRuns,
     workers: walk.map((step, index) => workerRow(step, index, leadIndex)),
     lead,
     status,
+    ...(status === 'cooling' ? { cooling: first.step.cooling.text } : {}),
     reason: resolved.reason,
   };
 }
@@ -1127,12 +1140,19 @@ function renderWorkerLines(row) {
   const width = Math.max(...row.workers.map((worker) => (worker.runs ? worker.runs.text : worker.text || '').length));
   return row.workers.map((worker, index) => {
     const what = (worker.runs ? worker.runs.text : worker.text || '').padEnd(width);
-    const extras = [worker.max_seconds ? rosterMaxText(worker.max_seconds) : '', worker.until ? `until ${worker.until}` : ''].filter(Boolean);
+    const extras = [worker.max_seconds ? rosterMaxText(worker.max_seconds) : '', worker.prep ? `prepped by ${worker.prep}` : '', worker.until ? `until ${worker.until}` : ''].filter(Boolean);
     const state = worker.status === 'leads' ? 'leads now' : worker.status === 'backup' ? 'backup' : `skipped, ${worker.why}`;
     return `  ${index + 1}. ${what} ${[state, ...extras].join(', ')}`.trimEnd();
   });
 }
 
+// Each worker's recent record under its job, only for workers with runs.
+function renderWorkerRecords(row) {
+  return (row.workers || [])
+    .filter((worker) => worker.record)
+    .map((worker) => `  ${worker.runs ? worker.runs.text : worker.engine}: ${worker.record.text}`);
+}
+
 function renderJobRoster(rows) {
   const width = Math.max(7, ...rows.map((row) => row.job.length));
   const ownerWidth = Math.max(24, ...rows.filter((row) => row.pick && row.runs).map((row) => row.runs.text.length));
@@ -1143,16 +1163,18 @@ function renderJobRoster(rows) {
     const fallsTo = `${row.like ? `falls back to ${row.like}` : 'router decides'}: ${nowText}`;
     if (!row.pick) return `${label} no pick, ${fallsTo}`;
     const owner = row.runs.text.padEnd(ownerWidth);
-    const backup = row.backup_runs ? `backup ${row.backup_runs.text}` : 'no backup';
-    const cap = row.max_seconds ? `${rosterMaxText(row.max_seconds)}, ` : '';
+    const backup = row.backup_runs ? `backup ${row.backup_runs.text}${row.backup_prep ? ` prepped by ${row.backup_prep}` : ''}` : 'no backup';
+    const cap = `${row.max_seconds ? `${rosterMaxText(row.max_seconds)}, ` : ''}${row.prep ? `prepped by ${row.prep}, ` : ''}`;
     const date = untilText(row.pick);
     const fallback = row.lead === 'backup' ? 'using backup' : row.lead === 'later' ? `using ${nowText}` : fallsTo;
     const status = row.status === 'expired' ? `expired, ${fallback}`
-      : row.status === 'not ready' ? `not ready, ${fallback}`
-        : date;
+      : row.status === 'cooling' ? `${row.cooling}, ${fallback}`
+        : row.status === 'not ready' ? `not ready, ${fallback}`
+          : date;
     const where = row.file ? `${row.from} (${row.file})` : row.from;
     const head = `${label} ${owner} ${backup.padEnd(backupWidth)} ${cap}${status}, ${where}`.trimEnd();
-    return [head, ...renderWorkerLines(row)].join('\n');
+    const suggestion = row.suggestion ? [`  suggestion: ${row.suggestion.text}`] : [];
+    return [head, ...renderWorkerLines(row), ...renderWorkerRecords(row), ...suggestion].join('\n');
   }).join('\n');
 }
 
@@ -1234,15 +1256,62 @@ function runRosterSessionCommand(rest, json, root, now) {
   return 0;
 }
 
+// Attach each worker's recent record (last 7 days) to the roster report, and
+// at most one suggestion per job when that record says the order is wrong.
+// Only the roster command reads the whole tail of the run file; the boot
+// line reads a smaller tail just to count suggestions. Nothing here writes
+// the roster: a suggestion is a line to read and a command a person may run.
+function attachRunRecords(report, root, now = new Date()) {
+  const runs = readRosterRuns(root, { now, days: RUN_DAYS });
+  if (!runs.length) return report;
+  for (const row of report.jobs || []) {
+    for (const worker of row.workers || []) {
+      if (!worker.engine) continue;
+      const record = summarizeRuns(workerRuns(runs, { job: row.key || row.job, engine: worker.engine, model: worker.model || '' }), { days: RUN_DAYS });
+      if (record) worker.record = record;
+    }
+  }
+  attachSuggestions(report.jobs, runs);
+  return report;
+}
+
+const RUNS_LIST_DAYS = 30;
+const RUNS_LIST_LIMIT = 20;
+
+// The recent attempts, newest first, one plain line each.
+function runRosterRunsCommand(job, json, root, now) {
+  const runs = recentRuns(readRosterRuns(root, { now, days: RUNS_LIST_DAYS }), { job, limit: RUNS_LIST_LIMIT });
+  if (json) {
+    console.log(JSON.stringify({ job: job || null, days: RUNS_LIST_DAYS, runs }, null, 2));
+    return 0;
+  }
+  if (!runs.length) {
+    console.log(job ? `no ${job} runs recorded in the last ${RUNS_LIST_DAYS} days` : `no runs recorded in the last ${RUNS_LIST_DAYS} days`);
+    return 0;
+  }
+  console.log([`recent ${job ? `${job} ` : ''}runs, newest first`, ...runs.map(renderRunLine)].join('\n'));
+  return 0;
+}
+
 function runRosterCommand(args, root, now = new Date()) {
   const json = args.includes('--json');
   const available = args.includes('--available');
+  const runsAt = args.indexOf('--runs');
+  if (runsAt !== -1) {
+    const other = args.slice(0, runsAt).filter((arg) => arg !== '--json');
+    const job = args.slice(runsAt + 1).filter((arg) => !String(arg).startsWith('--')).join(' ').trim();
+    if (other.length || available) {
+      console.error('usage: atris engine roster --runs [job] [--json]');
+      return 2;
+    }
+    return runRosterRunsCommand(job, json, root, now);
+  }
   const rest = args.filter((arg) => arg !== '--json' && arg !== '--available');
   const known = !rest.length
     || (rest.length === 1 && ['confirm', 'session'].includes(rest[0]))
     || (rest.length === 2 && rest[0] === 'session' && rest[1] === 'clear');
   if (!known || (available && rest.length)) {
-    console.error('usage: atris engine roster [confirm | session [clear] | --available] [--json]');
+    console.error('usage: atris engine roster [confirm | session [clear] | --available | --runs [job]] [--json]');
     return 2;
   }
   if (available) {
@@ -1252,13 +1321,13 @@ function runRosterCommand(args, root, now = new Date()) {
   }
   if (rest[0] === 'session') return runRosterSessionCommand(rest, json, root, now);
   if (rest[0] === 'confirm') confirmRoster(root, now);
-  const report = rosterReport(root, now);
+  const report = attachRunRecords(rosterReport(root, now), root, now);
   if (json) console.log(JSON.stringify(report, null, 2));
   else console.log(`${renderRosterReport(report)}\n\n${AVAILABLE_HINT}`);
   return 0;
 }
 
-const ASSIGN_USAGE = 'usage: atris engine assign <job> <tool> [--model <m>] [--effort low|medium|high|xhigh|max] [--max "20 min"] [--days <n>] [--add] [--backup "<tool> [model]"] [--like search|build|review] [--session | --everywhere], or atris engine assign <job> --remove <tool> | --clear. jobs live in atris/ROSTER.md (~/.atris/ROSTER.md with --everywhere, this shell only with --session) and you can edit that file any time';
+const ASSIGN_USAGE = 'usage: atris engine assign <job> <tool> [--model <m>] [--effort low|medium|high|xhigh|max] [--max "20 min"] [--prep <job>] [--days <n>] [--add] [--backup "<tool> [model]"] [--like search|build|review] [--session | --everywhere], atris engine assign <job> --promote "<tool> [model]" to move an existing worker to the top unchanged, or atris engine assign <job> --remove <tool> | --clear. jobs live in atris/ROSTER.md (~/.atris/ROSTER.md with --everywhere, this shell only with --session) and you can edit that file any time';
 
 function runAssignCommand(args, root, now = new Date()) {
   const job = args[0] && !String(args[0]).startsWith('--') ? args[0] : '';
@@ -1283,13 +1352,14 @@ function runAssignCommand(args, root, now = new Date()) {
   const flags = {};
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
-    if (!['--model', '--backup', '--days', '--like', '--effort', '--max', '--remove'].includes(arg) || !rest[i + 1] || rest[i + 1].startsWith('--')) {
+    if (!['--model', '--backup', '--days', '--like', '--effort', '--max', '--prep', '--remove', '--promote'].includes(arg) || !rest[i + 1] || rest[i + 1].startsWith('--')) {
       console.error(`invalid assign option "${arg}"`);
       return 2;
     }
     flags[arg.slice(2)] = rest[++i];
   }
   const removing = flags.remove !== undefined;
+  const promoting = flags.promote !== undefined;
   if (clear && (engine || Object.keys(flags).length || add)) {
     console.error('use --clear without an engine or other options');
     return 2;
@@ -1298,12 +1368,16 @@ function runAssignCommand(args, root, now = new Date()) {
     console.error('use --remove <tool> without other options');
     return 2;
   }
-  if (!clear && !removing && !engine) {
+  if (promoting && (engine || Object.keys(flags).length > 1 || add)) {
+    console.error('use --promote "<tool> [model]" without an engine or other options');
+    return 2;
+  }
+  if (!clear && !removing && !promoting && !engine) {
     console.error(ASSIGN_USAGE);
     return 2;
   }
   try {
-    setRosterPick(job, engine, { ...flags, clear, add, session, everywhere, now }, root);
+    setRosterPick(job, engine, { ...flags, clear, add, session, everywhere, now, note: (text) => console.log(text) }, root);
     printJobRoster(root, now);
     return 0;
   } catch (err) {
@@ -1942,8 +2016,8 @@ function runDispatchCommand(args, root) {
       : `engine dispatch: ${err.message}`);
     return 2;
   }
-  // The build line's model, effort, and time cap ride along when the roster
-  // picks this same engine for build.
+  // The build line's model, effort, time cap, and prep job ride along when
+  // the roster picks this same engine for build.
   const pin = rosterPinFor('executor', canonical, root);
   return runDispatchFlight({
     root,
@@ -1955,6 +2029,7 @@ function runDispatchCommand(args, root) {
     ...(pin.roster_model ? { model: pin.roster_model } : {}),
     ...(pin.roster_effort ? { effort: pin.roster_effort } : {}),
     ...(pin.roster_max_seconds ? { maxSeconds: pin.roster_max_seconds } : {}),
+    ...(pin.roster_prep ? { prep: pin.roster_prep } : {}),
   }).then((flight) => {
     if (json) console.log(JSON.stringify(flight, null, 2));
     return flight.paused.length ? 1 : 0;
@@ -2085,7 +2160,7 @@ function engineCommand(args = [], deps = {}) {
     if (sub === 'help' || args.includes('--help') || args.includes('-h')) {
       console.log('\n  atris engine watch [<id>|latest] [--no-follow]\n                           follow one live transcript or list running engine work');
       console.log('\n  long read-only asks: atris engine ask "..." --engine agy --timeout <seconds>\n                           quick asks default to 120 seconds; explicit jobs allow up to 3600\n                           follow live work with atris engine watch latest');
-      console.log('\n  atris engine            roster + current default\n  atris engine roster [--json] show every job and its workers in order: search, build, review, and your own\n  atris engine roster confirm renew every dated worker for 30 days\n  atris engine roster session [clear]\n                           show or drop the roster changes for this shell only\n  atris engine roster --available\n                           tools on this machine and the models each one offers\n  atris engine assign <job> <tool> [--like <kind>] [--model <m>] [--effort <level>] [--max "20 min"] [--backup "<tool> [model]"] [--days <n>] [--add] [--session | --everywhere]\n  atris engine assign <job> --remove <tool> | --clear [--session | --everywhere]\n                           sets the lead worker of the job; --add puts one more at the end; jobs: search, build, review,\n                           or your own like "small build" (--like search|build|review when the name does not say);\n                           --everywhere is for all projects; --session is this shell only (set ATRIS_ROSTER_SESSION=<name>)\n  atris engines --chart   show the fleet as an org chart\n  atris engine list --json [--all] full registry: default + engines with tier, roles, fallback, health (--all includes hidden engines)\n  atris engine set <name> --duty leader|errands|learning [--models "a, b"]\n                           arrange the fleet and save its model policy\n  atris engine resolve <role> or <job> [--json]\n                           choose the best ready engine for navigator|executor|validator or a roster job\n  atris engine health <name> --set ready|not_installed|credit_out\n                           flip runtime health, for example when credits run out\n  atris engine doctor [--json]\n                           probe which engine CLIs are installed here and sync that into health policy\n  atris engine <name>     make that engine the default here\n  atris engine test [name] preflight: run the engine CLI headless, report pass/fail\n  atris engine bench [names...] [--runs N]\n                           ranked latency scoreboard of engine passes\n  atris engine ask "<question>" --engine <name> [--engine <name> ...]\n                           ask several engines in parallel without allowing edits\n  atris engine ask --jobs <jobs.json>\n                           ask different read-only questions in parallel\n  atris engine validate <receipt-path|latest> [--engine <name>]\n                           check ask answers with a different read-only referee\n  atris engine validate scoreboard\n                           show pass rates by worker engine\n  atris engine dispatch <task-id> [<task-id> ...] --engine cursor|codex [--prompt-file <f>] [--yolo]\n                           one-command claim, worktree, build, verify, ship, ready\n  atris engine login <provider> --yes\n                           upload a local provider CLI login to the backend vault\n  atris engine login <provider> --computer [--seat <name>]\n  atris engine login <provider> --business <id> [--seat <name>]\n                           sign in on an Atris computer by device flow\n  atris engine login --list | --remove <provider>\n                           list or remove vaulted provider logins\n  atris engine seats       show which named accounts are ready to work\n  atris engine seed <provider> --business <id>|--user\n                           push a vaulted login onto an Atris computer\n  atris engine reset      back to the house default\n  --engine <name>         one run on that engine (mission run / autopilot / run)\n');
+      console.log('\n  atris engine            roster + current default\n  atris engine roster [--json] show every job and its workers in order: search, build, review, and your own\n  atris engine roster confirm renew every dated worker for 30 days\n  atris engine roster session [clear]\n                           show or drop the roster changes for this shell only\n  atris engine roster --available\n                           tools on this machine and the models each one offers\n  atris engine roster --runs [job]\n                           the last 20 runs, newest first, with tool, model, time, and outcome\n  atris engine assign <job> <tool> [--like <kind>] [--model <m>] [--effort <level>] [--max "20 min"] [--prep <job>] [--backup "<tool> [model]"] [--days <n>] [--add] [--session | --everywhere]\n  atris engine assign <job> --promote "<tool> [model]" | --remove <tool> | --clear [--session | --everywhere]\n                           sets the lead worker of the job; --promote moves one of its workers to the top as written;\n                           --add puts one more at the end; jobs: search, build, review,\n                           or your own like "small build" (--like search|build|review when the name does not say);\n                           --prep search has that job read the task first and hand this worker a short brief;\n                           --everywhere is for all projects; --session is this shell only (set ATRIS_ROSTER_SESSION=<name>)\n  atris engines --chart   show the fleet as an org chart\n  atris engine list --json [--all] full registry: default + engines with tier, roles, fallback, health (--all includes hidden engines)\n  atris engine set <name> --duty leader|errands|learning [--models "a, b"]\n                           arrange the fleet and save its model policy\n  atris engine resolve <role> or <job> [--json]\n                           choose the best ready engine for navigator|executor|validator or a roster job\n  atris engine health <name> --set ready|not_installed|credit_out\n                           flip runtime health, for example when credits run out\n  atris engine doctor [--json]\n                           probe which engine CLIs are installed here and sync that into health policy\n  atris engine <name>     make that engine the default here\n  atris engine test [name] preflight: run the engine CLI headless, report pass/fail\n  atris engine bench [names...] [--runs N]\n                           ranked latency scoreboard of engine passes\n  atris engine ask "<question>" --engine <name> [--engine <name> ...]\n                           ask several engines in parallel without allowing edits\n  atris engine ask --jobs <jobs.json>\n                           ask different read-only questions in parallel\n  atris engine validate <receipt-path|latest> [--engine <name>]\n                           check ask answers with a different read-only referee\n  atris engine validate scoreboard\n                           show pass rates by worker engine\n  atris engine dispatch <task-id> [<task-id> ...] --engine cursor|codex [--prompt-file <f>] [--yolo]\n                           one-command claim, worktree, build, verify, ship, ready\n  atris engine login <provider> --yes\n                           upload a local provider CLI login to the backend vault\n  atris engine login <provider> --computer [--seat <name>]\n  atris engine login <provider> --business <id> [--seat <name>]\n                           sign in on an Atris computer by device flow\n  atris engine login --list | --remove <provider>\n                           list or remove vaulted provider logins\n  atris engine seats       show which named accounts are ready to work\n  atris engine seed <provider> --business <id>|--user\n                           push a vaulted login onto an Atris computer\n  atris engine reset      back to the house default\n  --engine <name>         one run on that engine (mission run / autopilot / run)\n');
       return 0;
     }
     if (isFreshWorkspace(root)) {

package/commands/host.js

@@ -1,14 +1,17 @@
 'use strict';
 
 const { hostAction } = require('../lib/host');
+const { apiRequestJson } = require('../utils/api');
+const { loadCredentials, decodeJwtClaims } = require('../utils/auth');
 
 function parse(argv) {
   const options = {};
   const positionals = [];
-  const flags = new Set(['id', 'name', 'team', 'manager', 'door', 'now', 'started', 'question', 'event-id', 'from', 'text', 'reply-to', 'reply-to-ref', 'ref', 'decision', 'patch', 'expected-revision', 'source', 'evidence', 'reason', 'activity', 'as', 'when', 'at']);
+  const flags = new Set(['id', 'name', 'team', 'manager', 'door', 'now', 'started', 'question', 'event-id', 'from', 'text', 'reply-to', 'reply-to-ref', 'ref', 'decision', 'patch', 'expected-revision', 'source', 'evidence', 'reason', 'activity', 'as', 'when', 'at', 'room', 'slack-business', 'limit']);
   for (let i = 0; i < argv.length; i += 1) {
     const item = argv[i];
     if (item === '--json') { options.json = true; continue; }
+    if (item === '--dry-run') { options.dryRun = true; continue; }
     if (item.startsWith('--')) {
       const key = item.slice(2);
       if (!flags.has(key) || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error(`invalid --${key} value`);
@@ -18,8 +21,49 @@ function parse(argv) {
   return { options, positionals };
 }
 
+async function hostDeliver(root, options = {}, deps = {}) {
+  const { room, slack_business_id: businessId, messages } = hostAction(root, 'delivery');
+  if (!businessId) throw new Error('slack business id is missing; run atris host setup --slack-business <business id>');
+  if (room === 'personal') throw new Error('host delivery is for group rooms only');
+  if (options.limit != null && !/^(0|[1-9]\d*)$/.test(options.limit)) throw new Error('limit must be a non-negative integer');
+  const eligible = messages.filter((message) => /^slack:[UW][A-Z0-9]+$/.test(message.door || '') && message.draft !== true);
+  const selected = eligible.slice(0, options.limit == null ? undefined : Number(options.limit));
+  const result = { sent: 0, skipped: messages.length - eligible.length, failed: 0 };
+  if (options.dryRun) {
+    result.would_send = selected.map((message) => ({ id: message.id, to: message.door.slice(6), kind: message.kind, text: String(message.text).replace(/\s+/g, ' ').slice(0, 80) }));
+    return result;
+  }
+  if (!selected.length) return result;
+  const credentials = (deps.loadCredentials || loadCredentials)();
+  if (!credentials?.token || credentials.source === 'agent_token_file' || decodeJwtClaims(credentials.token)?.type === 'agent_access') {
+    throw new Error('log in as an Atris user with atris login before delivering');
+  }
+  const request = deps.apiRequestJson || apiRequestJson;
+  for (const message of selected) {
+    try {
+      const response = await request(`/business/${encodeURIComponent(businessId)}/host/slack/send`, {
+        method: 'POST', token: credentials.token, retries: 0,
+        body: { slack_user_id: message.door.slice(6), text: message.text, host_message_id: message.id },
+      });
+      if (!response.ok) throw new Error(`${response.status ? `http ${response.status}` : 'network error'}: ${response.error || 'request failed'}`);
+      if (typeof response.data?.ts !== 'string' || !response.data.ts.trim()) throw new Error('response is missing a Slack timestamp');
+      hostAction(root, 'sent', { id: message.id, ref: response.data.ts });
+      result.sent += 1;
+    } catch (error) {
+      result.failed = 1;
+      result.failure = { id: message.id, reason: error.message };
+      break;
+    }
+  }
+  return result;
+}
+
 function human(command, result) {
+  if (command === 'deliver') return result.would_send
+    ? [...result.would_send.map((message) => `${message.to} ${message.kind}: ${message.text}`), `dry run: ${result.would_send.length} would send, ${result.skipped} skipped`].join('\n')
+    : `host delivery: ${result.sent} sent, ${result.skipped} skipped, ${result.failure ? `failed ${result.failure.id}: ${result.failure.reason}` : '0 failed'}`;
   if (command === 'room') return result.text;
+  if (command === 'import') return `import complete: ${result.added} added, ${result.skipped} skipped, ${result.refused} refused, ${result.links_added} links added, ${result.links_skipped} links skipped`;
   if (command === 'due') return result.length ? result.map((entry) => `${entry.name} (${entry.id}) is due for a question.`).join('\n') : 'no questions due';
   if (command === 'outbox') return result.length ? result.map((entry) => `${entry.id} ${entry.kind} to ${entry.to}: ${entry.text}`).join('\n') : 'outbox empty';
   if (command === 'schedule') return result.length ? result.map((entry) => `${entry.attempt_id}: ${entry.names.a} (${entry.a}) and ${entry.names.b} (${entry.b}), ${entry.activity}`).join('\n') : 'no introductions need scheduling';
@@ -36,21 +80,29 @@ function human(command, result) {
   return `${command} complete: ${JSON.stringify(result)}`;
 }
 
-function hostCommand(argv = process.argv.slice(3), root = process.cwd()) {
+function hostCommand(argv = process.argv.slice(3), root = process.cwd(), deps = {}) {
   let jsonOutput = argv.includes('--json');
   try {
     const [command, ...rest] = argv;
     if (!command || command === '--help' || command === '-h') {
-      const usage = 'usage: atris host join|leave|pause|resume|forget|due|ask|receive|card|link|propose|people|outbox|sent|room|view|schedule|scheduled [options]';
+      const usage = 'usage: atris host setup|join|import|leave|pause|resume|forget|due|ask|receive|card|link|propose|people|outbox|deliver|sent|room|view|schedule|scheduled [options]';
       console.log(jsonOutput ? JSON.stringify({ usage }) : usage);
       return;
     }
     const { options, positionals } = parse(rest);
     jsonOutput = options.json;
     const args = { ...options };
+    if (command === 'import') args.file = positionals[0];
     if (['leave', 'pause', 'resume', 'forget', 'ask', 'card', 'sent', 'scheduled'].includes(command)) args.id = positionals[0];
     if (['link', 'propose'].includes(command)) { args.a = positionals[0]; args.b = positionals[1]; }
     if (command === 'receive') args.eventId = options.eventId;
+    if (command === 'deliver') return hostDeliver(root, args, deps).then((result) => {
+      console.log(jsonOutput ? JSON.stringify(result) : human(command, result));
+      if (result.failed) process.exitCode = 1;
+    }).catch((error) => {
+      console.error(jsonOutput ? JSON.stringify({ error: error.message }) : `host: ${error.message}`);
+      process.exitCode = 1;
+    });
     const result = hostAction(root, command, args);
     console.log(jsonOutput ? JSON.stringify(result) : human(command, result));
   } catch (error) {
@@ -59,4 +111,4 @@ function hostCommand(argv = process.argv.slice(3), root = process.cwd()) {
   }
 }
 
-module.exports = { hostCommand };
+module.exports = { hostCommand, hostDeliver, parse };