atris 3.30.12 → 3.32.0

package/commands/autoland.js

@@ -0,0 +1,379 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const autoland = require('../lib/autoland');
+const { operatorReady, hasAgentJargon } = autoland;
+
+function repoRoot(cwd = process.cwd()) {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  if (result.status !== 0) return cwd;
+  return result.stdout.trim() || cwd;
+}
+
+function projectName(root) {
+  return path.basename(root);
+}
+
+// The digest's "next, if you agree" section: top candidate moves from Atris
+// state, each with the member best suited to own it. Moves that can't explain
+// themselves are counted, not shown. Never blocks the digest.
+function digestNextMoves(root) {
+  try {
+    const { nextMoves } = require('../lib/next-moves');
+    const { resolveFunctionalOwner } = require('../lib/functional-owner');
+    const all = (nextMoves(root, 5) || []).filter((move) => move && move.title);
+    const ready = all.filter((move) => operatorReady(move.title)).slice(0, 3).map((move) => {
+      let owner = null;
+      try { owner = resolveFunctionalOwner({ title: move.title, root })?.owner || null; } catch {}
+      return { title: move.title, owner };
+    });
+    return { moves: ready, unexplained: all.length - ready.length };
+  } catch {
+    return { moves: [], unexplained: 0 };
+  }
+}
+
+function flag(args, name, fallback = '') {
+  const idx = args.indexOf(name);
+  if (idx === -1) return fallback;
+  return args[idx + 1] || fallback;
+}
+
+function runOwnCli(root, cliArgs) {
+  // Always spawn the bin this module shipped with. Resolving through the
+  // target root or a global `atris` breaks whenever the tick runs a project
+  // that isn't the CLI repo on a machine without a global install (CI, cron).
+  const bin = path.resolve(__dirname, '..', 'bin', 'atris.js');
+  const result = spawnSync(process.execPath, [bin, ...cliArgs], { cwd: root, encoding: 'utf8', timeout: 300000 });
+  return { status: result.status, stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };
+}
+
+function readProjection(root) {
+  try {
+    const raw = fs.readFileSync(path.join(root, '.atris', 'state', 'tasks.projection.json'), 'utf8');
+    const projection = JSON.parse(raw);
+    return Array.isArray(projection.tasks) ? projection.tasks : [];
+  } catch (err) {
+    return [];
+  }
+}
+
+function landSummarySafe(root) {
+  try {
+    return require('./land').landSummary(root);
+  } catch (err) {
+    return null;
+  }
+}
+
+function evaluateQueue(root, { strictVerify }) {
+  const cliArgs = ['task', 'auto-accept-certified', '--dry-run', '--json', '--limit', '50'];
+  if (strictVerify) cliArgs.push('--strict-verify');
+  const result = runOwnCli(root, cliArgs);
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return Array.isArray(parsed.results) ? parsed.results : [];
+  } catch (err) {
+    return [];
+  }
+}
+
+function plainReason(reason) {
+  const map = {
+    denied_tag_billing: 'money — yours to approve',
+    denied_tag_deploy: 'a deploy — yours to approve',
+    denied_tag_security: 'security — yours to approve',
+    denied_tag_customer: 'customer-facing — yours to approve',
+    denied_tag_external: 'outward-facing — yours to approve',
+    denied_tag_feedback: 'customer feedback — yours to approve',
+    denied_tag_voice: 'voice/comms — yours to approve',
+    needs_second_reviewer_or_third_pass: 'needs one more independent check first',
+    not_agent_certified: 'not certified yet',
+    insufficient_review_passes: 'not enough review passes yet',
+    strict_verify_missing: 'no recorded check command to re-run',
+    verify_failed: 'its check command failed on re-run',
+    proof_unmerged_or_draft_pr_boundary: 'its proof points at an unmerged draft',
+  };
+  return map[reason] || reason.replace(/_/g, ' ');
+}
+
+function showStatus(root, args) {
+  const json = args.includes('--json');
+  const policy = autoland.readPolicy(root);
+  const enabled = Boolean(policy && policy.enabled);
+  const strictVerify = policy ? policy.strict_verify !== false : true;
+  const results = evaluateQueue(root, { strictVerify })
+    .filter((r) => r.reason !== 'not_in_review');
+  const wouldLand = results.filter((r) => r.action === 'would_accept');
+  const blocked = results.filter((r) => r.action !== 'would_accept');
+  const tasks = readProjection(root);
+  const waiting = autoland.waitingOnHuman(tasks);
+
+  if (json) {
+    console.log(JSON.stringify({
+      enabled,
+      policy,
+      heartbeat_installed: autoland.cronInstalled(root),
+      would_land: wouldLand,
+      blocked,
+      waiting_on_human: waiting,
+    }, null, 2));
+    return 0;
+  }
+
+  console.log('');
+  console.log(`autoland — certified work lands itself; you keep the irreversible calls`);
+  console.log('');
+  console.log(`  policy: ${enabled ? `on (flipped by ${policy.enabled_by}${policy.enabled_at ? ` on ${String(policy.enabled_at).slice(0, 10)}` : ''})` : 'off — everything waits for you'}`);
+  console.log(`  heartbeat: ${autoland.cronInstalled(root) ? 'running hourly' : 'not installed'}`);
+  if (policy && policy.imessage_to) console.log(`  daily message: ${policy.imessage_to} at ${policy.digest_hour ?? autoland.DEFAULT_DIGEST_HOUR}:00`);
+  console.log('');
+  if (wouldLand.length > 0) {
+    console.log(`  ready to land on their own: ${wouldLand.length}`);
+    for (const r of wouldLand.slice(0, 10)) console.log(`    lands itself  ${r.ref}`);
+  } else {
+    console.log('  nothing is ready to land on its own right now.');
+  }
+  const humanOnly = blocked.filter((r) => String(r.reason || '').startsWith('denied_tag_'));
+  const needsWork = blocked.filter((r) => !String(r.reason || '').startsWith('denied_tag_'));
+  if (humanOnly.length > 0) {
+    console.log(`  yours to approve (protected lanes): ${humanOnly.length}`);
+    for (const r of humanOnly.slice(0, 10)) console.log(`    waits for you  ${r.ref} — ${plainReason(r.reason)}`);
+  }
+  if (needsWork.length > 0) {
+    console.log(`  not ready yet: ${needsWork.length}`);
+    for (const r of needsWork.slice(0, 10)) console.log(`    held back      ${r.ref} — ${plainReason(String(r.reason || ''))}`);
+  }
+  if (waiting.length > 0) {
+    console.log('');
+    console.log(`  waiting on a human right now: ${waiting.length}, oldest ${waiting[0].hours}h`);
+  }
+  console.log('');
+  if (!enabled) console.log("  flip it on: atris autoland on   (one decision; everything after is receipts)");
+  console.log('');
+  return 0;
+}
+
+function turnOn(root, args) {
+  const owner = flag(args, '--as', os.userInfo().username);
+  const to = flag(args, '--to', '');
+  const digestHour = Number(flag(args, '--digest-hour', autoland.DEFAULT_DIGEST_HOUR));
+  const alarmHours = Number(flag(args, '--alarm-hours', autoland.DEFAULT_ALARM_HOURS));
+  const policy = autoland.writePolicy(root, {
+    enabled: true,
+    enabled_by: owner,
+    enabled_at: new Date().toISOString(),
+    imessage_to: to || null,
+    digest_hour: Number.isFinite(digestHour) ? digestHour : autoland.DEFAULT_DIGEST_HOUR,
+    alarm_hours: Number.isFinite(alarmHours) && alarmHours > 0 ? alarmHours : autoland.DEFAULT_ALARM_HOURS,
+    strict_verify: !args.includes('--no-strict-verify'),
+  });
+  const cronOk = autoland.installCron(root);
+  console.log('');
+  console.log('autoland is on.');
+  console.log(`  certified, verified, reversible work now lands itself, accepted as ${owner}.`);
+  console.log('  protected lanes (money, deploys, security, customer, outward) still wait for you.');
+  console.log(`  heartbeat: ${cronOk ? 'installed, runs hourly' : 'could not install cron — run atris autoland tick yourself'}`);
+  if (policy.imessage_to) {
+    console.log(`  daily message to ${policy.imessage_to} at ${policy.digest_hour}:00; anything waiting on you past ${policy.alarm_hours}h pings you.`);
+  } else {
+    console.log('  no phone number set — digest goes to the log only. add one: atris autoland on --to <your number>');
+  }
+  console.log('  turn it off any time: atris autoland off');
+  console.log('');
+  return 0;
+}
+
+function turnOff(root) {
+  const policy = autoland.readPolicy(root) || {};
+  autoland.writePolicy(root, { ...policy, enabled: false, disabled_at: new Date().toISOString() });
+  const cronOk = autoland.uninstallCron(root);
+  console.log('');
+  console.log('autoland is off. everything waits for your accept again.');
+  console.log(`  heartbeat ${cronOk ? 'removed' : 'removal failed — check crontab -l'}.`);
+  console.log('');
+  return 0;
+}
+
+function runDigest(root, args, { forceSend = false } = {}) {
+  const policy = autoland.readPolicy(root) || {};
+  const tasks = readProjection(root);
+  const accepted = autoland.acceptedInLastDay(tasks);
+  const text = autoland.composeDigest({
+    accepted,
+    waiting: autoland.waitingOnHuman(tasks),
+    landed: landSummarySafe(root),
+    project: projectName(root),
+    nextMoves: digestNextMoves(root),
+  });
+  console.log(text);
+  // the full story: what each piece actually was, in its own words
+  const byRef = new Map(tasks.map((t) => [t.display_id || t.legacy_ref || t.id, t]));
+  const storied = accepted.auto.filter((item) => {
+    const t = byRef.get(item.ref);
+    return t && (t.review?.landing?.happened || t.metadata?.landing_happened);
+  });
+  if (storied.length > 0) {
+    let printedStoryHeader = false;
+    for (const item of storied) {
+      const t = byRef.get(item.ref);
+      const happened = String(t.review?.landing?.happened || t.metadata?.landing_happened || '').replace(/\s+/g, ' ').slice(0, 160);
+      if (!operatorReady(happened)) continue;
+      if (!printedStoryHeader) {
+        console.log('');
+        printedStoryHeader = true;
+      }
+      console.log(`  ${item.ref}  ${happened}`);
+    }
+  }
+  const shouldSend = (forceSend || args.includes('--send')) && policy.imessage_to;
+  if (shouldSend) {
+    const sent = autoland.sendImessage(root, policy.imessage_to, text);
+    console.log(sent.ok ? `(sent to ${policy.imessage_to})` : `(send failed: ${sent.output})`);
+    return sent.ok ? 0 : 1;
+  }
+  return 0;
+}
+
+function runTick(root, args) {
+  const json = args.includes('--json');
+  const policy = autoland.readPolicy(root);
+  const receipt = { at: new Date().toISOString(), landed: [], alarms: 0, digest_sent: false, enabled: Boolean(policy && policy.enabled) };
+  if (!policy || policy.enabled !== true) {
+    if (json) console.log(JSON.stringify(receipt));
+    else console.log('autoland is off; tick did nothing.');
+    return 0;
+  }
+
+  // 1. certify what has executable proof — re-run the runnable check named in
+  // each Review proof as a second actor. Without this the tick only lands rows
+  // some always-on mission happened to certify, and everything else waits on a
+  // human who never needed to look. Denied lanes and check-less proofs still wait.
+  if (policy.drain_reviews !== false) {
+    const certify = runOwnCli(root, ['task', 'certify-verified', '--json']);
+    try {
+      const parsed = JSON.parse(certify.stdout);
+      receipt.reviews_certified = parsed.certified ?? 0;
+      if (parsed.ok !== true) receipt.certify_error = 'certify-verified failed';
+    } catch {
+      receipt.certify_error = certify.stderr.slice(0, 200) || 'certify-verified output unreadable';
+    }
+  }
+
+  // 2. land what is eligible — the policy is the standing authorization
+  const cliArgs = ['task', 'auto-accept-certified', '--json', '--limit', '12'];
+  if (policy.strict_verify !== false) cliArgs.push('--strict-verify');
+  const accept = runOwnCli(root, cliArgs);
+  try {
+    const parsed = JSON.parse(accept.stdout);
+    receipt.landed = (parsed.results || []).filter((r) => r.action === 'accepted').map((r) => r.ref);
+  } catch (err) {
+    receipt.accept_error = accept.stderr.slice(0, 200) || 'auto-accept output unreadable';
+  }
+
+  // 2b. tell the operator the moment something lands: one text, one landing
+  // sentence per piece (the day-one PM sentence written at finish time),
+  // capped at three with the rest counted. Off with live_updates: false.
+  const tasksForLive = readProjection(root);
+  if (receipt.landed.length > 0 && policy.imessage_to && policy.live_updates !== false) {
+    const text = autoland.composeLiveUpdate({
+      landedRefs: receipt.landed,
+      tasks: tasksForLive,
+      project: projectName(root),
+    });
+    if (text) {
+      const sent = autoland.sendImessage(root, policy.imessage_to, text);
+      receipt.live_update_sent = sent.ok;
+    }
+  }
+
+  // 3. alarm on anything waiting on a human past the line
+  const state = autoland.readState(root);
+  const tasks = readProjection(root);
+  const waiting = autoland.waitingOnHuman(tasks);
+  const alarmHours = Number(policy.alarm_hours) || autoland.DEFAULT_ALARM_HOURS;
+  const due = autoland.dueForAlarm(waiting, state, { alarmHours });
+  if (due.length > 0 && policy.imessage_to) {
+    const text = autoland.composeAlarm({ waiting: due, project: projectName(root), alarmHours });
+    const sent = autoland.sendImessage(root, policy.imessage_to, text);
+    if (sent.ok) {
+      autoland.markAlerted(state, due);
+      receipt.alarms = due.length;
+    }
+  }
+
+  // 4. daily digest at the configured hour
+  const today = new Date().toISOString().slice(0, 10);
+  const digestHour = Number(policy.digest_hour ?? autoland.DEFAULT_DIGEST_HOUR);
+  if (new Date().getHours() === digestHour && state.last_digest_date !== today) {
+    const text = autoland.composeDigest({
+      accepted: autoland.acceptedInLastDay(tasks),
+      waiting,
+      landed: landSummarySafe(root),
+      project: projectName(root),
+      nextMoves: digestNextMoves(root),
+    });
+    if (policy.imessage_to) {
+      const sent = autoland.sendImessage(root, policy.imessage_to, text);
+      receipt.digest_sent = sent.ok;
+    }
+    receipt.digest_text = text;
+    state.last_digest_date = today;
+
+    // 5. once a day, keep the receipt shelf lean: compress old run receipts
+    // into the manifest and drop unreferenced clutter, newest 200 kept.
+    const prune = runOwnCli(root, ['mission', 'prune-runs', '--apply', '--days', '14', '--keep-newest', '200', '--json']);
+    try {
+      const pruned = JSON.parse(prune.stdout);
+      receipt.receipts_pruned = pruned.pruned_count ?? pruned.pruned ?? pruned.removed ?? 0;
+    } catch {
+      receipt.receipts_pruned = null;
+    }
+  }
+  autoland.writeState(root, state);
+
+  if (json) console.log(JSON.stringify(receipt));
+  else {
+    console.log(`autoland tick: ${receipt.reviews_certified ?? 0} reviews certified, ${receipt.landed.length} landed${receipt.landed.length ? ` (${receipt.landed.join(', ')})` : ''}, ${receipt.alarms} alarms, digest ${receipt.digest_sent ? 'sent' : 'not due'}`);
+  }
+  return 0;
+}
+
+function showHelp() {
+  console.log('');
+  console.log('atris autoland — you approve the policy once; certified work lands itself');
+  console.log('');
+  console.log('finished work that passed its checks and two independent reviews lands');
+  console.log('automatically with a receipt. money, deploys, security, customer, and');
+  console.log('outward-facing work always waits for you.');
+  console.log('');
+  console.log('  atris autoland                     what would land, what waits for you');
+  console.log('  atris autoland on [--to <phone>]   flip it on: hourly heartbeat, daily');
+  console.log('                                     message, ping when something waits');
+  console.log('                                     on you past 24h');
+  console.log('  atris autoland off                 back to approving every item');
+  console.log('  atris autoland digest [--send]     the daily message, now');
+  console.log('  atris autoland tick                one heartbeat (what the hourly cron runs)');
+  console.log('');
+  return 0;
+}
+
+function autolandCommand(args = []) {
+  const [sub, ...rest] = args;
+  if (!sub || sub.startsWith('--')) return showStatus(repoRoot(), args);
+  if (sub === 'help' || sub === '--help' || sub === '-h') return showHelp();
+  const root = repoRoot();
+  if (sub === 'on') return turnOn(root, rest);
+  if (sub === 'off') return turnOff(root);
+  if (sub === 'tick') return runTick(root, rest);
+  if (sub === 'digest') return runDigest(root, rest);
+  if (sub === 'status') return showStatus(root, rest);
+  console.error(`atris autoland: unknown subcommand '${sub}' (try: atris autoland help)`);
+  return 1;
+}
+
+module.exports = { autolandCommand, operatorReady, hasAgentJargon };

package/commands/autopilot-front.js

@@ -0,0 +1,273 @@
+// atris autopilot: point it at the workspace and it keeps going.
+// Each leg picks the most logical work — a moving mission first, then a
+// member choosing useful work, then a self-chosen mission — and drives it
+// through the mission runtime. It loops until stopped:
+//   atris autopilot stop   (from any terminal)  or Ctrl-C here.
+// The old suggest→justify→execute loop lives on behind `atris autopilot --legacy`.
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { pickRunnableMission, runBudgetSeconds } = require('./run-front');
+
+const CLI_PATH = path.join(__dirname, '..', 'bin', 'atris.js');
+const DEFAULT_LEG_WALL_SECONDS = 3600;
+const LEG_TICKS = 12;
+const FAST_FAIL_SECONDS = 30;
+const MAX_FAST_FAILS = 5;
+
+function statePath(root) { return path.join(root, '.atris', 'state', 'autopilot.json'); }
+function stopPath(root) { return path.join(root, '.atris', 'state', 'autopilot.stop'); }
+
+function readState(root) {
+  try { return JSON.parse(fs.readFileSync(statePath(root), 'utf8')); } catch { return null; }
+}
+
+function writeState(root, state) {
+  fs.mkdirSync(path.dirname(statePath(root)), { recursive: true });
+  fs.writeFileSync(statePath(root), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function clearState(root) {
+  try { fs.unlinkSync(statePath(root)); } catch {}
+}
+
+function stopRequested(root) { return fs.existsSync(stopPath(root)); }
+function requestStop(root) {
+  fs.mkdirSync(path.dirname(stopPath(root)), { recursive: true });
+  fs.writeFileSync(stopPath(root), `${new Date().toISOString()}\n`);
+}
+function clearStop(root) { try { fs.unlinkSync(stopPath(root)); } catch {} }
+
+function pidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function readValueFlag(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 && index + 1 < args.length ? args[index + 1] : null;
+}
+
+function positiveNumber(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+// Most logical member: the one who owns the newest mission, else the first
+// member on the team. Null when the workspace has no members yet.
+function pickMember(root, preferredOwner = '') {
+  let members = [];
+  try {
+    const { findAllMembers } = require('./member');
+    members = findAllMembers(path.join(root, 'atris', 'team')) || [];
+  } catch {
+    return null;
+  }
+  if (!members.length) return null;
+  const owner = String(preferredOwner || '').trim().toLowerCase();
+  if (owner) {
+    const owned = members.find((member) => String(member?.name || '').trim().toLowerCase() === owner);
+    if (owned) return owned.name;
+  }
+  return members[0]?.name || null;
+}
+
+function newestMissionOwner(root) {
+  let map;
+  try { map = require('./mission').loadMissionMap(root); } catch { return ''; }
+  const newest = Array.from(map.values())
+    .sort((a, b) => String(b?.updated_at || b?.created_at || '').localeCompare(String(a?.updated_at || a?.created_at || '')));
+  return newest[0]?.owner || '';
+}
+
+function legPlan(root, legWallSeconds) {
+  const mission = pickRunnableMission(root);
+  if (mission) {
+    return {
+      kind: 'mission',
+      label: `mission ${mission.id}: ${mission.objective}`,
+      args: ['mission', 'run', mission.id, '--max-ticks', String(LEG_TICKS), '--max-wall', String(legWallSeconds), '--complete-on-pass'],
+    };
+  }
+  const member = pickMember(root, newestMissionOwner(root));
+  if (member) {
+    // --runner atris2: member run defaults to codex_goal, which waits for a
+    // live Codex session; a headless leg would tick it without doing work.
+    return {
+      kind: 'member',
+      label: `member ${member} chooses useful work`,
+      args: ['member', 'run', member, '--runner', 'atris2', '--minutes', String(Math.max(5, Math.round(legWallSeconds / 60)))],
+    };
+  }
+  return {
+    kind: 'auto-mission',
+    label: 'self-chosen mission from Atris state',
+    args: [
+      'mission', 'run',
+      'Choose one bounded useful task from Atris state, complete it, and show plain proof.',
+      '--owner', 'mission-lead',
+      '--runner', 'atris2',
+      '--max-ticks', String(LEG_TICKS),
+      '--max-wall', String(legWallSeconds),
+    ],
+  };
+}
+
+function driveLeg(root, legArgs, current) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CLI_PATH, ...legArgs], { cwd: root, stdio: 'inherit' });
+    current.child = child;
+    // Stop fast: a stop file written by `atris autopilot stop` in another
+    // terminal terminates the running leg, not just the loop between legs.
+    const poll = setInterval(() => {
+      if (stopRequested(root)) { try { child.kill('SIGTERM'); } catch {} }
+    }, 2000);
+    if (poll.unref) poll.unref();
+    const finish = (code) => {
+      clearInterval(poll);
+      current.child = null;
+      resolve(Number.isFinite(code) ? code : 1);
+    };
+    child.on('error', () => finish(1));
+    child.on('close', finish);
+  });
+}
+
+function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+
+function autopilotStop(root = process.cwd()) {
+  requestStop(root);
+  const state = readState(root);
+  if (state && pidAlive(state.pid)) {
+    try { process.kill(state.pid, 'SIGTERM'); } catch {}
+    console.log(`Stopping autopilot (pid ${state.pid}).`);
+  } else {
+    console.log('No live autopilot process; stop marker written so the next start clears it.');
+  }
+  return 0;
+}
+
+function autopilotStatus(root = process.cwd()) {
+  const state = readState(root);
+  if (!state) { console.log('Autopilot is not running.'); return 0; }
+  const alive = pidAlive(state.pid);
+  console.log(`Autopilot ${alive ? 'running' : 'not running (stale state)'} — pid ${state.pid}, started ${state.started_at}, legs ${state.legs || 0}`);
+  if (state.current_leg) console.log(`Current leg: ${state.current_leg}`);
+  if (!alive) clearState(root);
+  return 0;
+}
+
+function showFrontHelp() {
+  console.log('');
+  console.log('Usage: atris autopilot [options]');
+  console.log('');
+  console.log('Keeps the workspace moving: picks the most logical mission or member,');
+  console.log('drives it through the mission runtime, then picks the next one.');
+  console.log('Runs until you stop it.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --minutes N | --hours N   Total budget (default: unlimited)');
+  console.log('  --leg-wall N              Seconds per leg (default: 3600)');
+  console.log('  --once                    Run a single leg, then exit');
+  console.log('  --legacy                  Old suggest→justify→execute loop');
+  console.log('');
+  console.log('Control:');
+  console.log('  atris autopilot stop      Stop fast, from any terminal');
+  console.log('  atris autopilot status    Show what the loop is doing');
+  console.log('');
+}
+
+async function autopilotFront(args = []) {
+  const root = process.cwd();
+  if (args[0] === 'stop') return autopilotStop(root);
+  if (args[0] === 'status') return autopilotStatus(root);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') { showFrontHelp(); return 0; }
+
+  const existing = readState(root);
+  if (existing && pidAlive(existing.pid) && existing.pid !== process.pid) {
+    console.log(`Autopilot already running (pid ${existing.pid}). Stop it first: atris autopilot stop`);
+    return 1;
+  }
+
+  clearStop(root);
+  const budgetSeconds = runBudgetSeconds(args);
+  const legWallDefault = positiveNumber(readValueFlag(args, '--leg-wall')) || DEFAULT_LEG_WALL_SECONDS;
+  const once = args.includes('--once');
+  const startedAt = Date.now();
+  const state = { pid: process.pid, started_at: new Date().toISOString(), legs: 0 };
+  writeState(root, state);
+
+  const current = { child: null };
+  // `autopilot stop` SIGTERMs this pid directly, so the farewell must print
+  // here — the signal always beats the loop's own stop-file check.
+  const onSignal = () => {
+    if (current.child) { try { current.child.kill('SIGTERM'); } catch {} }
+    const reason = stopRequested(root) ? 'stop requested' : 'interrupted';
+    console.log(`\nAutopilot off (${reason}). Legs run: ${state.legs}.`);
+    clearState(root);
+    clearStop(root);
+    process.exit(130);
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  console.log('Autopilot on. Stop anytime: Ctrl-C here, or `atris autopilot stop` anywhere.');
+
+  let fastFails = 0;
+  let stopReason = '';
+  while (true) {
+    if (stopRequested(root)) { stopReason = 'stop requested'; break; }
+    const elapsed = Math.round((Date.now() - startedAt) / 1000);
+    if (budgetSeconds && elapsed >= budgetSeconds) { stopReason = 'budget spent'; break; }
+    const legWall = budgetSeconds ? Math.min(legWallDefault, budgetSeconds - elapsed) : legWallDefault;
+
+    const plan = legPlan(root, Math.max(60, legWall));
+    state.legs += 1;
+    state.current_leg = plan.label;
+    state.updated_at = new Date().toISOString();
+    writeState(root, state);
+    console.log(`\nautopilot leg ${state.legs}: ${plan.label}`);
+
+    const legStarted = Date.now();
+    const code = await driveLeg(root, plan.args, current);
+    state.last_exit = code;
+    writeState(root, state);
+
+    if (once) { stopReason = 'single leg (--once)'; break; }
+    if (stopRequested(root)) { stopReason = 'stop requested'; break; }
+
+    // A leg that finishes in seconds means no real work happened — a crash,
+    // or a degenerate mission whose ticks record instantly (exit 0). Either
+    // way, back off and stop instead of hot-looping on it.
+    const legSeconds = (Date.now() - legStarted) / 1000;
+    if (legSeconds < FAST_FAIL_SECONDS) {
+      fastFails += 1;
+      if (fastFails >= MAX_FAST_FAILS) {
+        stopReason = `${MAX_FAST_FAILS} fast legs in a row (${code === 0 ? 'no progress' : 'failures'})`;
+        break;
+      }
+      await sleep(code === 0 ? 5000 : 15000);
+    } else {
+      fastFails = 0;
+      await sleep(2000);
+    }
+  }
+
+  clearStop(root);
+  clearState(root);
+  console.log(`\nAutopilot off (${stopReason}). Legs run: ${state.legs}.`);
+  return stopReason.includes('fast legs') ? 1 : 0;
+}
+
+module.exports = {
+  autopilotFront,
+  autopilotStop,
+  autopilotStatus,
+  legPlan,
+  pickMember,
+  stopRequested,
+  requestStop,
+  clearStop,
+  readState,
+  writeState,
+};