@oddessentials/agent-guild 0.35.0 → 0.36.0

package/README.md

@@ -39,10 +39,12 @@ terminal.
 | Node.js | 22 or newer |
 | Windows | 10 version 1809 or later, x64 or arm64. No WSL needed. |
 | macOS | 11 or later, Intel or Apple silicon |
-| Linux | x64 or arm64, with a desktop or over SSH |
+| Linux | x64 or arm64 with glibc 2.28 or later (for example Debian 10, Ubuntu 20.04 or RHEL 8), with a desktop or over SSH |
 
-No compiler is needed. A missing tool shows **Install** on its card;
-Antigravity CLI, which is not on npm, shows its install command instead.
+No compiler is needed, except on Linux without glibc, such as Alpine:
+`agent-guild` prints the commands that build its terminal library there. A
+missing tool shows **Install** on its card; Antigravity CLI, which is not on
+npm, shows its install command instead.
 
 ## Setup
 

package/bin/agent-guild.mjs

@@ -21,6 +21,7 @@ import {
 } from '../src/manager/config.mjs';
 import { defaultBoot, serviceFor, spawnManager, startService } from '../src/manager/launch.mjs';
 import { recordSignIn } from '../src/manager/autostart.mjs';
+import { ptyProblem } from '../src/manager/pty.mjs';
 import { EXIT_PORT_IN_USE, describeStartup, startupState, startupSummary, unitPort } from '../src/manager/systemd-service.mjs';
 
 function usage() {
@@ -106,6 +107,10 @@ async function ensureManager({ port = null } = {}) {
   const running = await health(knownUrl);
   if (running) return { url: knownUrl, started: false, version: running.version };
 
+  // Say why no manager can run here rather than start one that fails.
+  const problem = ptyProblem();
+  if (problem) throw new Error(problem);
+
   // While the boot service is on for this port, systemd is the one that starts a manager.
   const { boot, note } = await serviceFor(listenPort);
   if (boot) return startService({ boot, port: listenPort, url: expectedUrl, health });
@@ -161,7 +166,10 @@ async function requestShutdown(url, { restart = false } = {}) {
     headers: { Authorization: `Bearer ${loadOrCreateToken()}`, 'Content-Type': 'application/json' },
     body: JSON.stringify(restart ? { force: true, restart: true } : { force: true }),
   });
-  if (!res.ok) throw new Error(`${restart ? 'restart' : 'stop'} failed: HTTP ${res.status}`);
+  if (!res.ok) {
+    const { error } = await res.json().catch(() => ({}));
+    throw new Error(`${restart ? 'restart' : 'stop'} failed: ${error?.message ?? `HTTP ${res.status}`}`);
+  }
   const body = await res.json().catch(() => ({}));
   const running = body.running ?? 0;
   if (running > 0) console.log(`Ending ${running} running session(s).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {

package/src/manager/environment-probe.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { resolveCommand, killWindowsTree } from './command-resolver.mjs';
 import { scanPins } from './environment-pins.mjs';
+import { systemInfo, dockerInfo, isWsl, wslInteropEnabled } from './environment-system.mjs';
 
 export const RUNTIMES = [
   { id: 'node', label: 'Node.js', command: 'node', args: ['--version'], pattern: /^v(\d+\.\d+\.\d+(?:-[\w.-]+)?)\s*$/m },
@@ -57,10 +58,7 @@ export function passiveExecutable(file, id, { platform = process.platform, env =
     return { error: WINDOWS_ALIAS };
   }
   const head = read(real);
-  const binary = head[0] === 0x4d && head[1] === 0x5a // PE
-    || head[0] === 0x7f && head.subarray(1, 4).toString() === 'ELF'
-    || ['feedface', 'feedfacf', 'cefaedfe', 'cffaedfe', 'cafebabe', 'bebafeca', 'cafebabf', 'bfbafeca'].includes(head.subarray(0, 4).toString('hex'));
-  if (binary) {
+  if (nativeProgram(head)) {
     // rustup dispatches using argv[0]; preserve its rustc proxy's name.
     return { file: id === 'rust' && /\/rustup(?:\.exe)?$/.test(normalized) ? file : real };
   }
@@ -71,6 +69,12 @@ export function passiveExecutable(file, id, { platform = process.platform, env =
 
 const WINDOWS_ALIAS = 'A Windows execution alias was found. A runtime behind this alias has not been verified.';
 
+function nativeProgram(head) {
+  return head[0] === 0x4d && head[1] === 0x5a // PE
+    || head[0] === 0x7f && head.subarray(1, 4).toString() === 'ELF'
+    || ['feedface', 'feedfacf', 'cefaedfe', 'cffaedfe', 'cafebabe', 'bebafeca', 'cafebabf', 'bfbafeca'].includes(head.subarray(0, 4).toString('hex'));
+}
+
 function windowsAlias(file) {
   return /[\\/]windowsapps[\\/]/i.test(file);
 }
@@ -78,7 +82,7 @@ function windowsAlias(file) {
 // The helper has a second, independent overall deadline in Environment. A
 // timeout here resolves immediately, even if a descendant retains stdout.
 // The kill is recorded for directory cleanup and does not delay this result.
-export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, spawnProcess = spawn, kills = null } = {}) {
+export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, limit = LIMIT, spawnProcess = spawn, kills = null } = {}) {
   return new Promise((resolve) => {
     let child, timer, size = 0, output = '', settled = false;
     const stop = () => {
@@ -113,7 +117,7 @@ export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, spawnPr
       timer = setTimeout(() => finish({ error: 'Version check timed out.' }, true), timeoutMs);
       for (const stream of [child.stdout, child.stderr]) stream.on('data', (chunk) => {
         size += chunk.length;
-        if (size > LIMIT) return finish({ error: 'Version check produced too much output.' }, true);
+        if (size > limit) return finish({ error: 'Version check produced too much output.' }, true);
         output += chunk.toString();
       });
       child.on('error', () => finish({ error: 'Could not run the resolved executable.' }, true));
@@ -195,6 +199,229 @@ export function detectTools({ env, platform = process.platform, resolve = resolv
   return tools;
 }
 
+// Design tools an agent can drive from a terminal. A version is read only from
+// a native program whose real name is the tool's own: a snap, a Flatpak
+// launcher or another wrapper is reported by presence. Windows `convert` is a
+// disk utility, so ImageMagick is only `magick` there.
+export const DESIGN_TOOLS = [
+  {
+    id: 'blender', label: 'Blender', args: ['--version', '--factory-startup'],
+    commands: () => ['blender'],
+    pattern: /^Blender (\d+\.\d+(?:\.\d+)?)/m, program: /^blender(?:\.exe)?$/i, installed: /^Blender\b/i,
+  },
+  {
+    id: 'ffmpeg', label: 'FFmpeg', args: ['-version'],
+    commands: () => ['ffmpeg'],
+    pattern: /^ffmpeg version n?(\d+(?:\.\d+)+|N-\d+)/m, program: /^ffmpeg(?:\.exe)?$/i, installed: /^FFmpeg\b/i,
+  },
+  {
+    // GIMP's window program on Windows does not print its version; the console build does.
+    id: 'gimp', label: 'GIMP', args: ['--version'],
+    commands: (platform) => platform === 'win32' ? ['gimp-console'] : ['gimp-console', 'gimp'],
+    pattern: /version (\d+\.\d+\.\d+)/, installed: /^GIMP\b/i,
+    program: (platform) => platform === 'win32' ? /^gimp-console(?:-[\d.]+)?\.exe$/i : /^gimp(?:-console)?(?:-[\d.]+)?$/i,
+  },
+  {
+    id: 'inkscape', label: 'Inkscape', args: ['--version'],
+    commands: () => ['inkscape'],
+    pattern: /^Inkscape (\d+\.\d+(?:\.\d+)?)/m, program: /^inkscape(?:\.com|\.exe)?$/i, installed: /^Inkscape\b/i,
+  },
+  {
+    id: 'imagemagick', label: 'ImageMagick', args: ['-version'],
+    commands: (platform) => platform === 'win32' ? ['magick'] : ['magick', 'convert'],
+    pattern: /^Version: ImageMagick (\d+\.\d+\.\d+(?:-\d+)?)/m, program: /^(?:magick|convert)(?:-im\d[\w.]*)?(?:\.exe)?$/i, installed: /^ImageMagick\b/i,
+  },
+];
+const DESIGN_TIMEOUT_MS = 3000;
+const REGISTRY_LIMIT = 1024 * 1024;
+const UNINSTALL_KEYS = [
+  'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+  'HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+  'HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+];
+// Paths inside an install folder, Windows. A RegExp segment matches a directory entry.
+const WINDOWS_FILES = {
+  blender: [['blender.exe']],
+  ffmpeg: [['bin', 'ffmpeg.exe'], ['ffmpeg.exe'], [/^ffmpeg-/i, 'bin', 'ffmpeg.exe']],
+  gimp: [['bin', 'gimp-console.exe'], ['bin', /^gimp-console-[\d.]+\.exe$/i]],
+  inkscape: [['bin', 'inkscape.com'], ['bin', 'inkscape.exe']],
+  imagemagick: [['magick.exe']],
+};
+
+// Usual install locations, used only when PATH has no match. Each entry is an
+// absolute root followed by segments below it.
+export function designLocations(id, { platform = process.platform, env = process.env, registry = [] } = {}) {
+  if (platform === 'win32') {
+    const programFiles = [value(env, 'ProgramFiles'), value(env, 'ProgramW6432'), 'C:\\Program Files'].filter(Boolean);
+    const profile = value(env, 'USERPROFILE');
+    const local = value(env, 'LOCALAPPDATA') || (profile && path.win32.join(profile, 'AppData', 'Local'));
+    const folders = {
+      blender: programFiles.map((root) => [root, 'Blender Foundation', /^Blender/i]),
+      ffmpeg: [],
+      gimp: [...programFiles.map((root) => [root, /^GIMP/i]), ...(local ? [[local, 'Programs', /^GIMP/i]] : [])],
+      inkscape: programFiles.map((root) => [root, 'Inkscape']),
+      imagemagick: programFiles.map((root) => [root, /^ImageMagick/i]),
+    }[id];
+    return [...registry.map((dir) => [dir]), ...folders].flatMap((folder) => WINDOWS_FILES[id].map((file) => [...folder, ...file]));
+  }
+  const home = value(env, 'HOME') || os.homedir();
+  const bins = platform === 'darwin'
+    ? ['/opt/homebrew/bin', '/usr/local/bin', '/opt/local/bin']
+    : ['/usr/local/bin', '/usr/bin', '/snap/bin', '/home/linuxbrew/.linuxbrew/bin'];
+  const flatpaks = ['/var/lib/flatpak/exports/bin', path.posix.join(home, '.local/share/flatpak/exports/bin')];
+  const apps = ['/Applications', path.posix.join(home, 'Applications')];
+  const inBins = (names) => bins.flatMap((dir) => names.map((name) => [dir, name]));
+  const flatpak = (app) => platform === 'linux' ? flatpaks.map((dir) => [dir, app]) : [];
+  const bundle = (app, file) => platform === 'darwin' ? apps.map((dir) => [dir, app, 'Contents', 'MacOS', file]) : [];
+  return {
+    blender: [...bundle(/^Blender.*\.app$/i, 'Blender'), ...inBins(['blender']), ...flatpak('org.blender.Blender')],
+    ffmpeg: inBins(['ffmpeg']),
+    gimp: [...bundle(/^GIMP.*\.app$/i, /^gimp(?:-[\d.]+)?$/i), ...inBins(['gimp-console', 'gimp']), ...flatpak('org.gimp.GIMP')],
+    inkscape: [...bundle(/^Inkscape.*\.app$/i, 'inkscape'), ...inBins(['inkscape']), ...flatpak('org.inkscape.Inkscape')],
+    imagemagick: inBins(platform === 'darwin' ? ['magick'] : ['magick', 'convert']),
+  }[id];
+}
+
+// The first existing file among the locations, in order. Directory listings are sorted.
+export function findInstalled(locations, { platform = process.platform, readdir = fs.readdirSync, isFile = (file) => isExecutable(file, platform) } = {}) {
+  const join = platform === 'win32' ? path.win32.join : path.posix.join;
+  for (const [root, ...segments] of locations) {
+    let paths = [root];
+    for (const segment of segments) {
+      paths = paths.flatMap((dir) => {
+        if (typeof segment === 'string') return [join(dir, segment)];
+        try { return readdir(dir).filter((name) => segment.test(name)).sort().map((name) => join(dir, name)); } catch { return []; }
+      });
+    }
+    const hit = paths.find((file) => isFile(file));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function isExecutable(file, platform) {
+  try {
+    if (!fs.statSync(file).isFile()) return false;
+    if (platform !== 'win32') fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch { return false; }
+}
+
+// Install folders from Windows uninstall entries whose name is a design tool.
+// Each query is bounded; a failed query adds nothing.
+export async function windowsInstallFolders({ env, cwd, run = runProbe, kills = null } = {}) {
+  const reg = path.win32.join(value(env, 'SystemRoot') || 'C:\\Windows', 'System32', 'reg.exe');
+  const query = (args) => run(reg, ['query', ...args], { env, cwd, kills, timeoutMs: DESIGN_TIMEOUT_MS, limit: REGISTRY_LIMIT })
+    .then((result) => result.code === 0 ? result.output : '');
+  const entries = (output, name) => {
+    const found = [];
+    let key = null;
+    for (const line of output.split(/\r?\n/)) {
+      if (/^HKEY_/.test(line)) key = line.trim();
+      const match = line.match(new RegExp(`^\\s+${name}\\s+REG_(?:EXPAND_)?SZ\\s+(.+?)\\s*$`));
+      if (key && match) found.push({ key, value: match[1] });
+    }
+    return found;
+  };
+  const named = (await Promise.all(UNINSTALL_KEYS.map((root) => query([root, '/s', '/v', 'DisplayName']))))
+    .flatMap((output) => entries(output, 'DisplayName'))
+    .map(({ key, value: name }) => ({ key, tool: DESIGN_TOOLS.find((tool) => tool.installed.test(name)) }))
+    .filter(({ tool }) => tool);
+  const folders = Object.fromEntries(DESIGN_TOOLS.map(({ id }) => [id, []]));
+  await Promise.all(named.map(async ({ key, tool }) => {
+    const folder = entries(await query([key, '/v', 'InstallLocation']), 'InstallLocation')[0]?.value.replace(/^"(.*)"$/, '$1');
+    if (folder && path.win32.isAbsolute(folder)) folders[tool.id].push(folder);
+  }));
+  return folders;
+}
+
+// A Homebrew cask's command wrapper is exactly `exec "<program in the app>" "$@"`.
+// Only that exact form is followed; any other script stays unchecked.
+const HOMEBREW_WRAPPER = /\/Caskroom\/[^/]+\/[^/]+\/\.homebrew-command-wrappers\/[^/]+$/;
+
+function homebrewTarget(head) {
+  return head.toString('utf8').match(/^#!\/bin\/(?:ba)?sh\nexec "(\/[^"$`\\\n]+)"\s+"\$@"\n?$/)?.[1] ?? null;
+}
+
+// Why a found program's version is not read, or the program to run.
+export function designProgram(file, tool, { platform = process.platform, realpath = fs.realpathSync, read = readHead } = {}) {
+  let real = realpath(file);
+  const normalized = real.replaceAll('\\', '/');
+  if (/\/flatpak\/exports\/bin\//.test(file.replaceAll('\\', '/'))) return { reason: 'A Flatpak app. Its version is not checked.' };
+  if (/(?:^|\/)snap$/.test(normalized)) return { reason: 'A snap. Its version is not checked.' };
+  const head = read(real);
+  if (!nativeProgram(head)) {
+    const target = platform === 'darwin' && HOMEBREW_WRAPPER.test(normalized) ? homebrewTarget(head) : null;
+    if (!target) return { reason: 'A launcher script. Its version is not checked.' };
+    real = realpath(target);
+    if (!nativeProgram(read(real))) return { reason: 'A launcher script. Its version is not checked.' };
+  }
+  const name = path.posix.basename(real.replaceAll('\\', '/'));
+  const program = typeof tool.program === 'function' ? tool.program(platform) : tool.program;
+  if (!program.test(name)) return { reason: `This runs ${name}, so its version is not checked.` };
+  return { file: real };
+}
+
+// GTK programs write a D-Bus keyring and profile folders even for --version.
+// Point every home and profile location at the scan's own temporary folder.
+export function designEnv(env, cwd) {
+  const out = probeEnv(env);
+  const overrides = { DBUS_SESSION_BUS_ADDRESS: 'disabled:' };
+  for (const key of ['HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_STATE_HOME', 'INKSCAPE_PROFILE_DIR', 'GIMP2_DIRECTORY', 'GIMP3_DIRECTORY']) overrides[key] = cwd;
+  for (const key of Object.keys(out)) if (Object.hasOwn(overrides, key.toUpperCase())) delete out[key];
+  return { ...out, ...overrides };
+}
+
+export async function scanDesignTool(tool, {
+  env, cwd, platform = process.platform, resolve = resolveCommand, installed = async () => null,
+  inspect = designProgram, run = runProbe, kills = null, wslInterop = false,
+} = {}) {
+  const { id, label, args, pattern } = tool;
+  const base = { id, label, status: 'not_found', version: null, path: null, command: null, detail: null };
+  let command = null, file = null;
+  for (const name of tool.commands(platform)) {
+    file = resolve(name, env, platform, { onSkip: (candidate) => platform === 'win32' && windowsAlias(candidate) });
+    if (file) { command = name; break; }
+  }
+  // WSL puts the Windows PATH on its own. Agents there run a Windows program by its .exe name.
+  if (!file && wslInterop) {
+    for (const name of tool.commands('win32').map((name) => `${name}.exe`)) {
+      file = resolve(name, env, platform);
+      if (file) return { ...base, status: 'on_path', path: file, command: name, detail: 'A Windows program, run through WSL. Its version is not checked.' };
+    }
+  }
+  const onPath = Boolean(file);
+  if (!file) file = await installed(id);
+  if (!file) return { ...base, detail: 'Not on PATH or in the usual install locations.' };
+  const row = { ...base, status: onPath ? 'on_path' : 'not_on_path', path: file, command };
+  try {
+    const program = inspect(file, tool, { platform });
+    if (program.reason) return { ...row, detail: program.reason };
+    const result = await run(program.file, args, { env: designEnv(env, cwd), cwd, kills, timeoutMs: DESIGN_TIMEOUT_MS });
+    const version = !result.error && result.code === 0 ? pattern.exec(result.output)?.[1] : null;
+    if (version) return { ...row, version };
+    return { ...row, detail: result.error === 'Version check timed out.' ? 'The version check timed out.'
+      : result.error ? 'Could not read its version.' : 'Its version response was not recognized.' };
+  } catch { return { ...row, detail: 'Could not read its version.' }; }
+}
+
+export async function scanDesignTools({ env, cwd, platform = process.platform, resolve = resolveCommand, kills = null, send = () => {} } = {}) {
+  let folders = null;
+  // Read the registry at most once, and only when some tool is missing from PATH.
+  const registry = () => folders ??= platform === 'win32'
+    ? windowsInstallFolders({ env, cwd, kills }).catch(() => ({}))
+    : Promise.resolve({});
+  const installed = async (id) => findInstalled(designLocations(id, { platform, env, registry: (await registry())[id] || [] }), { platform });
+  const wslInterop = platform === 'linux' && isWsl({ env }) && wslInteropEnabled();
+  // Bounded concurrency: cold starts of large applications compete for the disk.
+  const queue = [...DESIGN_TOOLS];
+  await Promise.all([0, 1, 2].map(async () => {
+    for (let tool = queue.shift(); tool; tool = queue.shift()) {
+      send(await scanDesignTool(tool, { env, cwd, platform, resolve, installed, kills, wslInterop }));
+    }
+  }));
+}
+
 // Windows cannot remove a process's current working directory, and a probe
 // killed at its deadline can still hold that directory. Cleanup must not
 // decide whether the scan succeeded.
@@ -235,13 +462,25 @@ if (process.argv[2] === '--scan-environment' && process.send) {
     process.chdir(cwd);
     const env = { ...process.env };
     process.send({ tools: detectTools({ env }) });
-    // Two batches bound concurrency while giving each runtime its own result.
-    for (let i = 0; i < RUNTIMES.length; i += 3) {
-      await Promise.all(RUNTIMES.slice(i, i + 3).map(async (definition) => {
-        const runtime = await scanRuntime(definition, { env, cwd, kills });
-        process.send({ runtime });
-      }));
-    }
+    await Promise.all([
+      (async () => {
+        // Two batches bound concurrency while giving each runtime its own result.
+        for (let i = 0; i < RUNTIMES.length; i += 3) {
+          await Promise.all(RUNTIMES.slice(i, i + 3).map(async (definition) => {
+            const runtime = await scanRuntime(definition, { env, cwd, kills });
+            process.send({ runtime });
+          }));
+        }
+      })(),
+      scanDesignTools({ env, cwd, kills, send: (design) => process.send({ design }) }),
+      dockerInfo({ env, resolve: resolveCommand })
+        .catch(() => ({ status: 'failed', detail: 'The Docker check did not finish.' }))
+        .then((docker) => process.send({ docker })),
+      // System facts are the same for every scope, so only the manager asks.
+      process.argv.includes('--system') && systemInfo({ env, cwd, run: runProbe, kills })
+        .catch(() => null)
+        .then((system) => process.send({ system })),
+    ]);
     finished = true;
   } finally {
     await releaseScanDirectory(cwd, kills);

package/src/manager/environment-system.mjs

@@ -0,0 +1,205 @@
+// System facts and the Docker engine, for the environment helper. Reads only:
+// os, a few small files, one registry query on Windows, and one GET /version
+// on a local Docker socket or pipe. No docker process is started and a remote
+// engine is never contacted. Where systemd starts the engine on demand
+// (docker.socket, podman.socket), opening its socket starts it.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import { createHash } from 'node:crypto';
+
+const DOCKER_TIMEOUT_MS = 1500;
+const DOCKER_LIMIT = 256 * 1024;
+const REGISTRY_TIMEOUT_MS = 3000;
+const LXSS = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Lxss';
+// Linux's system sockets belong to the docker group; a rootless or Podman socket does not.
+const GROUP_SOCKETS = ['/var/run/docker.sock', '/run/docker.sock'];
+
+function value(env, name) {
+  return env[Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase())];
+}
+
+function readText(file, read) {
+  try { return read(file, 'utf8'); } catch { return null; }
+}
+
+export function isWsl({ env = process.env, release = os.release() } = {}) {
+  return Boolean(value(env, 'WSL_DISTRO_NAME')) || /microsoft|wsl/i.test(release);
+}
+
+// WSL 1 kernels end in "-Microsoft"; WSL 2 kernels name WSL2. Newer WSL registers interop as WSLInterop-late.
+export function wslInteropEnabled({ read = fs.readFileSync } = {}) {
+  return ['WSLInterop', 'WSLInterop-late'].some((name) => /^enabled/.test(readText(`/proc/sys/fs/binfmt_misc/${name}`, read) || ''));
+}
+
+function normalArch(name) {
+  const lower = String(name || '').toLowerCase();
+  if (['x86_64', 'amd64', 'x64'].includes(lower)) return 'x64';
+  if (['aarch64', 'arm64', 'aarch64_be'].includes(lower)) return 'arm64';
+  return lower || null;
+}
+
+function linuxName(read) {
+  for (const file of ['/etc/os-release', '/usr/lib/os-release']) {
+    const text = readText(file, read);
+    const match = text?.match(/^PRETTY_NAME=(["']?)(.+)\1\s*$/m);
+    if (match) return match[2];
+  }
+  return 'Linux';
+}
+
+function macName(read) {
+  const text = readText('/System/Library/CoreServices/SystemVersion.plist', read);
+  const version = text?.match(/<key>ProductVersion<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
+  return version ? `macOS ${version}` : 'macOS';
+}
+
+// Windows lists WSL distributions under the user's Lxss key. Reading it does not start WSL.
+export async function wslDistributions({ env, cwd, run, kills = null } = {}) {
+  const reg = path.win32.join(value(env, 'SystemRoot') || 'C:\\Windows', 'System32', 'reg.exe');
+  const result = await run(reg, ['query', LXSS, '/s'], { env, cwd, kills, timeoutMs: REGISTRY_TIMEOUT_MS });
+  if (result.error) return null;
+  if (result.code !== 0) return /unable to find/i.test(result.output) ? [] : null;
+  const fallback = result.output.match(/^\s+DefaultDistribution\s+REG_SZ\s+(\S+)/m)?.[1]?.toLowerCase();
+  const distros = new Map();
+  let key = null;
+  for (const line of result.output.split(/\r?\n/)) {
+    if (/^HKEY_/.test(line)) key = line.trim().split('\\').pop().toLowerCase();
+    const name = line.match(/^\s+DistributionName\s+REG_SZ\s+(.+?)\s*$/)?.[1];
+    const version = line.match(/^\s+Version\s+REG_DWORD\s+0x([0-9a-f]+)/i)?.[1];
+    if (!key || !key.startsWith('{')) continue;
+    const entry = distros.get(key) || { name: null, version: null, default: key === fallback };
+    if (name) entry.name = name;
+    if (version) entry.version = parseInt(version, 16);
+    distros.set(key, entry);
+  }
+  return [...distros.values()].filter((entry) => entry.name)
+    .sort((a, b) => Number(b.default) - Number(a.default) || a.name.localeCompare(b.name));
+}
+
+export async function systemInfo({
+  env = process.env, cwd, platform = process.platform, run, kills = null,
+  read = fs.readFileSync, release = os.release(), version = os.version(),
+  arch = process.arch, machine = os.machine(), cpus = os.cpus(), threads = os.availableParallelism(), memory = os.totalmem(),
+} = {}) {
+  // Node says 'unknown' for a CPU it cannot name, such as many arm64 cores on Linux.
+  const model = cpus[0]?.model?.trim();
+  const info = {
+    os: null, osDetail: null, arch: normalArch(arch), hostArch: null,
+    cpu: { model: model && model !== 'unknown' ? model : null, threads }, memory, wsl: null, wslDistributions: null,
+  };
+  // Linux names the kernel's architecture, which can differ from Node's
+  // without emulation (a 32-bit build on a 64-bit kernel), so only Windows
+  // and macOS name a host architecture.
+  const host = platform === 'win32' || platform === 'darwin' ? normalArch(machine) : null;
+  if (host && host !== info.arch) info.hostArch = host;
+  if (platform === 'win32') {
+    info.os = version || 'Windows';
+    info.osDetail = `Version ${release}`;
+    try { info.wslDistributions = await wslDistributions({ env, cwd, run, kills }); } catch { /* the row is left out */ }
+  } else if (platform === 'darwin') {
+    info.os = macName(read);
+    info.osDetail = `Darwin ${release}`;
+  } else {
+    info.os = linuxName(read);
+    info.osDetail = `Kernel ${release}`;
+    if (isWsl({ env, release })) {
+      info.wsl = { version: /WSL2/i.test(release) ? 2 : 1, distro: value(env, 'WSL_DISTRO_NAME') || null, interop: wslInteropEnabled({ read }) };
+    }
+  }
+  return info;
+}
+
+// Which engine the docker command would use: DOCKER_HOST, then DOCKER_CONTEXT,
+// then the config's current context, then the platform default.
+export function dockerEndpoint({ env = process.env, platform = process.platform, read = fs.readFileSync } = {}) {
+  const host = value(env, 'DOCKER_HOST');
+  if (host) return { endpoint: host, context: null, source: 'DOCKER_HOST' };
+  const home = platform === 'win32' ? value(env, 'USERPROFILE') || os.homedir() : value(env, 'HOME') || os.homedir();
+  const join = platform === 'win32' ? path.win32.join : path.posix.join;
+  const configDir = value(env, 'DOCKER_CONFIG') || join(home, '.docker');
+  let context = value(env, 'DOCKER_CONTEXT');
+  let source = 'DOCKER_CONTEXT';
+  if (!context) {
+    try { context = JSON.parse(read(join(configDir, 'config.json'), 'utf8')).currentContext; } catch { /* no config */ }
+    source = 'config';
+  }
+  if (!context || context === 'default') {
+    return { endpoint: platform === 'win32' ? 'npipe:////./pipe/docker_engine' : 'unix:///var/run/docker.sock', context: 'default', source: 'default' };
+  }
+  const id = createHash('sha256').update(context).digest('hex');
+  try {
+    const meta = JSON.parse(read(join(configDir, 'contexts', 'meta', id, 'meta.json'), 'utf8'));
+    const endpoint = meta?.Endpoints?.docker?.Host;
+    if (typeof endpoint === 'string' && endpoint) return { endpoint, context, source };
+  } catch { /* reported below */ }
+  return { endpoint: null, context, source, error: `Docker context ${context} was not found.` };
+}
+
+// A local socket or named pipe, or null for an engine reached over the network.
+export function localSocket(endpoint) {
+  if (/^unix:\/\//i.test(endpoint)) return endpoint.replace(/^unix:\/\//i, '') || null;
+  if (/^npipe:/i.test(endpoint)) {
+    const name = endpoint.replace(/^npipe:/i, '').replace(/^[/\\]+\.?[/\\]+pipe[/\\]+/i, '');
+    return name && !/[/\\]/.test(name) ? `\\\\.\\pipe\\${name}` : null;
+  }
+  return null;
+}
+
+export function requestVersion(socketPath, { timeoutMs = DOCKER_TIMEOUT_MS, request = http.request } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result) => { if (!settled) { settled = true; resolve(result); } };
+    try {
+      const req = request({ socketPath, path: '/version', method: 'GET', headers: { Host: 'docker' }, timeout: timeoutMs }, (res) => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+          if (body.length > DOCKER_LIMIT) { req.destroy(); finish({ error: 'too_large' }); }
+        });
+        res.on('end', () => finish({ status: res.statusCode, body }));
+        res.on('error', () => finish({ error: 'read' }));
+      });
+      req.on('timeout', () => { req.destroy(); finish({ error: 'timeout' }); });
+      req.on('error', (err) => finish({ error: err.code || 'error' }));
+      req.end();
+    } catch (err) { finish({ error: err.code || 'error' }); }
+  });
+}
+
+export async function dockerInfo({ env = process.env, platform = process.platform, read = fs.readFileSync, resolve, query = requestVersion } = {}) {
+  const cli = resolve('docker', env, platform);
+  const target = dockerEndpoint({ env, platform, read });
+  const row = {
+    status: 'failed', version: null, platform: null, os: null, arch: null, wsl2: false,
+    context: target.context, endpoint: target.endpoint, cli, detail: null,
+  };
+  if (target.error) return { ...row, detail: target.error };
+  const socket = localSocket(target.endpoint);
+  if (!socket) return { ...row, status: 'remote', detail: 'This engine is reached over the network, so it is not checked.' };
+  const result = await query(socket);
+  if (result.error === 'EACCES' || result.error === 'EPERM') {
+    return { ...row, status: 'denied', detail: platform === 'win32'
+      ? 'The engine is running, but this user cannot open its pipe.'
+      : `The engine socket exists, but this user cannot open it.${platform === 'linux' && GROUP_SOCKETS.includes(socket) ? ' Adding the user to the docker group allows it.' : ''}` };
+  }
+  if (['ENOENT', 'ECONNREFUSED', 'ENOTSOCK'].includes(result.error)) {
+    return cli
+      ? { ...row, status: 'stopped', detail: 'The Docker engine is not running.' }
+      : { ...row, status: 'not_found', detail: 'No docker command on PATH and no engine answered.' };
+  }
+  if (result.error === 'timeout') return { ...row, detail: 'The engine did not answer in time.' };
+  if (result.error || result.status !== 200) return { ...row, detail: 'The engine did not give a usable answer.' };
+  let data;
+  try { data = JSON.parse(result.body); } catch { return { ...row, detail: 'The engine did not give a usable answer.' }; }
+  const version = typeof data?.Version === 'string' ? data.Version : null;
+  if (!version) return { ...row, detail: 'The engine did not give a usable answer.' };
+  const text = (item) => typeof item === 'string' && item ? item.slice(0, 200) : null;
+  return {
+    ...row, status: 'running', version,
+    platform: text(data.Platform?.Name), os: text(data.Os), arch: text(data.Arch),
+    wsl2: data.Os === 'linux' && /microsoft-standard-WSL2/i.test(data.KernelVersion || ''),
+  };
+}

package/src/manager/environment.mjs

@@ -6,10 +6,10 @@ 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 { RUNTIMES, DESIGN_TOOLS } from './environment-probe.mjs';
 import { resolveProjectCwd } from './environment-pins.mjs';
 
-export const ENVIRONMENT_TIMEOUT_MS = 10000;
+export const ENVIRONMENT_TIMEOUT_MS = 15000;
 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.';
@@ -20,7 +20,9 @@ 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',
+  'GOROOT', 'GOTOOLCHAIN', 'DOTNET_ROOT', 'R_HOME', 'DOCKER_HOST', 'DOCKER_CONTEXT', 'DOCKER_CONFIG',
+  // Install folders searched for design tools that are not on PATH.
+  'LOCALAPPDATA', 'PROGRAMFILES', 'PROGRAMW6432',
 ];
 
 function hostName() {
@@ -35,8 +37,41 @@ function cloneRow(row) {
   };
 }
 
-function pendingRuntimes() {
-  return RUNTIMES.map(({ id, label }) => ({ id, label, status: 'pending', version: null, path: null }));
+function pendingRows(list) {
+  return list.map(({ id, label }) => ({ id, label, status: 'pending', version: null, path: null }));
+}
+
+const PENDING_DOCKER = { status: 'pending' };
+
+function scanRun(extra = {}) {
+  return { child: null, timer: null, rows: new Map(), designs: new Map(), tools: [], docker: null, system: undefined, withSystem: false, ...extra };
+}
+
+// Records one helper message. Returns true when the helper reports it is done.
+function takeMessage(run, message) {
+  if (message?.runtime && RUNTIMES.some((runtime) => runtime.id === message.runtime.id)) run.rows.set(message.runtime.id, message.runtime);
+  if (message?.design && DESIGN_TOOLS.some((tool) => tool.id === message.design.id)) run.designs.set(message.design.id, message.design);
+  if (Array.isArray(message?.tools)) run.tools = message.tools;
+  if (message?.docker && typeof message.docker === 'object') run.docker = message.docker;
+  if (run.withSystem && message && 'system' in message) run.system = message.system ?? null;
+  return Boolean(message?.done);
+}
+
+function scanComplete(run) {
+  return run.rows.size === RUNTIMES.length && run.designs.size === DESIGN_TOOLS.length
+    && Boolean(run.docker) && (!run.withSystem || run.system !== undefined);
+}
+
+// Every row has a fresh result; an unfinished check is a failure, never a stale success.
+function scanRows(run, error) {
+  const failed = ({ id, label }) => ({ id, label, status: 'failed', version: null, path: null, detail: error || 'The environment check did not finish.' });
+  return {
+    runtimes: RUNTIMES.map((row) => run.rows.get(row.id) ?? failed(row)),
+    designTools: DESIGN_TOOLS.map((row) => run.designs.get(row.id) ?? failed(row)),
+    docker: run.docker ?? { status: 'failed', detail: error || 'The environment check did not finish.' },
+    tools: run.tools,
+    ...(run.withSystem ? { system: run.system ?? null } : {}),
+  };
 }
 
 export function probePathEnv(env) {
@@ -76,7 +111,10 @@ export class Environment extends EventEmitter {
     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: pendingRuntimes(),
+      runtimes: pendingRows(RUNTIMES),
+      designTools: pendingRows(DESIGN_TOOLS),
+      docker: PENDING_DOCKER,
+      system: null,
       tools: [],
     };
   }
@@ -93,7 +131,7 @@ export class Environment extends EventEmitter {
       }
       return publishLaunch ? this.launch : this.snapshot();
     }
-    const run = { child: null, timer: null, rows: new Map(), tools: [], publishLaunch };
+    const run = scanRun({ publishLaunch, withSystem: true });
     this.run = run;
     this.value = { ...this.value, revision: this.value.revision + 1, refreshing: true, error: null };
     if (publishLaunch) this.armLaunch();
@@ -104,10 +142,7 @@ export class Environment extends EventEmitter {
       this.stopWorker(run.child);
       this.value = {
         ...this.value, revision: this.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,
+        ...scanRows(run, error),
       };
       if (!this.closed) this.emit('updated', this.snapshot());
       if (run.publishLaunch) this.storeLaunch();
@@ -116,21 +151,18 @@ export class Environment extends EventEmitter {
       // A preload in NODE_OPTIONS must not execute inside a passive scan.
       const env = { ...this.env };
       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'], {
+      run.child = this.forkWorker(new URL('./environment-probe.mjs', import.meta.url), ['--scan-environment', '--system'], {
         env, execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
         windowsHide: true, detached: process.platform !== 'win32',
       });
       run.child.on('message', (message) => {
-        if (this.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();
+        if (this.run === run && takeMessage(run, message)) finish();
       });
       run.child.once('error', () => finish('Could not start the environment check.'));
-      // Let messages already queued win. Exit is a failed check only when a runtime never reported.
+      // Let messages already queued win. Exit is a failed check only when a row never reported.
       run.child.once('exit', () => setImmediate(() => {
         if (this.run !== run) return;
-        finish(run.rows.size === RUNTIMES.length ? null : 'The environment check stopped before finishing.');
+        finish(scanComplete(run) ? null : 'The environment check stopped before finishing.');
       }));
       run.timer = setTimeout(() => finish('The environment check timed out.'), this.timeoutMs);
       run.timer.unref();
@@ -146,6 +178,8 @@ export class Environment extends EventEmitter {
       revision: (previous?.revision ?? 0) + 1, refreshing: true, checkedAt: previous?.checkedAt ?? null, error: null,
       detail: LAUNCH_DETAIL,
       runtimes: (previous?.runtimes ?? this.value.runtimes).map(cloneRow),
+      designTools: (previous?.designTools ?? this.value.designTools).map(cloneRow),
+      docker: { ...(previous?.docker ?? this.value.docker) },
       tools: (previous?.tools ?? this.value.tools).map((tool) => ({ ...tool })),
     };
     if (!this.closed) this.emit('updated', this.launch);
@@ -157,6 +191,8 @@ export class Environment extends EventEmitter {
       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),
+      designTools: this.value.designTools.map(cloneRow),
+      docker: { ...this.value.docker },
       tools: this.value.tools.map((tool) => ({ ...tool })),
     };
     if (!this.closed) this.emit('updated', this.launch);
@@ -287,7 +323,7 @@ export class Environment extends EventEmitter {
     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: [],
+      runtimes: pendingRows(RUNTIMES), designTools: pendingRows(DESIGN_TOOLS), docker: PENDING_DOCKER, tools: [],
     };
   }
 
@@ -299,7 +335,7 @@ export class Environment extends EventEmitter {
     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: [],
+      checkedAt: new Date().toISOString(), error: null, runtimes: [], designTools: [], docker: null, tools: [],
     };
     this.sessions.set(key, { value, run: null });
     return value;
@@ -307,7 +343,7 @@ export class Environment extends EventEmitter {
 
   startSession(entry, found) {
     if (this.closed || entry.run) return;
-    const run = { child: null, timer: null, rows: new Map(), tools: [] };
+    const run = scanRun();
     entry.run = run;
     entry.value = { ...entry.value, revision: entry.value.revision + 1, refreshing: true, error: null };
     const finish = (error = null) => {
@@ -317,10 +353,7 @@ export class Environment extends EventEmitter {
       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,
+        ...scanRows(run, error),
       };
       if (!this.closed) this.emit('updated', entry.value);
     };
@@ -332,15 +365,12 @@ export class Environment extends EventEmitter {
         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();
+        if (entry.run === run && takeMessage(run, message)) 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.');
+        finish(scanComplete(run) ? null : 'The environment check stopped before finishing.');
       }));
       run.timer = setTimeout(() => finish('The environment check timed out.'), this.timeoutMs);
       run.timer.unref();

package/src/manager/main.mjs

@@ -14,6 +14,7 @@ import { NewsFeed } from './news.mjs';
 import { Changelog } from './changelog.mjs';
 import { GitHub } from './github.mjs';
 import { createManagerServer } from './server.mjs';
+import { loadPty } from './pty.mjs';
 import { createNotesStore } from './notes.mjs';
 import { RemoteAccess, loadRemoteAccess } from './remote-access.mjs';
 import { SelfUpdate } from './self-update.mjs';
@@ -48,7 +49,9 @@ const VERSION_REFRESH_MS = 60 * 60 * 1000;
  * `supervised`: started by the Linux boot service, so systemd starts the next manager after a restart.
  */
 export async function startManager({ port = resolvePort(), host = DEFAULT_HOST, sessionDefaults, version = VERSION, packageFile = PACKAGE_FILE, github: githubOptions = {}, remoteAccess: remoteOptions = {}, autostart = null, boot, supervised = false } = {}) {
-  // Validate before creating files, processes or timers, so a typo fails startup cleanly.
+  // Validate before creating files, processes or timers, so a typo, or a
+  // system node-pty cannot run on, fails startup cleanly.
+  loadPty();
   const remoteSettings = loadRemoteAccess(paths.remoteAccess);
   ensureDataDir();
   const token = loadOrCreateToken();

package/src/manager/pty.mjs

@@ -0,0 +1,112 @@
+// node-pty, the library that runs each session's terminal. Its Linux builds
+// in the package need glibc 2.28 or later: on an older glibc they do not
+// load, and on musl (Alpine) the x64 one loads, then crashes the manager when
+// the first session starts. So the C library is checked before node-pty is
+// loaded, unless node-pty was compiled on this computer, which it then loads
+// in place of the builds it comes with.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+/** node-pty's folder. Looked up when needed, so commands that never run a terminal do not depend on it. */
+export function ptyDir() {
+  return path.dirname(require.resolve('node-pty/package.json'));
+}
+
+let glibc;
+
+/** The glibc version this process runs on, such as '2.39'; null on another C library, such as musl. */
+export function glibcVersion() {
+  if (glibc !== undefined) return glibc;
+  // Node.js reports it only on glibc, as npm reads it for a package's `libc`.
+  // Leaving out network details keeps the report from looking up host names.
+  const { report } = process;
+  const excludeNetwork = report.excludeNetwork;
+  report.excludeNetwork = true;
+  try {
+    glibc = report.getReport().header.glibcVersionRuntime ?? null;
+  } finally {
+    report.excludeNetwork = excludeNetwork;
+  }
+  return glibc;
+}
+
+/** True when node-pty's own builds run here: other systems than Linux, or glibc 2.28 or later. */
+function bundledBuildsRun({ platform = process.platform, glibc: version } = {}) {
+  if (platform !== 'linux') return true;
+  if (version === undefined) version = glibcVersion();
+  if (!version) return false;
+  const [major, minor] = version.split('.').map(Number);
+  return major > 2 || (major === 2 && minor >= 28);
+}
+
+/** Whether node-pty in `dir` was compiled on this computer; node-pty loads such a build before the ones it comes with. */
+export function ptyBuiltHere(dir = ptyDir()) {
+  return ['Release', 'Debug'].some((build) => fs.existsSync(path.join(dir, 'build', build, 'pty.node')));
+}
+
+const shellWord = (word) => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll('\'', '\'\\\'\'')}'`);
+
+/** The command that compiles node-pty in `dir` for this computer. */
+export function ptyBuildCommand(dir = ptyDir()) {
+  return `cd ${shellWord(dir)} && npx --yes node-gyp rebuild`;
+}
+
+/**
+ * On a computer that has to compile node-pty itself: the command that does,
+ * and whether the files on disk hold such a build. Null where node-pty's own
+ * builds run. `platform`, `glibc` and `dir` stand in for this computer's in tests.
+ */
+export function ptyBuild({ platform, glibc: version, dir } = {}) {
+  if (bundledBuildsRun({ platform, glibc: version })) return null;
+  dir ??= ptyDir();
+  return { command: ptyBuildCommand(dir), built: ptyBuiltHere(dir) };
+}
+
+/**
+ * Why node-pty cannot run here, as a message for the user, or null when it
+ * can. Takes the same stand-ins as ptyBuild().
+ */
+export function ptyProblem(opts = {}) {
+  const build = ptyBuild(opts);
+  if (!build || build.built) return null;
+  const version = opts.glibc === undefined ? glibcVersion() : opts.glibc;
+  if (version) {
+    return `Agent Guild needs glibc 2.28 or later on Linux, for example Debian 10, Ubuntu 20.04 or RHEL 8. This system has glibc ${version}.`;
+  }
+  return [
+    'Agent Guild\'s terminal library, node-pty, comes built for Linux with glibc 2.28 or later, and this system uses another C library, such as musl on Alpine.',
+    'To build it here, install Python 3, make, g++ and the Linux headers (on Alpine: apk add python3 make g++ linux-headers), then run this, and again after each Agent Guild upgrade:',
+    `  ${build.command}`,
+  ].join('\n');
+}
+
+/**
+ * Why a manager started from the files on disk could not run a terminal, or
+ * null. A manager running where node-pty's own builds do not means node-pty
+ * was compiled here, so the message is how to compile it again, on any C
+ * library. Takes the same stand-ins as ptyBuild().
+ */
+export function ptyRestartProblem(opts = {}) {
+  const build = ptyBuild(opts);
+  if (!build || build.built) return null;
+  return [
+    'Agent Guild\'s terminal library, node-pty, is built on this computer, and the files on disk no longer hold that build, as after an upgrade. Build it again, then restart:',
+    `  ${build.command}`,
+    'The manager was not restarted, and its sessions keep running.',
+  ].join('\n');
+}
+
+let pty = null;
+
+/** node-pty, loaded on first use. Throws with ptyProblem()'s message where it cannot run. */
+export function loadPty() {
+  if (pty) return pty;
+  const problem = ptyProblem();
+  if (problem) throw new Error(problem);
+  pty = require('node-pty');
+  return pty;
+}

package/src/manager/self-update.mjs

@@ -7,6 +7,7 @@ import { EventEmitter } from 'node:events';
 import { compareVersions, fetchManifest } from './versions.mjs';
 import { formatCommand } from './install-channels.mjs';
 import { buildSpawnSpec } from './command-resolver.mjs';
+import { ptyBuild } from './pty.mjs';
 
 const CHECK_TTL_MS = 60 * 60 * 1000;
 const FAILED_CHECK_TTL_MS = 5 * 60 * 1000;
@@ -39,13 +40,15 @@ export class SelfUpdate extends EventEmitter {
    * @param {string} opts.version        the running version
    * @param {string|null} [opts.packageFile]  the package.json the manager runs from; read again after an install
    * @param {import('./providers.mjs').ProviderRegistry} opts.registry  for the registry URL, npm, and fetch
+   * @param {() => ({ command: string, built: boolean }|null)} [opts.ptyBuild]  node-pty's build on this computer; a stand-in in tests
    */
-  constructor({ pkg, version, packageFile = null, registry }) {
+  constructor({ pkg, version, packageFile = null, registry, ptyBuild: readPtyBuild = ptyBuild }) {
     super();
     this.pkg = pkg;
     this.version = version;
     this.packageFile = packageFile;
     this.registry = registry;
+    this.readPtyBuild = readPtyBuild;
     this.latest = null;
     this.error = null;
     this.checkedAt = 0;
@@ -139,7 +142,7 @@ export class SelfUpdate extends EventEmitter {
     if (this.installing) {
       return {
         version: this.version, latestVersion: this.latest, available: false, command: null, guidance: null,
-        pendingVersion: null, installing: true, lastInstall: null,
+        pendingVersion: null, installing: true, lastInstall: null, ptyBuild: null,
       };
     }
     const installed = this.installedVersion();
@@ -155,6 +158,8 @@ export class SelfUpdate extends EventEmitter {
       pendingVersion: this.pendingVersion(installed),
       installing: false,
       lastInstall: this.lastInstall,
+      // Where node-pty has to be compiled here, an upgrade replaces that build.
+      ptyBuild: this.readPtyBuild(),
     };
   }
 

package/src/manager/server.mjs

@@ -14,6 +14,7 @@ import { createFolderBrowser } from './folder-browser.mjs';
 import { normalizeAccess } from './access-policy.mjs';
 import { NOTES_BODY_LIMIT, createNotesStore } from './notes.mjs';
 import { MODES as AUTOSTART_MODES } from './autostart.mjs';
+import { ptyRestartProblem } from './pty.mjs';
 
 const require = createRequire(import.meta.url);
 const API = '/api/v1';
@@ -154,6 +155,8 @@ export function createManagerServer({
   launcher = null,
   /** @type {(opts: { restart: boolean }) => void} */
   onShutdownRequest = () => {},
+  /** Why a manager started from the files on disk could not run a terminal, or null; a stand-in in tests. */
+  nextManagerProblem = ptyRestartProblem,
 }) {
   let access = normalizeAccess({ hosts: extraHosts, origins: extraOrigins });
   let policyVersion = 0;
@@ -429,6 +432,11 @@ export function createManagerServer({
       // so a client must say `force` while any of those is running. The same
       // guard serves every front end.
       const body = await readJsonBody(req);
+      // The next manager runs the files on disk. Where node-pty has to be
+      // built on this computer and an upgrade replaced that build, it would
+      // not start, so this one keeps running and says what to do first.
+      const problem = body.restart === true ? nextManagerProblem() : null;
+      if (problem) throw new HttpError(409, problem, 'pty_unavailable');
       const running = manager.runningCount();
       if (running > 0 && body.force !== true) {
         const err = new HttpError(409, `${running} session(s) are running; stopping the manager ends them`, 'sessions_running');

package/src/manager/session.mjs

@@ -4,10 +4,10 @@
 
 import { EventEmitter } from 'node:events';
 import crypto from 'node:crypto';
-import pty from 'node-pty';
 import headless from '@xterm/headless';
 import serializeAddon from '@xterm/addon-serialize';
 import { killWindowsTree } from './command-resolver.mjs';
+import { loadPty } from './pty.mjs';
 
 const { Terminal } = headless;
 const { SerializeAddon } = serializeAddon;
@@ -175,7 +175,7 @@ export class Session extends EventEmitter {
   }
 
   _start(spawnSpec, cwd = this.cwd) {
-    const proc = pty.spawn(spawnSpec.file, spawnSpec.args, {
+    const proc = loadPty().spawn(spawnSpec.file, spawnSpec.args, {
       name: 'xterm-256color',
       cols: this.cols,
       rows: this.rows,

package/web/app.js

@@ -879,26 +879,58 @@ function moveDockTab(e) {
 
 // ---- upgrading the manager ------------------------------------------------
 
+/**
+ * On a computer that compiles node-pty, the terminal library, itself: the
+ * build an installed upgrade replaced, which the manager will not restart
+ * without. Null otherwise.
+ */
+function ptyRebuild(u = state.upgrade) {
+  const build = u?.ptyBuild;
+  return u?.pendingVersion && build && !build.built ? build : null;
+}
+
+/**
+ * While an upgrade waits for node-pty to be compiled again, read the build
+ * once more when the user comes back to the page, from the terminal where
+ * they may have run the command. The manager sends no event for it.
+ */
+async function recheckPtyBuild() {
+  if (!state.connected || !ptyRebuild()) return;
+  try {
+    setUpgrade((await api('GET', '/info')).upgrade);
+  } catch { /* the next hello brings it */ }
+}
+
+/** A message about compiling node-pty here, with a button that copies the command. */
+function ptyBuildToast(message, build) {
+  toast(message, 20000, { label: 'Copy command', run: () => copyText(build.command, 'the command') });
+}
+
 function renderUpgrade() {
   const u = state.upgrade;
   const button = $('upgrade');
   const note = $('upgrade-note');
   const offer = Boolean(state.connected && u?.available && u.command);
+  const build = u?.ptyBuild;
   button.hidden = !offer;
   if (offer) {
     button.textContent = `Upgrade to ${u.latestVersion}`;
-    button.title = `Run "${u.command}" in a session. Sessions keep running; the new version is used once the manager is restarted.`;
+    button.title = `Run "${u.command}" in a session. Sessions keep running; the new version is used once the manager is restarted.` +
+      (build ? ` This computer builds node-pty, the terminal library, itself: after the upgrade, run "${build.command}" in a terminal before restarting.` : '');
   }
   // A newer version on disk is used by the next manager, so the restart
   // button becomes the way to pick it up.
   const restart = $('restart-manager');
   const pending = u?.pendingVersion;
+  const rebuild = ptyRebuild(u);
   restart.classList.toggle('pending', Boolean(pending));
   $('manager').classList.toggle('pending', Boolean(pending) && state.restartable);
   restart.textContent = pending ? `Restart to use v${pending}` : 'Restart manager';
-  restart.title = pending
-    ? `Agent Guild ${pending} is installed, but this manager is still ${u.version}. Restarting ends every session and starts the new version; this page reconnects by itself.`
-    : 'Stop the session manager and start it again. This ends every session; this page reconnects by itself.';
+  restart.title = rebuild
+    ? `Agent Guild ${pending} is installed, and node-pty, the terminal library, has to be built for this computer again before the manager can restart. Run "${rebuild.command}" in a terminal first.`
+    : pending
+      ? `Agent Guild ${pending} is installed, but this manager is still ${u.version}. Restarting ends every session and starts the new version; this page reconnects by itself.`
+      : 'Stop the session manager and start it again. This ends every session; this page reconnects by itself.';
   const panelUpgrade = $('changelog-upgrade');
   panelUpgrade.hidden = button.hidden;
   panelUpgrade.textContent = button.textContent;
@@ -914,6 +946,9 @@ function renderUpgrade() {
   if (u?.installing) {
     text = `Upgrading${u.latestVersion ? ` to v${u.latestVersion}` : ''}…`;
     title = 'npm is running in a session. Keep the manager running until it finishes.';
+  } else if (rebuild) {
+    text = `v${pending} installed · build node-pty before restarting`;
+    title = `This computer builds node-pty, the terminal library, itself, and the upgrade replaced that build. Run "${rebuild.command}" in a terminal, then restart.`;
   } else if (pending && !state.restartable) {
     text = `v${pending} installed · run "agent-guild restart" to use it`;
     title = `Agent Guild ${pending} is installed, but this manager is still ${u.version} and cannot restart itself. Run "agent-guild restart" in a terminal when your sessions are done; this page reconnects by itself.`;
@@ -926,6 +961,9 @@ function renderUpgrade() {
   } else if (u?.available && !u.command) {
     text = `v${u.latestVersion} available`;
     title = u.guidance || '';
+  } else if (offer && build) {
+    text = 'Build node-pty again after upgrading';
+    title = `This computer builds node-pty, the terminal library, itself, and an upgrade replaces that build. After upgrading, run "${build.command}" in a terminal before restarting.`;
   }
   note.hidden = !state.connected || !text;
   note.textContent = text;
@@ -940,7 +978,10 @@ function setUpgrade(upgrade, baseline = false) {
   renderVersion();
   if ($('changelog').open) renderChangelog();
   const pending = state.upgrade?.pendingVersion;
-  if (pending && pending !== before?.pendingVersion) {
+  const rebuild = ptyRebuild();
+  if (pending && pending !== before?.pendingVersion && rebuild) {
+    ptyBuildToast(`Agent Guild ${pending} is installed. Before restarting, build node-pty for this computer again: run "${rebuild.command}" in a terminal.`, rebuild);
+  } else if (pending && pending !== before?.pendingVersion) {
     toast(state.restartable
       ? `Agent Guild ${pending} is installed. Use "Restart to use v${pending}" in the top bar when your sessions are done.`
       : `Agent Guild ${pending} is installed. Run "agent-guild restart" in a terminal when your sessions are done.`, 10000);
@@ -5634,6 +5675,10 @@ async function stopManager({ force = false, restart = false } = {}) {
       }
       return;
     }
+    const build = state.upgrade?.ptyBuild;
+    if (err.code === 'pty_unavailable' && build) {
+      return ptyBuildToast(`The manager was not restarted, and its sessions keep running. First build node-pty, the terminal library, for this computer: run "${build.command}" in a terminal.`, build);
+    }
     toast(err.message, 8000);
   } finally {
     for (const button of buttons) button.disabled = false;
@@ -6123,10 +6168,12 @@ document.addEventListener('visibilitychange', () => {
     flushNotes();
   }
   if (document.visibilityState === 'visible' && state.connected && Date.now() - newsLoadedAt > 60000) loadNews();
+  if (document.visibilityState === 'visible') recheckPtyBuild();
   if (document.visibilityState === 'visible' && dockShows('github') && githubShownView() === 'actions') loadView('actions');
   else scheduleRuns();
   if (branchesVisible() && !viewData('branches')?.error) loadBranches({ resume: true });
 });
+addEventListener('focus', recheckPtyBuild);
 addEventListener('pagehide', () => {
   flushNotes();
   state.pageAway = true;

package/web/environment.js

@@ -1,4 +1,6 @@
 const STATES = { pending: 'Not checked', not_found: 'Not found', unavailable: 'Runtime unavailable', failed: 'Probe failed' };
+const DESIGN_STATES = { pending: 'Not checked', not_found: 'Not found', on_path: 'On PATH', not_on_path: 'Not on PATH', failed: 'Probe failed' };
+const DOCKER_STATES = { pending: 'Not checked', running: 'Running', stopped: 'Not running', denied: 'No access', remote: 'Not checked', not_found: 'Not found', failed: 'Probe failed' };
 const PIN_STATES = { configured: 'Configured', unreadable: 'Unreadable', invalid: 'Invalid' };
 const SCOPES = [
   ['manager', 'Manager', 'Manager environment'],
@@ -9,6 +11,37 @@ const SCOPES = [
 
 export function runtimeValue(row) { return row.status === 'ok' ? row.version : STATES[row.status] || 'Probe failed'; }
 
+export function designValue(row) {
+  const state = DESIGN_STATES[row.status] || DESIGN_STATES.failed;
+  if (!row.version) return state;
+  return row.status === 'not_on_path' ? `${row.version} · Not on PATH` : row.version;
+}
+
+export function formatMemory(bytes) { return `${(bytes / 1024 ** 3).toFixed(1)} GB`; }
+
+// Label, value and detail lines for each System row.
+export function systemRows(system) {
+  const rows = [];
+  const wsl = system.wsl;
+  rows.push({ label: 'OS', value: system.os, details: [wsl && `WSL ${wsl.version}${wsl.distro ? ` · ${wsl.distro}` : ''}`, system.osDetail] });
+  rows.push({ label: 'Architecture', value: system.hostArch ? `${system.arch} · emulated on ${system.hostArch}` : system.arch, details: [] });
+  rows.push({ label: 'CPU', value: `${system.cpu.threads} threads`, details: [system.cpu.model] });
+  rows.push({ label: 'Memory', value: formatMemory(system.memory), details: [wsl && 'Memory of the WSL virtual machine, set in .wslconfig. Windows can have more.'] });
+  if (wsl) rows.push({ label: 'Windows interop', value: wsl.interop ? 'On' : 'Off', details: [!wsl.interop && 'Agents cannot run Windows programs from this distribution.'] });
+  if (Array.isArray(system.wslDistributions)) {
+    const list = system.wslDistributions;
+    rows.push({
+      label: 'WSL', value: !list.length ? 'None installed' : list.length === 1 ? '1 distribution' : `${list.length} distributions`,
+      details: list.map((item) => `${item.name}${item.version ? ` · WSL ${item.version}` : ''}${item.default ? ' · default' : ''}`),
+    });
+  }
+  return rows.map((row) => ({ ...row, details: row.details.filter(Boolean) }));
+}
+
+export function dockerValue(docker) {
+  return docker.status === 'running' && docker.version ? docker.version : DOCKER_STATES[docker.status] || DOCKER_STATES.failed;
+}
+
 export function createEnvironmentUI({
   api, onAuthError, isAuthError = () => false, document = globalThis.document,
   workingFolder = () => '', sessions = () => [],
@@ -36,11 +69,16 @@ export function createEnvironmentUI({
           : !manager ? 'Not checked' : !found.length ? 'No runtime versions verified' : 'Manager environment';
   }
 
-  function rowElement(row) {
+  function rowHead(label, value) {
     const node = element('section', undefined, 'environment-row');
     const head = element('div', undefined, 'environment-row-head');
-    head.append(element('strong', row.label), element('span', runtimeValue(row)));
+    head.append(element('strong', label), element('span', value));
     node.append(head);
+    return node;
+  }
+
+  function rowElement(row) {
+    const node = rowHead(row.label, runtimeValue(row));
     if (row.command) node.append(element('p', `Command: ${row.command}`, 'environment-detail'));
     if (row.path) node.append(element('code', row.path, 'environment-path'));
     const detail = row.detail || (row.status === 'not_found' ? 'No executable was found on the manager’s PATH.' : '');
@@ -54,11 +92,37 @@ export function createEnvironmentUI({
     return node;
   }
 
+  function designElement(row) {
+    const node = rowHead(row.label, designValue(row));
+    if (row.command) node.append(element('p', `Command: ${row.command}`, 'environment-detail'));
+    if (row.path) node.append(element('code', row.path, 'environment-path'));
+    if (row.status === 'not_on_path') node.append(element('p', 'Installed outside PATH. Agents can run it once its folder is on PATH.', 'environment-detail'));
+    if (row.detail) node.append(element('p', row.detail, 'environment-detail'));
+    return node;
+  }
+
+  function systemElement(row) {
+    const node = rowHead(row.label, row.value);
+    for (const detail of row.details) node.append(element('p', detail, 'environment-detail'));
+    return node;
+  }
+
+  function dockerElement(docker) {
+    const node = rowHead('Docker Engine', dockerValue(docker));
+    if (docker.platform) node.append(element('p', docker.platform, 'environment-detail'));
+    if (docker.os) node.append(element('p', `${docker.os}${docker.arch ? `/${docker.arch}` : ''}${docker.wsl2 ? ' · runs in WSL 2' : ''}`, 'environment-detail'));
+    if (docker.context) node.append(element('p', `Context: ${docker.context}`, 'environment-detail'));
+    if (docker.endpoint) node.append(element('code', docker.endpoint, 'environment-path'));
+    if (docker.detail) node.append(element('p', docker.detail, 'environment-detail'));
+    if (docker.status !== 'pending') {
+      node.append(element('p', docker.cli ? 'Command: docker' : 'The docker command is not on PATH.', 'environment-detail'));
+      if (docker.cli) node.append(element('code', docker.cli, 'environment-path'));
+    }
+    return node;
+  }
+
   function pinElement(row) {
-    const node = element('section', undefined, 'environment-row');
-    const head = element('div', undefined, 'environment-row-head');
-    head.append(element('strong', row.label), element('span', PIN_STATES[row.status] || 'Invalid'));
-    node.append(head);
+    const node = rowHead(row.label, PIN_STATES[row.status] || 'Invalid');
     node.append(element('p', row.source, 'environment-detail'));
     if (row.version) node.append(element('code', row.version, 'environment-path'));
     if (row.detail) node.append(element('p', row.detail, 'environment-detail'));
@@ -143,6 +207,18 @@ export function createEnvironmentUI({
     $('environment-tools-note').hidden = !showTools;
     $('environment-tools').hidden = !showTools;
     $('environment-tools-empty').hidden = !showTools;
+    $('environment-runtimes-heading').textContent = scope === 'project' ? 'Version pins' : 'Runtimes';
+    $('environment-runtimes-heading').hidden = scope === 'session' && data?.availability === 'unavailable';
+    for (const id of ['environment-design-heading', 'environment-design-note', 'environment-design']) $(id).hidden = !showTools;
+    $('environment-design').replaceChildren(...(showTools ? data?.designTools || [] : []).map(designElement));
+    const docker = showTools && data?.docker ? data.docker : null;
+    $('environment-docker-heading').hidden = !docker;
+    $('environment-docker').hidden = !docker;
+    $('environment-docker').replaceChildren(...(docker ? [dockerElement(docker)] : []));
+    const system = scope === 'manager' && data?.system ? data.system : null;
+    $('environment-system-heading').hidden = !system;
+    $('environment-system').hidden = !system;
+    $('environment-system').replaceChildren(...(system ? systemRows(system).map(systemElement) : []));
     if (scope === 'project' && data && folder === projectFolder) {
       $('environment-runtimes').hidden = true;
       $('environment-runtimes').replaceChildren();
@@ -157,8 +233,8 @@ export function createEnvironmentUI({
     }
     if (showTools) {
       $('environment-tools').replaceChildren(...tools.map((tool) => {
-        const node = element('section', undefined, 'environment-row');
-        node.append(element('strong', `${tool.label} · Detected`), element('code', tool.path, 'environment-path'));
+        const node = rowHead(tool.label, 'Detected');
+        node.append(element('code', tool.path, 'environment-path'));
         return node;
       }));
       $('environment-tools-empty').hidden = Boolean(tools.length);

package/web/index.html

@@ -400,12 +400,20 @@
       <select id="environment-session" hidden></select>
       <p id="environment-status" class="environment-detail" role="status"></p>
       <button id="environment-refresh" class="btn" type="button">Refresh</button>
+      <h3 id="environment-system-heading" hidden>System</h3>
+      <div id="environment-system" hidden></div>
+      <h3 id="environment-runtimes-heading">Runtimes</h3>
       <div id="environment-runtimes"></div>
       <div id="environment-pins" hidden></div>
       <h3 id="environment-tools-heading">Detected tools</h3>
       <p id="environment-tools-note" class="environment-detail">Presence only. Activation and the runtimes these tools manage are not checked.</p>
       <div id="environment-tools"></div>
       <p id="environment-tools-empty" class="environment-detail"></p>
+      <h3 id="environment-design-heading">Design tools</h3>
+      <p id="environment-design-note" class="environment-detail">Agents can run a tool only when it is on PATH. A version is read only from the tool's own program.</p>
+      <div id="environment-design"></div>
+      <h3 id="environment-docker-heading">Docker</h3>
+      <div id="environment-docker"></div>
       <p id="environment-manager-node" class="environment-detail"></p>
     </div>
   </dialog>