atris 3.68.8 → 3.69.0

package/lib/member-autoland.js

@@ -0,0 +1,350 @@
+'use strict';
+
+// After an ignited member run ends with its check passing, hand the branch to
+// GitHub auto-merge. Every local gate fails closed: the branch stays put and
+// one plain line says which gate held it. GitHub then waits for the branch to
+// be up to date and CI green; this never merges, rebases, or polls itself.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const {
+  deniedTagOf,
+  declaredProtectedLane,
+  sniffedProtectedLane,
+} = require('./auto-accept-certified');
+const { isDecisionHoldTag, isDecisionTask } = require('./task-decision');
+
+// Git replacement refs can make a local check read different code than the
+// commit that gets pushed; every git and gh call here ignores them.
+function run(cmd, args, cwd) {
+  const env = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' };
+  const res = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: 120000, env });
+  return {
+    ok: res.status === 0,
+    stdout: String(res.stdout || '').trim(),
+    stderr: String(res.stderr || res.error?.message || '').trim(),
+  };
+}
+
+// The policy lives in the main checkout, not the mission's worktree copy.
+function mainCheckoutRoot(cwd) {
+  const common = run('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+  if (!common.ok || !common.stdout) return null;
+  return path.dirname(common.stdout);
+}
+
+function policyOn(cwd) {
+  const root = mainCheckoutRoot(cwd);
+  if (!root) return false;
+  try {
+    const policy = JSON.parse(fs.readFileSync(path.join(root, '.atris', 'policy', 'autoland.json'), 'utf8'));
+    return Boolean(policy) && typeof policy === 'object' && policy.enabled === true;
+  } catch {
+    return false;
+  }
+}
+
+const TAG_KEYS = new Set(['tag', 'tags', 'todo_tags', 'lane']);
+const METADATA_DEPTH_LIMIT = 6;
+const METADATA_TEXT_CAP = 64 * 1024;
+
+// Every string anywhere in metadata, and the ones anywhere below a tag key.
+// Metadata too deep or too large to read whole returns null, which holds.
+function metadataStrings(metadata) {
+  const texts = [];
+  const tags = [];
+  let size = 0;
+  const walk = (value, depth, tagged) => {
+    if (typeof value === 'string') {
+      size += value.length;
+      texts.push(value);
+      if (tagged) tags.push(value);
+      return size <= METADATA_TEXT_CAP;
+    }
+    if (!value || typeof value !== 'object') return true;
+    if (depth >= METADATA_DEPTH_LIMIT) return false;
+    if (Array.isArray(value)) return value.every((item) => walk(item, depth + 1, tagged));
+    return Object.entries(value).every(([key, item]) => walk(item, depth + 1, tagged || TAG_KEYS.has(key)));
+  };
+  return walk(metadata, 0, false) ? { texts, tags } : null;
+}
+
+// A row's protected lane, or null. Tags are its own tag and lane, every
+// string under a tag key anywhere in metadata, and '#tag' words in the title.
+// Text is the title, objective, and every string in metadata.
+function protectedLane(row) {
+  if (!row || typeof row !== 'object') return 'unreadable';
+  // Metadata is a plain object or absent; anything else, including stored
+  // text that would not parse, cannot be checked.
+  const meta = row.metadata;
+  if (row.metadata_unreadable || (meta !== undefined && meta !== null && (typeof meta !== 'object' || Array.isArray(meta)))) {
+    return 'metadata could not be read';
+  }
+  const found = metadataStrings(meta);
+  if (!found) return 'metadata too large to check';
+  const title = String(row.title || '');
+  const tags = [
+    row.tag,
+    row.lane,
+    ...(Array.isArray(row.tags) ? row.tags : []),
+    ...found.tags,
+    ...(title.match(/#[A-Za-z0-9_-]+/g) || []).map((t) => t.slice(1)),
+  ];
+  // Decision rows wait for a person; the same rule member go's picker uses.
+  if (isDecisionTask(row)) return 'needs a human decision';
+  for (const tag of tags) {
+    const text = String(tag ?? '');
+    if ([text, ...text.split(/[\s,]+/)].some(isDecisionHoldTag)) return 'needs a human decision';
+    const denied = deniedTagOf({ tag: text });
+    if (denied) return denied;
+  }
+  const objective = [title, typeof row.objective === 'string' ? row.objective : '', ...found.texts].filter(Boolean).join('\n');
+  const view = { title, objective, metadata: {} };
+  const declared = declaredProtectedLane(view);
+  if (declared) return `declared "${declared.phrase}"`;
+  const sniffed = sniffedProtectedLane(view);
+  if (sniffed) return sniffed.lane;
+  return null;
+}
+
+// Every task this mission points at, or null when a link is malformed.
+function linkedTaskIds(mission) {
+  const ids = [];
+  if (mission.task_ids !== undefined) {
+    if (!Array.isArray(mission.task_ids)) return null;
+    for (const id of mission.task_ids) {
+      if (typeof id !== 'string' || !id.trim()) return null;
+      ids.push(id.trim());
+    }
+  }
+  const xp = mission.xp_task;
+  if (xp !== undefined && xp !== null && (typeof xp !== 'object' || Array.isArray(xp))) return null;
+  for (const value of [mission.task_id, mission.task_ref, mission.current_task_id, xp?.task_id, xp?.ref]) {
+    if (value === undefined || value === null || value === '') continue;
+    if (typeof value !== 'string' || !value.trim()) return null;
+    ids.push(value.trim());
+  }
+  return [...new Set(ids)];
+}
+
+function defaultLoadTask(id) {
+  try {
+    const taskDb = require('./task-db');
+    return taskDb.getTask(taskDb.open(), id) || null;
+  } catch {
+    return null;
+  }
+}
+
+const RECEIPT_STAMP_RE = /^\d{4}-\d{2}-\d{2}T[0-9-]+Z\.json$/;
+
+// The newest run receipt this mission wrote in its own folder, or null.
+function latestRunReceipt(missionId, cwd) {
+  if (typeof missionId !== 'string' || !/^[A-Za-z0-9._-]+$/.test(missionId)) return null;
+  const dir = path.join(cwd, 'atris', 'runs');
+  const prefix = `mission-${missionId}-`;
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const latest = names
+    .filter((name) => name.startsWith(prefix) && RECEIPT_STAMP_RE.test(name.slice(prefix.length)))
+    .sort((a, b) => (a.slice(prefix.length) < b.slice(prefix.length) ? -1 : 1))
+    .pop();
+  if (!latest) return null;
+  try {
+    const receipt = JSON.parse(fs.readFileSync(path.join(dir, latest), 'utf8'));
+    if (!receipt || typeof receipt !== 'object' || receipt.mission_id !== missionId) return null;
+    return receipt;
+  } catch {
+    return null;
+  }
+}
+
+// Review must cover the final code of the final run. The newest receipt for
+// this mission must be a finished run's summary, recorded on a clean folder
+// whose code tree is the one checked out now, with nothing newer in the
+// mission's own state and no commit made after it. Every tick in that run
+// must have passed its check and a verdict from a reviewer engine other than
+// the member and every engine that did the work.
+function reviewHold(mission, workerEngine, cwd, pin = {}) {
+  const receipt = latestRunReceipt(mission.id, cwd);
+  if (!receipt) return 'no run receipt for this mission could be read';
+  const result = receipt.result && typeof receipt.result === 'object' ? receipt.result : {};
+  if (result.kind !== 'mission_run_summary') return 'the latest run has not finished';
+  const receiptAt = Date.parse(receipt.at || '');
+  if (!Number.isFinite(receiptAt)) return 'the latest run receipt has no time';
+  if (receipt.clean !== true) return 'the latest run ended with unsaved changes';
+  const head = run('git', ['rev-parse', 'HEAD^{tree}'], cwd);
+  if (!head.ok || !head.stdout || receipt.git_tree !== head.stdout) {
+    return 'the latest review was not recorded on the code that is checked out now';
+  }
+  const commitTime = run('git', ['log', '-1', '--format=%ct', 'HEAD'], cwd);
+  const committedAt = Number(commitTime.stdout) * 1000;
+  if (!commitTime.ok || !Number.isFinite(committedAt) || committedAt <= 0 || committedAt > receiptAt) {
+    return 'the code was committed after the latest review';
+  }
+
+  const ticks = Array.isArray(result.ticks) ? result.ticks : [];
+  if (!ticks.length || result.tick_count !== ticks.length) return 'no reviewed work is recorded on the latest run';
+  const lastTick = ticks[ticks.length - 1] || {};
+  const lastTickAt = Date.parse(mission.last_tick_at || '');
+  if (!Number.isFinite(lastTickAt) || lastTickAt > receiptAt) return 'the mission ran again after the latest receipt';
+  if (mission.last_tick_status !== 'ran') return 'the mission\'s last step did not finish cleanly';
+  if (mission.last_tick_index !== undefined && mission.last_tick_index !== lastTick.tick_index) {
+    return 'the mission ran again after the latest receipt';
+  }
+
+  const worker = String(workerEngine || mission.runner || '').trim().toLowerCase();
+  if (!worker || worker === 'auto') return 'the engine that did the work is unknown';
+  const self = new Set([mission.owner, worker, ...ticks.map((tick) => tick && tick.engine_id)]
+    .map((v) => String(v || '').trim().toLowerCase()).filter(Boolean));
+  for (const tick of ticks) {
+    if (!tick || typeof tick !== 'object' || tick.status !== 'ran' || tick.verifier_passed !== true) {
+      return 'a step on the latest run did not pass its check';
+    }
+    const referee = tick.referee_result;
+    if (!referee || typeof referee !== 'object' || referee.mode !== 'engine' || referee.passed !== true) {
+      return 'a reviewer on the latest run did not pass it';
+    }
+    const reviewer = String(referee.engine || '').trim().toLowerCase();
+    if (!reviewer || self.has(reviewer)) return 'the latest run was reviewed by the same engine that did the work';
+  }
+  if (lastTick.reviewed_git_tree !== head.stdout) return 'the review did not see the code that is checked out now';
+  pin.tree = head.stdout;
+  return null;
+}
+
+// The checked-out code as git sees it with config tricks switched off: every
+// untracked file listed, submodules compared, no file monitor, and no index
+// entry marked assume-unchanged or skip-worktree (anything but an 'H' tag).
+function gitCodeState(cwd) {
+  const status = run('git', [
+    '-c', 'status.showUntrackedFiles=all', '-c', 'core.fsmonitor=false',
+    'status', '--porcelain', '--untracked-files=all', '--ignore-submodules=none',
+  ], cwd);
+  const index = run('git', ['-c', 'core.fsmonitor=false', 'ls-files', '-v'], cwd);
+  const hidden = !index.ok || index.stdout.split('\n').some((line) => line && !line.startsWith('H '));
+  const tree = run('git', ['rev-parse', 'HEAD^{tree}'], cwd);
+  return {
+    clean: status.ok && !status.stdout && !hidden,
+    hidden,
+    status: status.ok ? status.stdout : null,
+    tree: tree.ok && tree.stdout ? tree.stdout : null,
+  };
+}
+
+// New files Atris writes for itself while a run is going (receipts, state,
+// logs). Changed tracked files always count.
+const BOOKKEEPING = /^\?\? (?:\.atris\/|atris\/(?:runs|status|logs)\/|atris\/team\/[^/]+\/logs\/)/;
+
+function codeStatus(state) {
+  if (!state || state.status == null) return null;
+  return state.status.split('\n').filter((line) => line && !BOOKKEEPING.test(line)).join('\n');
+}
+
+function unsavedHold(cwd) {
+  if (!gitCodeState(cwd).clean) return 'unsaved changes; the check may not match what would merge';
+  return null;
+}
+
+function held(gate, line) {
+  return { merged: false, auto_merge: false, gate, line: `left the branch for you: ${line}` };
+}
+
+function autolandMemberRun({ mission, cwd, summary = '', workerEngine = '', loadTask = defaultLoadTask } = {}) {
+  if (!mission || typeof mission !== 'object') return held('mission', 'the mission could not be read');
+  if (mission.verifier_result?.passed !== true) return held('check', 'the check did not pass');
+  if (!policyOn(cwd)) return held('policy', 'self-landing is not switched on in the main checkout');
+
+  const missionLane = protectedLane({ ...mission, title: mission.objective });
+  if (missionLane) return held('protected', `this mission sits in a protected area (${missionLane})`);
+  const taskIds = linkedTaskIds(mission);
+  if (!taskIds) return held('protected', 'the mission\'s linked tasks are not a clean list of ids');
+  for (const id of taskIds) {
+    let task = null;
+    try {
+      task = loadTask(id, cwd);
+    } catch {
+      task = null;
+    }
+    if (!task || typeof task !== 'object') return held('protected', `a linked task (${id}) could not be read`);
+    const lane = protectedLane(task);
+    if (lane) return held('protected', `a linked task sits in a protected area (${lane})`);
+  }
+
+  const unsaved = unsavedHold(cwd);
+  if (unsaved) return held('unsaved', unsaved);
+  const pin = {};
+  const reviewGap = reviewHold(mission, workerEngine, cwd, pin);
+  if (reviewGap) return held('review', reviewGap);
+  // Pin the commit the review passed on. Only this commit is pushed and
+  // merged, so a commit made after this point never rides along.
+  const headRead = run('git', ['rev-parse', 'HEAD'], cwd);
+  const headSha = headRead.ok ? headRead.stdout : '';
+  if (!/^[0-9a-f]{40,64}$/.test(headSha)) return held('branch', 'the latest commit could not be read');
+  const pinnedTree = () => {
+    const tree = run('git', ['rev-parse', `${headSha}^{tree}`], cwd);
+    return tree.ok && tree.stdout === pin.tree;
+  };
+  if (!pin.tree || !pinnedTree()) return held('review', 'the code moved while the review was being checked');
+
+  const branchRead = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+  const branch = String(mission.worktree?.branch || branchRead.stdout || '').trim();
+  if (!branch || branch === 'HEAD' || branch === 'master' || branch === 'main') {
+    return held('branch', 'the work is not on its own branch');
+  }
+  const remoteHead = run('git', ['ls-remote', '--symref', 'origin', 'HEAD'], cwd);
+  const base = (remoteHead.stdout.match(/^ref: refs\/heads\/(\S+)\s+HEAD$/m) || [])[1] || '';
+  if (!remoteHead.ok || !base) return held('base', 'the main branch on GitHub could not be read');
+  if (branch === base) return held('branch', 'the work is not on its own branch');
+
+  if (!pinnedTree()) return held('review', 'the reviewed commit no longer holds the reviewed code');
+  const push = run('git', ['push', 'origin', `${headSha}:refs/heads/${branch}`], cwd);
+  if (!push.ok) return held('push', `the branch could not be pushed (${push.stderr.split('\n')[0]})`);
+
+  // Find the open pull request from exactly this branch into the main
+  // branch, or open one. Merge is always addressed by number, never by a
+  // branch name gh might read as a number, and pinned to the pushed commit.
+  const listed = run('gh', [
+    'pr', 'list', '--head', branch, '--base', base, '--state', 'open',
+    '--json', 'number,headRefName,baseRefName,headRefOid,isCrossRepository',
+  ], cwd);
+  if (!listed.ok) return held('pull request', `open pull requests could not be read (${listed.stderr.split('\n')[0]})`);
+  let rows;
+  try {
+    rows = JSON.parse(listed.stdout || '[]');
+  } catch {
+    rows = null;
+  }
+  if (!Array.isArray(rows)) return held('pull request', 'open pull requests could not be read');
+  const matches = rows.filter((pr) => pr && pr.headRefName === branch && pr.baseRefName === base
+    && pr.isCrossRepository === false && Number.isInteger(pr.number) && pr.number > 0);
+  if (matches.length > 1) return held('pull request', 'more than one pull request is open for this branch');
+  let number = matches.length ? matches[0].number : 0;
+  let url = '';
+  if (!number) {
+    const title = String(mission.objective || branch).replace(/\s+/g, ' ').trim().slice(0, 70);
+    const body = String(summary || '').trim() || `Receipt: ${mission.receipt_path || 'none recorded'}`;
+    const created = run('gh', ['pr', 'create', '--head', branch, '--base', base, '--title', title, '--body', body], cwd);
+    url = created.ok ? created.stdout.split('\n').pop().trim() : '';
+    number = Number((url.match(/\/pull\/(\d+)$/) || [])[1] || 0);
+    if (!created.ok || !number) {
+      return held('pull request', `the pull request could not be opened (${(created.stderr || url).split('\n')[0]})`);
+    }
+  }
+  const label = url || `pull request #${number}`;
+
+  const merge = run('gh', ['pr', 'merge', String(number), '--auto', '--merge', '--match-head-commit', headSha], cwd);
+  if (!merge.ok) return held('auto-merge', `auto-merge could not be switched on for ${label}`);
+  return { merged: false, auto_merge: true, gate: null, url: label, line: `merges on its own once checks pass: ${label}` };
+}
+
+module.exports = {
+  autolandMemberRun,
+  codeStatus,
+  gitCodeState,
+};

package/lib/member-board.js

@@ -7,6 +7,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { RUN_TAG, runMarker } = require('./member-progress');
 
 const QUIET_AFTER_MS = 2 * 60 * 1000;
 const HIDE_DONE_AFTER_MS = 60 * 60 * 1000;
@@ -38,7 +39,23 @@ function parseLine(raw) {
   if (!m) return null;
   const at = Date.parse(m[1]);
   if (Number.isNaN(at)) return null;
-  return { at, text: m[3] };
+  return { at, mission: m[2], text: m[3] };
+}
+
+// "started: [pid 4242 engine claude] job" -> { pid, engine, job }. Older
+// lines have no tag, so pid stays null and the board cannot say if it lives.
+function parseStarted(text) {
+  const body = String(text || '').replace(/^started:\s*/, '');
+  const m = RUN_TAG.exec(body);
+  if (!m) return { pid: null, engine: '', run: '', job: body };
+  return { pid: Number(m[1]), engine: m[2] || '', run: m[3] || '', job: body.slice(m[0].length) };
+}
+
+// Signal 0 checks a process exists without touching it. EPERM means it
+// exists but belongs to someone else, which still counts as alive.
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
 }
 
 function cut(text, width) {
@@ -46,12 +63,16 @@ function cut(text, width) {
   return s.length > width ? `${s.slice(0, width - 3)}...` : s;
 }
 
-function ago(ms) {
+function span(ms) {
   const s = Math.max(0, Math.floor(ms / 1000));
-  if (s < 60) return `${s}s ago`;
-  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
-  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
-  return `${Math.floor(s / 86400)}d ago`;
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+function ago(ms) {
+  return `${span(ms)} ago`;
 }
 
 function escapeRe(s) {
@@ -61,7 +82,7 @@ function escapeRe(s) {
 // The current run is everything from the latest "started:" line on.
 // Steps that only write the member's own log are housekeeping, so the last
 // step column skips them unless nothing else happened.
-function memberRow(name, text, now) {
+function currentRun(text) {
   const lines = text.split('\n').map(parseLine).filter(Boolean);
   if (!lines.length) return null;
   let start = 0;
@@ -71,18 +92,35 @@ function memberRow(name, text, now) {
   const run = lines.slice(start);
   const startedLine = run[0].text.startsWith('started:') ? run[0] : null;
   const finished = [...run].reverse().find((l) => l.text.startsWith('finished:'));
+  // A stop wins over the runner's own "finished: failed" that may land first.
+  const stopped = run.some((l) => /^finished:\s*stopped\b/.test(l.text));
+  return { run, startedLine, finished, stopped, meta: parseStarted(startedLine ? startedLine.text : '') };
+}
+
+function memberRow(name, text, now) {
+  const current = currentRun(text);
+  if (!current) return null;
+  const { run, startedLine, finished, stopped, meta } = current;
   const ownLog = new RegExp(`atris/team/${escapeRe(name)}/logs\\b`);
   const steps = run.filter((l) => !l.text.startsWith('started:') && !l.text.startsWith('finished:'));
   const real = steps.filter((l) => !ownLog.test(l.text));
   const step = real[real.length - 1] || steps[steps.length - 1];
   const last = run[run.length - 1];
+  const alive = finished || meta.pid === null ? null : isAlive(meta.pid);
   let state;
-  if (finished) state = /^finished:\s*ok\b/.test(finished.text) ? 'done ok' : 'done failed';
+  if (stopped) state = 'stopped';
+  else if (finished) state = /^finished:\s*ok\b/.test(finished.text) ? 'done ok' : 'done failed';
+  else if (alive === false) state = 'stopped';
   else state = now - last.at < QUIET_AFTER_MS ? 'working' : 'quiet';
   return {
     member: name,
     state,
-    job: startedLine ? cut(startedLine.text.slice('started:'.length), JOB_WIDTH) : '',
+    pid: meta.pid,
+    engine: meta.engine,
+    // null when the started line has no pid; false once the run is over.
+    alive: meta.pid === null ? null : alive === true,
+    running_for: alive ? span(now - startedLine.at) : '',
+    job: startedLine ? cut(meta.job, JOB_WIDTH) : '',
     step: step ? cut(step.text, STEP_WIDTH) : '',
     ago: ago(now - last.at),
     at: last.at,
@@ -107,15 +145,21 @@ function readBoard({ dir = progressDir(), now = Date.now(), all = false } = {})
 function renderBoard(rows, dir = progressDir(), hidden = 0) {
   const note = hidden ? `${hidden} finished over an hour ago, hidden. --all shows them` : '';
   if (!rows.length) return note ? `nobody is working right now. ${note}` : `no member progress yet in ${dir}`;
-  const w = (key, min) => Math.max(min, ...rows.map((r) => r[key].length));
-  const nameW = w('member', 6);
-  const stateW = w('state', 5);
-  const agoW = w('ago', 3);
-  const jobW = Math.max(3, ...rows.map((r) => (r.job || '-').length));
-  const pad = (s, n) => s.padEnd(n);
-  const line = (a, b, c, d, e) => `${pad(a, nameW)}  ${pad(b, stateW)}  ${pad(c, agoW)}  ${pad(d, jobW)}  ${e}`.trimEnd();
-  const out = [line('member', 'state', 'ago', 'job', 'last step')];
-  for (const r of rows) out.push(line(r.member, r.state, r.ago, r.job || '-', r.step || '-'));
+  const cells = rows.map((r) => [
+    r.member,
+    r.state,
+    r.alive === null ? '-' : (r.alive ? 'yes' : 'no'),
+    r.engine || '-',
+    r.running_for || '-',
+    r.ago,
+    r.job || '-',
+    r.step || '-',
+  ]);
+  const head = ['member', 'state', 'alive', 'engine', 'running for', 'ago', 'job', 'last step'];
+  const widths = head.map((h, i) => Math.max(h.length, ...cells.map((c) => c[i].length)));
+  const line = (c) => c.map((v, i) => (i === c.length - 1 ? v : v.padEnd(widths[i]))).join('  ').trimEnd();
+  const out = [line(head)];
+  for (const c of cells) out.push(line(c));
   if (note) out.push('', note);
   return out.join('\n');
 }
@@ -141,6 +185,11 @@ function progressEvent(member, raw) {
   if (tagged) {
     event.kind = tagged[1];
     event.text = tagged[2];
+    if (tagged[1] === 'started') {
+      const meta = parseStarted(tagged[2]);
+      event.text = meta.job;
+      if (meta.pid !== null) { event.pid = meta.pid; event.engine = meta.engine; }
+    }
     if (tagged[1] === 'finished') event.ok = /^ok\b/.test(tagged[2]);
   }
   return event;
@@ -167,13 +216,13 @@ function afterLastNewline(file) {
   } catch { return 0; } finally { fs.closeSync(fd); }
 }
 
-function followBoard({ dir = progressDir(), emit, pollMs = 1000 } = {}) {
+function followBoard({ dir = progressDir(), emit, pollMs = 1000, orderByTime = false } = {}) {
   const offsets = new Map();
   const sizeOf = (file) => { try { return fs.statSync(file).size; } catch { return null; } };
   const list = () => { try { return fs.readdirSync(dir).filter((f) => f.endsWith('.log')); } catch { return []; } };
   for (const f of list()) offsets.set(f, afterLastNewline(path.join(dir, f)));
 
-  function readNew(f) {
+  function readNew(f, events) {
     const file = path.join(dir, f);
     const size = sizeOf(file);
     if (size === null) return;
@@ -195,7 +244,7 @@ function followBoard({ dir = progressDir(), emit, pollMs = 1000 } = {}) {
     const member = f.slice(0, -'.log'.length);
     for (const raw of buf.subarray(0, end).toString('utf8').split('\n')) {
       const event = progressEvent(member, raw.replace(/\r$/, ''));
-      if (event) emit(event);
+      if (event) events.push(event);
     }
   }
 
@@ -209,7 +258,10 @@ function followBoard({ dir = progressDir(), emit, pollMs = 1000 } = {}) {
         watcher.on('error', () => { try { watcher.close(); } catch {} watcher = null; });
       } catch { watcher = null; }
     }
-    for (const f of list()) readNew(f);
+    const events = [];
+    for (const f of list()) readNew(f, events);
+    if (orderByTime) events.sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+    for (const event of events) emit(event);
   }
   const timer = setInterval(scan, pollMs);
   scan();
@@ -223,6 +275,109 @@ function followBoard({ dir = progressDir(), emit, pollMs = 1000 } = {}) {
   };
 }
 
+// Stop a member's live run: SIGTERM its process group (the engine is spawned
+// detached, so the group is the run and everything it started), wait up to
+// graceMs, then SIGKILL whatever is left. Writes "finished: stopped" so the
+// board stops counting it. Resolves { ok, message } with one plain line.
+function signalRun(pid, sig) {
+  try { process.kill(-pid, sig); return; } catch {}
+  try { process.kill(pid, sig); } catch {}
+}
+
+function runAlive(pid) {
+  try { process.kill(-pid, 0); return true; } catch (e) { if (e.code === 'EPERM') return true; }
+  return isAlive(pid);
+}
+
+// Engines a member run can be, and the program name each one runs as.
+const ENGINE_PROGRAMS = Object.freeze({
+  claude: ['claude'], fable: ['claude'], haiku: ['claude'], codex: ['codex'],
+  cursor: ['cursor-agent'], composer: ['cursor-agent'], grok: ['grok'],
+  devin: ['devin'], agy: ['agy'], opencode: ['opencode'],
+});
+
+function readProcess(pid) {
+  const run = (fmt) => require('child_process').spawnSync('ps', ['-o', fmt, '-p', String(pid)], {
+    encoding: 'utf8', timeout: 3000, env: { ...process.env, LC_ALL: 'C', TZ: 'UTC' },
+  });
+  const head = run('pgid=,command=');
+  const born = run('lstart=');
+  if (head.status !== 0 || born.status !== 0) return null;
+  const m = /^\s*(\d+)\s+(.*)$/s.exec(String(head.stdout || '').trim());
+  const startedAt = Date.parse(`${String(born.stdout || '').trim()} UTC`);
+  return m ? { pgid: Number(m[1]), command: m[2], startedAt: Number.isFinite(startedAt) ? startedAt : null } : null;
+}
+
+// Only signal a pid that is, right now, a known engine program leading its
+// own process group, and never this process's own group or a system pid.
+// The engine process must have started within this many ms of the member's
+// own started line, which binds a stop to that exact run.
+const START_WINDOW_MS = 30000;
+
+function pidRunsEngine(pid, engine, deps = {}, startedLineAt = null, member = '', run = '') {
+  if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid) return false;
+  const key = String(engine || '').trim().toLowerCase();
+  if (!Object.prototype.hasOwnProperty.call(ENGINE_PROGRAMS, key)) return false;
+  const programs = ENGINE_PROGRAMS[key];
+  const info = (deps.readProcess || readProcess)(pid);
+  if (!info || info.pgid !== pid) return false;
+  if (!Number.isFinite(startedLineAt) || !Number.isFinite(info.startedAt)
+    || Math.abs(info.startedAt - startedLineAt) > START_WINDOW_MS) return false;
+  const ownGroup = (deps.readProcess || readProcess)(process.pid);
+  if (ownGroup && ownGroup.pgid === pid) return false;
+  const program = path.basename(String(info.command).trim().split(/\s+/)[0] || '');
+  if (!programs.includes(program)) return false;
+  // The run token proves the process is this member's run: it is on the first
+  // line of the engine's prompt and in no other member's log.
+  if (!/^[0-9a-f]{16}$/.test(String(run || '')) || !member) return false;
+  // The marker must open the engine's prompt: right after its -p flag, as
+  // whole words, so a command that merely mentions it does not count.
+  const escaped = runMarker(member, run).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // The program, then -p, then the marker: nothing earlier can carry it. ps on
+  // macOS prints the prompt's line break as the four characters \\012.
+  if (!new RegExp(`^\\S+\\s+-p\\s+${escaped}(?=\\s|\\\\012|\\?|$)`).test(String(info.command))) return false;
+  return { startedAt: info.startedAt, command: info.command };
+}
+
+async function stopMember(name, { dir = progressDir(), graceMs = 10000, pollMs = 100, now = () => Date.now(), deps = {} } = {}) {
+  const nothing = { ok: false, message: 'nothing running' };
+  const member = String(name || '').trim();
+  if (!member || !/^[A-Za-z0-9._-]+$/.test(member)) return nothing;
+  const file = path.join(dir, `${member}.log`);
+  let text = '';
+  try { text = readTail(file); } catch { return nothing; }
+  const current = currentRun(text);
+  if (!current || current.finished || !current.startedLine) return nothing;
+  const { pid, engine, run } = current.meta;
+  if (pid === null || !runAlive(pid)) return nothing;
+  // A pid from a run that died without a finished line can be reused by an
+  // unrelated program; only signal it while its command is still the engine.
+  const identity = pidRunsEngine(pid, engine, deps, current.startedLine.at, member, run);
+  if (!identity) return nothing;
+
+  const startedAt = current.startedLine.at;
+  signalRun(pid, 'SIGTERM');
+  const deadline = now() + graceMs;
+  // Poll on timers, not a busy loop, so a test parent can reap its child.
+  while (runAlive(pid) && now() < deadline) await new Promise((r) => setTimeout(r, pollMs));
+  // Check identity again before the hard kill: the pid may have been reused.
+  // Before the hard kill, the process must be the very same one: same start
+  // time and same command, token included.
+  const again = runAlive(pid) && pidRunsEngine(pid, engine, deps, current.startedLine.at, member, run);
+  const forced = Boolean(again) && again.startedAt === identity.startedAt && again.command === identity.command;
+  if (forced) signalRun(pid, 'SIGKILL');
+
+  const mission = current.startedLine.mission || '-';
+  try { fs.appendFileSync(file, `${new Date().toISOString()} ${mission} finished: stopped\n`, 'utf8'); } catch {}
+  const how = forced ? ', it had to be forced' : '';
+  return { ok: true, pid, forced, message: `stopped ${member} after ${span(now() - startedAt)} of work${how}` };
+}
+
+async function memberStopCommand(name) {
+  const result = await stopMember(name);
+  console.log(result.message);
+}
+
 function memberBoardCommand(...args) {
   const asJson = args.includes('--json');
   const all = args.includes('--all');
@@ -260,4 +415,7 @@ function memberBoardCommand(...args) {
   });
 }
 
-module.exports = { readBoard, renderBoard, memberRow, ago, progressEvent, followBoard, memberBoardCommand };
+module.exports = {
+  readBoard, renderBoard, memberRow, ago, progressEvent, followBoard, memberBoardCommand,
+  parseStarted, isAlive, stopMember, memberStopCommand,
+};