ai-agentmanager 0.0.0-stage → 1.0.0

package/public/touchscroll.js

@@ -0,0 +1,73 @@
+// Shared by the main UI and the hub's terminal.
+/**
+ * Swipe to scroll on phones and tablets: xterm.js doesn't scroll on touch. In the normal
+ * buffer this moves through the scrollback; in the alternate screen (full-screen apps) it
+ * sends wheel events so the app scrolls itself. A flick keeps scrolling and slows down.
+ */
+export function touchScroll(el, xterm) {
+  let lastY = null;
+  let lastT = 0;
+  let carry = 0; // fraction of a line not scrolled yet
+  let velocity = 0; // px per ms
+  let glide = 0;
+  const lineHeight = () => el.querySelector('.xterm-screen')?.clientHeight / xterm.rows || 17;
+  const scrollPx = (dy) => {
+    carry += dy / lineHeight();
+    const lines = Math.trunc(carry);
+    if (!lines) return;
+    carry -= lines;
+    if (xterm.buffer.active.type === 'normal') {
+      xterm.scrollLines(lines);
+    } else {
+      const target = el.querySelector('.xterm-screen');
+      const r = target.getBoundingClientRect();
+      for (let i = 0; i < Math.abs(lines); i++) {
+        target.dispatchEvent(
+          new WheelEvent('wheel', { deltaY: Math.sign(lines) * lineHeight(), deltaMode: 0, clientX: r.left + 10, clientY: r.top + 10, bubbles: true, cancelable: true }),
+        );
+      }
+    }
+  };
+  el.addEventListener(
+    'touchstart',
+    (e) => {
+      cancelAnimationFrame(glide);
+      if (e.touches.length !== 1) return (lastY = null);
+      lastY = e.touches[0].clientY;
+      lastT = e.timeStamp;
+      velocity = 0;
+      carry = 0;
+    },
+    { passive: true },
+  );
+  el.addEventListener(
+    'touchmove',
+    (e) => {
+      if (lastY === null || e.touches.length !== 1) return;
+      const y = e.touches[0].clientY;
+      const dy = lastY - y; // finger up = later content
+      const dt = Math.max(1, e.timeStamp - lastT);
+      velocity = 0.8 * (dy / dt) + 0.2 * velocity;
+      lastY = y;
+      lastT = e.timeStamp;
+      e.preventDefault();
+      scrollPx(dy);
+    },
+    { passive: false },
+  );
+  el.addEventListener('touchend', (e) => {
+    if (lastY === null) return;
+    lastY = null;
+    if (e.timeStamp - lastT > 80 || Math.abs(velocity) < 0.2) return; // finger paused: no flick
+    let prev = performance.now();
+    const step = (now) => {
+      const dt = now - prev;
+      prev = now;
+      velocity *= Math.pow(0.995, dt);
+      if (Math.abs(velocity) < 0.03) return;
+      scrollPx(velocity * dt);
+      glide = requestAnimationFrame(step);
+    };
+    glide = requestAnimationFrame(step);
+  });
+}

package/public/transport.js

@@ -0,0 +1,78 @@
+// How the page talks to the daemon. Locally: WebSockets. Over remote HTTPS:
+// Server-Sent Events plus POSTs, because iOS Safari applies an accepted
+// self-signed certificate to pages and fetches but not to WebSockets.
+
+export const REMOTE = location.protocol === 'https:';
+
+export const post = (url, body) =>
+  fetch(url, {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { 'content-type': 'application/json', 'x-agentmgr': '1' },
+    body: JSON.stringify(body ?? {}),
+  });
+
+/**
+ * Open the event stream (`{ events: true }`) or a terminal (`{ agentId, kind }`).
+ * Handlers: onOpen(), onMessage(msg), onClose({ code, reason }) when it ends for good.
+ * Returns { send(msg), close() } where msg is { t: 'i', d } (input) or { t: 'r', cols, rows } (resize).
+ */
+export function openStream({ events = false, agentId, kind = 'claude' }, h) {
+  if (!REMOTE) {
+    const path = events ? '/ws/events' : `/ws/term/${agentId}${kind === 'claude' ? '' : `?kind=${encodeURIComponent(kind)}`}`;
+    const ws = new WebSocket(`ws://${location.host}${path}`);
+    ws.onopen = () => h.onOpen?.();
+    ws.onmessage = (ev) => h.onMessage(JSON.parse(ev.data));
+    ws.onclose = (ev) => h.onClose?.({ code: ev.code, reason: ev.reason });
+    return {
+      send: (msg) => ws.readyState === WebSocket.OPEN && ws.send(JSON.stringify(msg)),
+      close: () => ws.close(),
+    };
+  }
+
+  const url = events ? '/api/events/stream' : `/api/agents/${agentId}/term/stream?kind=${encodeURIComponent(kind)}`;
+  const es = new EventSource(url);
+  let closed = false;
+  es.onopen = () => h.onOpen?.();
+  es.onmessage = (ev) => h.onMessage(JSON.parse(ev.data));
+  es.onerror = () => {
+    // CONNECTING means the browser is retrying by itself (network blip); CLOSED is final (e.g. 401).
+    if (es.readyState === EventSource.CLOSED && !closed) {
+      closed = true;
+      h.onClose?.({ code: 0, reason: 'stream closed' });
+    }
+  };
+
+  // Keystrokes: coalesced and sent strictly in order, one request at a time.
+  let queue = '';
+  let inflight = false;
+  const pump = async () => {
+    if (inflight || !queue) return;
+    inflight = true;
+    const d = queue;
+    queue = '';
+    try {
+      await post(`/api/agents/${agentId}/term/input`, { d, kind });
+    } finally {
+      inflight = false;
+      if (queue) pump();
+    }
+  };
+  let resizeTimer;
+  return {
+    send(msg) {
+      if (closed) return;
+      if (msg.t === 'i') {
+        queue += msg.d;
+        setTimeout(pump, 8);
+      } else if (msg.t === 'r') {
+        clearTimeout(resizeTimer);
+        resizeTimer = setTimeout(() => post(`/api/agents/${agentId}/term/resize`, { cols: msg.cols, rows: msg.rows, kind }), 150);
+      }
+    },
+    close() {
+      closed = true;
+      es.close();
+    },
+  };
+}

package/scripts/build-release.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Builds self-contained agentmgr bundles (Node runtime + app + node_modules).
+# Usage: scripts/build-release.sh <out-dir> [target...]
+#   targets: darwin-arm64 darwin-x64 linux-x64 (linux-x64 must be built on linux-x64)
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "$0")/.." && pwd)
+OUT=$(mkdir -p "${1:?out dir}" && cd "$1" && pwd); shift
+TARGETS=("${@:-darwin-arm64 darwin-x64}")
+NODE_VERSION=${NODE_VERSION:-22.22.0}
+VERSION=$(node -p "require('$ROOT/package.json').version")
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+# Install production deps once from the app source.
+mkdir -p "$WORK/app"
+cp -R "$ROOT/bin" "$ROOT/src" "$ROOT/public" "$ROOT/scripts" "$ROOT/package.json" "$ROOT/package-lock.json" "$ROOT/README.md" "$WORK/app/"
+(cd "$WORK/app" && npm ci --omit=dev --ignore-scripts --no-audit --no-fund >/dev/null)
+
+for t in ${TARGETS[@]}; do
+  echo "==> $t"
+  name="agentmanager-$VERSION-$t"
+  dest="$WORK/$name"
+  mkdir -p "$dest/runtime" "$dest/bin"
+  cp -R "$WORK/app" "$dest/app"
+
+  pty="$dest/app/node_modules/node-pty"
+  if [[ $t == linux-* ]]; then
+    # No linux prebuilds ship with node-pty; compile against the bundled Node.
+    (cd "$pty" && npx --yes node-gyp@11 rebuild --target="$NODE_VERSION" >/dev/null)
+    rm -rf "$pty/prebuilds"
+  else
+    find "$pty/prebuilds" -mindepth 1 -maxdepth 1 ! -name "$t" -exec rm -rf {} +
+    chmod 755 "$pty/prebuilds/$t/spawn-helper"
+  fi
+
+  curl -fsSL "https://nodejs.org/dist/v$NODE_VERSION/node-v$NODE_VERSION-$t.tar.gz" \
+    | tar -xz -C "$WORK" "node-v$NODE_VERSION-$t/bin/node"
+  mv "$WORK/node-v$NODE_VERSION-$t/bin/node" "$dest/runtime/node"
+  rm -rf "$WORK/node-v$NODE_VERSION-$t"
+
+  cat > "$dest/bin/agentmgr" <<'SH'
+#!/bin/sh
+# Resolve symlinks so `ln -s .../bin/agentmgr ~/.local/bin/agentmgr` works.
+SELF=$0
+while [ -L "$SELF" ]; do
+  LINK=$(readlink "$SELF")
+  case $LINK in /*) SELF=$LINK ;; *) SELF=$(dirname "$SELF")/$LINK ;; esac
+done
+DIR=$(cd "$(dirname "$SELF")/.." && pwd)
+exec "$DIR/runtime/node" "$DIR/app/bin/agentmgr.js" "$@"
+SH
+  chmod 755 "$dest/bin/agentmgr"
+
+  tar -czf "$OUT/$name.tar.gz" -C "$WORK" "$name"
+  rm -rf "$dest"
+  echo "    $OUT/$name.tar.gz ($(du -h "$OUT/$name.tar.gz" | cut -f1))"
+done

package/scripts/fix-pty.js

@@ -0,0 +1,15 @@
+// node-pty's macOS prebuilds ship spawn-helper without the execute bit,
+// which makes every spawn fail with "posix_spawnp failed".
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+try {
+  const root = path.dirname(createRequire(import.meta.url).resolve('node-pty/package.json'));
+  for (const dir of ['prebuilds/darwin-arm64', 'prebuilds/darwin-x64', 'build/Release']) {
+    const helper = path.join(root, dir, 'spawn-helper');
+    if (fs.existsSync(helper)) fs.chmodSync(helper, 0o755);
+  }
+} catch {
+  // node-pty not installed yet; nothing to fix
+}

package/src/backlog.js

@@ -0,0 +1,413 @@
+// The backlog: work orders that agents pick up automatically, one item per
+// agent, up to a parallel limit per project, until each item is complete.
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { parsePriority, projectOf } from './manager.js';
+import { dispatchPrompt, hash } from './judge.js';
+
+const now = () => new Date().toISOString();
+const err = (status, message) => Object.assign(new Error(message), { status });
+
+// queued → active → review → done; blocked / cancelled on the side.
+const OPEN = new Set(['queued', 'active', 'review', 'blocked']);
+
+export class Backlog extends EventEmitter {
+  constructor({ manager, store, config }) {
+    super();
+    this.manager = manager;
+    this.store = store;
+    this.config = config;
+    store.data.backlog ??= { items: {}, limits: {}, autoRun: true };
+    this.data = store.data.backlog;
+    this.dispatching = false;
+    this.plan = null; // the AI judge's dispatch plan: { hash, data, pending }
+
+    manager.on('change', (agent) => this.onAgent(agent));
+    manager.on('removed', (id) => this.onAgentRemoved(id));
+    this.timer = setInterval(() => this.dispatch().catch(() => {}), 2000);
+    this.timer.unref();
+  }
+
+  // ------------------------------------------------------------ queries
+
+  defaultLimit() {
+    return this.config.backlogParallel ?? 2;
+  }
+
+  limitFor(projectKey) {
+    return this.data.limits[projectKey] ?? this.defaultLimit();
+  }
+
+  items() {
+    return Object.values(this.data.items).sort(
+      (a, b) => a.priority - b.priority || a.order - b.order || a.createdAt.localeCompare(b.createdAt),
+    );
+  }
+
+  view() {
+    const items = this.items().map((it) => {
+      const agent = it.agentId ? this.store.get(it.agentId) : null;
+      return {
+        ...it,
+        agent: agent
+          ? {
+              id: agent.id,
+              name: agent.name,
+              status: agent.status,
+              briefStatus: agent.brief?.status ?? null,
+              attention: this.manager.view(agent).runtime.attention,
+            }
+          : null,
+      };
+    });
+    const projects = {};
+    for (const it of items) {
+      const shortcut = Object.values(this.store.data.projects ?? {}).find((x) => x.key === it.projectKey)?.shortcut ?? null;
+      const p = (projects[it.projectKey] ??= { key: it.projectKey, name: it.projectName, shortcut, limit: this.limitFor(it.projectKey), counts: {} });
+      p.counts[it.status] = (p.counts[it.status] ?? 0) + 1;
+    }
+    return {
+      autoRun: this.data.autoRun,
+      defaultLimit: this.defaultLimit(),
+      maxActive: this.config.backlogMaxActive ?? 4,
+      projects: Object.values(projects),
+      items,
+    };
+  }
+
+  changed() {
+    this.store.save();
+    this.emit('change', this.view());
+  }
+
+  get(id) {
+    const it = this.data.items[id];
+    if (!it) throw err(404, `No backlog item "${id}"`);
+    return it;
+  }
+
+  // ------------------------------------------------------------ editing
+
+  /** Queue one item per title. Options are what an agent would take (repo, dir, base, project, ...). */
+  add(titles, { repo, dir, base, project, worktree, permissionMode, model, plan, planReview, engine, priority = 2 } = {}) {
+    const list = titles.map((t) => String(t ?? '').trim()).filter(Boolean);
+    if (!list.length) throw err(400, 'At least one item is required');
+    const pr = parsePriority(priority);
+    // A project shortcut fills in the repo / folder / base branch.
+    const entry = project ? this.manager.resolveProject(project) : null;
+    if (entry) {
+      if (!repo && !dir) {
+        repo = entry.repo ?? undefined;
+        dir = entry.dir ?? undefined;
+      }
+      base ??= entry.base ?? undefined;
+      project = entry.key.startsWith('custom:') ? entry.name : undefined;
+    }
+    const p = projectOf({ project: project?.trim() || null, repo: repo?.trim() || null, requestedDir: dir?.trim() || null });
+    const order = Math.max(0, ...Object.values(this.data.items).map((i) => i.order ?? 0)) + 1;
+    const added = list.map((title, i) => {
+      const it = {
+        id: crypto.randomBytes(3).toString('hex'),
+        title,
+        projectKey: p.key,
+        projectName: p.name,
+        project: project?.trim() || null,
+        repo: repo?.trim() || null,
+        dir: dir?.trim() || null,
+        base: base?.trim() || null,
+        // Parallel agents on one folder must not trample each other.
+        worktree: worktree ?? true,
+        permissionMode: permissionMode || null,
+        model: model || null,
+        engine: engine || null,
+        plan: Boolean(plan),
+        planReview: planReview ?? null,
+        priority: pr,
+        order: order + i,
+        status: 'queued',
+        agentId: null,
+        notes: '',
+        createdAt: now(),
+        startedAt: null,
+        reviewAt: null,
+        doneAt: null,
+      };
+      this.data.items[it.id] = it;
+      return it;
+    });
+    this.changed();
+    this.dispatch().catch(() => {});
+    return added;
+  }
+
+  update(id, fields) {
+    const it = this.get(id);
+    if ('title' in fields && it.status === 'queued') it.title = String(fields.title).trim() || it.title;
+    if ('priority' in fields) {
+      it.priority = parsePriority(fields.priority, it.priority);
+      if (it.agentId && this.store.get(it.agentId)) this.manager.update(it.agentId, { priority: it.priority });
+    }
+    if ('notes' in fields) it.notes = String(fields.notes ?? '');
+    this.changed();
+    return it;
+  }
+
+  /** Reorder within the queue: "up", "down", "top" or "bottom" among items of the same priority. */
+  move(id, where) {
+    const it = this.get(id);
+    const peers = this.items().filter((x) => x.priority === it.priority && x.status === 'queued');
+    const i = peers.findIndex((x) => x.id === id);
+    if (i < 0) throw err(409, 'Only queued items can be reordered');
+    const j = { up: i - 1, down: i + 1, top: 0, bottom: peers.length - 1 }[where];
+    if (j === undefined) throw err(400, 'where must be up, down, top or bottom');
+    const target = Math.max(0, Math.min(peers.length - 1, j));
+    peers.splice(target, 0, ...peers.splice(i, 1));
+    const base = Math.min(...peers.map((x) => x.order));
+    peers.forEach((x, k) => (x.order = base + k));
+    this.changed();
+    return it;
+  }
+
+  remove(id) {
+    const it = this.get(id);
+    if (it.status === 'active') throw err(409, 'Cancel the item first (its agent is working on it)');
+    delete this.data.items[id];
+    this.changed();
+    return { id };
+  }
+
+  settings({ autoRun, limits, project, limit } = {}) {
+    if (typeof autoRun === 'boolean') this.data.autoRun = autoRun;
+    if (limits && typeof limits === 'object') Object.assign(this.data.limits, limits);
+    if (project !== undefined && limit !== undefined) {
+      const key =
+        this.manager.resolveProject(project)?.key ??
+        this.items().find((x) => x.projectKey === project || x.projectName === project)?.projectKey ??
+        project;
+      const n = Number(limit);
+      if (!(n >= 0 && n <= 20)) throw err(400, 'limit must be 0-20');
+      this.data.limits[key] = n;
+    }
+    this.changed();
+    this.dispatch().catch(() => {});
+    return this.view();
+  }
+
+  // ------------------------------------------------------------ lifecycle
+
+  /** Start an item now, even if its project is at its limit or the backlog is paused. */
+  start(id) {
+    const it = this.get(id);
+    if (it.status !== 'queued' && it.status !== 'blocked') throw err(409, `Item is ${it.status}`);
+    if (it.status === 'blocked' && it.agentId && this.store.get(it.agentId)) {
+      this.manager.start(it.agentId); // retries a failed setup
+      Object.assign(it, { status: 'active', activeSince: now() });
+      this.changed();
+      return it;
+    }
+    return this.launch(it);
+  }
+
+  launch(it) {
+    const agent = this.manager.create({
+      intent: it.title,
+      repo: it.repo,
+      dir: it.dir,
+      base: it.base,
+      worktree: it.worktree,
+      project: it.project,
+      permissionMode: it.permissionMode,
+      model: it.model,
+      engine: it.engine ?? undefined,
+      plan: it.plan,
+      planReview: it.planReview ?? undefined,
+      priority: it.priority,
+      name: undefined,
+    });
+    Object.assign(it, { status: 'active', agentId: agent.id, startedAt: now(), activeSince: now() });
+    this.store.patch(agent.id, { backlogItem: it.id });
+    this.changed();
+    return it;
+  }
+
+  /** Accept the agent's work: the item is done. */
+  accept(id) {
+    const it = this.get(id);
+    if (!['review', 'active', 'blocked'].includes(it.status)) throw err(409, `Item is ${it.status}`);
+    Object.assign(it, { status: 'done', doneAt: now() });
+    this.changed();
+    return it;
+  }
+
+  /** Send it back: the same agent session continues, with the reviewer's note. */
+  reopen(id, { note } = {}) {
+    const it = this.get(id);
+    if (!['review', 'done', 'blocked'].includes(it.status)) throw err(409, `Item is ${it.status}`);
+    if (!it.agentId || !this.store.get(it.agentId)) {
+      Object.assign(it, { status: 'queued', agentId: null, reviewAt: null, doneAt: null });
+      this.changed();
+      return it;
+    }
+    // Only a brief update after this point counts as "done" again.
+    Object.assign(it, { status: 'active', reviewAt: null, doneAt: null, activeSince: now() });
+    this.changed();
+    const agentId = it.agentId;
+    const message = `Reopened from review${note ? `: ${note}` : '.'} Please continue until the task is complete, and set the brief's Status back to done when it is.`;
+    // Resume if closed, then type the note into its session.
+    Promise.resolve(this.manager.start(agentId))
+      .then(() => new Promise((r) => setTimeout(r, 1500)))
+      .then(() => {
+        this.manager.write(agentId, message);
+        setTimeout(() => this.manager.write(agentId, '\r'), 200);
+      })
+      .catch(() => {});
+    return it;
+  }
+
+  cancel(id) {
+    const it = this.get(id);
+    if (!OPEN.has(it.status)) throw err(409, `Item is ${it.status}`);
+    it.status = 'cancelled';
+    this.changed();
+    return it;
+  }
+
+  // ------------------------------------------------------------ automation
+
+  /** Follow the agent: its brief saying "done", or the agent ending, sends the item to review. */
+  onAgent(agent) {
+    const it = agent.backlogItem && this.data.items[agent.backlogItem];
+    if (!it) return;
+    let next = it.status;
+    if (it.status === 'active') {
+      if (agent.status === 'error') next = 'blocked';
+      else if (agent.brief?.status === 'done' && agent.brief.updatedAt > (it.activeSince ?? '')) next = 'review';
+      // The AI judge read the agent saying it finished (it may not have updated its brief).
+      else if (agent.aiReview?.verdict && agent.aiReview.trigger === 'screen' && agent.aiReview.at > (it.activeSince ?? '')) next = 'review';
+      else if (agent.status === 'exited' || (agent.status === 'stopped' && agent.desired === 'stopped')) next = 'review';
+    } else if (it.status === 'blocked' && agent.status === 'running') {
+      next = 'active';
+      it.activeSince = now();
+    }
+    if (next !== it.status) {
+      it.status = next;
+      if (next === 'review') it.reviewAt = now();
+      this.changed();
+      if (next !== 'active') this.dispatch().catch(() => {});
+    }
+  }
+
+  onAgentRemoved(id) {
+    for (const it of Object.values(this.data.items)) {
+      if (it.agentId === id && OPEN.has(it.status) && it.status !== 'queued') {
+        it.status = 'cancelled';
+        this.changed();
+      }
+    }
+  }
+
+  /**
+   * The order to consider queued items in. Priority always wins; within a priority the AI judge
+   * may move up what others depend on, hold back an item that waits for another open item or
+   * would collide with work in progress, and suggest splitting one that bundles several tasks.
+   * Resolves to null while the judge is thinking (dispatch tries again shortly).
+   */
+  planned(items) {
+    const queued = items.filter((x) => x.status === 'queued');
+    const active = items.filter((x) => x.status === 'active');
+    const judge = this.manager.judge;
+    if (!judge?.enabled || !queued.length || (queued.length < 2 && !active.length)) return items;
+    const h = hash(JSON.stringify([queued.map((x) => [x.id, x.title, x.priority]), active.map((x) => x.id)]));
+    if (this.plan?.hash !== h) {
+      this.plan = { hash: h, data: null, pending: true };
+      const changes = (x) => (x.agentId && this.manager.changeSets.get(x.agentId)) || null;
+      const prompt = dispatchPrompt(
+        queued.map((x) => ({ id: x.id, title: x.title, priority: x.priority, project: x.projectName })),
+        active.map((x) => ({ id: x.id, title: x.title, project: x.projectName, changes: changes(x) })),
+        judge.examples('dispatch'),
+      );
+      judge.ask(`dispatch:${h}`, null, prompt, (d) => Array.isArray(d.order)).then((data) => {
+        if (this.plan?.hash !== h) return;
+        this.plan = { hash: h, data, pending: false };
+        this.applyPlan(data);
+        this.dispatch().catch(() => {});
+      });
+    }
+    if (this.plan.pending) return null;
+    const d = this.plan.data;
+    if (!d) return items;
+    const rank = new Map(d.order.map((id, i) => [id, i]));
+    const r = (x) => rank.get(x.id) ?? Infinity;
+    const held = new Set((d.hold ?? []).filter((x) => this.data.items[x.after] && OPEN.has(this.data.items[x.after].status) && x.after !== x.id).map((x) => x.id));
+    return [...items].filter((x) => !held.has(x.id)).sort((a, b) => a.priority - b.priority || r(a) - r(b) || a.order - b.order);
+  }
+
+  /** Keep the judge's holds and split suggestions on the items, for the backlog view. */
+  applyPlan(d) {
+    let changed = false;
+    for (const it of Object.values(this.data.items)) {
+      const hold = d && it.status === 'queued' ? (d.hold ?? []).find((x) => x.id === it.id && this.data.items[x.after] && x.after !== it.id) : null;
+      const split = d && it.status === 'queued' ? (d.split ?? []).find((x) => x.id === it.id && Array.isArray(x.parts) && x.parts.length > 1) : null;
+      const next = {
+        aiHold: hold ? { after: hold.after, afterTitle: this.data.items[hold.after].title, reason: String(hold.reason ?? '') } : null,
+        aiSplit: split && !it.splitDismissed ? { reason: String(split.reason ?? ''), parts: split.parts.map(String).slice(0, 8) } : null,
+      };
+      if (JSON.stringify([it.aiHold ?? null, it.aiSplit ?? null]) !== JSON.stringify([next.aiHold, next.aiSplit])) {
+        Object.assign(it, next);
+        changed = true;
+      }
+    }
+    if (changed) this.changed();
+  }
+
+  /** Replace a queued item with several, as the judge suggested (or as edited). */
+  split(id, parts) {
+    const it = this.get(id);
+    if (it.status !== 'queued') throw err(409, 'Only queued items can be split');
+    const titles = (Array.isArray(parts) ? parts : it.aiSplit?.parts ?? []).map((t) => String(t).trim()).filter(Boolean);
+    if (titles.length < 2) throw err(400, 'Give at least two parts');
+    const { repo, dir, base, project, worktree, permissionMode, model, plan, planReview, engine, priority } = it;
+    const added = this.add(titles, { repo, dir, base, project, worktree, permissionMode, model, plan, planReview, engine, priority });
+    this.manager.judge?.feedback('dispatch', { summary: `split "${it.title}"`, verdict: it.aiSplit ? 'split suggested' : 'not suggested', outcome: 'split it' });
+    delete this.data.items[id];
+    this.changed();
+    return added;
+  }
+
+  /** Keep an item whole although the judge suggested splitting it. */
+  keepWhole(id) {
+    const it = this.get(id);
+    if (it.aiSplit) this.manager.judge?.feedback('dispatch', { summary: `split "${it.title}" into ${it.aiSplit.parts.length}`, verdict: 'split suggested', outcome: 'kept it whole' });
+    Object.assign(it, { aiSplit: null, splitDismissed: true });
+    this.changed();
+    return it;
+  }
+
+  /** Start queued items wherever a project has a free slot (and the global cap allows). */
+  async dispatch() {
+    if (!this.data.autoRun || this.dispatching || this.manager.closing) return [];
+    this.dispatching = true;
+    try {
+      const started = [];
+      const all = this.items();
+      let active = all.filter((x) => x.status === 'active').length;
+      const max = this.config.backlogMaxActive ?? 4;
+      // Nothing can start: don't spend a judge call on the order.
+      if (active >= max || !all.some((x) => x.status === 'queued' && all.filter((y) => y.projectKey === x.projectKey && y.status === 'active').length < this.limitFor(x.projectKey))) return [];
+      const items = this.planned(all);
+      if (!items) return [];
+      for (const it of items) {
+        if (active >= max) break;
+        if (it.status !== 'queued') continue;
+        const busy = items.filter((x) => x.projectKey === it.projectKey && x.status === 'active').length;
+        if (busy >= this.limitFor(it.projectKey)) continue;
+        this.launch(it);
+        started.push(it.id);
+        active++;
+      }
+      return started;
+    } finally {
+      this.dispatching = false;
+    }
+  }
+}