ai-agentmanager 1.3.1 → 1.5.0

package/src/server.js

@@ -1,13 +1,14 @@
 import fs from 'node:fs';
 import http from 'node:http';
 import https from 'node:https';
+import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
 import { WebSocketServer } from 'ws';
 import { ensureHome, HOST, loadConfig, paths, PORT, saveConfig } from './config.js';
-import { AgentManager, shellNumber } from './manager.js';
+import { AgentManager, MACHINE, shellNumber } from './manager.js';
 import { Backlog } from './backlog.js';
 import { Races } from './races.js';
 import { Review } from './review.js';
@@ -18,6 +19,9 @@ import { Landing } from './landing.js';
 import { Budgets } from './budgets.js';
 import { stats } from './stats.js';
 import { Playbooks } from './playbooks.js';
+import { Updates } from './update.js';
+import { identity } from './identity.js';
+import { Studio } from './studio.js';
 import { Memory } from './memory.js';
 import { doctor } from './doctor.js';
 import { Triggers, tokenMatches } from './triggers.js';
@@ -55,7 +59,7 @@ function isAllowedOrigin(origin, port) {
 }
 
 const PUBLIC_REMOTE_API = new Set(['POST /api/login', 'GET /api/session']);
-const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|shutdown$)/;
+const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|update(\/|$)|editors$|agents\/[\w-]+\/open-in$|shutdown$)/;
 const HOOK_PATH = '/api/hooks/agents';
 const NO_REPO_KINDS = new Set(['general', 'assistant']);
 
@@ -69,6 +73,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const backlog = new Backlog({ manager, store, config });
   const races = new Races({ manager, store });
   const review = new Review({ manager });
+  const studio = new Studio({ manager, review });
   const teams = new Teams({ manager, store, config });
   const cleanup = new Cleanup({ manager, store, config, teams });
   const landing = new Landing({ manager, store, config });
@@ -87,6 +92,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const budgets = new Budgets({ manager, store, config, notifier });
   const playbooks = new Playbooks({ manager, store });
   const memory = new Memory({ manager, config });
+  const updates = new Updates({ config });
   let remoteServer = null;
   let remotePort = null;
   // Live browser tabs: what a page does is saved on the agent's tab; popups become new tabs.
@@ -233,6 +239,23 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post('/agents/:id/plan/changes', wrap((req) => manager.requestPlanChanges(req.params.id, req.body?.note)));
   api.post('/agents/:id/plan/review', wrap((req) => manager.setPlanReview(req.params.id, req.body?.on === true)));
   api.post('/agents/:id/handoff', wrap((req) => manager.maybeHandoff(manager.mustGet(req.params.id).id, { force: true })));
+  // ---------------------------------------------------------- studio: files and editor
+  api.get('/agents/:id/files', wrap((req) => studio.list(req.params.id, req.query.dir ?? '')));
+  api.post('/agents/:id/files', wrap((req) => studio.create(req.params.id, req.body?.path, req.body?.type)));
+  api.post('/agents/:id/files/rename', wrap((req) => studio.rename(req.params.id, req.body?.from, req.body?.to)));
+  api.get('/agents/:id/file', wrap((req) => studio.read(req.params.id, req.query.path)));
+  api.put('/agents/:id/file', wrap((req) => studio.write(req.params.id, req.body?.path, req.body?.content, { mtimeMs: req.body?.mtimeMs ?? null, force: Boolean(req.body?.force) })));
+  api.delete('/agents/:id/file', wrap((req) => studio.remove(req.params.id, req.query.path)));
+  api.get('/agents/:id/file/original', wrap((req) => studio.original(req.params.id, req.query.path)));
+  api.get('/agents/:id/search', wrap((req) => studio.search(req.params.id, req.query.q)));
+  // Opening VS Code or Cursor happens on this computer, so only from it.
+  api.get('/editors', wrap(() => studio.editors()));
+  api.post('/agents/:id/open-in', wrap((req) => studio.openIn(req.params.id, req.body?.editor, req.body?.path ?? null)));
+  // The machine terminal: shells in the home folder, not tied to an agent (Open Terminal).
+  api.get('/machine/shells', wrap(() => ({ shells: manager.shellNumbers(MACHINE), home: os.homedir() })));
+  api.post('/machine/shell/new', wrap(() => ({ n: manager.nextShellNumber(MACHINE) })));
+  api.post('/machine/shell/close', wrap((req) => manager.closeShell(MACHINE, req.body?.n ? Number(req.body.n) : undefined)));
+  api.post('/machine/shell/drop', wrap((req) => manager.dropShell(MACHINE, Number(req.body?.n) || 1)));
   api.post('/agents/:id/shell/close', wrap((req) => manager.closeShell(req.params.id, req.body?.n ? Number(req.body.n) : undefined)));
   api.post('/agents/:id/shell/new', wrap((req) => ({ n: manager.nextShellNumber(manager.mustGet(req.params.id).id) })));
   api.post('/agents/:id/shell/drop', wrap((req) => manager.dropShell(req.params.id, Number(req.body?.n) || 1)));
@@ -409,6 +432,18 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post('/agents/:id/review/ack', wrap((req) => manager.ackReview(req.params.id, req.body?.action)));
   api.get('/about', wrap(() => about({ port, config: { home: paths.home, claudeBin: config.claudeBin } })));
   api.get('/about/latest', wrap(() => latestRelease()));
+  api.get('/me', wrap(async (req) => ({ ...(await identity()), remote: Boolean(req.remote) })));
+  // Updating runs npm or git here and restarts the daemon, so only from this computer.
+  api.get('/update', wrap(() => updates.status()));
+  api.post('/update/check', wrap(async () => (await updates.refresh(), updates.status())));
+  api.post('/update', wrap(() => updates.apply()));
+  api.put(
+    '/update',
+    wrap((req) => {
+      saveConfig({ updates: updates.setCheck(req.body?.check !== false) });
+      return updates.status();
+    }),
+  );
   api.get('/judge', wrap(() => manager.judge.status()));
   // On or off for this daemon, kept in config.json. The judge spends calls on your own engine plan.
   api.put('/judge', wrap((req) => {
@@ -651,14 +686,17 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   });
 
   const termKind = (q) => (shellNumber(q) ? `shell:${shellNumber(q)}` : 'claude');
+  // The machine terminal (Open Terminal) has no agent: its shells live under MACHINE.
+  const termAgent = (id) => (id === MACHINE ? { id: MACHINE } : manager.mustGet(id));
   const attachTerm = (id, kind, client) =>
     shellNumber(kind) ? manager.attachShell(id, client, shellNumber(kind)) : manager.attach(id, client);
   api.get('/agents/:id/term/stream', (req, res) => {
     let agent;
     const kind = termKind(req.query.kind);
     try {
-      agent = manager.mustGet(req.params.id);
-      manager.plugins.check('terminal.open', { agent: manager.auditView(agent), kind });
+      agent = termAgent(req.params.id);
+      if (agent.id === MACHINE) manager.plugins.check('terminal.open', { agent: null, kind: 'machine' });
+      else manager.plugins.check('terminal.open', { agent: manager.auditView(agent), kind });
     } catch (err) {
       return res.status(err.status || 404).json({ error: err.message });
     }
@@ -699,7 +737,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post(
     '/agents/:id/term/input',
     wrap((req) => {
-      const agent = manager.mustGet(req.params.id);
+      const agent = termAgent(req.params.id);
       if (typeof req.body?.d !== 'string') throw fail(400, 'd (string) is required');
       manager.write(agent.id, req.body.d, termKind(req.body.kind));
       return { ok: true };
@@ -708,7 +746,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post(
     '/agents/:id/term/resize',
     wrap((req) => {
-      const agent = manager.mustGet(req.params.id);
+      const agent = termAgent(req.params.id);
       manager.resize(agent.id, req.body?.cols | 0, req.body?.rows | 0, termKind(req.body?.kind));
       return { ok: true };
     }),
@@ -780,12 +818,13 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     if (!m) return ws.close(1008, 'unknown endpoint');
     let session;
     try {
-      const agent = manager.mustGet(m[1]);
+      // The machine terminal has no agent; its shells live under MACHINE.
+      const agent = m[1] === MACHINE ? { id: MACHINE } : manager.mustGet(m[1]);
       const client = {
         send: (msg) => ws.readyState === ws.OPEN && ws.send(JSON.stringify(msg)),
         close: () => ws.close(1000, 'agent removed'),
       };
-      const kind = termKind(url.searchParams.get('kind'));
+      const kind = agent.id === MACHINE ? `shell:${shellNumber(url.searchParams.get('kind')) || 1}` : termKind(url.searchParams.get('kind'));
       session = attachTerm(agent.id, kind, client);
       client.send({ t: 'hello', id: agent.id, kind, running: session.running, backlog: session.backlog });
       ws.on('message', (raw) => {
@@ -854,6 +893,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     triggers.close();
     budgets.close();
     playbooks.close();
+    updates.close();
     assistant.close();
     console.log(`[agentmgr] shutting down (${reason}); closing agents so their sessions are saved`);
     await manager.stopAll({ final: true });

package/src/studio.js

@@ -0,0 +1,255 @@
+// The studio: browse and edit an agent's files from the app (a file tree and an editor), search
+// them, compare a file with where the agent started, and open the folder in VS Code or Cursor.
+// Every path is resolved inside the agent's folder; links that point outside it are refused.
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as git from './git.js';
+import { NO_REPO } from './manager.js';
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+export const MAX_FILE_BYTES = 2_000_000;
+// Listed but not opened by default: noisy, huge or generated.
+export const HIDDEN = new Set(['.git', 'node_modules', '.DS_Store', '__pycache__', '.venv', 'dist', 'build', '.next', 'target', 'coverage']);
+const EDITORS = {
+  vscode: { label: 'VS Code', bins: ['code', '/usr/local/bin/code', '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code'] },
+  cursor: { label: 'Cursor', bins: ['cursor', '/usr/local/bin/cursor', '/Applications/Cursor.app/Contents/Resources/app/bin/cursor'] },
+};
+
+/**
+ * `rel` inside `root`, as an absolute path, or an error. Refuses "..", absolute paths and
+ * symlinks that resolve outside the folder (checked on the nearest part that exists).
+ */
+export function resolveInside(root, rel = '') {
+  const realRoot = fs.realpathSync(root);
+  const clean = String(rel ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+  if (clean.split('/').includes('..')) throw err(400, 'Paths may not contain ".."');
+  const abs = path.join(realRoot, clean);
+  let probe = abs;
+  while (!fs.existsSync(probe) && probe !== realRoot) probe = path.dirname(probe);
+  const real = fs.realpathSync(probe);
+  if (real !== realRoot && !real.startsWith(realRoot + path.sep)) throw err(403, 'That path is outside the agent folder');
+  return abs;
+}
+
+const statOf = (abs, rel) => {
+  try {
+    return fs.statSync(abs);
+  } catch {
+    throw err(404, `${rel || 'That path'} doesn't exist`);
+  }
+};
+
+/** True when the bytes look like text (no NUL in the first 8 KB). */
+export const isText = (buf) => !buf.subarray(0, 8192).includes(0);
+
+/** A language id for the editor from a file name. */
+export function languageOf(name) {
+  const ext = path.extname(name).toLowerCase().slice(1);
+  const base = path.basename(name).toLowerCase();
+  if (base === 'dockerfile') return 'dockerfile';
+  if (base === 'makefile') return 'makefile';
+  const map = {
+    js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript', ts: 'typescript', tsx: 'typescript', json: 'json', md: 'markdown',
+    py: 'python', rb: 'ruby', go: 'go', rs: 'rust', java: 'java', kt: 'kotlin', swift: 'swift', c: 'c', h: 'c', cc: 'cpp', cpp: 'cpp', hpp: 'cpp',
+    cs: 'csharp', php: 'php', sh: 'shell', bash: 'shell', zsh: 'shell', yml: 'yaml', yaml: 'yaml', toml: 'ini', ini: 'ini', html: 'html', css: 'css',
+    scss: 'scss', less: 'less', sql: 'sql', xml: 'xml', svg: 'xml', vue: 'html', graphql: 'graphql', lua: 'lua', r: 'r', scala: 'scala', dart: 'dart',
+  };
+  return map[ext] ?? 'plaintext';
+}
+
+const which = (bin) => new Promise((resolve) => (bin.startsWith('/') ? resolve(fs.existsSync(bin) ? bin : null) : execFile('/usr/bin/env', ['which', bin], (e, out) => resolve(e ? null : out.trim() || null))));
+
+export class Studio {
+  constructor({ manager, review }) {
+    this.manager = manager;
+    this.review = review;
+  }
+
+  agentDir(ref) {
+    const agent = this.manager.mustGet(ref);
+    if (NO_REPO.has(agent.kind) && !agent.workdir) throw err(400, 'This session has no folder');
+    if (!agent.workdir || !fs.existsSync(agent.workdir)) throw err(409, 'The agent folder is not ready yet');
+    return { agent, root: agent.workdir };
+  }
+
+  check(agent, action, details = {}) {
+    this.manager.plugins.check(action, { agent: this.manager.auditView(agent), ...details });
+  }
+
+  /** One folder's entries: folders first, then files, by name. */
+  list(ref, dir = '') {
+    const { root } = this.agentDir(ref);
+    const abs = resolveInside(root, dir);
+    if (!statOf(abs, dir).isDirectory()) throw err(400, 'Not a folder');
+    const entries = fs
+      .readdirSync(abs, { withFileTypes: true })
+      .map((d) => {
+        const rel = path.posix.join(String(dir).replace(/^\/+|\/+$/g, ''), d.name);
+        let type = d.isDirectory() ? 'dir' : 'file';
+        let size = null;
+        if (d.isSymbolicLink()) {
+          try {
+            const st = fs.statSync(resolveInside(root, rel));
+            type = st.isDirectory() ? 'dir' : 'file';
+            size = st.isFile() ? st.size : null;
+          } catch {
+            type = 'link';
+          }
+        } else if (type === 'file') {
+          try {
+            size = fs.statSync(path.join(abs, d.name)).size;
+          } catch {}
+        }
+        return { name: d.name, path: rel, type, size, hidden: HIDDEN.has(d.name) };
+      })
+      .sort((a, b) => (a.type === 'dir') - (b.type === 'dir') ? (b.type === 'dir') - (a.type === 'dir') : a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+    return { root, dir: String(dir).replace(/^\/+|\/+$/g, ''), entries };
+  }
+
+  read(ref, rel) {
+    const { root } = this.agentDir(ref);
+    const abs = resolveInside(root, rel);
+    const st = statOf(abs, rel);
+    if (!st.isFile()) throw err(400, 'Not a file');
+    const base = { path: rel, size: st.size, mtimeMs: st.mtimeMs, language: languageOf(rel) };
+    if (st.size > MAX_FILE_BYTES) return { ...base, tooLarge: true, max: MAX_FILE_BYTES };
+    const buf = fs.readFileSync(abs);
+    if (!isText(buf)) return { ...base, binary: true };
+    return { ...base, content: buf.toString('utf8') };
+  }
+
+  /** Save a file. With `mtimeMs` (from when it was opened), refuses if it changed since. */
+  write(ref, rel, content, { mtimeMs = null, force = false } = {}) {
+    const { agent, root } = this.agentDir(ref);
+    if (typeof content !== 'string') throw err(400, 'content (string) is required');
+    if (Buffer.byteLength(content) > MAX_FILE_BYTES) throw err(413, `Files over ${MAX_FILE_BYTES / 1e6} MB can't be saved from the editor`);
+    const abs = resolveInside(root, rel);
+    this.check(agent, 'agent.files', { op: 'write', path: rel });
+    if (fs.existsSync(abs)) {
+      const st = fs.statSync(abs);
+      if (!st.isFile()) throw err(400, 'Not a file');
+      if (mtimeMs != null && !force && Math.abs(st.mtimeMs - Number(mtimeMs)) > 1) {
+        throw Object.assign(err(409, 'The file changed on disk since you opened it (the agent may have edited it)'), { conflict: true });
+      }
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    const st = fs.statSync(abs);
+    return { path: rel, size: st.size, mtimeMs: st.mtimeMs };
+  }
+
+  create(ref, rel, type = 'file') {
+    const { agent, root } = this.agentDir(ref);
+    if (!String(rel ?? '').trim()) throw err(400, 'A name is required');
+    const abs = resolveInside(root, rel);
+    if (fs.existsSync(abs)) throw err(409, `${rel} already exists`);
+    this.check(agent, 'agent.files', { op: 'create', path: rel });
+    if (type === 'dir') fs.mkdirSync(abs, { recursive: true });
+    else {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, '');
+    }
+    return { path: rel, type };
+  }
+
+  rename(ref, from, to) {
+    const { agent, root } = this.agentDir(ref);
+    const a = resolveInside(root, from);
+    const b = resolveInside(root, to);
+    if (!fs.existsSync(a)) throw err(404, `${from} doesn't exist`);
+    if (fs.existsSync(b)) throw err(409, `${to} already exists`);
+    if (a === fs.realpathSync(root)) throw err(400, "The agent folder itself can't be renamed");
+    this.check(agent, 'agent.files', { op: 'rename', path: from, to });
+    fs.mkdirSync(path.dirname(b), { recursive: true });
+    fs.renameSync(a, b);
+    return { from, to };
+  }
+
+  remove(ref, rel) {
+    const { agent, root } = this.agentDir(ref);
+    const abs = resolveInside(root, rel);
+    if (abs === fs.realpathSync(root) || !String(rel ?? '').trim()) throw err(400, "The agent folder itself can't be deleted here");
+    if (!fs.existsSync(abs)) throw err(404, `${rel} doesn't exist`);
+    this.check(agent, 'agent.files', { op: 'delete', path: rel });
+    fs.rmSync(abs, { recursive: true, force: true });
+    return { path: rel, deleted: true };
+  }
+
+  /** Text search: git grep in a repository (ignored files skipped), else a bounded walk. */
+  async search(ref, q, { max = 200 } = {}) {
+    const { root } = this.agentDir(ref);
+    const term = String(q ?? '');
+    if (term.trim().length < 2) throw err(400, 'Search for at least 2 characters');
+    const hits = [];
+    if (await git.isGitRepo(root)) {
+      const out = await git
+        .run('git', ['grep', '-n', '-I', '--untracked', '--fixed-strings', '-i', '--full-name', '-e', term], { cwd: root, timeout: 20_000 })
+        .catch((e) => (e.code === 1 ? '' : Promise.reject(e)));
+      for (const line of out.split('\n')) {
+        const m = line.match(/^(.*?):(\d+):(.*)$/);
+        if (m) hits.push({ path: m[1], line: Number(m[2]), text: m[3].slice(0, 300) });
+        if (hits.length >= max) break;
+      }
+      return { q: term, hits, truncated: hits.length >= max };
+    }
+    const lower = term.toLowerCase();
+    const walk = (dir) => {
+      for (const d of fs.readdirSync(path.join(root, dir), { withFileTypes: true })) {
+        if (hits.length >= max) return;
+        if (HIDDEN.has(d.name)) continue;
+        const rel = path.posix.join(dir, d.name);
+        if (d.isDirectory()) walk(rel);
+        else if (d.isFile()) {
+          const buf = fs.readFileSync(path.join(root, rel));
+          if (buf.length > MAX_FILE_BYTES || !isText(buf)) continue;
+          buf.toString('utf8').split('\n').forEach((text, i) => {
+            if (hits.length < max && text.toLowerCase().includes(lower)) hits.push({ path: rel, line: i + 1, text: text.slice(0, 300) });
+          });
+        }
+      }
+    };
+    walk('');
+    return { q: term, hits, truncated: hits.length >= max };
+  }
+
+  /** The file as it was where the agent started (its base), for a side-by-side diff. */
+  async original(ref, rel) {
+    const { agent, root } = this.agentDir(ref);
+    resolveInside(root, rel);
+    if (!(await git.isGitRepo(root))) return { path: rel, content: null, why: 'Not a git repository' };
+    const base = await this.review.base(agent).catch(() => null);
+    const at = base?.sha ?? 'HEAD';
+    const prefix = (await git.run('git', ['rev-parse', '--show-prefix'], { cwd: root }).catch(() => '')).trim();
+    const content = await git.run('git', ['show', `${at}:${prefix}${rel}`], { cwd: root, timeout: 10_000, trim: false }).catch(() => null);
+    return { path: rel, content, base: base?.ref ?? 'HEAD', new: content === null };
+  }
+
+  /** Editors on this machine that can open the folder. */
+  async editors() {
+    const found = [];
+    for (const [id, e] of Object.entries(EDITORS)) {
+      for (const bin of e.bins) {
+        const at = await which(bin);
+        if (at) {
+          found.push({ id, label: e.label, bin: at });
+          break;
+        }
+      }
+    }
+    return found;
+  }
+
+  /** Open the agent's folder (and a file in it) in VS Code or Cursor on this machine. */
+  async openIn(ref, editor = 'vscode', rel = null) {
+    const { root } = this.agentDir(ref);
+    const e = (await this.editors()).find((x) => x.id === editor);
+    if (!e) throw err(404, `${EDITORS[editor]?.label ?? editor} isn't installed (its "${editor === 'cursor' ? 'cursor' : 'code'}" command wasn't found)`);
+    const args = [root];
+    if (rel) args.push('--goto', resolveInside(root, rel));
+    const child = spawn(e.bin, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});
+    child.unref();
+    return { ok: true, editor: e.label, folder: root };
+  }
+}

package/src/update.js

@@ -0,0 +1,160 @@
+// Updating Agent Manager in place, then restarting so agents resume on the new version. Two kinds
+// of install: a git checkout (cloned at a release tag, or `npm link`ed from one) moves to the
+// newest release tag; an npm install runs `npm install -g <package>@<version>`. A checkout on a
+// branch or with uncommitted changes is someone's working copy, so it is left alone.
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { paths } from './config.js';
+import { latestRelease, newerThan } from './about.js';
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BIN = path.join(root, 'bin', 'agentmgr.js');
+const err = (status, message) => Object.assign(new Error(message), { status });
+const CHECK_EVERY_MS = 12 * 3_600_000;
+
+const run = (cmd, args, { cwd = root, timeoutMs = 120_000 } = {}) =>
+  new Promise((resolve, reject) => {
+    execFile(cmd, args, { cwd, timeout: timeoutMs, maxBuffer: 8 << 20, env: process.env }, (e, stdout, stderr) => {
+      if (e) reject(Object.assign(new Error(`${cmd} ${args.join(' ')}: ${(stderr || e.message).trim().split('\n').pop()}`), { status: 500 }));
+      else resolve(stdout.trim());
+    });
+  });
+
+const pkg = (dir = root) => JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+
+/** The newest release tag (vX.Y.Z, no pre-releases) among `tags`, or null. */
+export function newestTag(tags) {
+  return (
+    tags
+      .map((t) => t.trim())
+      .filter((t) => /^v\d+\.\d+\.\d+$/.test(t))
+      .sort((a, b) => (newerThan(a.slice(1), b.slice(1)) ? -1 : newerThan(b.slice(1), a.slice(1)) ? 1 : 0))[0] ?? null
+  );
+}
+
+/** How this copy was installed: 'git' (a checkout, worktrees included) or 'npm'. */
+export const installKind = (dir = root) => (fs.existsSync(path.join(dir, '.git')) ? 'git' : 'npm');
+
+/** Why a git checkout can't be moved to a release tag, or null when it can. */
+export async function gitBlocker(dir = root) {
+  const branch = await run('git', ['symbolic-ref', '-q', '--short', 'HEAD'], { cwd: dir }).catch(() => '');
+  if (branch) return `This copy is a git checkout on branch "${branch}" (someone's working copy); update it with git, or run a release from a checkout at a release tag`;
+  const changed = await run('git', ['status', '--porcelain', '--untracked-files=no'], { cwd: dir });
+  if (changed) return 'This checkout has uncommitted changes; commit or discard them first';
+  return null;
+}
+
+/** What is installed, the newest release, and whether this copy can update itself to it. */
+export async function checkUpdate({ dir = root, fetchTags = true } = {}) {
+  const kind = installKind(dir);
+  const current = pkg(dir).version;
+  if (kind === 'git') {
+    if (fetchTags) await run('git', ['fetch', '--tags', '--quiet', 'origin'], { cwd: dir, timeoutMs: 60_000 });
+    const tag = newestTag((await run('git', ['tag', '-l', 'v*'], { cwd: dir })).split('\n'));
+    const latest = tag ? tag.slice(1) : current;
+    const newer = newerThan(latest, current);
+    return { kind, current, latest, newer, blocker: newer ? await gitBlocker(dir) : null, checkedAt: new Date().toISOString() };
+  }
+  const r = await latestRelease();
+  return { kind, current, latest: r.latest, newer: r.newer, blocker: null, checkedAt: new Date().toISOString() };
+}
+
+/** Put the newest release in place (no restart). Returns { from, to } or { upToDate }. */
+export async function installUpdate({ dir = root, log = () => {} } = {}) {
+  const info = await checkUpdate({ dir });
+  if (!info.newer) return { upToDate: true, current: info.current };
+  if (info.blocker) throw err(409, info.blocker);
+  if (info.kind === 'git') {
+    const lockBefore = await run('git', ['rev-parse', 'HEAD:package-lock.json'], { cwd: dir }).catch(() => '');
+    log(`checking out v${info.latest}`);
+    await run('git', ['checkout', '--quiet', '--detach', `v${info.latest}`], { cwd: dir });
+    const lockAfter = await run('git', ['rev-parse', 'HEAD:package-lock.json'], { cwd: dir }).catch(() => '');
+    if (lockAfter !== lockBefore || !fs.existsSync(path.join(dir, 'node_modules'))) {
+      log('installing dependencies');
+      await run('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir, timeoutMs: 600_000 });
+    }
+  } else {
+    const name = pkg(dir).name;
+    log(`npm install -g ${name}@${info.latest}`);
+    await run('npm', ['install', '-g', `${name}@${info.latest}`], { timeoutMs: 600_000 }).catch((e) => {
+      throw err(500, `${e.message}${/EACCES|permission/i.test(e.message) ? ' (npm needs write access to its global folder)' : ''}`);
+    });
+  }
+  return { from: info.current, to: info.latest, kind: info.kind };
+}
+
+/** Restart the daemon from a separate process, so it outlives this one (`agentmgr restart`). */
+export function restartDetached() {
+  const out = fs.openSync(paths.log, 'a');
+  const child = spawn(process.execPath, [BIN, 'restart'], { detached: true, stdio: ['ignore', out, out], env: process.env });
+  child.unref();
+}
+
+/** The daemon's side: a check twice a day (config "updates": { "check": false } turns it off). */
+export class Updates {
+  constructor({ config = {}, log = (m) => console.log(`[agentmgr] ${m}`), check = checkUpdate } = {}) {
+    this.config = config;
+    this.log = log;
+    this.check = check;
+    this.last = null;
+    this.busy = null;
+    this.schedule();
+  }
+
+  get enabled() {
+    return this.config.updates?.check !== false && process.env.AGENTMGR_UPDATE_CHECK !== '0';
+  }
+
+  /** Start or stop the periodic check to match the setting. */
+  schedule() {
+    this.close();
+    if (!this.enabled) return;
+    this.first = setTimeout(() => this.refresh().catch(() => {}), 30_000);
+    this.timer = setInterval(() => this.refresh().catch(() => {}), CHECK_EVERY_MS);
+    this.first.unref?.();
+    this.timer.unref?.();
+  }
+
+  setCheck(on) {
+    this.config.updates = { ...this.config.updates, check: Boolean(on) };
+    this.schedule();
+    return this.config.updates;
+  }
+
+  close() {
+    clearTimeout(this.first);
+    clearInterval(this.timer);
+  }
+
+  async refresh() {
+    try {
+      this.last = await this.check();
+    } catch (e) {
+      this.last = { ...(this.last ?? {}), error: e.message, checkedAt: new Date().toISOString() };
+      throw e;
+    }
+    return this.last;
+  }
+
+  status() {
+    return { check: this.enabled, updating: Boolean(this.busy), ...(this.last ?? {}) };
+  }
+
+  /** Install the newest release, then restart onto it. Answers before the restart begins. */
+  async apply({ restart = restartDetached } = {}) {
+    if (this.busy) throw err(409, 'An update is already running');
+    this.busy = installUpdate({ log: (m) => this.log(`update: ${m}`) });
+    try {
+      const r = await this.busy;
+      if (r.upToDate) return r;
+      this.log(`update: ${r.from} → ${r.to} installed; restarting`);
+      this.last = { ...(this.last ?? {}), current: r.to, newer: false };
+      setTimeout(restart, 200);
+      return { ...r, restarting: true };
+    } finally {
+      this.busy = null;
+    }
+  }
+}