@oddessentials/agent-guild 0.33.2 → 0.35.0

package/src/manager/environment.mjs

@@ -1,37 +1,102 @@
-// Read-only snapshot of the manager environment. Discovery runs outside the
-// manager: even a blocked filesystem lookup cannot hold up terminals or HTTP.
+// Read-only environment snapshots. Discovery runs outside the manager: even a
+// blocked filesystem lookup cannot hold up terminals or HTTP. Each scope
+// reports its own fact and never fills a gap from another scope.
+import os from 'node:os';
+import { createHash } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { fork } from 'node:child_process';
 import { killWindowsTree } from './command-resolver.mjs';
 import { RUNTIMES } from './environment-probe.mjs';
+import { resolveProjectCwd } from './environment-pins.mjs';
 
 export const ENVIRONMENT_TIMEOUT_MS = 10000;
+export const LAUNCH_DETAIL = 'Launch PATH, profiles not applied. The selected shell is not consulted.';
+export const SESSION_DETAIL = 'Spawn PATH, before the shell startup files.';
+export const MULTIPLEXER_DETAIL = 'This session is tmux or herdr. Its environment is not the spawn record.';
+// Toolchain shims (rustup, pyenv, asdf, mise, volta, nodenv) read their home
+// and selected version from these, so a session probe without them reports
+// a runtime the session can actually run as unavailable.
+const PATH_ENV = [
+  'PATH', 'PATHEXT', 'SYSTEMROOT', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'XDG_DATA_HOME', 'XDG_CONFIG_HOME',
+  'NVM_DIR', 'VOLTA_HOME', 'NODENV_ROOT', 'NODENV_VERSION', 'PYENV_ROOT', 'PYENV_VERSION',
+  'ASDF_DIR', 'ASDF_DATA_DIR', 'MISE_DATA_DIR', 'MISE_CONFIG_DIR', 'RUSTUP_HOME', 'RUSTUP_TOOLCHAIN', 'CARGO_HOME',
+  'GOROOT', 'GOTOOLCHAIN', 'DOTNET_ROOT', 'R_HOME',
+];
+
+function hostName() {
+  try { return os.hostname(); } catch { return null; }
+}
+
+function cloneRow(row) {
+  return {
+    ...row,
+    ...(row.alternatives ? { alternatives: row.alternatives.map((item) => ({ ...item })) } : {}),
+    ...(row.runtimes ? { runtimes: row.runtimes.map((item) => ({ ...item })) } : {}),
+  };
+}
+
+function pendingRuntimes() {
+  return RUNTIMES.map(({ id, label }) => ({ id, label, status: 'pending', version: null, path: null }));
+}
+
+export function probePathEnv(env) {
+  const out = {};
+  for (const [key, value] of Object.entries(env || {})) {
+    if (typeof value === 'string' && PATH_ENV.includes(key.toUpperCase())) out[key] = value;
+  }
+  return out;
+}
+
+function pathIdentity(env, cwd) {
+  const key = Object.keys(env).find((name) => name.toUpperCase() === 'PATH');
+  return createHash('sha256').update(`${key ? env[key] : ''}\0${cwd || ''}`).digest('hex').slice(0, 16);
+}
 
 export class Environment extends EventEmitter {
-  constructor({ env, forkWorker = fork, timeoutMs = ENVIRONMENT_TIMEOUT_MS } = {}) {
+  constructor({ env, forkWorker = fork, timeoutMs = ENVIRONMENT_TIMEOUT_MS, hostname = hostName(), sessionLookup = () => null } = {}) {
     super();
     this.env = env ?? process.env;
     this.forkWorker = forkWorker;
     this.timeoutMs = timeoutMs;
+    this.host = hostname;
+    this.sessionLookup = sessionLookup;
     this.closed = false;
     this.run = null;
-    this.value = {
-      scope: 'manager', platform: process.platform, revision: 0, refreshing: false, checkedAt: null, error: null,
+    this.launch = null;
+    this.projects = new Map();
+    this.sessions = new Map();
+    this.value = this.blankManager();
+  }
+
+  setSessionLookup(sessionLookup) { this.sessionLookup = sessionLookup; }
+
+  snapshot() { return this.value; }
+
+  blankManager() {
+    return {
+      scope: 'manager', host: this.host, platform: process.platform, revision: 0, refreshing: false, checkedAt: null, error: null,
       managerNode: { version: process.versions.node, path: process.execPath },
-      runtimes: RUNTIMES.map(({ id, label }) => ({ id, label, status: 'pending', version: null, path: null })),
+      runtimes: pendingRuntimes(),
       tools: [],
     };
   }
 
-  snapshot() { return this.value; }
-
   // Never awaits discovery. A refresh reads the manager's current environment;
   // it does not reload shell profiles, the registry, or a client's working folder.
-  refresh() {
-    if (this.closed || this.run) return this.snapshot();
-    const run = { child: null, timer: null, rows: new Map(), tools: [] };
+  // publishLaunch stores a labeled copy when this same helper finishes.
+  refresh({ publishLaunch = false } = {}) {
+    if (this.closed) return publishLaunch && this.launch ? this.launch : this.snapshot();
+    if (this.run) {
+      if (publishLaunch && !this.run.publishLaunch) {
+        this.run.publishLaunch = true;
+        this.armLaunch();
+      }
+      return publishLaunch ? this.launch : this.snapshot();
+    }
+    const run = { child: null, timer: null, rows: new Map(), tools: [], publishLaunch };
     this.run = run;
     this.value = { ...this.value, revision: this.value.revision + 1, refreshing: true, error: null };
+    if (publishLaunch) this.armLaunch();
     const finish = (error = null) => {
       if (this.run !== run) return;
       this.run = null;
@@ -44,7 +109,8 @@ export class Environment extends EventEmitter {
         }),
         tools: run.tools,
       };
-      if (!this.closed) this.emit('updated');
+      if (!this.closed) this.emit('updated', this.snapshot());
+      if (run.publishLaunch) this.storeLaunch();
     };
     try {
       // A preload in NODE_OPTIONS must not execute inside a passive scan.
@@ -56,7 +122,7 @@ export class Environment extends EventEmitter {
       });
       run.child.on('message', (message) => {
         if (this.run !== run) return;
-        if (message?.runtime && RUNTIMES.some((r) => r.id === message.runtime.id)) run.rows.set(message.runtime.id, message.runtime);
+        if (message?.runtime && RUNTIMES.some((runtime) => runtime.id === message.runtime.id)) run.rows.set(message.runtime.id, message.runtime);
         if (Array.isArray(message?.tools)) run.tools = message.tools;
         if (message?.done) finish();
       });
@@ -69,8 +135,229 @@ export class Environment extends EventEmitter {
       run.timer = setTimeout(() => finish('The environment check timed out.'), this.timeoutMs);
       run.timer.unref();
     } catch { finish('Could not start the environment check.'); }
-    this.emit('updated');
-    return this.snapshot();
+    if (!this.closed) this.emit('updated', this.snapshot());
+    return publishLaunch ? this.launch : this.snapshot();
+  }
+
+  armLaunch() {
+    const previous = this.launch;
+    this.launch = {
+      scope: 'launch', host: this.host, platform: process.platform,
+      revision: (previous?.revision ?? 0) + 1, refreshing: true, checkedAt: previous?.checkedAt ?? null, error: null,
+      detail: LAUNCH_DETAIL,
+      runtimes: (previous?.runtimes ?? this.value.runtimes).map(cloneRow),
+      tools: (previous?.tools ?? this.value.tools).map((tool) => ({ ...tool })),
+    };
+    if (!this.closed) this.emit('updated', this.launch);
+  }
+
+  storeLaunch() {
+    this.launch = {
+      scope: 'launch', host: this.host, platform: this.value.platform,
+      revision: (this.launch?.revision ?? 0) + 1, refreshing: false, checkedAt: this.value.checkedAt, error: this.value.error,
+      detail: LAUNCH_DETAIL,
+      runtimes: this.value.runtimes.map(cloneRow),
+      tools: this.value.tools.map((tool) => ({ ...tool })),
+    };
+    if (!this.closed) this.emit('updated', this.launch);
+    return this.launch;
+  }
+
+  openLaunch({ refresh = false } = {}) {
+    if (refresh) return this.refresh({ publishLaunch: true });
+    if (this.launch?.checkedAt) return this.launch;
+    if (this.value.checkedAt && !this.run) return this.storeLaunch();
+    return this.refresh({ publishLaunch: true });
+  }
+
+  projectKey(dir) {
+    return `project:${process.platform === 'win32' ? dir.toLowerCase() : dir}`;
+  }
+
+  openProject(cwd, { refresh = false } = {}) {
+    const dir = resolveProjectCwd(cwd);
+    const key = this.projectKey(dir);
+    let entry = this.projects.get(key);
+    if (!entry) {
+      entry = { value: this.blankProject(dir), run: null, identityRun: null };
+      this.projects.set(key, entry);
+    }
+    if (refresh || !entry.value.checkedAt) this.startProject(entry, dir, false);
+    else this.startProject(entry, dir, true);
+    return entry.value;
+  }
+
+  blankProject(cwd) {
+    return {
+      scope: 'project', host: this.host, platform: process.platform, cwd, revision: 0, refreshing: false,
+      checkedAt: null, error: null, stale: false, detail: null, identity: null, pins: [],
+    };
+  }
+
+  startProject(entry, dir, identityOnly) {
+    if (this.closed) return;
+    if (identityOnly) {
+      if (entry.run || entry.identityRun) return;
+      this.forkPins(entry, dir, true);
+      return;
+    }
+    this.stopWorker(entry.identityRun?.child);
+    entry.identityRun = null;
+    if (entry.run) return;
+    entry.value = { ...entry.value, revision: entry.value.revision + 1, refreshing: true, error: null, stale: false, detail: null };
+    this.forkPins(entry, dir, false);
+    if (!this.closed) this.emit('updated', entry.value);
+  }
+
+  forkPins(entry, dir, identityOnly) {
+    const run = { child: null, timer: null, result: null, revision: entry.value.revision };
+    if (identityOnly) entry.identityRun = run;
+    else entry.run = run;
+    const finish = (error = null) => {
+      const current = identityOnly ? entry.identityRun : entry.run;
+      if (current !== run) return;
+      if (identityOnly) entry.identityRun = null;
+      else entry.run = null;
+      clearTimeout(run.timer);
+      this.stopWorker(run.child);
+      if (identityOnly) this.finishIdentity(entry, run, error);
+      else this.finishProject(entry, error, run.result);
+    };
+    try {
+      run.child = this.forkWorker(new URL('./environment-probe.mjs', import.meta.url), [identityOnly ? '--pin-identity' : '--scan-pins', dir], {
+        env: probeProcessEnv(), execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        windowsHide: true, detached: process.platform !== 'win32',
+      });
+      run.child.on('message', (message) => {
+        if ((identityOnly ? entry.identityRun : entry.run) !== run) return;
+        if (message?.done) finish(message.error && !run.result ? message.error : null);
+        else if (message?.error) run.result = { error: message.error };
+        else if (message?.identity) run.result = message;
+      });
+      run.child.once('error', () => finish(identityOnly ? 'identity' : 'Could not read the project pins.'));
+      run.child.once('exit', () => setImmediate(() => {
+        if ((identityOnly ? entry.identityRun : entry.run) !== run) return;
+        finish(run.result ? null : (identityOnly ? 'identity' : 'The project check stopped before finishing.'));
+      }));
+      run.timer = setTimeout(() => finish(identityOnly ? 'identity' : 'The project check timed out.'), this.timeoutMs);
+      run.timer.unref();
+    } catch { finish(identityOnly ? 'identity' : 'Could not read the project pins.'); }
+  }
+
+  finishProject(entry, error, result) {
+    const pins = Array.isArray(result?.pins) ? result.pins : entry.value.pins;
+    const identity = result?.identity || entry.value.identity;
+    entry.value = {
+      ...entry.value, revision: entry.value.revision + 1, refreshing: false, checkedAt: new Date().toISOString(),
+      error: result?.error || error, stale: false, detail: null, identity, pins,
+    };
+    if (!this.closed) this.emit('updated', entry.value);
+  }
+
+  finishIdentity(entry, run, error) {
+    if (entry.run || entry.value.revision !== run.revision) return;
+    if (error || !run.result?.identity || run.result.error) {
+      entry.value = { ...entry.value, stale: true, detail: 'Could not confirm the pin files are unchanged.' };
+    } else if (run.result.identity !== entry.value.identity) {
+      entry.value = { ...entry.value, stale: true, detail: null };
+    } else {
+      entry.value = { ...entry.value, stale: false, detail: null };
+    }
+    if (!this.closed) this.emit('updated', entry.value);
+  }
+
+  openSession(id, { refresh = false } = {}) {
+    const found = this.sessionLookup(id);
+    if (!found) return null;
+    if (found.multiplexer) return this.unavailableSession(id, found);
+    const key = `session:${id}:${pathIdentity(found.pathEnv, found.spawnCwd)}`;
+    for (const other of [...this.sessions.keys()]) {
+      if (other.startsWith(`session:${id}:`) && other !== key) this.dropSession(other);
+    }
+    let entry = this.sessions.get(key);
+    if (!entry) {
+      entry = { value: this.blankSession(id, found), run: null };
+      this.sessions.set(key, entry);
+    }
+    if (refresh || !entry.value.checkedAt) this.startSession(entry, found);
+    return entry.value;
+  }
+
+  blankSession(id, found) {
+    return {
+      scope: 'session', host: this.host, platform: process.platform, sessionId: id, spawnCwd: found.spawnCwd,
+      availability: 'ok', detail: SESSION_DETAIL, revision: 0, refreshing: false, checkedAt: null, error: null,
+      runtimes: pendingRuntimes(), tools: [],
+    };
+  }
+
+  unavailableSession(id, found) {
+    const key = `session:${id}:unavailable`;
+    const existing = this.sessions.get(key);
+    if (existing) return existing.value;
+    for (const other of [...this.sessions.keys()]) if (other.startsWith(`session:${id}:`) && other !== key) this.dropSession(other);
+    const value = {
+      scope: 'session', host: this.host, platform: process.platform, sessionId: id, spawnCwd: found.spawnCwd,
+      availability: 'unavailable', detail: MULTIPLEXER_DETAIL, revision: 1, refreshing: false,
+      checkedAt: new Date().toISOString(), error: null, runtimes: [], tools: [],
+    };
+    this.sessions.set(key, { value, run: null });
+    return value;
+  }
+
+  startSession(entry, found) {
+    if (this.closed || entry.run) return;
+    const run = { child: null, timer: null, rows: new Map(), tools: [] };
+    entry.run = run;
+    entry.value = { ...entry.value, revision: entry.value.revision + 1, refreshing: true, error: null };
+    const finish = (error = null) => {
+      if (entry.run !== run) return;
+      entry.run = null;
+      clearTimeout(run.timer);
+      this.stopWorker(run.child);
+      entry.value = {
+        ...entry.value, revision: entry.value.revision + 1, refreshing: false, checkedAt: new Date().toISOString(), error,
+        runtimes: RUNTIMES.map(({ id, label }) => run.rows.get(id) ?? {
+          id, label, status: 'failed', version: null, path: null, detail: error || 'The environment check did not finish.',
+        }),
+        tools: run.tools,
+      };
+      if (!this.closed) this.emit('updated', entry.value);
+    };
+    try {
+      const env = probePathEnv(found.pathEnv);
+      for (const key of Object.keys(env)) if (key.toUpperCase() === 'NODE_OPTIONS') delete env[key];
+      run.child = this.forkWorker(new URL('./environment-probe.mjs', import.meta.url), ['--scan-environment'], {
+        env, execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        windowsHide: true, detached: process.platform !== 'win32',
+      });
+      run.child.on('message', (message) => {
+        if (entry.run !== run) return;
+        if (message?.runtime && RUNTIMES.some((runtime) => runtime.id === message.runtime.id)) run.rows.set(message.runtime.id, message.runtime);
+        if (Array.isArray(message?.tools)) run.tools = message.tools;
+        if (message?.done) finish();
+      });
+      run.child.once('error', () => finish('Could not start the environment check.'));
+      run.child.once('exit', () => setImmediate(() => {
+        if (entry.run !== run) return;
+        finish(run.rows.size === RUNTIMES.length ? null : 'The environment check stopped before finishing.');
+      }));
+      run.timer = setTimeout(() => finish('The environment check timed out.'), this.timeoutMs);
+      run.timer.unref();
+    } catch { finish('Could not start the environment check.'); }
+    if (!this.closed) this.emit('updated', entry.value);
+  }
+
+  forgetSession(id) {
+    for (const key of [...this.sessions.keys()]) if (key.startsWith(`session:${id}:`)) this.dropSession(key);
+  }
+
+  dropSession(key) {
+    const entry = this.sessions.get(key);
+    if (!entry) return;
+    clearTimeout(entry.run?.timer);
+    this.stopWorker(entry.run?.child);
+    this.sessions.delete(key);
   }
 
   stopWorker(child) {
@@ -86,5 +373,23 @@ export class Environment extends EventEmitter {
       this.stopWorker(this.run.child);
       this.run = null;
     }
+    for (const entry of this.projects.values()) {
+      clearTimeout(entry.run?.timer);
+      clearTimeout(entry.identityRun?.timer);
+      this.stopWorker(entry.run?.child);
+      this.stopWorker(entry.identityRun?.child);
+    }
+    for (const entry of this.sessions.values()) {
+      clearTimeout(entry.run?.timer);
+      this.stopWorker(entry.run?.child);
+    }
+  }
+}
+
+function probeProcessEnv() {
+  const env = {};
+  for (const key of ['SystemRoot', 'SYSTEMROOT', 'PATHEXT', 'ComSpec', 'COMSPEC']) {
+    if (process.env[key]) env[key] = process.env[key];
   }
+  return env;
 }

package/src/manager/github-views.mjs

@@ -7,6 +7,10 @@ const PAGE = 30;
 const RUNNING = new Set(['queued', 'in_progress', 'waiting', 'requested', 'pending']);
 const WEB = 'https://github.com';
 const ISSUE_RE = /^[1-9]\d{0,9}$/;
+const STATUS_PAGE = 'https://www.githubstatus.com';
+const STATUS_TTL_MS = 60 * 1000;
+const STATUS_TIMEOUT_MS = 5000;
+const OUTAGES = new Set(['degraded_performance', 'partial_outage', 'major_outage', 'under_maintenance']);
 
 function refusal(status, code, message) {
   return Object.assign(new Error(message), { status, code });
@@ -82,6 +86,20 @@ function cleanPull(raw, fullName) {
   };
 }
 
+/** The Actions part of a githubstatus.com summary: null while it is operational or unreadable. */
+export function actionsService(summary) {
+  const component = (Array.isArray(summary?.components) ? summary.components : []).find((c) => c?.name === 'Actions' && !c.group_id);
+  if (!component || !OUTAGES.has(component.status)) return null;
+  const incident = (Array.isArray(summary.incidents) ? summary.incidents : [])
+    .find((i) => Array.isArray(i?.components) && i.components.some((c) => c?.id === component.id));
+  const name = text(incident?.name, 200).trim();
+  return {
+    status: component.status,
+    incident: name ? { name, url: /^[a-z0-9]{1,32}$/.test(incident.id) ? `${STATUS_PAGE}/incidents/${incident.id}` : STATUS_PAGE } : null,
+    url: STATUS_PAGE,
+  };
+}
+
 function checkTitle(title) {
   if (typeof title !== 'string' || !title.trim()) throw refusal(400, 'bad_title', 'title must be a non-empty string');
   if (title.trim().length > 256) throw refusal(400, 'bad_title', 'Keep the title to 256 characters or fewer.');
@@ -95,7 +113,20 @@ function checkBody(body) {
   return body;
 }
 
-export function createViews(github) {
+export function createViews(github, { now = Date.now } = {}) {
+  let service = null;
+
+  /** GitHub's own word on Actions, read without an account and shared by every repository for a minute. */
+  function actionsStatus() {
+    if (service && now() - service.at < STATUS_TTL_MS) return service.read;
+    const read = github.fetchImpl(`${github.statusUrl}/api/v2/summary.json`, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(STATUS_TIMEOUT_MS),
+    }).then((res) => (res.ok ? res.json() : null)).then(actionsService, () => null);
+    service = { at: now(), read };
+    return read;
+  }
+
   /** One request for the repository's account. GitHub's own refusals become answers the page can show as they are. */
   async function call(accountId, owner, name, route, init) {
     const account = github.account(accountId);
@@ -185,11 +216,12 @@ export function createViews(github) {
     },
 
     async actions(accountId, owner, name) {
-      const { body, res, repo } = await call(accountId, owner, name, `/actions/runs?per_page=${PAGE}`);
+      const [{ body, res, repo }, outage] = await Promise.all([call(accountId, owner, name, `/actions/runs?per_page=${PAGE}`), actionsStatus()]);
       const runs = (Array.isArray(body?.workflow_runs) ? body.workflow_runs : []).map((item) => cleanRun(item, repo.fullName)).filter(Boolean);
       return {
         runs,
         running: runs.some((run) => RUNNING.has(run.status)),
+        service: outage,
         truncated: Boolean(nextLink(res.headers.get('link'))),
         url: `${WEB}/${repo.fullName}/actions`,
       };

package/src/manager/github.mjs

@@ -14,6 +14,7 @@ export const GITHUB_CLIENT_ID = 'Ov23lif6qqYKtXZTb130';
 export const GITHUB_SCOPES = ['repo', 'write:public_key'];
 const API_URL = 'https://api.github.com';
 const WEB_URL = 'https://github.com';
+const STATUS_URL = 'https://www.githubstatus.com';
 const SSH_HOST = 'git@github.com';
 
 /** GitHub's published SSH host keys (docs: "GitHub's SSH key fingerprints"). */
@@ -241,7 +242,7 @@ function failure(err) {
 
 export class GitHub extends EventEmitter {
   constructor({
-    dir, registry, clientId = GITHUB_CLIENT_ID, apiUrl = API_URL, webUrl = WEB_URL,
+    dir, registry, clientId = GITHUB_CLIENT_ID, apiUrl = API_URL, webUrl = WEB_URL, statusUrl = STATUS_URL,
     fetchImpl = (...args) => fetch(...args), run = runSpec, hostname = os.hostname(), timeoutMs = FETCH_TIMEOUT_MS,
   }) {
     super();
@@ -250,6 +251,7 @@ export class GitHub extends EventEmitter {
     this.clientId = clientId;
     this.apiUrl = apiUrl.replace(/\/+$/, '');
     this.webUrl = webUrl.replace(/\/+$/, '');
+    this.statusUrl = statusUrl.replace(/\/+$/, '');
     this.fetchImpl = fetchImpl;
     this.run = run;
     this.hostname = hostname;

package/src/manager/launch.mjs

@@ -2,12 +2,18 @@
 // the `agent-guild` CLI, which starts one when none is running, and by a
 // manager that restarts itself: both run the package on disk, so a restart
 // after an upgrade comes up on the new version.
+//
+// While the Linux boot service is on, systemd is the one that starts a
+// manager: a supervised manager exits for systemd to start the next one,
+// and one started without systemd hands its restart over to it.
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { ensureDataDir, paths } from './config.mjs';
+import { dataDir, ensureDataDir, paths } from './config.mjs';
+import { stableExecPath } from './autostart.mjs';
+import { EXIT_RESTART, UNIT_UNSAFE, bootSupported, createBootService, journalCommand, startupState, unitPort } from './systemd-service.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 /** The manager entry point, from the package files on disk. */
@@ -62,3 +68,89 @@ export function launcherPath(platform = process.platform, rootDir = ROOT_DIR) {
     return null;
   }
 }
+
+/**
+ * Starts the manager that follows one restarting on `port`, once that one
+ * has released the port, and resolves to the exit code it should leave with.
+ *
+ * - Under the boot service (`supervised`): EXIT_RESTART, so systemd starts
+ *   the next one, after resetting its start count so that restarts never
+ *   use up the limit kept for crash loops.
+ * - With the boot service on for this port: systemd starts it, so the next
+ *   manager is supervised.
+ * - Otherwise, or if systemd refuses: a detached manager, as before.
+ *
+ * @param {{ supervised?: boolean, boot?: object|null, port: number, spawn?: typeof spawnManager, log?: (line: string) => void }} opts
+ */
+export async function nextManager({ supervised = false, boot = null, port, spawn = spawnManager, log = console.log }) {
+  if (supervised) {
+    await boot?.resetFailed().catch(() => {});
+    log('[manager] exiting for systemd to start the next manager');
+    return EXIT_RESTART;
+  }
+  if (boot) {
+    try {
+      const read = await boot.read();
+      if (read.enabled && unitPort(await boot.text()) === port) {
+        await boot.resetFailed();
+        await boot.start({ block: false });
+        log('[manager] systemd is starting the next manager');
+        return 0;
+      }
+    } catch (err) {
+      log(`[manager] systemd could not start the next manager (${err.message}); starting it directly`);
+    }
+  }
+  const child = spawn({ note: 'restarting manager', env: { ...process.env, AGENT_GUILD_PORT: String(port) } });
+  log(`[manager] started the next manager (pid ${child.pid})`);
+  return 0;
+}
+
+/** The package script a unit runs: this package's, as the manager names it. */
+export const PACKAGE_SCRIPT = path.join(ROOT_DIR, 'bin', 'agent-guild.mjs');
+
+/** The boot service on a Linux that can offer it with the default data folder, or null. */
+export function defaultBoot() {
+  return bootSupported() && !process.env.AGENT_GUILD_HOME ? createBootService({ dataDir: dataDir() }) : null;
+}
+
+/**
+ * The boot service when it should start the manager on `port`: on, and for
+ * that port. `note` says why an existing unit was passed over, so the
+ * caller can say so rather than start an unsupervised manager silently.
+ */
+export async function serviceFor(port, boot = defaultBoot()) {
+  if (!boot) return { boot: null, note: null };
+  const read = await boot.read().catch((err) => ({ reachable: false, reason: err.message, enabled: false }));
+  if (!read.reachable) {
+    const text = await boot.text().catch(() => null);
+    return { boot: null, note: text ? `The boot service could not be used (${read.reason}), so the session manager runs without systemd.` : null };
+  }
+  if (!read.enabled || unitPort(await boot.text()) !== port) return { boot: null, note: null };
+  return { boot, note: null };
+}
+
+/**
+ * Starts the manager through systemd and resolves once `health` answers at
+ * `url`. The unit is first pointed at this Node.js and package, as a manager
+ * does at each start, so a Node.js removed since cannot keep it failing; a
+ * failed state is cleared so systemd does not refuse the start. Throws with
+ * the service's last journal lines when it does not come up.
+ */
+export async function startService({ boot, port, url, health, execPath = stableExecPath(process.execPath), script = PACKAGE_SCRIPT, timeoutMs = 20000, pollMs = 250 }) {
+  if (![execPath, script].some((p) => UNIT_UNSAFE.test(p)) && await boot.write({ execPath, script, port })) await boot.reload();
+  await boot.resetFailed();
+  await boot.start({ block: true });
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const up = await health(url, 500);
+    if (up) return { url, started: true, version: up.version };
+    const read = await boot.read().catch(() => null);
+    const state = read && startupState(read.show, { pid: null, port });
+    if (state && ['failed', 'port-in-use', 'stopped'].includes(state.kind)) break;
+    if (Date.now() >= deadline) break;
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  const journal = await boot.journal(20);
+  throw new Error(`the session manager did not start under systemd.${journal ? `\n\nRecent log (${journalCommand(20)}):\n${journal}` : ''}`);
+}