atris 3.52.0 → 3.55.0

package/commands/teach.js

@@ -1,86 +1,95 @@
 'use strict';
 
 /**
- * atris teach — turn one bad turn into a permanent guard.
+ * atris teach — local cases under ./atris/teach only.
  *
- *   atris teach                          list cases and which ones are guards
- *   atris teach add --id <id> --prompt "…" --require "<fragment>" [--complaint "…"]
- *   atris teach run [<id>]               run one case (or all) and advance state
- *   atris teach guards                   rerun every promoted guard (regression suite)
+ *   atris teach                 list cases in atris/teach
+ *   atris teach <id>            show one case file
+ *   atris teach --help          usage
  *
- * Thin shim over `python -m rl.teach` in the backend venv, which owns the
- * red gate: a case must be observed FAILING before it can become a guard.
- * Nonzero exit means a guard regressed.
+ * Does not call the backend or dump account-global state.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
 
-const BACKEND_ROOT = '/Users/keshavrao/arena/atrisos-backend';
-
-function requireVenvPython() {
-  const venvPython = path.join(BACKEND_ROOT, 'venv/bin/python');
-  if (!fs.existsSync(venvPython)) {
-    console.error(`✗ Backend venv not found: ${venvPython}`);
-    process.exit(1);
-  }
-  return venvPython;
-}
+const TEACH_DIR = path.join('atris', 'teach');
 
 function usage() {
-  console.log('atris teach — a bad turn becomes a failing benchmark, then a guard');
+  console.log('atris teach — local cases under ./atris/teach');
   console.log('');
-  console.log('  atris teach                  list cases (red = not yet fixed, guard = protected)');
-  console.log('  atris teach add …            record a misbehavior as a red case');
-  console.log('  atris teach run [<id>]       run a case; a red case is SUPPOSED to fail');
-  console.log('  atris teach guards           rerun every guard; nonzero exit = regression');
-  console.log('  atris teach drafts           corrections captured from live turns');
-  console.log('  atris teach fix <id>         brief a fix for a reproduced case (--dispatch to run it)');
-  console.log('  atris teach scaffold …       turn a captured correction into a red case');
-  console.log('  atris teach mine             which recorded tick failures could become cases');
+  console.log('  atris teach              list case files in atris/teach');
+  console.log('  atris teach <id>         show atris/teach/<id>.md (or .json)');
+  console.log('  atris teach --help       this help');
   console.log('');
-  console.log('  add flags: --id <kebab> --prompt "…" --require "<fragment>" (repeatable)');
-  console.log('             --complaint "…" --file path=@localfile --forbid-changed-files');
+  console.log('Teach only reads ./atris/teach. It does not call the backend.');
 }
 
-/**
- * Map the operator-facing verbs onto `python -m rl.teach` arguments.
- * Returns null for help.
- */
-function buildArgs(subcommand, args) {
-  if (!subcommand || subcommand === 'list') return ['list'];
-  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') return null;
-  if (subcommand === 'add') return ['add', ...args];
-  if (subcommand === 'guards') return ['run', '--guards', ...args];
-  if (subcommand === 'mine') return ['mine', ...args];
-  if (subcommand === 'drafts') return ['drafts', ...args];
-  if (subcommand === 'fix') {
-    // `atris teach fix <id>` -> `fix --case <id>`
-    if (args.length && !args[0].startsWith('-')) return ['fix', '--case', args[0], ...args.slice(1)];
-    return ['fix', ...args];
-  }
-  if (subcommand === 'scaffold') return ['scaffold', ...args];
-  if (subcommand === 'run') {
-    // `atris teach run <id>` -> `run --case <id>`; bare `run` runs every case.
-    if (args.length && !args[0].startsWith('-')) return ['run', '--case', args[0], ...args.slice(1)];
-    return ['run', ...args];
+function teachRoot(cwd = process.cwd()) {
+  return path.join(path.resolve(cwd), TEACH_DIR);
+}
+
+function listCaseFiles(root) {
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root)
+    .filter((name) => /\.(md|json)$/i.test(name))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function resolveCaseFile(root, id) {
+  const slug = String(id || '').replace(/\.(md|json)$/i, '');
+  for (const ext of ['.md', '.json']) {
+    const candidate = path.join(root, `${slug}${ext}`);
+    if (fs.existsSync(candidate)) return candidate;
   }
-  // `atris teach <id>` is shorthand for running that one case.
-  if (!subcommand.startsWith('-')) return ['run', '--case', subcommand, ...args];
   return null;
 }
 
-module.exports = function teach(subcommand, ...args) {
-  const moduleArgs = buildArgs(subcommand, args);
-  if (moduleArgs === null) {
+function teach(subcommand, ...args) {
+  const cwd = process.cwd();
+  if (!subcommand || subcommand === 'list') {
+    const root = teachRoot(cwd);
+    if (!fs.existsSync(root)) {
+      console.log('no atris/teach folder here. add cases under ./atris/teach.');
+      return 0;
+    }
+    const files = listCaseFiles(root);
+    if (!files.length) {
+      console.log('atris/teach is empty.');
+      return 0;
+    }
+    console.log(`cases in ${TEACH_DIR}:`);
+    for (const name of files) console.log(`  ${name.replace(/\.(md|json)$/i, '')}`);
+    return 0;
+  }
+
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
     usage();
-    return;
+    return 0;
+  }
+
+  if (subcommand === 'add' || subcommand === 'run' || subcommand === 'guards'
+    || subcommand === 'mine' || subcommand === 'drafts' || subcommand === 'fix'
+    || subcommand === 'scaffold') {
+    console.error('atris teach only reads ./atris/teach. backend teach verbs are disabled.');
+    console.error('add a case file under atris/teach/<id>.md and run: atris teach <id>');
+    return 2;
   }
-  const result = spawnSync(requireVenvPython(), ['-m', 'rl.teach', ...moduleArgs], {
-    cwd: path.join(BACKEND_ROOT, 'backend'),
-    stdio: 'inherit',
-  });
-  process.exit(result.status === null ? 1 : result.status);
-};
 
+  const root = teachRoot(cwd);
+  const file = resolveCaseFile(root, subcommand);
+  if (!file) {
+    console.error(`no case "${subcommand}" in ${TEACH_DIR}`);
+    return 1;
+  }
+  const extra = args.join(' ').trim();
+  if (extra && extra !== '--raw') {
+    console.error(`unknown teach option: ${extra}`);
+    return 2;
+  }
+  const body = fs.readFileSync(file, 'utf8');
+  process.stdout.write(body.endsWith('\n') ? body : `${body}\n`);
+  return 0;
+}
+
+module.exports = teach;

package/commands/terminal.js

@@ -27,6 +27,8 @@ const path = require('path');
 const { loadCredentials, abortOnAuthFailure } = require('../utils/auth');
 const { apiRequestJson } = require('../utils/api');
 const { loadBusinesses, saveBusinesses } = require('./business');
+const { requireAccountBound, refuseAccountGlobal } = require('../lib/account-bound');
+const { argsWantHelp, wantsJson } = require('../lib/noninteractive');
 
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -103,17 +105,31 @@ async function terminalAtris() {
   //   atris terminal --help
   const args = process.argv.slice(3);
 
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log('Usage: atris terminal [business] <command> [--timeout N]');
-    console.log('');
-    console.log('  atris terminal example-co "ls /workspace/atris/"');
-    console.log('  atris terminal "find /workspace -name \\"*.md\\""    # auto-detect business');
-    console.log('  atris terminal example-co "rm -rf /workspace/cruft" --timeout 30');
-    console.log('');
-    console.log('  --timeout N    seconds to wait for the command (default 30, max 120)');
-    process.exit(0);
+  if (args.length === 0 || argsWantHelp(args) || wantsJson(args)) {
+    const usage = 'Usage: atris terminal [business] <command> [--timeout N]';
+    if (wantsJson(args)) {
+      console.log(JSON.stringify({
+        ok: false,
+        command: 'terminal',
+        error: 'usage',
+        usage,
+      }, null, 2));
+    } else {
+      console.log(usage);
+      console.log('');
+      console.log('  atris terminal example-co "ls /workspace/atris/"');
+      console.log('  atris terminal "find /workspace -name \\"*.md\\""    # auto-detect business');
+      console.log('  atris terminal example-co "rm -rf /workspace/cruft" --timeout 30');
+      console.log('');
+      console.log('  --timeout N    seconds to wait for the command (default 30, max 120)');
+    }
+    process.exit(2);
   }
 
+  const gate = requireAccountBound(args);
+  if (!gate.ok) process.exit(refuseAccountGlobal());
+  args.splice(0, args.length, ...gate.args);
+
   // Parse --timeout
   let timeoutSec = 30;
   const tIdx = args.indexOf('--timeout');

package/commands/topup.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const { apiRequestJson } = require('../utils/api');
+const { loadCredentials, openBrowser } = require('../utils/auth');
+const {
+  NOT_LOGGED_IN,
+  wantsHelp,
+  wantsJson,
+  tokenFrom,
+  oneLine,
+  printResult,
+  formatDollars,
+  checkoutUrl,
+  parseAmountUsd,
+} = require('../lib/developer-api');
+
+function showTopupHelp() {
+  console.log('usage: atris topup [amount_usd] [--json]');
+  console.log('create a stripe checkout for credits and print the url. default amount is 10.');
+}
+
+async function topupCommand(args = [], deps = {}) {
+  if (wantsHelp(args)) {
+    showTopupHelp();
+    return 0;
+  }
+
+  const json = wantsJson(args);
+  const io = { log: deps.log || console.log, err: deps.err || console.error };
+  const parsed = parseAmountUsd(args, 10);
+  if (!parsed.ok) {
+    printResult({ json, ok: false, error: parsed.error, payload: { ok: false, error: parsed.error } }, io);
+    return 1;
+  }
+
+  const load = deps.loadCredentials || loadCredentials;
+  const request = deps.apiRequestJson || apiRequestJson;
+  const open = deps.openBrowser || openBrowser;
+  const token = tokenFrom(load());
+  if (!token) {
+    printResult({ json, ok: false, error: NOT_LOGGED_IN, payload: { ok: false, error: NOT_LOGGED_IN } }, io);
+    return 1;
+  }
+
+  try {
+    const result = await request('/credits/purchase', {
+      method: 'POST',
+      token,
+      body: { amount_usd: parsed.amount },
+    });
+    if (!result || !result.ok) {
+      const error = oneLine(result && result.error);
+      printResult({ json, ok: false, error, payload: { ok: false, error, status: result && result.status } }, io);
+      return 1;
+    }
+    const data = result.data || {};
+    const url = checkoutUrl(data);
+    if (!url) {
+      const error = 'checkout url was missing from the response';
+      printResult({ json, ok: false, error, payload: { ok: false, error } }, io);
+      return 1;
+    }
+    const credits = data.credits_to_add != null ? data.credits_to_add : parsed.amount * 100;
+    const text = `open this checkout to add ${formatDollars(parsed.amount)} (${credits} credits):\n${url}`;
+    printResult({
+      json,
+      ok: true,
+      text,
+      payload: {
+        ok: true,
+        amount_usd: parsed.amount,
+        credits_to_add: credits,
+        checkout_url: url,
+      },
+    }, io);
+    if (!json) {
+      const tty = deps.isTty != null ? deps.isTty : Boolean(process.stdout && process.stdout.isTTY);
+      if (tty) open(url);
+    }
+    return 0;
+  } catch (error) {
+    const message = oneLine(error && error.message);
+    printResult({ json, ok: false, error: message, payload: { ok: false, error: message } }, io);
+    return 1;
+  }
+}
+
+module.exports = { topupCommand, showTopupHelp };

package/commands/truth.js

@@ -3,13 +3,18 @@
 //   1. .atris/state/missions.jsonl        — mission states (dedupe by id, latest wins)
 //   2. ~/.atris/tasks.db                  — task counts by status, scoped to this workspace unless --all is passed
 //   3. atris/features/*/                  — validate.md frontmatter + newest proof/ receipt age
-//   4. ~/.atris/heartbeat/{registry,state}.json — declared loops vs last_run / fails
+//   4. atris/loops/*.md                   — workspace loops by default; pass --global for ~/.atris/heartbeat
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { execFileSync } = require('child_process');
 const taskDb = require('../lib/task-db');
+const { parseScopeFlag } = require('../lib/cli-scope');
+const {
+  requireAccountBound,
+  refuseAccountGlobal,
+} = require('../lib/account-bound');
 
 const STALE_DAYS = 7;
 
@@ -186,20 +191,61 @@ function loadHeartbeats() {
   });
 }
 
+// Workspace loops live in atris/loops/*.md (not ~/.atris/heartbeat).
+function loadWorkspaceLoops(cwd) {
+  const dir = path.join(cwd, 'atris', 'loops');
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir).sort()) {
+    if (!name.endsWith('.md') || name === 'LOOPS.md' || name === 'TICK.md') continue;
+    const filePath = path.join(dir, name);
+    let text = '';
+    try { text = fs.readFileSync(filePath, 'utf8'); } catch { continue; }
+    const logDates = [...text.matchAll(/^- (\d{4}-\d{2}-\d{2}):/gm)].map((m) => m[1]).sort();
+    let verdict;
+    let lastRunAgeDays = null;
+    if (logDates.length === 0) {
+      verdict = 'never-ran';
+    } else {
+      const newest = logDates[logDates.length - 1];
+      lastRunAgeDays = daysAgo(Date.parse(`${newest}T00:00:00Z`));
+      if (lastRunAgeDays != null && lastRunAgeDays > STALE_DAYS) verdict = 'stale';
+      else verdict = 'proven';
+    }
+    out.push({
+      id: name.replace(/\.md$/, ''),
+      verdict,
+      lastRunAgeDays,
+      fails: 0,
+    });
+  }
+  return out;
+}
+
 function truthCommand(args = []) {
   const cwd = process.cwd();
-  const json = args.includes('--json');
-  const summary = args.includes('--summary');
-  const all = args.includes('--all');
+  const scopeFlag = parseScopeFlag(args);
+  const rest = scopeFlag.args;
+  const json = rest.includes('--json') || args.includes('--json');
+  const summary = rest.includes('--summary') || args.includes('--summary');
+  const all = rest.includes('--all') || args.includes('--all');
+  const hasAtris = fs.existsSync(path.join(cwd, 'atris'));
+
+  // Unbound scratch folders must not dump machine-global heartbeats.
+  // A local atris/ tree (or --global / --account) is enough to continue.
+  if (!hasAtris && !scopeFlag.global) {
+    const gate = requireAccountBound(rest);
+    if (!gate.ok) return refuseAccountGlobal();
+  }
 
   const missions = loadMissions(cwd);
   const taskCounts = loadTaskCounts({ cwd, all });
-  const scope = all
+  const scope = all || scopeFlag.global
     ? { kind: 'global' }
     : { kind: 'workspace', workspace_root: taskCounts.workspaceRoot };
   const tasks = taskCounts.counts;
   const features = loadFeatures(cwd);
-  const heartbeats = loadHeartbeats();
+  const heartbeats = scopeFlag.global ? loadHeartbeats() : loadWorkspaceLoops(cwd);
 
   const featureTally = {};
   for (const f of features) featureTally[f.verdict] = (featureTally[f.verdict] || 0) + 1;

package/commands/usage.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const { apiRequestJson } = require('../utils/api');
+const { loadCredentials } = require('../utils/auth');
+const {
+  NOT_LOGGED_IN,
+  ROLLOUT_MESSAGE,
+  wantsHelp,
+  wantsJson,
+  tokenFrom,
+  isNotFound,
+  oneLine,
+  printResult,
+} = require('../lib/developer-api');
+
+function showUsageHelp() {
+  console.log('usage: atris usage [--json]');
+  console.log('show developer api usage for the logged-in account.');
+}
+
+function renderUsage(data = {}) {
+  const raw = data && typeof data === 'object' ? data : {};
+  const usage = raw.usage && typeof raw.usage === 'object' ? raw.usage : raw;
+  const lines = [];
+  if (raw.agent_name || raw.agent_id) {
+    lines.push(`${raw.agent_name || 'agent'} ${raw.agent_id || ''}`.trim());
+  }
+  const keys = Object.keys(usage).filter((key) => key !== 'agent_name' && key !== 'agent_id');
+  if (keys.length === 0) {
+    lines.push('no usage recorded.');
+    return lines.join('\n');
+  }
+  for (const key of keys) {
+    const value = usage[key];
+    if (value && typeof value === 'object') {
+      lines.push(`${key}: ${oneLine(value)}`);
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+async function usageCommand(args = [], deps = {}) {
+  if (wantsHelp(args)) {
+    showUsageHelp();
+    return 0;
+  }
+
+  const json = wantsJson(args);
+  const io = { log: deps.log || console.log, err: deps.err || console.error };
+  const load = deps.loadCredentials || loadCredentials;
+  const request = deps.apiRequestJson || apiRequestJson;
+  const token = tokenFrom(load());
+  if (!token) {
+    printResult({ json, ok: false, error: NOT_LOGGED_IN, payload: { ok: false, error: NOT_LOGGED_IN } }, io);
+    return 1;
+  }
+
+  try {
+    const result = await request('/developer/usage', { method: 'GET', token });
+    if (isNotFound(result)) {
+      printResult({
+        json,
+        ok: false,
+        error: ROLLOUT_MESSAGE,
+        payload: { ok: false, error: ROLLOUT_MESSAGE, status: 404 },
+      }, io);
+      return 1;
+    }
+    if (!result || !result.ok) {
+      const error = oneLine(result && result.error);
+      printResult({ json, ok: false, error, payload: { ok: false, error, status: result && result.status } }, io);
+      return 1;
+    }
+    const data = result.data || {};
+    printResult({
+      json,
+      ok: true,
+      text: renderUsage(data),
+      payload: { ok: true, ...data },
+    }, io);
+    return 0;
+  } catch (error) {
+    const message = oneLine(error && error.message);
+    printResult({ json, ok: false, error: message, payload: { ok: false, error: message } }, io);
+    return 1;
+  }
+}
+
+module.exports = { usageCommand, showUsageHelp, renderUsage };

package/commands/verify.js

@@ -119,7 +119,7 @@ function verifyWorkspace(cwd, atrisDir) {
   }
   console.log('');
 
-  return results;
+  return results.issues.length === 0 ? 0 : 1;
 }
 
 /**
@@ -208,7 +208,8 @@ function verifyTask(cwd, atrisDir, taskId) {
   }
   console.log('');
 
-  return results;
+  const mapOk = mapCheck.documented !== false;
+  return (passed === total && testPass && mapOk) ? 0 : 1;
 }
 
 /**

package/commands/version.js

@@ -1,9 +1,11 @@
 const fs = require('fs');
 const path = require('path');
+const { rejectUnsupportedJson } = require('../lib/noninteractive');
 
 const PACKAGE_JSON_PATH = path.join(__dirname, '..', 'package.json');
 
-function showVersion() {
+function showVersion(args = process.argv.slice(3)) {
+  rejectUnsupportedJson('version', args);
   try {
     const packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, 'utf8'));
     console.log(`atris v${packageJson.version}`);

package/commands/voice.js

@@ -176,7 +176,11 @@ function voiceCommand(args, options = {}) {
   const subcommand = args[0];
   const stdout = options.stdout || process.stdout;
   const stderr = options.stderr || process.stderr;
-  if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+  if (!subcommand) {
+    showVoiceHelp(stderr);
+    return 2;
+  }
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
     showVoiceHelp(stdout);
     return 0;
   }

package/commands/who.js

@@ -5,6 +5,7 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 
 const { repoRoot } = require('./stream');
+const { parseScopeFlag, pathUnderRoot } = require('../lib/cli-scope');
 const {
   buildWorkforcePresence,
   isFinishedReceipt,
@@ -73,6 +74,34 @@ function collectReceipts(root, fsModule = fs) {
   return receipts;
 }
 
+function processCwds(pids, deps = {}) {
+  const byPid = new Map();
+  const list = (Array.isArray(pids) ? pids : []).map(String).filter(Boolean);
+  if (!list.length) return byPid;
+  const readlink = deps.readlink || fs.readlinkSync;
+  const execFile = deps.execFile || execFileSync;
+  if (process.platform === 'linux') {
+    for (const pid of list) {
+      try { byPid.set(String(pid), readlink(`/proc/${pid}/cwd`)); } catch {}
+    }
+    return byPid;
+  }
+  try {
+    const out = execFile('lsof', ['-a', '-d', 'cwd', '-Fn', '-p', list.join(',')], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    let current = null;
+    for (const line of String(out || '').split(/\r?\n/)) {
+      if (line.startsWith('p')) current = line.slice(1);
+      else if (line.startsWith('n') && current) byPid.set(current, line.slice(1));
+    }
+  } catch {
+    // keep empty map
+  }
+  return byPid;
+}
+
 function collectProcesses(deps = {}) {
   if (Array.isArray(deps.processes)) return deps.processes;
   const execFile = deps.execFile || execFileSync;
@@ -81,24 +110,50 @@ function collectProcesses(deps = {}) {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
     });
-    return parsePsOutput(output);
+    const rows = parsePsOutput(output);
+    const cwdByPid = processCwds(rows.map((row) => row.pid), deps);
+    return rows.map((row) => ({
+      ...row,
+      cwd: cwdByPid.get(String(row.pid)) || null,
+    }));
   } catch {
     return [];
   }
 }
 
+function filterProcessesToWorkspace(processes, root) {
+  const resolved = path.resolve(root);
+  return (Array.isArray(processes) ? processes : []).filter((row) => {
+    if (row.cwd && pathUnderRoot(row.cwd, resolved)) return true;
+    const command = String(row.command || '');
+    return command.includes(resolved) || command.includes(root);
+  });
+}
+
 function collectWorkforcePresence(deps = {}) {
   const fsModule = deps.fs || fs;
   const root = deps.root || repoRoot(deps.cwd || process.cwd());
+  const scope = deps.scope === 'global' ? 'global' : 'workspace';
   const receipts = Array.isArray(deps.receipts) ? deps.receipts : collectReceipts(root, fsModule);
-  return buildWorkforcePresence({
+  let processes;
+  if (Array.isArray(deps.processes)) {
+    // Caller-owned fixture/list: do not re-scope.
+    processes = deps.processes;
+  } else {
+    processes = collectProcesses(deps);
+    if (scope !== 'global') {
+      processes = filterProcessesToWorkspace(processes, root);
+    }
+  }
+  const presence = buildWorkforcePresence({
     nowMs: typeof deps.now === 'function' ? deps.now() : Date.now(),
     staleAfterMs: deps.staleAfterMs,
-    processes: collectProcesses(deps),
+    processes,
     tasks: Array.isArray(deps.tasks) ? deps.tasks : collectTasks(root, fsModule),
     missions: Array.isArray(deps.missions) ? deps.missions : collectMissions(root, fsModule),
     receipts,
   });
+  return { ...presence, scope };
 }
 
 function archiveFinishedRuns(root, receipts, fsModule = fs) {
@@ -132,11 +187,12 @@ function helpText() {
   return [
     'atris who - show local engines and team members from live process and final run state',
     '',
-    'usage: atris who [--json]',
+    'usage: atris who [--json] [--global]',
     'usage: atris who --clear [--json]',
     '',
+    'default scope is this workspace. pass --global for the whole machine.',
     '--clear archives finished run receipts under atris/runs/archive/.',
-  ].join('\n');
+  ].join('\\n');
 }
 
 function whoCommand(args = [], deps = {}) {
@@ -146,25 +202,27 @@ function whoCommand(args = [], deps = {}) {
     write(`${helpText()}\n`);
     return 0;
   }
-  if (args.some((arg) => !['--json', '--clear'].includes(arg))) {
-    error('usage: atris who [--json] [--clear]\n');
+  const scope = parseScopeFlag(args);
+  const rest = scope.args;
+  if (rest.some((arg) => !['--json', '--clear'].includes(arg))) {
+    error('usage: atris who [--json] [--clear] [--global]\n');
     return 2;
   }
 
   const fsModule = deps.fs || fs;
   const root = deps.root || repoRoot(deps.cwd || process.cwd());
   const receipts = Array.isArray(deps.receipts) ? deps.receipts : collectReceipts(root, fsModule);
-  if (args.includes('--clear')) {
+  if (rest.includes('--clear')) {
     const summary = archiveFinishedRuns(root, receipts, fsModule);
-    if (args.includes('--json')) write(`${JSON.stringify(summary, null, 2)}\n`);
+    if (rest.includes('--json')) write(`${JSON.stringify(summary, null, 2)}\n`);
     else if (summary.failed.length) write(`archived ${summary.archived} finished runs; ${summary.failed.length} could not be archived.\n`);
     else if (summary.archived) write(`archived ${summary.archived} finished run${summary.archived === 1 ? '' : 's'} in ${summary.archive_dir}.\n`);
     else write('no finished runs to clear.\n');
     return summary.failed.length ? 1 : 0;
   }
 
-  const presence = collectWorkforcePresence({ ...deps, root, receipts });
-  const output = args.includes('--json')
+  const presence = collectWorkforcePresence({ ...deps, root, receipts, scope: scope.kind });
+  const output = rest.includes('--json')
     ? JSON.stringify(presence, null, 2)
     : renderWorkforcePresence(presence);
   write(`${output}\n`);