@oddessentials/agent-guild 0.35.0 → 0.37.0

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;