ai-agentmanager 1.3.0 → 1.4.0

package/src/cli.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import { Command, Option } from 'commander';
 import WebSocket from 'ws';
 import { HOST, PORT } from './config.js';
-import { api, BASE, ensureDaemon, isRunning } from './client.js';
+import { api, BASE, ensureDaemon, health, isRunning, waitForExit } from './client.js';
 import { about, latestRelease } from './about.js';
 
 const tty = process.stdout.isTTY;
@@ -271,10 +271,16 @@ export async function main(argv) {
     .command('serve')
     .description('Run the agent daemon (API + web UI) in the foreground')
     .action(async () => {
-      if (await isRunning()) {
+      const h = await health();
+      if (h && !h.closing) {
         // Clean exit, so a login service doesn't keep retrying while another daemon owns the port.
         return console.log(`[agentmgr] a daemon is already running at ${BASE}; not starting another`);
       }
+      if (h?.closing) {
+        // One that is shutting down closes its agents first; start once it has exited.
+        console.log(`[agentmgr] waiting for the previous daemon (pid ${h.pid}) to finish shutting down`);
+        if (!(await waitForExit(h.pid))) return console.log(`[agentmgr] the previous daemon (pid ${h.pid}) is still shutting down; not starting`);
+      }
       const { startServer } = await import('./server.js');
       const { url } = await startServer();
       console.log(`[agentmgr] listening on ${url}`);
@@ -1340,9 +1346,11 @@ export async function main(argv) {
     .option('--strategy <s>', 'close-delete (both automatically), close (close automatically, delete by hand), manual, or off')
     .option('--close-after <days>', 'close sessions idle this many days')
     .option('--delete-after <days>', 'delete agents closed this many days')
+    .option('--max-open <n>', 'keep at most this many agents open; the ones idle longest are closed above it ("off": no limit)')
     .action(async (opts) => {
       await daemon();
       const patch = {
+        ...(opts.maxOpen ? { maxRunning: /^(off|none|0)$/i.test(opts.maxOpen) ? null : Number(opts.maxOpen) } : {}),
         ...(opts.strategy ? { strategy: opts.strategy } : {}),
         ...(opts.closeAfter ? { closeAfterDays: Number(opts.closeAfter) } : {}),
         ...(opts.deleteAfter ? { deleteAfterDays: Number(opts.deleteAfter) } : {}),
@@ -1359,6 +1367,8 @@ export async function main(argv) {
       const c = await api('GET', '/cleanup');
       const what = { 'close-delete': 'closes and deletes automatically', close: 'closes automatically; delete with --run', manual: 'nothing automatic; use --run', off: 'off' }[c.strategy];
       console.log(`${bold('Clean up')}: ${c.strategy} (${what}) · close after ${c.closeAfterDays} days idle · delete ${c.deleteAfterDays} days after closing`);
+      console.log(`${bold('Open agents')}: ${c.running} open · ${c.maxRunning ? `at most ${c.maxRunning} (the ones idle longest close above it)` : 'no limit (set one: --max-open <n>)'}`);
+      if (c.lastCap) console.log(dim(`  last closed for the limit ${new Date(c.lastCap.at).toLocaleString()}: ${c.lastCap.closed.map((x) => x.name).join(', ')}`));
       const rows = [
         ...c.close.map((x) => [yellow('close'), x.name, `idle ${x.idleDays}d`, '']),
         ...c.delete.map((x) => [red('delete'), x.name, `closed ${x.closedDays}d`, '']),
@@ -1685,6 +1695,19 @@ export async function main(argv) {
       .option('--url <url>', 'hub address')
       .action((ref, opts) => fleetAct(opts, ref, action, {}, (a, r) => `${action === 'start' ? 'starting' : 'stopping'} ${r.name}/${a.name}`));
   }
+  fleetCmd
+    .command('move')
+    .description('Move an agent to another machine and continue it there: same conversation, branch and uncommitted work (both machines need "move")')
+    .argument('<agent>', 'machine/agent (or a unique agent id or name)')
+    .requiredOption('--to <machine>', 'the machine to move it to')
+    .option('--url <url>', 'hub address')
+    .action(async (ref, opts) => {
+      const f = await hubApi(opts, 'GET', '/fleet');
+      const { runner, agent } = resolveFleetAgent(f, ref);
+      console.log(dim(`moving ${runner.name}/${agent.name} to ${opts.to}…`));
+      const out = await hubApi(opts, 'POST', `/runners/${runner.id}/agents/${agent.id}/move`, { to: opts.to });
+      console.log(`${green('✓')} ${agent.name} now runs on ${out.to.machine} as ${out.to.agent}${out.agent?.status ? ` (${out.agent.status})` : ''}`);
+    });
   fleetCmd
     .command('new')
     .description('Start a new agent on another machine, in one of its projects (needs "create")')
@@ -1789,10 +1812,11 @@ export async function main(argv) {
     .description('Register the daemon with launchd (macOS) or systemd --user (Linux) and start it')
     .action(async () => {
       const svc = await import('./service.js');
-      if (await isRunning()) {
+      const h = await health();
+      if (h) {
         // Hand over to the service-managed daemon; running agents are resumed by it.
-        await api('POST', '/shutdown');
-        for (let i = 0; i < 50 && (await isRunning()); i++) await new Promise((r) => setTimeout(r, 200));
+        if (!h.closing) await api('POST', '/shutdown');
+        await waitForExit(h.pid, { onWait: (s) => console.log(dim(`closing agents… (${s}s)`)) });
       }
       const res = await svc.install();
       for (let i = 0; i < 100 && !(await isRunning()); i++) await new Promise((r) => setTimeout(r, 200));
@@ -2001,7 +2025,8 @@ export async function main(argv) {
     .description('Flush, stop the daemon, and start it again; running agents resume their sessions')
     .action(async () => {
       const svc = await import('./service.js');
-      if (await isRunning()) {
+      const before = await health();
+      if (before && !before.closing) {
         try {
           const r = await api('POST', '/flush');
           console.log(dim(`saved ${r.agents} agents, scrollback for ${r.scrollback}`));
@@ -2011,24 +2036,61 @@ export async function main(argv) {
           console.log(dim('running daemon is an older version (no flush); restarting it to upgrade'));
         }
         await api('POST', '/shutdown');
-        for (let i = 0; i < 100 && (await isRunning()); i++) await new Promise((res) => setTimeout(res, 200));
+      }
+      // Wait for the old process itself to exit: it answers until every agent is closed.
+      if (before?.pid) {
+        const gone = await waitForExit(before.pid, { onWait: (s) => console.log(dim(`closing agents… (${s}s)`)) });
+        if (!gone) throw new Error(`The daemon (pid ${before.pid}) is still shutting down after 5 minutes; check the log`);
       }
       const st = await svc.status();
       if (st.loaded) await svc.kickstart();
       else await ensureDaemon({ quiet: true });
-      for (let i = 0; i < 100 && !(await isRunning()); i++) await new Promise((res) => setTimeout(res, 200));
-      if (!(await isRunning())) throw new Error('Daemon did not come back; check the log');
+      const back = async () => {
+        const h = await health();
+        return Boolean(h && !h.closing && h.pid !== before?.pid);
+      };
+      for (let i = 0; i < 150 && !(await back()); i++) await new Promise((res) => setTimeout(res, 200));
+      if (!(await back())) throw new Error('Daemon did not come back; check the log');
       const agents = await api('GET', '/agents');
       console.log(`${green('✓')} restarted${st.loaded ? ' (login service)' : ''}; ${agents.filter((a) => a.desired === 'running').length} agents set to resume`);
     });
 
+  program
+    .command('update')
+    .description('Install the newest release and restart onto it (agents resume); a git checkout moves to the newest release tag')
+    .option('--check', 'only say whether a newer release exists')
+    .option('--auto-check <on|off>', 'whether the daemon checks for a new release twice a day (shown in the app)')
+    .action(async (opts) => {
+      const up = await import('./update.js');
+      if (opts.autoCheck) {
+        const on = /^(on|true|yes|1)$/i.test(opts.autoCheck);
+        if ((await health())?.pid) await api('PUT', '/update', { check: on });
+        else (await import('./config.js')).saveConfig({ updates: { check: on } });
+        return console.log(`Update checks ${on ? green('on') : dim('off')}`);
+      }
+      const info = await up.checkUpdate();
+      if (!info.newer) return console.log(`${green('✓')} ${info.current} is the newest release`);
+      if (info.blocker) throw new Error(`${info.latest} is available, but: ${info.blocker}`);
+      if (opts.check) return console.log(`${yellow(info.latest)} is available (you have ${info.current}); install it: agentmgr update`);
+      const r = await up.installUpdate({ log: (m) => console.log(dim(m)) });
+      console.log(`${green('✓')} installed ${r.to} (was ${r.from})`);
+      if (!(await health())) return console.log(dim('The daemon is not running; it starts on the new version next time'));
+      // The new version's own restart, not the copy of it loaded in this process.
+      const { spawnSync } = await import('node:child_process');
+      const res = spawnSync(process.execPath, [process.argv[1], 'restart'], { stdio: 'inherit' });
+      if (res.status !== 0) process.exitCode = res.status ?? 1;
+    });
+
   program
     .command('shutdown')
     .description('Stop the daemon (running agents are closed; sessions are kept)')
     .action(async () => {
-      if (!(await isRunning())) return console.log('Daemon is not running');
-      await api('POST', '/shutdown');
-      console.log('Daemon stopped');
+      const h = await health();
+      if (!h) return console.log('Daemon is not running');
+      if (!h.closing) await api('POST', '/shutdown');
+      // It closes every agent before it exits; say stopped only once it has.
+      const gone = await waitForExit(h.pid, { onWait: (s) => console.log(dim(`closing agents… (${s}s)`)) });
+      console.log(gone ? 'Daemon stopped' : yellow(`The daemon (pid ${h.pid}) is still shutting down; check the log`));
     });
 
   try {

package/src/client.js

@@ -19,18 +19,58 @@ export async function api(method, route, body) {
   return data;
 }
 
+/** The daemon's /health answer ({ ok, pid, closing, … }), or null when nothing answers. */
+export async function health() {
+  try {
+    return await api('GET', '/health');
+  } catch {
+    return null;
+  }
+}
+
+/** A daemon that answers and isn't shutting down. */
 export async function isRunning() {
+  const h = await health();
+  return Boolean(h && !h.closing);
+}
+
+const alive = (pid) => {
   try {
-    await api('GET', '/health');
+    process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+};
+
+/**
+ * Wait for a daemon process to exit. Shutting down closes every agent first (to save their
+ * sessions), which takes a while with many agents, and it answers /health until then.
+ * Returns true once it is gone, false after `timeoutMs`.
+ */
+export async function waitForExit(pid, { timeoutMs = 300_000, onWait = null } = {}) {
+  if (!pid) return true;
+  const start = Date.now();
+  let told = 0;
+  while (alive(pid)) {
+    if (Date.now() - start > timeoutMs) return false;
+    if (onWait && Date.now() - told > 10_000) {
+      told = Date.now();
+      onWait(Math.round((Date.now() - start) / 1000));
+    }
+    await new Promise((r) => setTimeout(r, 500));
   }
+  return true;
 }
 
-/** Start the daemon in the background if it is not already listening. */
+/** Start the daemon in the background if it is not already listening (waiting out one that is shutting down). */
 export async function ensureDaemon({ quiet = false } = {}) {
-  if (await isRunning()) return false;
+  const h = await health();
+  if (h && !h.closing) return false;
+  if (h?.closing) {
+    if (!quiet) process.stderr.write(`agentmgr: waiting for the daemon (pid ${h.pid}) to finish shutting down…\n`);
+    if (!(await waitForExit(h.pid))) throw new Error(`The daemon (pid ${h.pid}) is still shutting down; try again in a minute`);
+  }
   ensureHome();
   const log = fs.openSync(paths.log, 'a');
   const child = spawn(process.execPath, [BIN, 'serve'], {
@@ -39,7 +79,7 @@ export async function ensureDaemon({ quiet = false } = {}) {
     env: process.env,
   });
   child.unref();
-  for (let i = 0; i < 50; i++) {
+  for (let i = 0; i < 150; i++) {
     await new Promise((r) => setTimeout(r, 100));
     if (await isRunning()) {
       if (!quiet) process.stderr.write(`agentmgr: started daemon at ${BASE} (log: ${paths.log})\n`);

package/src/fleet.js

@@ -45,6 +45,7 @@ export function fleetAgent(a) {
     stuck: Array.isArray(a.stuck) ? a.stuck.length : num(a.stuck) ?? 0,
     conflicts: Array.isArray(a.conflicts) ? a.conflicts.length : num(a.conflicts) ?? 0,
     raceId: str(a.raceId, 20),
+    movedTo: str(typeof a.movedTo === 'string' ? a.movedTo : a.movedTo?.machine, 60),
     error: str(a.error, 300),
     createdAt: iso(a.createdAt),
     updatedAt: iso(a.updatedAt),

package/src/git.js

@@ -7,7 +7,7 @@ const baseEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: '0' });
 
 const cancelled = () => Object.assign(new Error('Cancelled'), { cancelled: true });
 
-export function run(cmd, args, { cwd, timeout = 60_000, signal, env } = {}) {
+export function run(cmd, args, { cwd, timeout = 60_000, signal, env, trim = true } = {}) {
   return new Promise((resolve, reject) => {
     execFile(cmd, args, { cwd, timeout, signal, env: { ...baseEnv(), ...env }, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
       if (err) {
@@ -15,7 +15,7 @@ export function run(cmd, args, { cwd, timeout = 60_000, signal, env } = {}) {
         err.message = `${cmd} ${args.join(' ')} failed: ${(stderr || err.message).trim()}`;
         reject(err);
       } else {
-        resolve(stdout.trim());
+        resolve(trim ? stdout.trim() : stdout);
       }
     });
   });

package/src/handoff.js

@@ -0,0 +1,240 @@
+// Moving an agent to another machine through the hub, so it continues there: same session (its
+// conversation), same branch, its uncommitted work. Code travels through the repo's own remote
+// (a handoff branch holding a snapshot of the folder, deleted once the move is done); the
+// conversation travels through the hub in chunks; the hub keeps neither. Both machines must
+// allow "move" in their hub settings.
+//
+// On the machine it leaves: export (close the session, snapshot and push the work, hold the
+// transcript), chunk (pieces of the transcript), done (mark it moved, or start it again if the
+// move failed). On the machine it joins: import (create the agent in the matching project, with
+// the same session id), put (transcript pieces), finish (check out the work, place the
+// conversation, resume it if it was running).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as git from './git.js';
+import { projectRef } from './fleet.js';
+import { engineOf } from './engines/index.js';
+import { briefPath } from './brief.js';
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+export const CHUNK_BYTES = 512 * 1024; // base64 keeps a piece under the runner link's 1 MB frames
+const EXPIRE_MS = 30 * 60_000;
+export const handoffBranch = (agentId) => `agentmgr-handoff/${agentId}`;
+const MAX_TRANSCRIPT_BYTES = 200 * 1024 * 1024;
+/** A plain object of links small enough to keep (they come from the other machine). */
+const small = (o) => Boolean(o) && typeof o === 'object' && !Array.isArray(o) && JSON.stringify(o).length < 100_000;
+
+/** A transcript's lines with the old folder replaced by the new one where Claude recorded it. */
+export function moveTranscript(text, fromCwd, toCwd) {
+  if (!fromCwd || fromCwd === toCwd) return text;
+  return text
+    .split('\n')
+    .map((line) => {
+      if (!line.includes(fromCwd)) return line;
+      try {
+        const o = JSON.parse(line);
+        if (o.cwd === fromCwd) o.cwd = toCwd;
+        else if (typeof o.cwd === 'string' && o.cwd.startsWith(`${fromCwd}/`)) o.cwd = toCwd + o.cwd.slice(fromCwd.length);
+        return JSON.stringify(o);
+      } catch {
+        return line;
+      }
+    })
+    .join('\n');
+}
+
+export class Handoff {
+  constructor({ manager, log = (m) => console.log(`[agentmgr] ${m}`) }) {
+    this.manager = manager;
+    this.log = log;
+    this.exports = new Map(); // exportId -> { agentId, buf, wasRunning, at, remote, branch }
+    this.imports = new Map(); // importId -> { agentId, manifest, parts: [], at }
+  }
+
+  sweep() {
+    const old = Date.now() - EXPIRE_MS;
+    for (const [k, v] of this.exports) if (v.at < old) this.exports.delete(k);
+    for (const [k, v] of this.imports) if (v.at < old) this.imports.delete(k);
+  }
+
+  // ------------------------------------------------------------- leaving
+
+  async export(agent) {
+    this.sweep();
+    const m = this.manager;
+    if (agent.kind !== 'task') throw err(400, 'Only task agents can move to another machine');
+    if (agent.status === 'preparing') throw err(409, 'The agent is still setting up');
+    if (agent.movedTo) throw err(409, `Already moved to ${agent.movedTo.machine}`);
+    const dir = agent.workdir;
+    if (!dir || !(await git.isGitRepo(dir))) throw err(400, 'The agent folder is not a git repository');
+    const remote = await git.run('git', ['remote', 'get-url', 'origin'], { cwd: dir }).catch(() => '');
+    if (!remote) throw err(400, "The agent's repository has no remote (origin), so its work can't reach another machine");
+    const engine = engineOf(agent);
+    if (engine.id !== 'claude') throw err(400, `Moving ${engine.label} sessions isn't supported yet`);
+    const info = m.projectInfo(agent);
+    const wasRunning = Boolean(m.runtimes.get(agent.id)?.pty);
+    // Close the session so Claude writes everything; it stays closed here from now on.
+    await m.stop(agent.id);
+    await m.flush().catch(() => {});
+    const snap = await git.snapshot(dir, `agentmgr handoff of ${agent.name}`);
+    if (!snap) throw err(400, 'The agent folder has no commits yet');
+    const branch = handoffBranch(agent.id);
+    await git.run('git', ['push', '--force', '--no-verify', 'origin', `${snap.sha}:refs/heads/${branch}`], { cwd: dir, timeout: 180_000 });
+    const file = engine.sessionFile(dir, agent.sessionId);
+    const buf = fs.existsSync(file) ? fs.readFileSync(file) : Buffer.alloc(0);
+    if (buf.length > MAX_TRANSCRIPT_BYTES) throw err(413, 'The conversation is too large to move');
+    const exportId = crypto.randomBytes(8).toString('hex');
+    this.exports.set(exportId, { agentId: agent.id, buf, wasRunning, at: Date.now(), dir, branch });
+    const brief = m.briefFile?.(agent.id)?.markdown ?? null;
+    this.log(`handoff: ${agent.name} packed for another machine (${buf.length} bytes of conversation, work on ${branch})`);
+    return {
+      exportId,
+      manifest: {
+        from: { agentId: agent.id, workdir: fs.realpathSync(dir) },
+        name: agent.name,
+        intent: agent.intent,
+        priority: agent.priority,
+        model: agent.model ?? null,
+        permissionMode: agent.permissionMode ?? null,
+        notes: agent.notes ?? null,
+        baseRef: agent.baseRef ?? null,
+        links: { prs: agent.prs ?? {}, bugs: agent.bugs ?? {} },
+        brief: brief && brief.length < 200_000 ? brief : null,
+        project: { ref: projectRef(info), name: info.name },
+        branch: agent.git?.branch ?? agent.branch ?? null,
+        handoffBranch: branch,
+        head: snap.head,
+        snapshot: snap.sha,
+        sessionId: agent.sessionId,
+        transcriptBytes: buf.length,
+        chunks: Math.ceil(buf.length / CHUNK_BYTES),
+        wasRunning,
+      },
+    };
+  }
+
+  chunk(exportId, i) {
+    const x = this.exports.get(String(exportId));
+    if (!x) throw err(404, 'That move expired; start it again');
+    const n = Number(i);
+    if (!(n >= 0) || n * CHUNK_BYTES >= Math.max(x.buf.length, 1)) throw err(400, 'No such piece');
+    return { i: n, data: x.buf.subarray(n * CHUNK_BYTES, (n + 1) * CHUNK_BYTES).toString('base64') };
+  }
+
+  /** After the other machine answered: mark the agent moved (and drop the handoff branch), or undo. */
+  async done(exportId, { ok, machine, agentId: newId } = {}) {
+    const x = this.exports.get(String(exportId));
+    if (!x) throw err(404, 'That move expired');
+    this.exports.delete(String(exportId));
+    const m = this.manager;
+    if (!ok) {
+      // It stays here: open it again as it was.
+      await git.run('git', ['push', '--no-verify', 'origin', '--delete', x.branch], { cwd: x.dir, timeout: 60_000 }).catch(() => {});
+      if (x.wasRunning) await m.start(x.agentId).catch(() => {});
+      return m.get(x.agentId);
+    }
+    // The other machine has the work now; the branch was only the way there.
+    await git.run('git', ['push', '--no-verify', 'origin', '--delete', x.branch], { cwd: x.dir, timeout: 60_000 }).catch(() => {});
+    m.patch(x.agentId, { movedTo: { machine: String(machine ?? 'another machine').slice(0, 60), agentId: newId ?? null, at: new Date().toISOString() }, desired: 'stopped' });
+    this.log(`handoff: ${m.store.get(x.agentId)?.name} moved to ${machine}`);
+    return m.get(x.agentId);
+  }
+
+  // ------------------------------------------------------------- joining
+
+  /** Create the agent in the project that matches, with the same session; it sets up its folder. */
+  import(manifest, policy, allowedProject) {
+    this.sweep();
+    const m = this.manager;
+    const mf = manifest && typeof manifest === 'object' ? manifest : {};
+    if (!/^[\w-]{8,64}$/.test(String(mf.sessionId ?? ''))) throw err(400, 'Missing session');
+    if (!/^[0-9a-f]{40,64}$/.test(String(mf.snapshot ?? '')) || !/^[0-9a-f]{40,64}$/.test(String(mf.head ?? ''))) throw err(400, 'Missing work snapshot');
+    if (!/^agentmgr-handoff\/[\w-]{1,40}$/.test(String(mf.handoffBranch ?? ''))) throw err(400, 'Bad handoff branch');
+    const ref = String(mf.project?.ref ?? '');
+    const entry = m.listProjects().find((p) => projectRef(p) === ref);
+    if (!entry) throw err(400, `This machine has no project for ${mf.project?.name ?? ref}`);
+    if (!allowedProject(policy.projects, entry.name, entry.shortcut)) throw err(403, 'This machine does not share that project with the hub');
+    if (m.store.list().some((a) => a.sessionId === mf.sessionId && !a.movedTo)) throw err(409, 'That session is already on this machine');
+    const [agent] = m.createMany([String(mf.intent ?? '').slice(0, 10_000) || 'Moved agent'], {
+      project: entry.shortcut,
+      priority: mf.priority,
+      model: mf.model ?? undefined,
+      permissionMode: ['default', 'acceptEdits', 'plan'].includes(mf.permissionMode) ? mf.permissionMode : undefined,
+      sessionId: mf.sessionId,
+      start: false,
+      name: mf.name ? String(mf.name).slice(0, 60) : undefined,
+    });
+    const importId = crypto.randomBytes(8).toString('hex');
+    this.imports.set(importId, { agentId: agent.id, manifest: mf, parts: [], at: Date.now() });
+    return { importId, agentId: agent.id, name: agent.name };
+  }
+
+  put(importId, i, data) {
+    const x = this.imports.get(String(importId));
+    if (!x) throw err(404, 'That move expired');
+    const n = Number(i);
+    if (!(n >= 0 && n < Math.max(1, Number(x.manifest.chunks) || 0))) throw err(400, 'No such piece');
+    x.parts[n] = Buffer.from(String(data ?? ''), 'base64');
+    return { i: n };
+  }
+
+  /** A move that failed after the agent was created here: remove it again. */
+  async cancel(importId) {
+    const x = this.imports.get(String(importId));
+    if (!x) return { ok: true };
+    this.imports.delete(String(importId));
+    await this.manager.remove(x.agentId, { deleteWorkspace: true }).catch(() => {});
+    return { ok: true };
+  }
+
+  async finish(importId, { timeoutMs = 170_000 } = {}) {
+    const x = this.imports.get(String(importId));
+    if (!x) throw err(404, 'That move expired');
+    const m = this.manager;
+    const mf = x.manifest;
+    const chunks = Number(mf.chunks) || 0;
+    for (let i = 0; i < chunks; i++) if (!x.parts[i]) throw err(400, `Piece ${i + 1} of the conversation is missing`);
+    const buf = Buffer.concat(x.parts.slice(0, chunks));
+    if (buf.length !== Number(mf.transcriptBytes)) throw err(400, 'The conversation arrived incomplete');
+    // Wait for its folder (a clone or worktree of the project).
+    const until = Date.now() + timeoutMs;
+    let agent = m.store.get(x.agentId);
+    while (agent && (agent.status === 'preparing' || !agent.workdir || !fs.existsSync(agent.workdir))) {
+      if (agent.status === 'error') throw err(500, `Setting up the folder failed: ${agent.error ?? 'unknown error'}`);
+      if (Date.now() > until) throw err(504, 'Setting up the folder is taking too long');
+      await new Promise((r) => setTimeout(r, 500));
+      agent = m.store.get(x.agentId);
+    }
+    if (!agent) throw err(404, 'The new agent was removed');
+    const dir = agent.workdir;
+    const opts = { cwd: dir, timeout: 180_000 };
+    await git.run('git', ['fetch', '--no-tags', 'origin', `+refs/heads/${mf.handoffBranch}:refs/agentmgr/handoff/${agent.id}`], opts);
+    const branch = /^[\w./-]{1,200}$/.test(String(mf.branch ?? '')) && !String(mf.branch).includes('..') ? mf.branch : null;
+    if (branch) await git.run('git', ['checkout', '-q', '-B', branch, mf.head], opts);
+    else await git.run('git', ['checkout', '-q', '--detach', mf.head], opts);
+    await git.restoreSnapshot(dir, mf.snapshot);
+    await git.run('git', ['update-ref', '-d', `refs/agentmgr/handoff/${agent.id}`], opts).catch(() => {});
+    // The conversation, where Claude looks for it in this folder.
+    const engine = engineOf(agent);
+    const file = engine.sessionFile(dir, mf.sessionId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, moveTranscript(buf.toString('utf8'), mf.from?.workdir, fs.realpathSync(dir)));
+    m.patch(agent.id, {
+      movedFrom: { machine: mf.fromMachine ? String(mf.fromMachine).slice(0, 60) : null, agentId: mf.from?.agentId ?? null, at: new Date().toISOString() },
+      ...(mf.notes ? { notes: String(mf.notes).slice(0, 20_000) } : {}),
+      ...(mf.baseRef ? { baseRef: String(mf.baseRef).slice(0, 300) } : {}),
+      ...(small(mf.links?.prs) ? { prs: mf.links.prs } : {}),
+      ...(small(mf.links?.bugs) ? { bugs: mf.links.bugs } : {}),
+      ...(branch ? { branch } : {}),
+    });
+    if (mf.brief) {
+      fs.mkdirSync(path.dirname(briefPath(agent.id)), { recursive: true });
+      fs.writeFileSync(briefPath(agent.id), String(mf.brief));
+    }
+    this.imports.delete(String(importId));
+    if (mf.wasRunning) await m.start(agent.id);
+    this.log(`handoff: ${agent.name} arrived${mf.fromMachine ? ` from ${mf.fromMachine}` : ''}${mf.wasRunning ? ' and resumed' : ''}`);
+    return m.get(agent.id);
+  }
+}

package/src/hub.js

@@ -35,7 +35,10 @@ export const ACTION_PERMS = {
   answer: 'inbox', 'prompt-key': 'inbox', nudge: 'inbox', 'dismiss-stuck': 'inbox', 'warn-conflict': 'inbox',
   tell: 'control', start: 'control', stop: 'control', checkpoint: 'control', priority: 'control', create: 'create',
   signin: 'signin',
+  'handoff-export': 'move', 'handoff-chunk': 'move', 'handoff-done': 'move', 'handoff-import': 'move', 'handoff-put': 'move', 'handoff-finish': 'move', 'handoff-cancel': 'move',
 };
+// Run only as steps of a move (POST /api/runners/:id/agents/:agent/move), never one by one.
+const HANDOFF_STEP = /^handoff-/;
 
 const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
 const secret = () => crypto.randomBytes(32).toString('base64url');
@@ -490,7 +493,7 @@ export async function startHub({
   };
 
   /** Ask a machine to do something; resolves with its reply. */
-  function rpc(runnerId, action, args) {
+  function rpc(runnerId, action, args, { timeoutMs = RPC_TIMEOUT_MS } = {}) {
     const l = live.get(runnerId);
     if (!l?.hello) return Promise.reject(fail(409, 'That machine is offline'));
     const perm = ACTION_PERMS[action];
@@ -501,7 +504,7 @@ export async function startHub({
       const timer = setTimeout(() => {
         l.rpcs.delete(id);
         reject(fail(504, 'The machine did not answer in time'));
-      }, RPC_TIMEOUT_MS);
+      }, timeoutMs);
       l.rpcs.set(id, { resolve, reject, timer });
       l.ws.send(JSON.stringify({ t: 'rpc', id, action, args }));
     });
@@ -550,12 +553,57 @@ export async function startHub({
     }),
   );
 
+  // Move an agent to another machine: its work through the repo's remote, its conversation through
+  // here in pieces (kept in memory only for the move). Both machines must allow "move".
+  async function moveAgent(from, agentId, to, by) {
+    const step = (what) => log(`move ${agentId} ${from.name} → ${to.name}: ${what}`);
+    const exp = await rpc(from.id, 'handoff-export', { agent: agentId }, { timeoutMs: 240_000 });
+    step('packed');
+    let imp = null;
+    try {
+      imp = await rpc(to.id, 'handoff-import', { manifest: { ...exp.manifest, fromMachine: from.name } }, { timeoutMs: 60_000 });
+      for (let i = 0; i < exp.manifest.chunks; i++) {
+        const piece = await rpc(from.id, 'handoff-chunk', { exportId: exp.exportId, i }, { timeoutMs: 60_000 });
+        await rpc(to.id, 'handoff-put', { importId: imp.importId, i, data: piece.data }, { timeoutMs: 60_000 });
+      }
+      step(`conversation sent (${exp.manifest.chunks} piece(s))`);
+      const fin = await rpc(to.id, 'handoff-finish', { importId: imp.importId }, { timeoutMs: 240_000 });
+      await rpc(from.id, 'handoff-done', { exportId: exp.exportId, ok: true, machine: to.name, agentId: imp.agentId }, { timeoutMs: 60_000 }).catch((e) => step(`marking it moved failed: ${e.message}`));
+      audit(`${by} moved ${from.name}/${agentId} to ${to.name}/${imp.agentId}`);
+      return { ok: true, from: { machine: from.name, agent: agentId }, to: { machine: to.name, agent: imp.agentId }, agent: fin.agent };
+    } catch (e) {
+      step(`failed: ${e.message}`);
+      if (imp) await rpc(to.id, 'handoff-cancel', { importId: imp.importId }, { timeoutMs: 60_000 }).catch(() => {});
+      await rpc(from.id, 'handoff-done', { exportId: exp.exportId, ok: false }, { timeoutMs: 60_000 }).catch(() => {});
+      audit(`${by} failed to move ${from.name}/${agentId} to ${to.name}: ${e.message}`);
+      throw e;
+    }
+  }
+  const runnerByRef = (ref) => store.data.runners[ref] ?? Object.values(store.data.runners).find((x) => x.name.toLowerCase() === String(ref ?? '').toLowerCase());
+  api.post(
+    '/runners/:id/agents/:agent/move',
+    wrap(async (req) => {
+      const from = runnerByRef(req.params.id);
+      const to = runnerByRef(req.body?.to);
+      if (!from) throw fail(404, `No machine ${req.params.id}`);
+      if (!to) throw fail(400, 'Pick the machine to move it to');
+      if (to.id === from.id) throw fail(400, 'It is already on that machine');
+      for (const r of [from, to]) {
+        const l = live.get(r.id);
+        if (!l?.hello) throw fail(409, `${r.name} is offline`);
+        if (!l.hello.policy.allow.includes('move')) throw fail(403, `${r.name} doesn't allow "move" from the hub`);
+      }
+      return moveAgent(from, String(req.params.agent).slice(0, 40), to, req.auth);
+    }),
+  );
+
   api.post(
     '/runners/:id/actions',
     wrap(async (req) => {
       const r = store.data.runners[req.params.id];
       if (!r) throw fail(404, `No machine ${req.params.id}`);
       const { action, args = {} } = req.body ?? {};
+      if (HANDOFF_STEP.test(String(action))) throw fail(400, 'Moving an agent is one request: POST /api/runners/<machine>/agents/<agent>/move');
       const what = `${String(action).slice(0, 40)}${args.agent ? ` on ${r.name}/${String(args.agent).slice(0, 40)}` : ` on ${r.name}`}`;
       try {
         const out = await rpc(r.id, action, args);

package/src/hubactions.js

@@ -10,11 +10,13 @@
 //   terminal  live Claude terminals
 //   shell     shells in an agent's folder (runs any command: grant with care)
 //   signin    one-time sign-in links to this machine's own page (full access there: grant with care)
+//   move      move agents to and from other machines (their work goes through the repo's remote)
 import { engineOf, installed } from './engines/index.js';
 import { allowedProject } from './fleet.js';
 import { createTicket } from './remote.js';
+import { Handoff } from './handoff.js';
 
-export const PERMISSIONS = ['view', 'inbox', 'control', 'create', 'terminal', 'shell', 'signin'];
+export const PERMISSIONS = ['view', 'inbox', 'control', 'create', 'terminal', 'shell', 'signin', 'move'];
 // The hub may not start agents that skip permission prompts.
 const HUB_PERMISSION_MODES = new Set(['default', 'acceptEdits', 'plan']);
 
@@ -58,8 +60,18 @@ export const ACTIONS = {
   priority: { perm: 'control', run: (m, a, args) => m.update(a.id, { priority: args.priority }) },
   create: { perm: 'create', agentless: true, run: (m, _a, args, policy) => createAgent(m, args, policy) },
   signin: { perm: 'signin', agentless: true, run: () => ({ ticket: createTicket() }) },
+  // Moving an agent between machines (src/handoff.js); both machines must allow "move".
+  'handoff-export': { perm: 'move', raw: true, run: (m, a) => handoffOf(m).export(a) },
+  'handoff-chunk': { perm: 'move', agentless: true, raw: true, run: (m, _a, args) => handoffOf(m).chunk(args.exportId, args.i) },
+  'handoff-done': { perm: 'move', agentless: true, run: (m, _a, args) => handoffOf(m).done(args.exportId, { ok: Boolean(args.ok), machine: args.machine, agentId: args.agentId }) },
+  'handoff-import': { perm: 'move', agentless: true, raw: true, run: (m, _a, args, policy) => handoffOf(m).import(args.manifest, policy, allowedProject) },
+  'handoff-put': { perm: 'move', agentless: true, raw: true, run: (m, _a, args) => handoffOf(m).put(args.importId, args.i, args.data) },
+  'handoff-finish': { perm: 'move', agentless: true, run: (m, _a, args) => handoffOf(m).finish(args.importId) },
+  'handoff-cancel': { perm: 'move', agentless: true, raw: true, run: (m, _a, args) => handoffOf(m).cancel(args.importId) },
 };
 
+const handoffOf = (m) => (m.handoff ??= new Handoff({ manager: m }));
+
 function createAgent(manager, args, policy) {
   const entry = manager.resolveProject(String(args.project ?? ''));
   if (!entry) throw err(400, 'Pick one of the projects this machine shares');
@@ -89,6 +101,7 @@ export async function runAction(manager, policy, action, args = {}) {
   manager.plugins?.check('hub.action', { action, agent: agent ? manager.auditView(agent) : null });
   manager.plugins?.emit('hub.action', { action, agent: agent ? manager.auditView(agent) : null });
   const out = await def.run(manager, agent, args, policy);
+  if (def.raw) return { ok: true, ...out };
   // Enough for the hub to confirm; the next state frame carries the rest.
   if (out?.ticket) return { ok: true, ticket: out.ticket };
   if (Array.isArray(out)) return { ok: true, agents: out.map((a) => ({ id: a.id, name: a.name })) };