@oddessentials/agent-guild 0.2.0 → 0.3.0

package/README.md

@@ -36,6 +36,12 @@ coding tool, and see at a glance which sessions and agents are working.
   not survive a computer restart. **Stop manager** in the top bar stops the
   manager and ends every session; it asks first while any session is still
   running.
+* **Stay current.** When a newer Agent Guild is on npm, an **Upgrade**
+  button appears in the top bar and runs `npm install -g` in a session you
+  can watch. Sessions keep running; stop the manager and run `agent-guild
+  open` to use the new version.
+* **Light or dark.** The page follows your system theme and the top-bar
+  toggle switches it. The guild artwork is the dark theme.
 
 ## Requirements
 
@@ -95,6 +101,10 @@ one platform under a `win32` or `darwin` key. See
 | `modelPattern` | Regular expression that finds the model name on the tool's screen when the tool does not report it. |
 | `resumeArgs` | Arguments that resume the tool's own session, with `{id}` standing for the id, e.g. `["--resume", "{id}"]`. Without it the card has no **Existing** button. |
 | `env` | Extra environment variables for the tool. |
+| `accounts` | Further sign-ins of the tool, each in its own home folder, e.g. `[{ "id": "work", "label": "Work", "dir": "~/.claude-work" }]`. Without `dir`, the folder is `accounts/<provider>/<account>` in the data folder. The card shows one chip per account with its own meters, and a session starts under the chip picked; the tool signs in from inside the first session, and its reporting hooks are copied into the folder on first use. An entry with id `default` renames the tool's own sign-in. Needs `homeVar`. |
+| `homeVar` | The environment variable that moves the tool's home folder, e.g. `CLAUDE_CONFIG_DIR`. Set for Claude Code, Codex CLI, Gemini CLI and Grok Build by default. |
+| `accountEnv` | Further variables set for every account other than the default, with `{dir}` standing for the account's folder. By default Claude Code's secure-storage folder follows the account, and Gemini CLI keeps the account's sign-in in a file rather than the shared OS keychain. |
+| `hooks` | `{ "path", "example" }`: the hooks file inside the home folder and the file in `examples/` copied there for a new account. |
 | `color`, `monogram`, `icon` | Icon appearance. `icon` is a URL path; you can also drop `<id>.svg` into `web/icons/`. |
 | `install`, `docs` | Help shown when the tool is not installed. |
 | `usageUrl`, `billingUrl` | `https://` links to the vendor's usage and billing pages, shown on the card. The defaults point at the subscription pages; set your API console instead, or `null` to hide a link. Google's usage link opens AI Studio, which counts API-key usage only, not the Gemini CLI sign-in quota the card's meters show. |
@@ -102,10 +112,11 @@ one platform under a `win32` or `darwin` key. See
 The page's "Working folder" field sets where new sessions start. It defaults
 to your home folder.
 
-Version checks ask the registry from npm's global configuration (the one
-`npm install -g` uses) about once an hour, and installs use the same
-registry. Set `AGENT_GUILD_NPM_REGISTRY` to override it for both, or
-`AGENT_GUILD_NO_UPDATE_CHECK=1` to skip the checks.
+Version checks, for the tools and for Agent Guild itself, ask the registry
+from npm's global configuration (the one `npm install -g` uses) about once
+an hour, and installs use the same registry. Set `AGENT_GUILD_NPM_REGISTRY`
+to override it for both, or `AGENT_GUILD_NO_UPDATE_CHECK=1` to skip the
+checks.
 
 ## Show agents and models
 
@@ -160,6 +171,8 @@ coding tool in `tests/fixtures`. CI runs them on Windows, macOS and Linux.
 ## Current limits
 
 * Sessions end when the manager stops or the computer restarts.
-* Gemini CLI usage meters need its sign-in in the OS keychain (macOS, or
-  Linux with `secret-tool`) or in the older `oauth_creds.json`; Gemini CLI's
-  encrypted-file storage cannot be read.
+* Gemini CLI usage meters read its sign-in where Gemini CLI keeps it:
+  `oauth_creds.json`, or with `GEMINI_FORCE_ENCRYPTED_FILE_STORAGE=true`
+  the OS keychain (macOS, or Linux with `secret-tool`) or its encrypted
+  credentials file. A sign-in kept in the Windows Credential Manager
+  cannot be read.

package/config/providers.default.json

@@ -8,6 +8,9 @@
       "package": "@anthropic-ai/claude-code",
       "versionArgs": ["--version"],
       "usage": "claude",
+      "homeVar": "CLAUDE_CONFIG_DIR",
+      "accountEnv": { "CLAUDE_SECURESTORAGE_CONFIG_DIR": "{dir}" },
+      "hooks": { "path": "settings.json", "example": "claude-code-settings.json" },
       "modelPattern": "claude-(?:opus|sonnet|haiku|fable|\\d)[a-z0-9.-]*|\\b(?:opus|sonnet|haiku|fable)\\s?\\d+(?:\\.\\d+)?",
       "args": [],
       "resumeArgs": ["--resume", "{id}"],
@@ -41,6 +44,8 @@
       "package": "@openai/codex",
       "versionArgs": ["--version"],
       "usage": "codex",
+      "homeVar": "CODEX_HOME",
+      "hooks": { "path": "hooks.json", "example": "codex-hooks.json" },
       "modelPattern": "\\bgpt-\\d[a-z0-9.-]*",
       "args": [],
       "resumeArgs": ["resume", "{id}"],
@@ -72,6 +77,9 @@
       "package": "@google/gemini-cli",
       "versionArgs": ["--version"],
       "usage": "gemini",
+      "homeVar": "GEMINI_CLI_HOME",
+      "accountEnv": { "GEMINI_FORCE_FILE_STORAGE": "true" },
+      "hooks": { "path": ".gemini/settings.json", "example": "gemini-settings.json" },
       "modelPattern": "\\bgemini-\\d[a-z0-9.-]*",
       "args": [],
       "resumeArgs": ["--resume", "{id}"],
@@ -92,6 +100,8 @@
       "command": "grok",
       "package": "@xai-official/grok",
       "versionArgs": ["--version"],
+      "homeVar": "GROK_HOME",
+      "hooks": { "path": "hooks/agent-guild.json", "example": "grok-hooks.json" },
       "modelPattern": "\\bgrok-(?:build|\\d)[a-z0-9.-]*",
       "args": [],
       "resumeArgs": ["--resume", "{id}"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.2.0",
+  "version": "0.3.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/config.mjs

@@ -8,10 +8,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 
 export const DEFAULT_PORT = 47821;
 export const DEFAULT_HOST = '127.0.0.1';
-export const VERSION = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+/** The package.json the manager runs from; an upgrade replaces it in place. */
+export const PACKAGE_FILE = fileURLToPath(new URL('../../package.json', import.meta.url));
+const packageJson = JSON.parse(fs.readFileSync(PACKAGE_FILE, 'utf8'));
+export const VERSION = packageJson.version;
+export const PACKAGE_NAME = packageJson.name;
 
 /** Per-user data directory. Override with AGENT_GUILD_HOME (used by tests). */
 export function dataDir() {
@@ -37,6 +42,7 @@ export const paths = {
   get token() { return path.join(dataDir(), 'auth-token'); },
   get runtime() { return path.join(dataDir(), 'manager.json'); },
   get providers() { return path.join(dataDir(), 'providers.json'); },
+  get accounts() { return path.join(dataDir(), 'accounts'); },
   get log() { return path.join(dataDir(), 'manager.log'); },
   /** Launchers for agent-guild-report, put first on every session's PATH. */
   get shims() { return path.join(dataDir(), 'bin'); },

package/src/manager/main.mjs

@@ -9,10 +9,13 @@ import { SessionManager } from './session-manager.mjs';
 import { UsageMonitor } from './usage.mjs';
 import { ModelStats } from './model-stats.mjs';
 import { createManagerServer } from './server.mjs';
+import { SelfUpdate } from './self-update.mjs';
 import { resolveBaseEnv, pathReader } from './shell-env.mjs';
 import { writeReportShims } from './report-shims.mjs';
 import {
   DEFAULT_HOST,
+  PACKAGE_FILE,
+  PACKAGE_NAME,
   VERSION,
   ensureDataDir,
   loadOrCreateToken,
@@ -27,7 +30,8 @@ const rootDir = path.resolve(here, '../..');
 
 const VERSION_REFRESH_MS = 60 * 60 * 1000;
 
-export async function startManager({ port = resolvePort(), host = DEFAULT_HOST, sessionDefaults } = {}) {
+/** `version` and `packageFile` stand in for the real ones in tests. */
+export async function startManager({ port = resolvePort(), host = DEFAULT_HOST, sessionDefaults, version = VERSION, packageFile = PACKAGE_FILE } = {}) {
   ensureDataDir();
   const token = loadOrCreateToken();
   const baseEnv = resolveBaseEnv();
@@ -51,12 +55,17 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   });
 
   let api;
-  const manager = new SessionManager({ registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir });
+  const selfUpdate = new SelfUpdate({ pkg: PACKAGE_NAME, version, packageFile, registry });
+  const manager = new SessionManager({ registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate });
   const usage = new UsageMonitor({ registry, env: baseEnv });
   const modelStats = new ModelStats({ registry });
   let closing = null;
 
-  const versionTimer = setInterval(() => registry.refreshVersions().catch(() => {}), VERSION_REFRESH_MS);
+  const refreshVersions = () => {
+    registry.refreshVersions().catch(() => {});
+    selfUpdate.refresh().catch(() => {});
+  };
+  const versionTimer = setInterval(refreshVersions, VERSION_REFRESH_MS);
   versionTimer.unref();
 
   const shutdown = (reason = 'shutdown') => {
@@ -86,7 +95,8 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     host,
     port,
     webDir,
-    version: VERSION,
+    version,
+    selfUpdate,
     extraOrigins,
     onShutdownRequest: () => shutdown('requested via API').then(() => process.exit(0)),
   });
@@ -106,11 +116,11 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     host,
     port: api.port,
     url: api.url,
-    version: VERSION,
+    version,
     startedAt: new Date().toISOString(),
   });
-  console.log(`[manager] Agent Guild ${VERSION} listening on ${api.url} (pid ${process.pid})`);
-  registry.refreshVersions().catch(() => {});
+  console.log(`[manager] Agent Guild ${version} listening on ${api.url} (pid ${process.pid})`);
+  refreshVersions();
   return { api, manager, registry, token, shutdown };
 }
 

package/src/manager/providers.mjs

@@ -11,8 +11,9 @@ import { EventEmitter } from 'node:events';
 import { fileURLToPath } from 'node:url';
 import { resolveCommand, resolveAllCommands, pathKey, buildSpawnSpec, runSpec } from './command-resolver.mjs';
 import { compareVersions, probeVersion, fetchManifest, latestVersion, DEFAULT_NPM_REGISTRY } from './versions.mjs';
-import { CHANNEL_LABELS, classifyInstall, formatCommand, helpDescribes, knownLaunchers, listInstallations, platformDependency } from './install-channels.mjs';
+import { CHANNEL_LABELS, classifyInstall, expandHome, formatCommand, helpDescribes, knownLaunchers, listInstallations, platformDependency } from './install-channels.mjs';
 import { weavePaths } from './shell-env.mjs';
+import { paths } from './config.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const DEFAULTS_FILE = path.resolve(here, '../../config/providers.default.json');
@@ -86,6 +87,50 @@ function normalizeChannels(raw) {
   return out;
 }
 
+function normalizeHooks(raw) {
+  if (!raw || typeof raw !== 'object' || typeof raw.path !== 'string' || typeof raw.example !== 'string') return null;
+  const parts = raw.path.split(/[\\/]+/);
+  if (parts.some((part) => part === '' || part === '.' || part === '..') || !/^[A-Za-z0-9._-]+$/.test(raw.example)) return null;
+  return { path: parts.join('/'), example: raw.example };
+}
+
+const DEFAULT_ACCOUNT = 'default';
+
+function normalizeAccounts(raw, id, homeVar, warnings) {
+  const accounts = [{ id: DEFAULT_ACCOUNT, label: 'Default', dir: null }];
+  if (raw === undefined || raw === null) return accounts;
+  if (!Array.isArray(raw)) {
+    warnings.push(`provider "${id}": ignored accounts; it must be an array`);
+    return accounts;
+  }
+  if (!homeVar && raw.length > 0) {
+    warnings.push(`provider "${id}": ignored accounts; the provider has no homeVar`);
+    return accounts;
+  }
+  for (const entry of raw) {
+    const item = typeof entry === 'string' ? { id: entry } : entry;
+    const accountId = item && typeof item === 'object' ? String(item.id ?? '') : '';
+    if (!ID_RE.test(accountId)) {
+      warnings.push(`provider "${id}": skipped account with invalid id ${JSON.stringify(item?.id ?? entry)}`);
+      continue;
+    }
+    const label = typeof item.label === 'string' && item.label.trim() ? item.label.trim().slice(0, 40) : accountId.charAt(0).toUpperCase() + accountId.slice(1);
+    const dir = typeof item.dir === 'string' && item.dir.trim() ? item.dir.trim() : null;
+    const existing = accounts.find((a) => a.id === accountId);
+    if (existing) {
+      if (accountId !== DEFAULT_ACCOUNT) {
+        warnings.push(`provider "${id}": skipped duplicate account "${accountId}"`);
+        continue;
+      }
+      existing.label = label;
+      if (dir) warnings.push(`provider "${id}": ignored dir of the default account; it uses the tool's own home folder`);
+      continue;
+    }
+    accounts.push({ id: accountId, label, dir });
+  }
+  return accounts;
+}
+
 function httpsUrl(value, field, id, warnings) {
   if (value === undefined || value === null || value === '') return null;
   try {
@@ -99,6 +144,7 @@ function httpsUrl(value, field, id, warnings) {
 function normalize(raw, platform, warnings) {
   const merged = { ...raw, ...(raw[platform] || {}) };
   for (const key of PLATFORM_KEYS) delete merged[key];
+  const homeVar = typeof merged.homeVar === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(merged.homeVar) ? merged.homeVar : null;
   return {
     id: merged.id,
     vendor: String(merged.vendor || merged.id),
@@ -111,6 +157,10 @@ function normalize(raw, platform, warnings) {
     args: Array.isArray(merged.args) ? merged.args.map(String) : [],
     resumeArgs: Array.isArray(merged.resumeArgs) ? merged.resumeArgs.map(String) : [],
     env: normalizeEnv(merged.env),
+    homeVar,
+    accountEnv: normalizeEnv(merged.accountEnv),
+    hooks: normalizeHooks(merged.hooks),
+    accounts: normalizeAccounts(merged.accounts, merged.id, homeVar, warnings),
     color: String(merged.color || '#64748B'),
     monogram: String(merged.monogram || String(merged.vendor || merged.id).charAt(0)).slice(0, 2),
     icon: merged.icon ? String(merged.icon) : null,
@@ -172,10 +222,12 @@ export class ProviderRegistry extends EventEmitter {
    * @param {string} [opts.registryUrl]   npm registry for lookups and installs; default: npm's own configuration
    * @param {boolean} [opts.checkUpdates] false skips registry lookups entirely
    * @param {Function} [opts.fetchImpl]
+   * @param {string} [opts.accountsDir]  where accounts without a dir get their home folders
    */
-  constructor({ userFile, env, platform = process.platform, iconDir, registryUrl = null, checkUpdates = true, fetchImpl, pathReader = null } = {}) {
+  constructor({ userFile, env, platform = process.platform, iconDir, registryUrl = null, checkUpdates = true, fetchImpl, pathReader = null, accountsDir = paths.accounts } = {}) {
     super();
     this.userFile = userFile;
+    this.accountsDir = accountsDir;
     this.env = env || process.env;
     this.platform = platform;
     this.iconDir = iconDir;
@@ -184,6 +236,7 @@ export class ProviderRegistry extends EventEmitter {
     this.fetchImpl = fetchImpl;
     this.pathReader = pathReader;
     this._pathReadAt = 0;
+    this._pathPending = null;
     this._installs = new Map();
     this.versions = new Map();
     this._refreshing = null;
@@ -209,6 +262,8 @@ export class ProviderRegistry extends EventEmitter {
   npmRegistryUrl() {
     if (this.registryUrl) return Promise.resolve(this.registryUrl);
     this._npmRegistry ??= (async () => {
+      // PATH discovery in flight may change which npm is found; wait for it.
+      await this._pathPending;
       const npm = this.resolveNpm();
       if (!npm) return DEFAULT_NPM_REGISTRY;
       try {
@@ -236,11 +291,18 @@ export class ProviderRegistry extends EventEmitter {
     return pending;
   }
 
-  async refreshPath({ force = false } = {}) {
-    if (!this.pathReader) return false;
+  /** Resolves to true when the PATH changed. A concurrent caller waits for the read already in flight. */
+  refreshPath({ force = false } = {}) {
+    if (!this.pathReader) return Promise.resolve(false);
     const now = Date.now();
-    if (!force && now - this._pathReadAt < PATH_REFRESH_MS) return false;
+    if (!force && now - this._pathReadAt < PATH_REFRESH_MS) return this._pathPending ?? Promise.resolve(false);
     this._pathReadAt = now;
+    const pending = this._readPath().finally(() => { if (this._pathPending === pending) this._pathPending = null; });
+    this._pathPending = pending;
+    return pending;
+  }
+
+  async _readPath() {
     const discovered = await Promise.resolve().then(() => this.pathReader()).catch(() => null);
     if (!discovered) return false;
     const key = pathKey(this.env, this.platform);
@@ -462,6 +524,27 @@ export class ProviderRegistry extends EventEmitter {
     return this.providers.find((p) => p.id === id) || null;
   }
 
+  accountFor(provider, account) {
+    if (account.id === DEFAULT_ACCOUNT || !provider.homeVar) return { id: account.id, label: account.label, dir: null, env: {} };
+    const p = this.platform === 'win32' ? path.win32 : path.posix;
+    const own = account.dir ? expandHome(account.dir, this.env, this.platform) : null;
+    const dir = own && p.isAbsolute(own) ? p.normalize(own) : p.join(this.accountsDir, provider.id, own || account.id);
+    const env = { [provider.homeVar]: dir };
+    for (const [key, value] of Object.entries(provider.accountEnv)) env[key] = value.replaceAll('{dir}', dir);
+    return { id: account.id, label: account.label, dir, env };
+  }
+
+  accountsFor(provider) {
+    return provider.accounts.map((account) => this.accountFor(provider, account));
+  }
+
+  account(provider, id = null) {
+    const wanted = id === null || id === undefined || id === '' ? DEFAULT_ACCOUNT : String(id);
+    const found = provider.accounts.find((a) => a.id === wanted);
+    if (!found) throw refusal(404, 'unknown_account', `${provider.tool} has no account "${wanted}"`);
+    return this.accountFor(provider, found);
+  }
+
   commandFor(provider) {
     return provider.command === '@shell' ? defaultShell(this.env, this.platform) : provider.command;
   }
@@ -529,6 +612,7 @@ export class ProviderRegistry extends EventEmitter {
       warnings: this.installWarnings(provider, installs),
       npmNote: provider.npmNote,
       usageSource: provider.usage === null ? null : typeof provider.usage === 'string' ? provider.usage : 'command',
+      accounts: provider.accounts.map(({ id, label }) => ({ id, label })),
       modelPattern: provider.modelPattern,
       color: provider.color,
       monogram: provider.monogram,

package/src/manager/self-update.mjs

@@ -0,0 +1,205 @@
+// The manager's own version against the npm registry, and the npm session
+// that upgrades it. The running process keeps its code after an upgrade:
+// the new version is used once the manager is restarted.
+
+import fs from 'node:fs';
+import { EventEmitter } from 'node:events';
+import { compareVersions, fetchManifest } from './versions.mjs';
+import { formatCommand } from './install-channels.mjs';
+import { buildSpawnSpec } from './command-resolver.mjs';
+
+const CHECK_TTL_MS = 60 * 60 * 1000;
+const FAILED_CHECK_TTL_MS = 5 * 60 * 1000;
+
+/** Shown as the provider of the upgrade session. */
+export const SELF_PROVIDER = Object.freeze({
+  id: 'agent-guild',
+  vendor: 'Agent Guild',
+  tool: 'Agent Guild',
+  color: '#5B5BD6',
+  monogram: 'AG',
+  iconUrl: null,
+  modelPattern: null,
+  env: {},
+});
+
+/** True for a build that is not a published release, such as a git checkout. */
+export function isDevelopmentBuild(version) {
+  return !version || /^0\.0\.0(?:-|$)/.test(String(version));
+}
+
+function refusal(status, code, message) {
+  return Object.assign(new Error(message), { status, code });
+}
+
+export class SelfUpdate extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.pkg            the manager's npm package name
+   * @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
+   */
+  constructor({ pkg, version, packageFile = null, registry }) {
+    super();
+    this.pkg = pkg;
+    this.version = version;
+    this.packageFile = packageFile;
+    this.registry = registry;
+    this.latest = null;
+    this.error = null;
+    this.checkedAt = 0;
+    this.lastInstall = null;
+    /** True from the start of an upgrade session until its npm process has exited. */
+    this.installing = false;
+    /** The on-disk version a failed upgrade left behind, not to be trusted until an upgrade completes. */
+    this.suspectVersion = null;
+    this._refreshing = null;
+  }
+
+  /** Ask the registry for the latest release, hourly unless `force`. Emits "updated" on a change. */
+  refresh({ force = false } = {}) {
+    const run = () => this._refresh(force);
+    const pending = this._refreshing ? this._refreshing.then(run, run) : run();
+    this._refreshing = pending;
+    pending.finally(() => { if (this._refreshing === pending) this._refreshing = null; }).catch(() => {});
+    return pending;
+  }
+
+  async _refresh(force) {
+    if (!this.registry.checkUpdates || isDevelopmentBuild(this.version)) return;
+    const now = Date.now();
+    const ttl = this.error ? FAILED_CHECK_TTL_MS : CHECK_TTL_MS;
+    if (!force && now - this.checkedAt < ttl) return;
+    this.checkedAt = now;
+    const registryUrl = await this.registry.npmRegistryUrl();
+    const { manifest, error } = await fetchManifest(this.pkg, 'latest', { registryUrl, fetchImpl: this.registry.fetchImpl });
+    // A failed check keeps the release already known; it is still published.
+    const latest = manifest?.version ?? this.latest;
+    const changed = latest !== this.latest || error !== this.error;
+    this.latest = latest;
+    this.error = error;
+    if (changed) this.emit('updated');
+  }
+
+  /** Forget an upgrade's outcome once a newer release or a different install supersedes it. */
+  _pruneLastInstall(installed) {
+    const last = this.lastInstall;
+    if (last && (last.version !== this.latest || last.installedVersion !== installed)) this.lastInstall = null;
+  }
+
+  /** The version of the package files on disk, or null when unreadable (for example mid-install). */
+  installedVersion() {
+    if (!this.packageFile) return null;
+    try {
+      const version = JSON.parse(fs.readFileSync(this.packageFile, 'utf8')).version;
+      return typeof version === 'string' ? version : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * True while the files on disk are what an upgrade that did not finish
+   * left behind: npm may have replaced package.json before it was stopped.
+   * Kept apart from `lastInstall`, which a newer release supersedes; the
+   * files stay suspect until an upgrade completes or they change again.
+   */
+  _diskSuspect(installed) {
+    return this.suspectVersion !== null && installed === this.suspectVersion;
+  }
+
+  /** A version installed on disk that the running manager does not use yet, or null. */
+  pendingVersion(installed = this.installedVersion()) {
+    if (this._diskSuspect(installed)) return null;
+    return installed && installed !== this.version && compareVersions(installed, this.version) > 0 ? installed : null;
+  }
+
+  /** True when the latest release is newer than the running manager and not yet, or not reliably, on disk. */
+  available(installed = this.installedVersion()) {
+    if (!this.latest || compareVersions(this.latest, this.version) <= 0) return false;
+    return this._diskSuspect(installed) || compareVersions(this.latest, installed || this.version) > 0;
+  }
+
+  args() {
+    return this.registry.npmArgs({ args: ['install', '-g'], package: this.pkg }, this.latest);
+  }
+
+  /** The npm command that performs the upgrade, or null without npm on PATH or a known release. */
+  command() {
+    const npm = this.registry.resolveNpm();
+    return npm && this.latest ? formatCommand(npm, this.args()) : null;
+  }
+
+  /** Public description, sent in `/info`, `hello` and `manager.upgrade`. */
+  describe() {
+    // While npm runs, the files on disk are in flux: package.json may already
+    // be new while dependencies are still being written, so nothing is
+    // offered or announced until the process has exited.
+    if (this.installing) {
+      return {
+        version: this.version, latestVersion: this.latest, available: false, command: null, guidance: null,
+        pendingVersion: null, installing: true, lastInstall: null,
+      };
+    }
+    const installed = this.installedVersion();
+    this._pruneLastInstall(installed);
+    const available = this.available(installed);
+    const command = available ? this.command() : null;
+    return {
+      version: this.version,
+      latestVersion: this.latest,
+      available,
+      command,
+      guidance: available && !command ? `npm was not found on PATH. Install Node.js from https://nodejs.org, then run: npm install -g ${this.pkg}@${this.latest}` : null,
+      pendingVersion: this.pendingVersion(installed),
+      installing: false,
+      lastInstall: this.lastInstall,
+    };
+  }
+
+  /** Spawn spec for the upgrade session and the version it installs, or throws with a user-facing message. */
+  async spec() {
+    if (this.installing) throw refusal(409, 'upgrade_in_progress', 'Agent Guild is already being upgraded');
+    if (isDevelopmentBuild(this.version)) {
+      throw refusal(400, 'not_updatable', `This is a development build of Agent Guild (${this.version}); it is not upgraded from the registry.`);
+    }
+    if (!this.registry.checkUpdates) {
+      throw refusal(400, 'not_updatable', 'Version checks are off (AGENT_GUILD_NO_UPDATE_CHECK), so Agent Guild cannot upgrade itself.');
+    }
+    await this.refresh();
+    const installed = this.installedVersion();
+    this._pruneLastInstall(installed);
+    if (!this.available(installed)) {
+      throw refusal(400, 'not_updatable', this.latest
+        ? `Agent Guild ${this.latest} is the latest release${this.pendingVersion(installed) ? ' and is installed; restart the manager to use it' : ''}.`
+        : `Could not read the latest Agent Guild release${this.error ? `: ${this.error}` : ''}. Nothing was changed.`);
+    }
+    const npm = this.registry.resolveNpm();
+    if (!npm) {
+      throw refusal(409, 'npm_unavailable', 'npm was not found on PATH. Install Node.js from https://nodejs.org and restart the session manager.');
+    }
+    // buildSpawnSpec wraps npm.cmd in cmd.exe on Windows, which a PTY needs.
+    return { spec: buildSpawnSpec(npm, this.args(), this.registry.env, this.registry.platform), version: this.latest };
+  }
+
+  /** An upgrade session started; hold the lock until finishInstall. Emits "updated". */
+  beginInstall() {
+    this.installing = true;
+    this.emit('updated');
+  }
+
+  /** Record how the upgrade session ended, once its process has exited. The files on disk say whether the running copy was replaced. */
+  finishInstall({ exitCode = null, version = this.latest } = {}) {
+    this.installing = false;
+    const installed = this.installedVersion();
+    let outcome;
+    if (exitCode !== 0) outcome = 'failed';
+    else if (installed && version && compareVersions(installed, version) >= 0) outcome = 'installed';
+    else outcome = 'unchanged';
+    if (outcome === 'failed') this.suspectVersion = installed;
+    else if (outcome === 'installed') this.suspectVersion = null;
+    this.lastInstall = { outcome, exitCode, version, installedVersion: installed, at: Date.now() };
+    this.emit('updated');
+  }
+}

package/src/manager/server.mjs

@@ -106,9 +106,11 @@ export function createManagerServer({
   port = 0,
   webDir,
   version = '0.0.0',
+  selfUpdate = null,
   extraOrigins = [],
   onShutdownRequest = () => {},
 }) {
+  const upgradeInfo = () => (selfUpdate ? selfUpdate.describe() : null);
   const startedAt = new Date().toISOString();
   const vendor = vendorFiles();
   let boundPort = port;
@@ -198,6 +200,7 @@ export function createManagerServer({
     requireAuth(req, url);
 
     if (route === '/info' && method === 'GET') {
+      selfUpdate?.refresh().catch(() => {});
       return sendJson(res, 200, {
         name: 'agent-guild',
         version,
@@ -205,8 +208,13 @@ export function createManagerServer({
         platform: process.platform,
         startedAt,
         warnings: registry.warnings,
+        upgrade: upgradeInfo(),
       });
     }
+    if (route === '/upgrade' && method === 'POST') {
+      const session = await manager.upgrade();
+      return sendJson(res, 201, { session: session.toJSON() });
+    }
     if (route === '/providers' && method === 'GET') {
       registry.refreshVersions().catch(() => {});
       return sendJson(res, 200, { providers: registry.list() });
@@ -333,10 +341,11 @@ export function createManagerServer({
   }
   manager.on('event', broadcast);
   registry.on('updated', () => broadcast({ type: 'providers.updated', providers: registry.list() }));
+  selfUpdate?.on('updated', () => broadcast({ type: 'manager.upgrade', upgrade: upgradeInfo() }));
 
   function handleEvents(ws) {
     eventClients.add(ws);
-    safeSend(ws, { type: 'hello', version, sessions: manager.list() });
+    safeSend(ws, { type: 'hello', version, upgrade: upgradeInfo(), sessions: manager.list() });
     ws.on('close', () => eventClients.delete(ws));
     ws.on('message', () => { /* events socket is server -> client only */ });
   }