atris 3.77.0 → 3.79.0

package/lib/held-pull-requests.js

@@ -234,15 +234,16 @@ const GIT_REPOSITORY_VARIABLES = [
 
 // Which repository a workspace came from: the owner and name its origin remote points at, asked of
 // git in the workspace's own folder. Null when git cannot say (no folder, no origin) or the remote
-// does not read as a GitHub repository.
-function originRepoOf(root, { run = spawnSync } = {}) {
+// does not read as a GitHub repository. `run` and `timeoutMs` (10 seconds unless told) are for the
+// caller that holds git to a limit of its own, and for tests.
+function originRepoOf(root, { run = spawnSync, timeoutMs = 10000 } = {}) {
   if (!root) return null;
   const env = { ...process.env };
   for (const key of GIT_REPOSITORY_VARIABLES) delete env[key];
   const done = run('git', ['-C', String(root), 'remote', 'get-url', 'origin'], {
     encoding: 'utf8',
     env,
-    timeout: 10000,
+    timeout: timeoutMs,
     killSignal: 'SIGKILL',
     stdio: ['ignore', 'pipe', 'ignore'],
   }) || {};
@@ -289,6 +290,14 @@ function leftAloneDetail(reason) {
   return 'it changed while GitHub was being asked, so it was left alone';
 }
 
+// The jobs among `rows` that wait on a pull request, oldest first (by when they were made, then by row id).
+// The order is the order the sweep goes through them in.
+function heldJobsAmong(taskStore, rows) {
+  return rows
+    .filter((row) => row.status === 'review' && taskStore.heldPullRequestOf(row))
+    .sort((a, b) => (Number(a.created_at || 0) - Number(b.created_at || 0)) || String(a.id).localeCompare(String(b.id)));
+}
+
 // Check every held job against GitHub and, unless dryRun, write down what happened.
 //
 //   taskStore      lib/task-db
@@ -298,6 +307,21 @@ function leftAloneDetail(reason) {
 //   ask            how to ask GitHub about a link (askGitHub); asked once per link per run
 //   askBranch      how to ask GitHub for a repository's default branch (askDefaultBranch); asked
 //                  once per repository per run, and only for a pull request that was merged
+//   askOrigin      how to read the repository a workspace came from (originRepoOf); asked once per
+//                  workspace per run, and only for a pull request that was merged or closed
+//   only           a row id: sweep that one job and none of the others (the automatic run goes job
+//                  by job, to say each result as it is made)
+//   listing        task rows already read. Given, this call lists and numbers nothing itself, and `only`
+//                  still picks from it. A job in it is named by its number if the row has one (display_id or
+//                  legacy_ref) and by its id if it has not. The automatic run reads the workspace once for the
+//                  whole run and hands each call its job, because it prints no task number and so has none to
+//                  make. Left out, as the manual sweep leaves it, this call lists and numbers the workspace
+//                  itself.
+//   nameOf         how a refusal names the other job that has the pull request, given its row id. Left
+//                  out, the name is the one that job has in its own workspace's numbering, which lists
+//                  that workspace's tasks and so can start git when checkouts are linked to it. The
+//                  automatic run, which says nothing of a refusal and keeps to a time limit, gives the
+//                  row id itself.
 //
 // Returns { ok, action, dry_run, scope, actor, outage, summary, results }. ok is false only on
 // an outage. Each result is { task_id, ref, title, builder, workspace_root, pull_request,
@@ -305,15 +329,18 @@ function leftAloneDetail(reason) {
 // unknown or not_asked, and action is what was done: landed, released, would_land,
 // would_release, none, left_alone, or refused (the pull request is not this job's build: nothing
 // was written, and detail is the plain line saying why).
-function sweepHeldJobs(taskStore, db, { workspaceRoot = null, actor, dryRun = false, ask = askGitHub, askBranch = askDefaultBranch } = {}) {
+function sweepHeldJobs(taskStore, db, { workspaceRoot = null, actor, dryRun = false, ask = askGitHub, askBranch = askDefaultBranch, askOrigin = originRepoOf, only = null, nameOf = null, listing = null } = {}) {
   if (!actor) throw new Error('actor required');
   const scope = workspaceRoot ? 'workspace' : 'everywhere';
-  // No task list yet means nothing is held.
-  const inScope = db ? taskStore.listTasks(db, { workspaceRoot: workspaceRoot || null }) : [];
-  const held = inScope
-    .filter((row) => row.status === 'review' && taskStore.heldPullRequestOf(row))
-    .sort((a, b) => (Number(a.created_at || 0) - Number(b.created_at || 0)) || String(a.id).localeCompare(String(b.id)));
-  const named = taskStore.withTaskDisplayRefs(held, inScope);
+  let named;
+  if (listing) {
+    named = heldJobsAmong(taskStore, listing).filter((row) => !only || row.id === only);
+  } else {
+    // No task list yet means nothing is held.
+    const inScope = db ? taskStore.listTasks(db, { workspaceRoot: workspaceRoot || null }) : [];
+    const held = heldJobsAmong(taskStore, inScope).filter((row) => !only || row.id === only);
+    named = taskStore.withTaskDisplayRefs(held, inScope);
+  }
 
   // Each question goes to GitHub once per run, whatever the answer: a failure is not asked again.
   const answers = new Map();
@@ -347,17 +374,17 @@ function sweepHeldJobs(taskStore, db, { workspaceRoot = null, actor, dryRun = fa
   // A workspace's origin is read once per run, and only if a pull request needs it.
   const origins = new Map();
   const originOf = (root) => {
-    if (!origins.has(root)) origins.set(root, originRepoOf(root));
+    if (!origins.has(root)) origins.set(root, askOrigin(root));
     return origins.get(root);
   };
 
-  // The name a person reads for a job, in its own workspace's numbering.
-  const refOfJob = (id) => {
+  // The name a person reads for a job, in its own workspace's numbering, unless the caller names jobs itself.
+  const refOfJob = nameOf || ((id) => {
     const task = taskStore.getTask(db, id);
     if (!task) return String(id);
     const [shown] = taskStore.withTaskDisplayRefs([task], taskStore.listTasks(db, { workspaceRoot: task.workspace_root || null }));
     return (shown && (shown.display_id || shown.legacy_ref || shown.id)) || String(id);
-  };
+  });
   // Why this pull request is not this job's to settle, when another job has it.
   const takenReason = (taken, answer) => (taken.how === 'landed'
     ? `pull request ${answer.number} in ${answer.repo} already landed with ${refOfJob(taken.id)}`
@@ -586,4 +613,4 @@ function describeHeldSweep(report) {
   return lines;
 }
 
-module.exports = { ASK_TIMEOUT_MS, askGitHub, askDefaultBranch, branchNamesJob, originRepoOf, sweepHeldJobs, describeHeldSweep };
+module.exports = { ASK_TIMEOUT_MS, askGitHub, askDefaultBranch, branchNamesJob, heldJobsAmong, originRepoOf, sweepHeldJobs, describeHeldSweep };

package/lib/landing-check.js

@@ -0,0 +1,296 @@
+'use strict';
+
+// Whether a landing really landed. The rating counts a job as landed when its record says it merged. The
+// builder picker steers by that count, so it asks more of each landing, and it asks git, on this computer:
+//
+//   One. The commit the record names is on origin's default branch. The branch is listed once (git rev-list, back to
+//        a day before the earliest claim the caller will ask about), and every commit is looked up in that list.
+//        However many landings there are, git is asked the same few questions, and no process is started for any one
+//        landing.
+//   Two. The commit is no older than the claim it lands, allowing five minutes for clocks that disagree. Work
+//        that was already on the branch before the job began is not what the job landed. Every commit is read
+//        in one batched call (git rev-list --stdin), however many landings there are.
+//   Three. No other job recorded the same commit first. The check does not know jobs: the caller passes
+//        `owns(commit)`, and a landing counts only when one of its commits is the caller's to claim.
+//
+// The default branch is the one origin/HEAD names, and nothing else: origin/main and origin/master are never
+// guessed, because a repository whose default branch is something else would be checked against the wrong
+// branch without a word. When origin/HEAD is not set, or names a branch this folder does not have, no landing can be
+// checked here and the reason names the fix (git remote set-head origin --auto). The same goes for a folder
+// that is not a git repository, a computer without git, and a folder with no origin.
+//
+// Before anything is counted, refresh() fetches origin's default branch once (and only that branch), so a merge
+// that happened a minute ago is known. The fetch names where the branch goes (+refs/heads/<branch>:refs/remotes/
+// origin/<branch>), so the ref that is checked is the ref that was fetched, whatever the repository's own fetch
+// settings say. If the fetch fails or takes too long, no landing can be checked, and the reason says so. Everything
+// else asks only about this computer's repository; the fetch is the one question that goes out, and it is marked so
+// a stand-in for git can tell it apart.
+//
+// Everything git does before a pick shares one budget of five seconds, counted from the first question: each
+// question is given what is left of it, the question about the person's ssh settings and the fetch included. When it
+// is gone nothing more is asked, and no landing can be checked. Git never prompts a person: its standard input is
+// closed, GIT_TERMINAL_PROMPT is 0, and the fetch runs ssh in batch mode (-o BatchMode=yes). A person's own ssh
+// command (GIT_SSH_COMMAND, GIT_SSH or core.sshCommand) is not replaced: the fetch runs it as it is, the five
+// seconds still end it, and notes() says so in one line.
+//
+// A landing with no commit, a commit git cannot find or that sits on a side branch only, a commit made before the
+// claim, or one another job recorded first: none of these count as landed. The check changes nothing the rating
+// counts. One check lives for one run: it reads the default branch once, reads each commit once, and looks up
+// each commit in what it read. If git stops answering in time (a hung disk, a lock) or the budget runs out, the
+// check stops asking and cannotCheck() says so: nothing more counts as landed.
+//
+// The limit of listing only the window: `git rev-list --max-age` skips a commit older than the limit and does not
+// walk on to its parents, so a branch whose commit dates run backwards by more than a day (a clock set wrong, a
+// rebase on a machine far behind) can hide commits behind such a commit. A hidden commit is not landed, which is
+// the safe answer. The day on top of the five minutes of skew is what that allowance is.
+
+const { spawnSync } = require('child_process');
+
+const HEX = /^[0-9a-f]{7,64}$/i;
+const COMMIT_KEYS = ['merge_commit', 'merge_commit_sha', 'merge_sha'];
+
+// A folder's own git, not the repository of whatever hook or script started this run.
+const GIT_POINTERS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_NAMESPACE', 'GIT_SHALLOW_FILE', 'GIT_PREFIX'];
+
+// All of git's work before a pick shares this long, as short as the fetch a worktree start makes
+// (commands/worktree.js refreshRemoteRef): it runs before a flight's first job is dealt, and a slow network is
+// answered by dealing in turn, not by waiting.
+const BUDGET_MS = 5000;
+// A commit made up to this long before its claim still counts: two computers' clocks are never quite together.
+const SKEW_MS = 5 * 60 * 1000;
+// The default branch is listed back to this much before the skew allowance, for commits whose dates are out of order.
+const WINDOW_MARGIN_MS = 24 * 60 * 60 * 1000;
+const FIX = 'git remote set-head origin --auto';
+const ORIGIN_BRANCH = /^refs\/remotes\/origin\/([^\s:-][^\s:]*)$/;
+// Run ssh so that it cannot wait on a person (no password, no host-key question).
+const BATCH_SSH = 'ssh -o BatchMode=yes';
+
+// The commits one landing record names, from the same places the rating looks for a merge (the record itself,
+// its landing, its pull request). A merged pull request's merge commit is checked like any other commit.
+function commitsOf(payload) {
+  const record = payload && typeof payload === 'object' ? payload : {};
+  const places = [record, record.landing, record.pull_request, record.pr]
+    .filter((place) => place && typeof place === 'object' && !Array.isArray(place));
+  const found = [];
+  for (const place of places) {
+    for (const key of COMMIT_KEYS) {
+      if (typeof place[key] === 'string' && HEX.test(place[key])) found.push(place[key].toLowerCase());
+    }
+  }
+  return [...new Set(found)];
+}
+
+function cleanEnv(base) {
+  const env = { ...base, GIT_TERMINAL_PROMPT: '0' };
+  for (const key of GIT_POINTERS) delete env[key];
+  return env;
+}
+
+// Start git in `root`. Standard input is closed unless there is text for it, `timeout` is what is left of the budget,
+// and git never prompts. `input` is text for git's standard input. `network` marks the one question that goes out; it
+// is given `ssh` (the ssh command to run, when the check chose one) and keeps the repository's own network settings.
+function runGit(spawn, base, root, args, { input, network = false, ssh = '', timeout } = {}) {
+  const env = cleanEnv(base);
+  if (!network) env.GIT_NO_LAZY_FETCH = '1';
+  if (ssh) env.GIT_SSH_COMMAND = ssh;
+  const done = spawn('git', ['-C', root, ...args], {
+    env,
+    encoding: 'utf8',
+    timeout,
+    killSignal: 'SIGKILL',
+    maxBuffer: 64 * 1024 * 1024,
+    ...(input === undefined ? {} : { input }),
+    stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'],
+  });
+  if (done.error) return { status: -1, stdout: '', missing: done.error.code === 'ENOENT', timedOut: done.error.code === 'ETIMEDOUT' };
+  return { status: done.status, stdout: String(done.stdout || ''), missing: false, timedOut: false };
+}
+
+// `run(root, args, { input, network, ssh, timeout })` stands in for git in tests, and `spawn` for the operating
+// system's way of starting it. They answer { status, stdout, missing, timedOut }. `env` is the environment git
+// runs in (this process's by default), `now` the clock the budget is counted on, and `since` (milliseconds) the
+// earliest claim any landing asked about could have: the default branch is listed back to a day before it.
+function createLandingCheck(root, { run, spawn = spawnSync, env = process.env, now = Date.now, budgetMs = BUDGET_MS, since } = {}) {
+  const gitRun = run || ((dir, args, options) => runGit(spawn, env, dir, args, options));
+  let startedAt = null;    // the first question starts the budget
+  let spent = false;       // the budget is used up, or git did not answer in time: no more questions are asked
+  let target = null;       // { ref, branch }, or { problem }: looked up once
+  let fetched = null;      // null until refresh() has run, then '' or why it could not fetch
+  let unreadable = '';     // why the commits, or the default branch, could not be read
+  const told = [];         // what the check did that a person should hear about
+  const sightings = new Map();   // a commit as spelled (lower case) -> { oid, time } or null
+  let onBranch = null;           // the full ids of the commits on the default branch inside the window
+
+  // Every question goes through here, with what is left of the budget. Once git has not answered in time, or the
+  // budget is gone, no more are asked.
+  function ask(args, options = {}) {
+    const silent = { status: -1, stdout: '', missing: false, timedOut: true };
+    if (spent) return silent;
+    if (startedAt === null) startedAt = now();
+    const left = budgetMs - (now() - startedAt);
+    if (left <= 0) {
+      spent = true;
+      return silent;
+    }
+    const answer = gitRun(root, args, { ...options, timeout: left });
+    if (answer.timedOut) spent = true;
+    return answer;
+  }
+
+  // The branch to check against, or why there is none. Looked up once.
+  function look() {
+    if (target) return target;
+    const fail = (problem) => (target = { problem });
+    const inside = ask(['rev-parse', '--git-dir']);
+    if (inside.missing) return fail('git is not installed here');
+    if (inside.timedOut) return fail('git did not answer in time');
+    if (inside.status !== 0) return fail('this folder is not a git repository');
+    const head = ask(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+    if (head.timedOut) return fail('git did not answer in time');
+    const named = head.status === 0 ? ORIGIN_BRANCH.exec(head.stdout.trim()) : null;
+    if (!named) {
+      // Not set. Say which of two things it is: no origin at all, or an origin whose default branch was never read.
+      const remote = ask(['remote', 'get-url', 'origin']);
+      if (remote.timedOut) return fail('git did not answer in time');
+      return fail(remote.status === 0 ? `origin's default branch is not set here, so there is no branch to check against; fix it with ${FIX}` : 'no origin branch');
+    }
+    const ref = head.stdout.trim();
+    const there = ask(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+    if (there.timedOut) return fail('git did not answer in time');
+    if (there.status !== 0) return fail(`origin's default branch, origin/${named[1]}, is not in this folder; fix it with ${FIX}`);
+    return (target = { ref, branch: named[1] });
+  }
+
+  // Why no landing can be checked in this folder at all, or ''. A fetch that failed counts: a folder that cannot
+  // bring origin up to date does not vouch for anything. So does a git that stopped answering.
+  function cannotCheck() {
+    return look().problem || fetched || unreadable || '';
+  }
+
+  // The ssh command the fetch runs with, or '' to leave ssh as the repository has it. A person's own ssh command
+  // (GIT_SSH_COMMAND, GIT_SSH, or core.sshCommand in the repository's settings) is never replaced: it runs as it is, the
+  // five seconds still end the fetch, and the check says so. With none, ssh is told never to wait on a person.
+  function sshForFetch() {
+    let own = '';
+    if (String(env.GIT_SSH_COMMAND || '').trim()) own = 'GIT_SSH_COMMAND';
+    else if (String(env.GIT_SSH || '').trim()) own = 'GIT_SSH';
+    else {
+      const configured = ask(['config', '--get', 'core.sshCommand']);
+      if (configured.status === 0 && configured.stdout.trim()) own = 'core.sshCommand';
+    }
+    if (!own) return BATCH_SSH;
+    told.push(`your own ssh command (${own}) was left as it is, so ssh may stop to ask for a password; the fetch gives up after five seconds either way`);
+    return '';
+  }
+
+  // Fetch origin's default branch, once. Returns '' when it worked, else why it did not. Asked again, it answers the
+  // same and does not try again. A folder that cannot be checked is not fetched.
+  function refresh() {
+    const found = look();
+    if (found.problem) return found.problem;
+    if (fetched !== null) return fetched;
+    const ssh = sshForFetch();
+    const spec = `+refs/heads/${found.branch}:refs/remotes/origin/${found.branch}`;
+    const done = ask(['fetch', 'origin', spec], { network: true, ...(ssh ? { ssh } : {}) });
+    if (done.timedOut) fetched = 'could not fetch origin in time';
+    else if (done.status !== 0) fetched = 'could not fetch origin';
+    else fetched = '';
+    // What was unknown before the fetch may be known now.
+    if (!fetched) {
+      sightings.clear();
+      onBranch = null;
+    }
+    return fetched;
+  }
+
+  // The commits as git has them, in one batched call: a Map from each commit as spelled (lower case) to
+  // { oid, time } (the full id and the commit time in milliseconds), or to null when git does not have it, or when a
+  // short spelling starts more than one commit. What was read before is not read again.
+  function read(commits) {
+    const names = [...new Set((Array.isArray(commits) ? commits : []).map((commit) => String(commit == null ? '' : commit).trim().toLowerCase()).filter((commit) => HEX.test(commit)))];
+    const fresh = names.filter((name) => !sightings.has(name));
+    if (fresh.length) {
+      const found = look();
+      if (found.problem || spent || unreadable) {
+        for (const name of fresh) sightings.set(name, null);
+      } else {
+        // --ignore-missing goes first: git reads it before the names on standard input. With it, a name git does not
+        // have, or one that starts two commits, is left out instead of ending the whole batch.
+        const answer = ask(['rev-list', '--ignore-missing', '--no-walk=unsorted', '--stdin', '--format=%H %ct'], { input: `${fresh.join('\n')}\n` });
+        if (answer.timedOut) unreadable = 'git did not answer in time';
+        else if (answer.status !== 0) unreadable = 'git could not read the commits';
+        const commitsRead = [];
+        if (!unreadable) {
+          for (const line of answer.stdout.split('\n')) {
+            const one = /^([0-9a-f]{40,64}) (\d+)$/.exec(line.trim());
+            if (one) commitsRead.push({ oid: one[1], time: Number(one[2]) * 1000 });
+          }
+        }
+        // Each spelling is looked up in a map of the commits it could start, not compared against every commit: one
+        // entry for each commit and each length a spelling was given in (a spelling is 7 to 64 digits).
+        const lengths = [...new Set(fresh.map((name) => name.length))];
+        const starting = new Map();
+        for (const one of commitsRead) {
+          for (const length of lengths) {
+            if (length > one.oid.length) continue;
+            const prefix = one.oid.slice(0, length);
+            const held = starting.get(prefix);
+            if (held) held.push(one); else starting.set(prefix, [one]);
+          }
+        }
+        for (const name of fresh) {
+          const starts = starting.get(name) || [];
+          sightings.set(name, starts.length === 1 ? starts[0] : null);
+        }
+        // A commit asked for by a short spelling is also known by its full id, which is how a later landing may name it.
+        for (const one of commitsRead) if (!sightings.has(one.oid)) sightings.set(one.oid, one);
+      }
+    }
+    return new Map(names.map((name) => [name, sightings.get(name) || null]));
+  }
+
+  // The commits on the default branch, listed once: the full ids of everything reachable from it inside the window,
+  // or null when git could not list it (cannotCheck says why).
+  function branchCommits(ref) {
+    if (onBranch) return onBranch;
+    if (unreadable) return null;
+    const edge = Number.isFinite(since) ? since - SKEW_MS - WINDOW_MARGIN_MS : 0;
+    const window = edge > 0 ? [`--max-age=${Math.floor(edge / 1000)}`] : [];
+    const answer = ask(['rev-list', ...window, ref, '--']);
+    if (answer.timedOut) unreadable = 'git did not answer in time';
+    else if (answer.status !== 0) unreadable = 'git could not read the default branch';
+    if (unreadable) return null;
+    onBranch = new Set(answer.stdout.split('\n').map((line) => line.trim().toLowerCase()).filter(Boolean));
+    return onBranch;
+  }
+
+  return {
+    cannotCheck,
+    refresh,
+    read,
+    // What the check did that a person should hear about, in plain words: a line each, said once. Empty when it left
+    // nothing of theirs alone.
+    notes: () => told.slice(),
+    // True when one of these commits is on the default branch, is no older than `claimedAt` (a time in
+    // milliseconds, if given; five minutes of skew allowed) and is `owns(commit)`'s to claim (if given; it is
+    // handed the full id, and only for a commit that is already landed). No commits, or no branch to check, is false.
+    landed(commits, { claimedAt, owns } = {}) {
+      const found = look();
+      if (found.problem || fetched || unreadable) return false;
+      const seen = read(commits);
+      if (unreadable) return false;
+      const listed = [...seen.values()].some(Boolean) ? branchCommits(found.ref) : null;
+      if (!listed) return false;
+      return [...seen.keys()].some((name) => {
+        const sighting = seen.get(name);
+        if (!sighting) return false;
+        if (Number.isFinite(claimedAt) && sighting.time < claimedAt - SKEW_MS) return false;
+        if (!listed.has(sighting.oid)) return false;
+        return typeof owns === 'function' ? Boolean(owns(sighting.oid)) : true;
+      });
+    },
+  };
+}
+
+module.exports = { commitsOf, createLandingCheck };

package/lib/runner-command.js

@@ -191,20 +191,23 @@ function shellWord(value) {
   return `'${s.replace(/'/g, "'\\''")}'`;
 }
 
-function firstConfiguredEnv(names) {
+// Every reader below takes the environment it reads from and defaults to this process's. A launch is built in
+// this process, so it reads process.env; a caller that wants to know what a launch would carry (launchFor) hands
+// in the environment the launch would be built in, and nothing here looks at this process then.
+function firstConfiguredEnv(names, env = process.env) {
   for (const name of names) {
-    const value = String(process.env[name] || '').trim();
+    const value = String(env[name] || '').trim();
     if (value) return value;
   }
   return '';
 }
 
-function resolveRunnerProfileName() {
-  return String(process.env.ATRIS_RUNNER_PROFILE || '').trim();
+function resolveRunnerProfileName(env = process.env) {
+  return String(env.ATRIS_RUNNER_PROFILE || '').trim();
 }
 
-function resolveRunnerProfile() {
-  const name = resolveRunnerProfileName();
+function resolveRunnerProfile(env = process.env) {
+  const name = resolveRunnerProfileName(env);
   if (!name) return null;
   const profile = RUNNER_PROFILES[name];
   if (!profile) {
@@ -213,8 +216,8 @@ function resolveRunnerProfile() {
   return profile;
 }
 
-function runnerProfileValue(key) {
-  const profile = resolveRunnerProfile();
+function runnerProfileValue(key, env = process.env) {
+  const profile = resolveRunnerProfile(env);
   return profile && profile[key] ? profile[key] : '';
 }
 
@@ -233,10 +236,10 @@ function isSpendGatedModel(model) {
 
 // `fallback` is the model to run instead. An engine that is not the claude cli
 // cannot take a claude model id, so it passes '' and rides its own default.
-function applySpendGate(model, { silent = false, fallback = SPEND_FALLBACK_MODEL } = {}) {
+function applySpendGate(model, { silent = false, fallback = SPEND_FALLBACK_MODEL, env = process.env } = {}) {
   const value = String(model || '').trim();
   if (!value || !isSpendGatedModel(value)) return value;
-  if (String(process.env.ATRIS_CLAUDE_SPEND_OK || '').trim() === value) return value;
+  if (String(env.ATRIS_CLAUDE_SPEND_OK || '').trim() === value) return value;
   if (!silent && !spendGateWarned.has(`${value}>${fallback}`)) {
     spendGateWarned.add(`${value}>${fallback}`);
     const instead = fallback || "that engine's own default model";
@@ -251,37 +254,37 @@ function resetSpendGateWarnings() {
 
 // Engines that run only their own vendor's models drop any claude model name
 // later, so the gate has nothing to stop there and stays quiet.
-function runnerDropsClaudeModels() {
-  const name = resolveRunnerProfileName();
+function runnerDropsClaudeModels(env = process.env) {
+  const name = resolveRunnerProfileName(env);
   const def = name ? RUNNER_PROFILE_DEFS[RUNNER_PROFILE_ALIASES[name] || name] : null;
   if (def && def.ownModelsOnly) return true;
-  return Boolean(ownModelsOnlyEngineForBin(resolveClaudeRunnerBin()));
+  return Boolean(ownModelsOnlyEngineForBin(resolveClaudeRunnerBin(env)));
 }
 
 // Whether the launch goes through the claude cli, the only engine that can take
 // the cheap claude fallback by name.
-function runnerRidesClaudeCli() {
-  const name = resolveRunnerProfileName();
+function runnerRidesClaudeCli(env = process.env) {
+  const name = resolveRunnerProfileName(env);
   const canonical = name ? (RUNNER_PROFILE_ALIASES[name] || name) : '';
   return !canonical || canonical === 'claude' || canonical === 'fable' || canonical === 'haiku';
 }
 
 // The choke point: every unattended Claude launch (mission, autopilot, run,
 // pulse, fleet) resolves its model here, directly or via buildRunnerCommand.
-function resolveClaudeRunnerModel(mission) {
-  const model = resolveClaudeRunnerModelUngated(mission);
-  if (!isSpendGatedModel(model) || runnerDropsClaudeModels()) return model;
-  return applySpendGate(model, { fallback: runnerRidesClaudeCli() ? SPEND_FALLBACK_MODEL : '' });
+function resolveClaudeRunnerModel(mission, { env = process.env, silent = false } = {}) {
+  const model = resolveClaudeRunnerModelUngated(mission, env);
+  if (!isSpendGatedModel(model) || runnerDropsClaudeModels(env)) return model;
+  return applySpendGate(model, { fallback: runnerRidesClaudeCli(env) ? SPEND_FALLBACK_MODEL : '', env, silent });
 }
 
-function resolveClaudeRunnerModelUngated(mission) {
+function resolveClaudeRunnerModelUngated(mission, env = process.env) {
   const explicit = mission && mission.model != null ? normalizeClaudeModelName(mission.model) : '';
   if (explicit) return explicit;
-  const env = normalizeClaudeModelName(firstConfiguredEnv(['ATRIS_RUNNER_MODEL']));
-  if (env) return env;
-  const profileModel = normalizeClaudeModelName(runnerProfileValue('model'));
+  const fromEnv = normalizeClaudeModelName(firstConfiguredEnv(['ATRIS_RUNNER_MODEL'], env));
+  if (fromEnv) return fromEnv;
+  const profileModel = normalizeClaudeModelName(runnerProfileValue('model', env));
   if (profileModel) return profileModel;
-  const legacyEnv = normalizeClaudeModelName(firstConfiguredEnv(['ATRIS_CLAUDE_MODEL']));
+  const legacyEnv = normalizeClaudeModelName(firstConfiguredEnv(['ATRIS_CLAUDE_MODEL'], env));
   if (legacyEnv) return legacyEnv;
   return DEFAULT_CLAUDE_RUNNER_MODEL;
 }
@@ -290,12 +293,12 @@ function resolveClaudeRunnerModelUngated(mission) {
 // mission model) or the profile's own pin. ATRIS_RUNNER_MODEL is left out on
 // purpose: it usually names a claude model, which devin or grok would reject.
 // '' means nothing is pinned, so the engine's CLI picks its own default.
-function resolvePinnedRunnerModel(mission) {
+function resolvePinnedRunnerModel(mission, { env = process.env, silent = false } = {}) {
   const explicit = mission && mission.model != null ? String(mission.model).trim() : '';
-  const pinned = explicit || runnerProfileValue('model');
+  const pinned = explicit || runnerProfileValue('model', env);
   // Cheap check first: an ungated pin never needs the profile looked up.
-  if (!isSpendGatedModel(pinned) || runnerDropsClaudeModels()) return pinned;
-  return applySpendGate(pinned, { fallback: runnerRidesClaudeCli() ? SPEND_FALLBACK_MODEL : '' });
+  if (!isSpendGatedModel(pinned) || runnerDropsClaudeModels(env)) return pinned;
+  return applySpendGate(pinned, { fallback: runnerRidesClaudeCli(env) ? SPEND_FALLBACK_MODEL : '', env, silent });
 }
 
 // The own-models-only engine a runner bin launches ("codex", "/opt/bin/grok"),
@@ -326,22 +329,22 @@ function runnerModelFor(engineId, model) {
   return isClaudeFamilyModel(value) ? '' : value;
 }
 
-function resolveClaudeRunnerBin() {
-  const env = firstConfiguredEnv(['ATRIS_RUNNER_BIN']);
-  if (env) return env;
-  const profileBin = runnerProfileValue('bin');
+function resolveClaudeRunnerBin(env = process.env) {
+  const fromEnv = firstConfiguredEnv(['ATRIS_RUNNER_BIN'], env);
+  if (fromEnv) return fromEnv;
+  const profileBin = runnerProfileValue('bin', env);
   if (profileBin) return profileBin;
-  const legacyEnv = firstConfiguredEnv(['ATRIS_CLAUDE_BIN']);
+  const legacyEnv = firstConfiguredEnv(['ATRIS_CLAUDE_BIN'], env);
   if (legacyEnv) return legacyEnv;
   return DEFAULT_CLAUDE_RUNNER_BIN;
 }
 
-function resolveClaudeRunnerCommandTemplate() {
-  const env = firstConfiguredEnv(['ATRIS_RUNNER_COMMAND_TEMPLATE']);
-  if (env) return env;
-  const profileTemplate = runnerProfileValue('commandTemplate');
+function resolveClaudeRunnerCommandTemplate(env = process.env) {
+  const fromEnv = firstConfiguredEnv(['ATRIS_RUNNER_COMMAND_TEMPLATE'], env);
+  if (fromEnv) return fromEnv;
+  const profileTemplate = runnerProfileValue('commandTemplate', env);
   if (profileTemplate) return profileTemplate;
-  return firstConfiguredEnv(['ATRIS_CLAUDE_COMMAND_TEMPLATE']);
+  return firstConfiguredEnv(['ATRIS_CLAUDE_COMMAND_TEMPLATE'], env);
 }
 
 function buildRunnerAvailabilityCommand() {
@@ -453,6 +456,42 @@ function buildRunnerCommand({ promptFile, allowedTools, model, effort } = {}) {
   return cmd;
 }
 
+// What the launch of one engine would carry, decided from `env` (this process's by default) and without launching
+// anything or saying anything: { engine, bin, model }, or null for an engine nobody knows. `model` is the pin a
+// caller would hand buildRunnerCommand (a roster pick). The model is the --model of the command buildRunnerCommand
+// builds for this engine under ATRIS_RUNNER_PROFILE=<engine>, the way the fleet builds it: the same precedence,
+// the same spend gate, and a claude model dropped by an engine that cannot take one. '' means the launch carries
+// none. A caller that must judge the launch (the builder picker asks the Claude spend guard about it) asks here
+// and never works the model out for itself.
+//
+// Only the fleet's own launch is read. A command template somebody wrote (ATRIS_RUNNER_COMMAND_TEMPLATE, or the
+// older ATRIS_CLAUDE_COMMAND_TEMPLATE) can start anything with anything: a model in it may be a flag, a word of the
+// prompt, another command's, or one the shell works out only when it runs. It is never read for its model. The
+// answer is { engine, bin, model: '', custom: true }, and a caller that has to judge it counts the model as one it
+// cannot tell. A template that is the engine's own is the fleet's launch like any other.
+function launchFor(engineId, { env = process.env, model } = {}) {
+  const asked = String(engineId || '').trim().toLowerCase();
+  const name = RUNNER_PROFILE_ALIASES[asked] || asked;
+  if (!name || !RUNNER_PROFILE_DEFS[name]) return null;
+  const scoped = { ...env, ATRIS_RUNNER_PROFILE: name };
+  const bin = resolveClaudeRunnerBin(scoped);
+  const template = resolveClaudeRunnerCommandTemplate(scoped);
+  if (template && template !== runnerProfileValue('commandTemplate', scoped)) {
+    return { engine: name, bin, model: '', custom: true };
+  }
+  const mission = { model };
+  const binEngine = ownModelsOnlyEngineForBin(bin);
+  const modelFor = (value) => {
+    const forProfile = runnerModelFor(name, value);
+    return binEngine ? runnerModelFor(binEngine, forProfile) : forProfile;
+  };
+  const hasModelSlot = !template || /\{(?:model|modelFlag)\}/.test(template);
+  const hasPinSlot = Boolean(template) && /\{pinnedModelFlag\}/.test(template);
+  const resolved = hasModelSlot ? resolveClaudeRunnerModel(mission, { env: scoped, silent: true }) : '';
+  const pinned = hasPinSlot ? resolvePinnedRunnerModel(mission, { env: scoped, silent: true }) : '';
+  return { engine: name, bin, model: modelFor(hasModelSlot ? resolved : pinned) };
+}
+
 // Whether the installed codex prints JSONL events and can write its final
 // answer to a file. Asked once per program; an older codex without the flags
 // keeps today's plain launch.
@@ -518,4 +557,5 @@ module.exports = {
   buildRunnerAvailabilityCommand,
   runnerAvailabilityFailureMessage,
   buildRunnerCommand,
+  launchFor,
 };