ai-agentmanager 1.3.0 → 1.4.0

package/public/machine.js

@@ -0,0 +1,114 @@
+// Open Terminal: shells on this computer, in your home folder, not tied to any agent. Works from
+// any signed-in device (over remote access it streams like an agent's shell). The shells keep
+// running when the window is hidden; × ends one.
+import { openStream } from '/transport.js';
+
+const MACHINE = '__machine__';
+
+export function initMachine({ api, esc, toast, $, Terminal, FitAddon }) {
+  const dialog = $('#machine-dialog');
+  let xterm = null;
+  let fit = null;
+  let conn = null;
+  let current = null;
+  let shells = [];
+
+  function ensure() {
+    if (xterm) return;
+    xterm = new Terminal({ cursorBlink: true, fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', fontSize: 13, scrollback: 10000, theme: { background: '#0f1117' } });
+    fit = new FitAddon();
+    xterm.loadAddon(fit);
+    xterm.open($('#machine-term'));
+    xterm.onData((d) => conn?.send({ t: 'i', d }));
+    xterm.onResize(({ cols, rows }) => conn?.send({ t: 'r', cols, rows }));
+    new ResizeObserver(() => dialog.open && fit.fit()).observe($('#machine-term'));
+  }
+
+  function renderTabs() {
+    const nums = [...new Set([...shells, current].filter(Boolean))].sort((a, b) => a - b);
+    $('#machine-tabs').innerHTML = nums
+      .map((n) => `<button class="term-tab ${n === current ? 'active' : ''}" data-n="${n}" role="tab">Terminal ${n}<span class="x" data-drop="${n}" title="End this terminal">×</span></button>`)
+      .join('');
+  }
+
+  function connect(n) {
+    conn?.close();
+    current = n;
+    xterm.reset();
+    renderTabs();
+    conn = openStream(
+      { agentId: MACHINE, kind: `shell:${n}` },
+      {
+        onOpen: () => {
+          fit.fit();
+          conn.send({ t: 'r', cols: xterm.cols, rows: xterm.rows });
+          xterm.focus();
+        },
+        onMessage: (msg) => {
+          if (msg.t === 'hello' && msg.backlog) xterm.write(msg.backlog);
+          else if (msg.t === 'o') xterm.write(msg.d);
+          else if (msg.t === 'exit') xterm.write('\r\n\x1b[2m[terminal ended; reopen it with + Terminal]\x1b[0m\r\n');
+          else if (msg.t === 'error') xterm.write(`\r\n\x1b[31m${msg.error}\x1b[0m\r\n`);
+        },
+        onClose: ({ reason }) => reason && xterm.write(`\r\n\x1b[2m[${reason}]\x1b[0m\r\n`),
+      },
+    );
+    xterm.focus();
+  }
+
+  async function refresh() {
+    const r = await api('GET', '/machine/shells');
+    shells = r.shells;
+    $('#machine-title').textContent = r.home;
+    return r;
+  }
+
+  $('#machine-btn').onclick = async () => {
+    try {
+      dialog.showModal();
+      ensure();
+      await refresh();
+      const n = current && shells.includes(current) ? current : shells[0] ?? (await api('POST', '/machine/shell/new')).n;
+      requestAnimationFrame(() => connect(n));
+    } catch (err) {
+      dialog.close();
+      toast(`Error: ${err.message}`, 5000);
+    }
+  };
+  $('#machine-new').onclick = async () => {
+    const { n } = await api('POST', '/machine/shell/new');
+    shells = [...new Set([...shells, n])];
+    connect(n);
+  };
+  $('#machine-close').onclick = () => {
+    conn?.close();
+    conn = null;
+    dialog.close();
+  };
+  dialog.addEventListener('close', () => {
+    conn?.close();
+    conn = null;
+  });
+  $('#machine-tabs').addEventListener('click', async (e) => {
+    const drop = e.target.closest('[data-drop]');
+    if (drop) {
+      e.stopPropagation();
+      const n = Number(drop.dataset.drop);
+      await api('POST', '/machine/shell/drop', { n });
+      await refresh();
+      shells = shells.filter((x) => x !== n);
+      if (n === current) {
+        if (shells.length) connect(shells[0]);
+        else {
+          current = null;
+          conn?.close();
+          dialog.close();
+        }
+      } else renderTabs();
+      return;
+    }
+    const tab = e.target.closest('[data-n]');
+    if (tab && Number(tab.dataset.n) !== current) connect(Number(tab.dataset.n));
+  });
+  return {};
+}

package/public/menu.js

@@ -0,0 +1,92 @@
+// The menu at the right of the top bar: who this runs as (Claude account, git identity, computer)
+// and the settings and preferences: Settings…, Clean up, Alerts, Remote access, About.
+
+export function initMenu({ api, esc, toast, $ }) {
+  const btn = $('#menu-btn');
+  const menu = $('#menu');
+  const remote = () => document.body.classList.contains('remote');
+
+  const open = (on) => {
+    menu.hidden = !on;
+    btn.setAttribute('aria-expanded', String(on));
+  };
+  btn.onclick = (e) => {
+    e.stopPropagation();
+    open(menu.hidden);
+  };
+  document.addEventListener('click', (e) => {
+    if (!menu.hidden && !menu.contains(e.target)) open(false);
+  });
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && !menu.hidden) open(false);
+  });
+  // Any item closes the menu; its own handler does the rest.
+  menu.addEventListener('click', (e) => {
+    if (e.target.closest('button')) open(false);
+  });
+  $('#menu-about').onclick = () => $('#about-btn').click();
+
+  async function loadMe() {
+    try {
+      const me = await api('GET', '/me');
+      const initials = me.display
+        .split(/[\s@._-]+/)
+        .filter(Boolean)
+        .slice(0, 2)
+        .map((w) => w[0].toUpperCase())
+        .join('');
+      $('#me-avatar').textContent = initials || '·';
+      $('#me-name').textContent = me.display;
+      $('#me-display').textContent = me.display;
+      $('#me-email').textContent = me.email ?? '';
+      $('#me-email').hidden = !me.email;
+      const where = [me.claude ? `Claude account${me.claude.organization && !me.claude.organization.includes(me.claude.email) ? ` · ${me.claude.organization}` : ''}` : null, me.user && me.host ? `${me.user} on ${me.host}` : null, me.remote ? 'signed in from this device' : null].filter(Boolean);
+      $('#me-where').innerHTML = where.map(esc).join('<br>');
+      btn.title = `${me.display}${me.email ? ` (${me.email})` : ''}: settings and preferences`;
+    } catch {
+      // An older daemon has no /me: the menu still works.
+      $('#me-display').textContent = 'Settings';
+    }
+  }
+
+  // ------------------------------------------------------------ Settings dialog
+  const dialog = $('#settings-dialog');
+  const form = $('#settings-form');
+  $('#settings-btn').onclick = async () => {
+    $('#settings-error').hidden = true;
+    try {
+      const c = await api('GET', '/cleanup');
+      form.maxRunning.value = c.maxRunning ?? '';
+      $('#settings-running').textContent = `Open now: ${c.running}.`;
+      if (!remote()) {
+        const u = await api('GET', '/update').catch(() => null);
+        form.updateCheck.checked = u?.check !== false;
+      }
+      dialog.showModal();
+    } catch (err) {
+      toast(`Error: ${err.message}`, 5000);
+    }
+  };
+  $('#settings-cancel').onclick = () => dialog.close();
+  dialog.addEventListener('click', (e) => {
+    const go = e.target.closest('[data-open]');
+    if (!go) return;
+    dialog.close();
+    $(`#${go.dataset.open}`).click();
+  });
+  form.addEventListener('submit', async (e) => {
+    e.preventDefault();
+    try {
+      const c = await api('PUT', '/cleanup', { maxRunning: form.maxRunning.value.trim() || null });
+      if (!remote()) await api('PUT', '/update', { check: form.updateCheck.checked }).catch(() => {});
+      dialog.close();
+      toast(c.maxRunning ? `At most ${c.maxRunning} agents open; the ones idle longest close above that` : 'No limit on open agents');
+    } catch (err) {
+      $('#settings-error').textContent = err.message;
+      $('#settings-error').hidden = false;
+    }
+  });
+
+  loadMe();
+  return { loadMe };
+}

package/public/style.css

@@ -55,6 +55,12 @@ a:hover { text-decoration: underline; }
 .brand { display: flex; align-items: center; gap: 10px; }
 .brand h1 { font-size: 16px; margin: 0; font-weight: 600; }
 .logo { color: var(--accent); }
+.update-btn { font-size: 12px; padding: 2px 10px; border-radius: 999px; background: var(--accent); color: var(--accent-text); border: none; cursor: pointer; }
+.update-btn:disabled { opacity: 0.6; cursor: progress; }
+.about-auto { display: flex; align-items: center; gap: 6px; margin-right: auto; font-size: 13px; }
+.home-link { display: flex; align-items: center; gap: 10px; color: inherit; text-decoration: none; border-radius: 6px; }
+.home-link:hover h1 { text-decoration: underline; text-underline-offset: 3px; }
+.home-link:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 .conn { font-size: 12px; color: var(--muted); }
 .about-btn { font-size: 12px; padding: 2px 8px; color: var(--muted); background: transparent; border: 1px solid var(--border); border-radius: 999px; font-variant-numeric: tabular-nums; }
 .about-btn:hover, .about-btn:focus-visible { color: var(--text); border-color: var(--accent); }
@@ -149,6 +155,10 @@ body.term-max .layout { grid-template-columns: 1fr; }
 .recent-bar input[type="number"] { width: 56px; flex: none; padding: 2px 6px; font-size: 12px; }
 .agent-list { list-style: none; margin: 0; padding: 0; }
 .agent-list li.project { border-bottom: 1px solid var(--border); }
+.agent-list li.agent[draggable='true'] { cursor: grab; }
+.agent-list li.agent.dragging { opacity: 0.45; }
+.agent-list li.project.drop-target { outline: 2px dashed var(--accent); outline-offset: -2px; background: color-mix(in srgb, var(--accent) 10%, transparent); }
+.agent-list li.project.drop-target .project-head .pname::after { content: '  ← move here'; color: var(--accent); font-weight: 500; }
 .project-head {
   width: 100%; display: flex; align-items: center; gap: 8px; padding: 9px 14px; border: 0; border-radius: 0;
   background: var(--panel-2); font-weight: 600; text-align: left; position: sticky; top: 0; z-index: 1;
@@ -333,6 +343,11 @@ body.term-max .layout { grid-template-columns: 1fr; }
 .term-wrap.browsing .browser { display: flex; }
 .term-wrap.browsing .terminal, .term-wrap.browsing .keybar, .term-wrap.browsing .compose,
 .term-wrap.browsing #term-attach, .term-wrap.browsing #term-fit, .term-wrap.browsing .term-drop { display: none !important; }
+/* Code replaces the terminal the same way. */
+.code { display: none; flex: 1; min-height: 0; background: #1e1e1e; color: #d4d4d4; }
+.term-wrap.coding .code { display: flex; }
+.term-wrap.coding .terminal, .term-wrap.coding .keybar, .term-wrap.coding .compose, .term-wrap.coding .browser,
+.term-wrap.coding #term-attach, .term-wrap.coding #term-fit, .term-wrap.coding .term-drop { display: none !important; }
 .browser-bar { display: flex; gap: 6px; align-items: center; padding: 6px 10px; background: #161a22; border-top: 1px solid #30363d; }
 .browser-bar input { flex: 1; min-width: 0; font: 13px ui-monospace, SFMono-Regular, Menlo, monospace; }
 .browser-bar button, .browser-bar a { color: #c9d1d9; border-color: #30363d; }
@@ -729,3 +744,68 @@ input.inline { display: inline-block; width: 80px; padding: 1px 4px; }
 .setup-mark { color: var(--green); font-weight: 700; }
 .setup-check { padding: 6px 10px; border-radius: 6px; margin: 6px 0; border-left: 3px solid var(--yellow); background: var(--panel-2); font-size: 13px; }
 .setup-check.fail { border-left-color: var(--red); }
+
+/* ---------------------------------------------------------------- menu and settings */
+.menu-wrap { position: relative; }
+.menu-btn { display: flex; align-items: center; gap: 8px; padding: 3px 10px 3px 4px; border-radius: 999px; }
+.avatar { display: inline-grid; place-items: center; width: 24px; height: 24px; border-radius: 50%; background: var(--accent); color: var(--accent-text); font-size: 11px; font-weight: 600; }
+.me-name { max-width: 140px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13px; }
+.burger { font-size: 15px; line-height: 1; opacity: 0.8; }
+.menu { position: absolute; right: 0; top: calc(100% + 6px); z-index: 50; min-width: 240px; padding: 6px; background: var(--panel, var(--bg)); border: 1px solid var(--border); border-radius: 10px; box-shadow: 0 8px 28px rgba(0, 0, 0, 0.18); display: flex; flex-direction: column; }
+.menu[hidden] { display: none; }
+.menu > button { text-align: left; background: none; border: none; padding: 7px 10px; border-radius: 6px; cursor: pointer; color: inherit; font: inherit; }
+.menu > button:hover, .menu > button:focus-visible { background: color-mix(in srgb, var(--accent) 12%, transparent); }
+.menu-me { display: flex; flex-direction: column; gap: 2px; padding: 6px 10px 10px; margin-bottom: 4px; border-bottom: 1px solid var(--border); overflow-wrap: anywhere; }
+.menu-sep { height: 1px; background: var(--border); margin: 4px 0; }
+.settings-dialog .hint { margin: 0; }
+.settings-dialog input.num { width: 7em; }
+@media (max-width: 720px) {
+  .me-name { display: none; }
+  .menu-btn { padding: 3px 8px 3px 4px; }
+}
+
+/* ---------------------------------------------------------------- code (studio editor) */
+.code-side { width: 240px; flex: 0 0 240px; display: flex; flex-direction: column; min-height: 0; background: #181818; border-right: 1px solid #2b2b2b; }
+.code.no-side .code-side { display: none; }
+.code-side-bar, .code-tabs-bar { display: flex; align-items: center; gap: 2px; padding: 4px 6px; background: #181818; border-bottom: 1px solid #2b2b2b; min-height: 32px; }
+.code-side-bar .spacer, .code-tabs-bar .spacer { flex: 1; }
+.code button { background: none; border: none; color: #cccccc; font: inherit; font-size: 12px; cursor: pointer; border-radius: 4px; padding: 3px 7px; }
+.code button:hover { background: #2a2d2e; }
+.code button.active { background: #37373d; color: #fff; }
+.code .code-icon { padding: 3px 5px; }
+.code .code-btn { border: 1px solid #3c3c3c; }
+.code-tree { flex: 1; overflow: auto; padding: 4px 0; font-size: 13px; }
+.code-node { padding: 2px 8px; white-space: nowrap; cursor: pointer; overflow: hidden; text-overflow: ellipsis; user-select: none; }
+.code-node:hover { background: #2a2d2e; }
+.code-node.selected { background: #37373d; }
+.code-node.active { color: #fff; }
+.code-node.dim { opacity: 0.55; }
+.code-node .caret { display: inline-block; width: 14px; color: #8b8b8b; }
+.code-search { display: flex; flex-direction: column; gap: 6px; padding: 6px; min-height: 0; flex: 1; }
+.code-search[hidden] { display: none; }
+.code-search input { background: #252526; color: #ddd; border: 1px solid #3c3c3c; border-radius: 4px; padding: 5px 7px; font-size: 13px; }
+.code-hits { overflow: auto; flex: 1; font-size: 12px; }
+.code-hit { padding: 4px 6px; border-radius: 4px; cursor: pointer; overflow-wrap: anywhere; }
+.code-hit:hover { background: #2a2d2e; }
+.code-hit div { color: #9d9d9d; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre-wrap; }
+.code-main { flex: 1; min-width: 0; display: flex; flex-direction: column; position: relative; }
+.code-tabs { display: flex; gap: 2px; overflow-x: auto; min-width: 0; scrollbar-width: none; }
+.code .code-tab { white-space: nowrap; border-radius: 4px 4px 0 0; padding: 4px 8px; }
+.code-tab .x { margin-left: 6px; opacity: 0.6; }
+.code-tab .x:hover { opacity: 1; }
+.code-editor { flex: 1; min-height: 0; position: relative; }
+.code-editor[hidden], .code-empty[hidden] { display: none; }
+.code-diff { position: absolute; inset: 0; }
+.code-empty { flex: 1; display: grid; place-items: center; padding: 24px; color: #8b8b8b; text-align: center; font-size: 13px; }
+.code-plain { width: 100%; height: 100%; resize: none; border: none; outline: none; background: #1e1e1e; color: #d4d4d4; font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; padding: 8px 12px; tab-size: 2; }
+.code-status { padding: 2px 10px; font-size: 11px; color: #9d9d9d; background: #181818; border-top: 1px solid #2b2b2b; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-height: 18px; }
+@media (max-width: 720px) {
+  .code-side { position: absolute; z-index: 3; inset: 0 auto 0 0; width: min(82vw, 300px); }
+}
+.code { position: relative; }
+
+/* ---------------------------------------------------------------- machine terminal */
+.machine-dialog { width: min(1100px, calc(100vw - 24px)); height: min(720px, calc(100vh - 24px)); max-height: none; background: #0f1117; color: #c9d1d9; border-color: #30363d; }
+.machine-dialog[open] { display: flex; flex-direction: column; }
+.machine-dialog .terminal { flex: 1; min-height: 0; }
+.machine-dialog #machine-title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: #8b93a7; margin-left: 8px; }

package/public/update.js

@@ -0,0 +1,88 @@
+// Updating from the app: a button in the top bar when a newer release is out, and "Update and
+// restart" in About. The daemon installs it (git checkout of the release tag, or npm install -g)
+// and restarts onto it; this page then waits for it to come back and reloads.
+
+export function initUpdate({ api, esc, toast, $ }) {
+  const remote = () => document.body.classList.contains('remote');
+  let state = null;
+
+  function show(s) {
+    state = s;
+    const btn = $('#update-btn');
+    const ready = s?.newer && !s.blocker && !s.updating;
+    btn.hidden = !ready;
+    if (ready) {
+      btn.textContent = `Update to ${s.latest}`;
+      btn.title = `Version ${s.latest} is out (you have ${s.current}). Installs it and restarts; running agents resume.`;
+    }
+    $('#about-auto').checked = s?.check !== false;
+    $('#about-install').hidden = !ready;
+  }
+
+  async function load() {
+    if (remote()) return;
+    try {
+      show(await api('GET', '/update'));
+    } catch {
+      // An older daemon has no /update.
+    }
+  }
+
+  async function waitForRestart(from) {
+    for (let i = 0; i < 300; i++) {
+      await new Promise((r) => setTimeout(r, 2000));
+      try {
+        const a = await api('GET', '/about');
+        if (a.daemon.pid !== from) return location.reload();
+      } catch {
+        // Down while it restarts.
+      }
+    }
+    toast('The daemon has not come back yet; check ~/.agentmanager/daemon.log', 8000);
+  }
+
+  async function install() {
+    if (!state?.newer) return;
+    if (!confirm(`Update to ${state.latest} and restart?\n\nRunning agents are closed and resume on the new version. This takes a minute or two with many agents.`)) return;
+    const before = (await api('GET', '/about')).daemon.pid;
+    $('#update-btn').disabled = $('#about-install').disabled = true;
+    toast(`Installing ${state.latest}…`, 60_000);
+    try {
+      const r = await api('POST', '/update');
+      if (r.upToDate) {
+        toast(`${r.current} is the newest release`);
+        return load();
+      }
+      toast(`Installed ${r.to}; restarting… (agents resume)`, 600_000);
+      await waitForRestart(before);
+    } catch (err) {
+      toast(`Update failed: ${err.message}`, 10_000);
+    } finally {
+      $('#update-btn').disabled = $('#about-install').disabled = false;
+    }
+  }
+
+  /** "Check for updates" in About: the daemon's check where it can update itself. */
+  async function check() {
+    if (remote()) return null;
+    const s = await api('POST', '/update/check');
+    show(s);
+    if (!s.newer) return `You have the newest release (${esc(s.current)}).`;
+    if (s.blocker) return `Version ${esc(s.latest)} is out. ${esc(s.blocker)}.`;
+    return `Version ${esc(s.latest)} is out (you have ${esc(s.current)}). <b>Update and restart</b> installs it; running agents resume.`;
+  }
+
+  $('#update-btn').onclick = install;
+  $('#about-install').onclick = install;
+  $('#about-auto').onchange = async (e) => {
+    try {
+      show(await api('PUT', '/update', { check: e.target.checked }));
+    } catch (err) {
+      toast(`Error: ${err.message}`, 5000);
+    }
+  };
+  load();
+  // The daemon checks twice a day; look at what it found now and then.
+  setInterval(load, 30 * 60_000);
+  return { load, check };
+}

package/src/cleanup.js

@@ -5,11 +5,15 @@
 // and "off". Never touched: agents marked Keep, agents still setting up or working, members of a
 // team that is still going, and, for deleting, agents with an open pull request or with work
 // that exists only in their worktree (uncommitted changes or commits on no other branch).
+// Optionally, a cap on open sessions ("maxRunning"): above it, the agents idle longest are closed
+// (they resume when opened), so the machine stays responsive. The same agents are left alone,
+// plus ones waiting for an answer and ones active in the last few minutes.
 import fs from 'node:fs';
 import * as git from './git.js';
 
 export const STRATEGIES = ['close-delete', 'close', 'manual', 'off'];
-export const CLEANUP_DEFAULTS = { strategy: 'close', closeAfterDays: 14, deleteAfterDays: 14 };
+export const CLEANUP_DEFAULTS = { strategy: 'close', closeAfterDays: 14, deleteAfterDays: 14, maxRunning: null };
+const CAP_GRACE_MS = 5 * 60_000;
 const DAY = 86_400_000;
 const TEAM_DONE = new Set(['done', 'stopped']);
 
@@ -24,6 +28,7 @@ export function cleanupSettings(config = {}) {
     strategy: STRATEGIES.includes(c.strategy) ? c.strategy : CLEANUP_DEFAULTS.strategy,
     closeAfterDays: n(c.closeAfterDays, CLEANUP_DEFAULTS.closeAfterDays),
     deleteAfterDays: n(c.deleteAfterDays, CLEANUP_DEFAULTS.deleteAfterDays),
+    maxRunning: Number(c.maxRunning) >= 1 ? Math.min(500, Math.floor(Number(c.maxRunning))) : null,
   };
 }
 
@@ -56,11 +61,70 @@ export class Cleanup {
     this.firstTimer.unref?.();
     this.timer = setInterval(() => this.sweep().catch((e) => this.log(`clean up: ${e.message}`)), (config.cleanupEveryMin ?? 360) * 60_000);
     this.timer.unref?.();
+    // The cap: checked soon after agents change (one starts) and every minute.
+    this.onChange = () => {
+      if (!this.settings.maxRunning || this.capSoon) return;
+      this.capSoon = setTimeout(() => {
+        this.capSoon = null;
+        this.enforceCap().catch((e) => this.log(`cap: ${e.message}`));
+      }, config.capDelayMs ?? 5000);
+      this.capSoon.unref?.();
+    };
+    manager.on?.('change', this.onChange);
+    this.capTimer = setInterval(() => this.enforceCap().catch((e) => this.log(`cap: ${e.message}`)), 60_000);
+    this.capTimer.unref?.();
   }
 
   close() {
     clearTimeout(this.firstTimer);
     clearInterval(this.timer);
+    clearTimeout(this.capSoon);
+    clearInterval(this.capTimer);
+    this.manager.off?.('change', this.onChange);
+  }
+
+  /** Open sessions that count toward the cap (not the assistant's). */
+  runningAgents() {
+    return this.store.list().filter((a) => a.kind !== 'assistant' && this.manager.runtimes.get(a.id)?.pty);
+  }
+
+  /** Which agents to close to get back under the cap: idle longest first, protected ones skipped. */
+  capPlan(now = Date.now()) {
+    const max = this.settings.maxRunning;
+    const running = this.runningAgents();
+    if (!max || running.length <= max) return { max, running: running.length, close: [] };
+    const activeAt = (a) => Date.parse(this.manager.activeAt(a, this.manager.runtimes.get(a.id)) ?? a.createdAt) || now;
+    const closable = running
+      .filter((a) => !this.protectedBy(a) && !this.manager.runtimes.get(a.id)?.attention && now - activeAt(a) >= (this.config.capGraceMs ?? CAP_GRACE_MS))
+      .sort((x, y) => activeAt(x) - activeAt(y));
+    return { max, running: running.length, close: closable.slice(0, running.length - max).map((a) => ({ id: a.id, name: a.name, idleMin: Math.floor((now - activeAt(a)) / 60_000) })) };
+  }
+
+  async enforceCap() {
+    if (this.capping) return null;
+    const plan = this.capPlan();
+    if (!plan.close.length) return null;
+    this.capping = true;
+    const closed = [];
+    try {
+      for (const row of plan.close) {
+        try {
+          await this.manager.stop(row.id);
+          this.manager.patch(row.id, { closedBy: 'cap' });
+          closed.push(row);
+        } catch (e) {
+          this.log(`cap: couldn't close ${row.name}: ${e.message}`);
+        }
+      }
+    } finally {
+      this.capping = false;
+    }
+    if (closed.length) {
+      this.log(`cap: ${plan.running} open, limit ${plan.max}; closed ${closed.map((r) => `${r.name} (idle ${r.idleMin} min)`).join(', ')}`);
+      this.store.data.cleanup.lastCap = { at: new Date().toISOString(), closed };
+      this.store.save();
+    }
+    return closed;
   }
 
   get settings() {
@@ -73,8 +137,13 @@ export class Cleanup {
     for (const k of ['closeAfterDays', 'deleteAfterDays']) {
       if (patch[k] !== undefined && !(Number(patch[k]) >= 1)) throw err(400, `${k} must be 1 or more`);
     }
+    // maxRunning: a number of open sessions, or empty/null/0 for no cap.
+    if (patch.maxRunning !== undefined && patch.maxRunning !== null && patch.maxRunning !== '' && Number(patch.maxRunning) !== 0 && !(Number(patch.maxRunning) >= 1)) {
+      throw err(400, 'maxRunning must be 1 or more, or empty for no cap');
+    }
     const next = cleanupSettings({ cleanup: { ...this.config.cleanup, ...patch } });
     this.config.cleanup = next;
+    if (next.maxRunning) this.onChange?.();
     return next;
   }
 
@@ -181,6 +250,6 @@ export class Cleanup {
 
   async status() {
     const s = this.settings;
-    return { ...s, ...(await this.plan()), lastRun: this.store.data.cleanup.lastRun ?? null };
+    return { ...s, ...(await this.plan()), running: this.runningAgents().length, lastRun: this.store.data.cleanup.lastRun ?? null, lastCap: this.store.data.cleanup.lastCap ?? null };
   }
 }