@oddessentials/agent-guild 0.20.0 → 0.21.0

package/README.md

@@ -67,6 +67,17 @@ Prompt are also offered when found. On macOS and Linux it follows your login
 shell. Pick the default chip to clear a saved choice and follow the default
 again. The choice applies to new sessions.
 
+**Work inside tmux or herdr.** When installed, the Shell card also offers
+tmux (3.2 or later, on macOS and Linux) and herdr. A tmux card runs a tmux
+session of its own, with your own configuration, and tools in it report to
+the card as they would in a shell. A herdr card opens your herdr session and
+shows the agents herdr sees in its panes, working, blocked or idle. Stopping
+or closing either card only detaches it, as closing a terminal window would:
+the session keeps running, **Reattach** on the card brings it back, and the
+card names the command that reattaches it from a terminal. Stopping or
+restarting the manager detaches them the same way, and the cards come back,
+closed and ready to reattach, when it starts again.
+
 <img src="docs/images/terminal.webp" alt="An open Claude Code session with its helper agents shown in the header">
 
 **Agents and models at work.** Helper agents that a tool starts appear on its
@@ -254,7 +265,9 @@ npm test
 
 ## Current limits
 
-* Sessions end when the manager stops or the computer restarts.
+* Sessions end when the manager stops or the computer restarts, except a
+  Shell session in tmux or herdr, which keeps running in it while the
+  manager is stopped.
 * Antigravity CLI and Grok Build have no usage meter.
 * Antigravity CLI has one account per computer user: it keeps its sign-in in
   the system keychain and has no setting for another home folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {

package/src/manager/command-resolver.mjs

@@ -83,8 +83,9 @@ export function resolveAllCommands(command, env = process.env, platform = proces
   return hits;
 }
 
-export function killWindowsTree(pid, done = () => {}) {
-  execFile('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, timeout: 5000 }, (err) => done(err));
+/** End a Windows process and, unless `tree` is false, every process it started. */
+export function killWindowsTree(pid, done = () => {}, { tree = true } = {}) {
+  execFile('taskkill', ['/PID', String(pid), ...(tree ? ['/T'] : []), '/F'], { windowsHide: true, timeout: 5000 }, (err) => done(err));
 }
 
 /** Quote one argument for a cmd.exe command line. */
@@ -121,10 +122,11 @@ export function buildSpawnSpec(resolvedPath, args = [], env = process.env, platf
 }
 
 /**
- * Run a spawn spec to completion without a terminal. Resolves with its
- * output; rejects with the error carrying stdout and stderr.
+ * Run a spawn spec to completion without a terminal, with `input` on its
+ * stdin. Resolves with its output; rejects with the error carrying stdout
+ * and stderr.
  */
-export function runSpec(spec, { env, timeoutMs = 15000, cwd } = {}) {
+export function runSpec(spec, { env, timeoutMs = 15000, cwd, input } = {}) {
   return new Promise((resolve, reject) => {
     const opts = { env, cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 };
     let args = spec.args;
@@ -133,10 +135,11 @@ export function runSpec(spec, { env, timeoutMs = 15000, cwd } = {}) {
       args = [args];
     }
     try {
-      execFile(spec.file, args, opts, (err, stdout, stderr) => {
+      const child = execFile(spec.file, args, opts, (err, stdout, stderr) => {
         if (err) reject(Object.assign(err, { stdout, stderr }));
         else resolve({ stdout, stderr });
       });
+      if (input !== undefined) child.stdin.end(input);
     } catch (err) {
       reject(err);
     }

package/src/manager/config.mjs

@@ -48,6 +48,8 @@ export const paths = {
   /** Launchers for agent-guild-report, put first on every session's PATH. */
   get shims() { return path.join(dataDir(), 'bin'); },
   get reporting() { return path.join(dataDir(), 'reporting'); },
+  /** The tmux and herdr cards a restarted manager brings back, report tokens included. */
+  get multiplexers() { return path.join(dataDir(), 'multiplexers.json'); },
 };
 
 function writePrivate(file, contents) {
@@ -72,6 +74,25 @@ export function loadOrCreateToken() {
   return token;
 }
 
+/** Where the manager keeps its tmux and herdr cards, readable only by the user since they hold report tokens. */
+export const multiplexerStore = {
+  load() {
+    try {
+      const { cards } = JSON.parse(fs.readFileSync(paths.multiplexers, 'utf8'));
+      return Array.isArray(cards) ? cards : [];
+    } catch {
+      return [];
+    }
+  },
+  save(cards) {
+    ensureDataDir();
+    // Written aside and renamed, so a crash never leaves half a file.
+    const next = `${paths.multiplexers}.${process.pid}.tmp`;
+    writePrivate(next, JSON.stringify({ cards }, null, 2) + '\n');
+    fs.renameSync(next, paths.multiplexers);
+  },
+};
+
 export function writeRuntimeFile(info) {
   ensureDataDir();
   writePrivate(paths.runtime, JSON.stringify(info, null, 2) + '\n');

package/src/manager/herdr.mjs

@@ -0,0 +1,156 @@
+// The agents herdr sees in its panes, for a herdr card. herdr tracks every
+// coding agent in its panes and whether it is working, blocked or idle, with
+// no hooks of ours. Its socket API pushes an event when an agent appears or
+// leaves and, for a pane named in the subscription, when its agent changes
+// state; each event triggers a fresh agent.list, as herdr's documentation
+// advises, since events and reads share no sequence.
+
+import net from 'node:net';
+import { buildSpawnSpec, runSpec } from './command-resolver.mjs';
+
+const ANY_PANE = ['pane.agent_detected', 'pane.closed', 'pane.exited'];
+const STATUS = { working: 'working', blocked: 'waiting' };
+const REQUEST_TIMEOUT_MS = 10000;
+
+/** Card agent reports for herdr's agent list. Idle, done and unknown agents show as idle. */
+export function herdrAgentReports(agents) {
+  return (Array.isArray(agents) ? agents : [])
+    .filter((agent) => typeof agent?.pane_id === 'string' && typeof agent.agent === 'string')
+    .map((agent) => ({
+      agentId: `herdr:${agent.pane_id}`,
+      name: agent.agent,
+      kind: 'agent',
+      status: STATUS[agent.agent_status] ?? 'idle',
+      detail: typeof agent.cwd === 'string' ? agent.cwd : '',
+    }));
+}
+
+/**
+ * Where to reach the herdr session that a client started with `env` uses:
+ * the one HERDR_SESSION names, else the default. herdr names its Windows
+ * pipe after the socket path.
+ */
+export function herdrSocket(listing, env, platform = process.platform) {
+  const sessions = Array.isArray(listing?.sessions) ? listing.sessions : [];
+  const session = sessions.find((s) => (env.HERDR_SESSION ? s.name === env.HERDR_SESSION : s.default === true));
+  if (!session?.running || typeof session.socket_path !== 'string') return null;
+  return platform === 'win32' ? `\\\\.\\pipe\\${session.socket_path}` : session.socket_path;
+}
+
+/** Call `onLine` with each JSON line read from `socket`. */
+function readLines(socket, onLine) {
+  let buffer = '';
+  socket.setEncoding('utf8');
+  socket.on('data', (chunk) => {
+    buffer += chunk;
+    for (let end = buffer.indexOf('\n'); end !== -1; end = buffer.indexOf('\n')) {
+      const line = buffer.slice(0, end).trim();
+      buffer = buffer.slice(end + 1);
+      if (!line) continue;
+      try { onLine(JSON.parse(line)); } catch { /* not JSON */ }
+    }
+  });
+}
+
+/** One request on its own connection: resolves with its result. */
+function request(socketPath, method, params = {}) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(socketPath);
+    socket.setTimeout(REQUEST_TIMEOUT_MS, () => socket.destroy(new Error(`herdr did not answer ${method}`)));
+    socket.on('connect', () => socket.write(`${JSON.stringify({ id: 'agent-guild', method, params })}\n`));
+    readLines(socket, (msg) => {
+      socket.end();
+      if (msg.error) reject(new Error(msg.error.message || msg.error.code));
+      else resolve(msg.result);
+    });
+    socket.on('error', reject);
+    socket.on('close', () => reject(new Error(`herdr closed the connection before answering ${method}`)));
+  });
+}
+
+export class HerdrAgents {
+  /**
+   * @param {object} opts
+   * @param {string} opts.herdr   the herdr executable
+   * @param {object} opts.env     the environment the card's herdr client runs with
+   * @param {(agents: object[]) => void} opts.onAgents  called with herdr's agent list after each change
+   */
+  constructor({ herdr, env, platform = process.platform, onAgents }) {
+    Object.assign(this, { herdr, env, platform, onAgents });
+    this.socketPath = null;
+    this.subscription = null;
+    this.panes = null;
+    this.connecting = false;
+    this.reading = false;
+    this.readAgain = false;
+    this.stopped = false;
+  }
+
+  /** Connect unless connected. A server that was still starting is found on a later call. */
+  poke() {
+    if (this.stopped || this.subscription || this.connecting) return;
+    this.connecting = true;
+    this._connect().finally(() => { this.connecting = false; });
+  }
+
+  stop() {
+    this.stopped = true;
+    this.subscription?.destroy();
+    this.subscription = null;
+  }
+
+  async _connect() {
+    try {
+      const spec = buildSpawnSpec(this.herdr, ['session', 'list', '--json'], this.env, this.platform);
+      const { stdout } = await runSpec(spec, { env: this.env, timeoutMs: REQUEST_TIMEOUT_MS });
+      this.socketPath = herdrSocket(JSON.parse(stdout), this.env, this.platform);
+    } catch {
+      return;
+    }
+    if (this.socketPath && !this.stopped) this._subscribe([]);
+  }
+
+  /** Replace the subscription: any pane's agent arriving or leaving, and each of `panes` changing state. */
+  _subscribe(panes) {
+    this.subscription?.destroy();
+    this.panes = panes;
+    const socket = net.connect(this.socketPath);
+    this.subscription = socket;
+    const subscriptions = [...ANY_PANE.map((type) => ({ type })), ...panes.map((pane) => ({ type: 'pane.agent_status_changed', pane_id: pane }))];
+    socket.on('connect', () => socket.write(`${JSON.stringify({ id: 'agent-guild', method: 'events.subscribe', params: { subscriptions } })}\n`));
+    readLines(socket, (msg) => {
+      if (this.subscription !== socket) return;
+      // herdr refuses a subscription naming a pane that has closed, and ends one that fell behind;
+      // start over from no panes. Anything else, the acknowledgement included, is a reason to read.
+      if (msg.error) return panes.length ? this._subscribe([]) : socket.destroy();
+      this._read();
+    });
+    socket.on('error', () => {});
+    socket.on('close', () => {
+      if (this.subscription === socket) this.subscription = null;
+    });
+  }
+
+  /** Read herdr's agent list, once more if an event arrives meanwhile, and follow the panes it names. */
+  async _read() {
+    if (this.reading) {
+      this.readAgain = true;
+      return;
+    }
+    this.reading = true;
+    try {
+      do {
+        this.readAgain = false;
+        const { agents = [] } = (await request(this.socketPath, 'agent.list')) ?? {};
+        if (this.stopped) return;
+        this.onAgents(agents);
+        const panes = agents.map((agent) => agent?.pane_id).filter((pane) => typeof pane === 'string').sort();
+        if (this.subscription && panes.join('\n') !== this.panes.join('\n')) this._subscribe(panes);
+      } while (this.readAgain && !this.stopped);
+    } catch {
+      // herdr went away or did not answer; the next event or poke tries again.
+    } finally {
+      this.reading = false;
+    }
+  }
+}

package/src/manager/main.mjs

@@ -25,6 +25,7 @@ import {
   VERSION,
   ensureDataDir,
   loadOrCreateToken,
+  multiplexerStore,
   paths,
   removeRuntimeFile,
   resolvePort,
@@ -67,7 +68,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   registry.reportingEnabled = (provider) => sessionHooks.enabled(provider);
   sessionHooks.warm();
   const manager = new SessionManager({
-    registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate, github, sessionHooks,
+    registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate, github, sessionHooks, store: multiplexerStore,
   });
   const usage = new UsageMonitor({ registry, env: baseEnv });
   const history = new SessionHistory({ registry, env: baseEnv });
@@ -146,6 +147,10 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     }
     throw err;
   }
+  // tmux and herdr cards come back closed, ready to reattach, before the
+  // runtime file announces this manager; after listening, since a card's
+  // environment names the API's URL.
+  await manager.restore();
 
   writeRuntimeFile({
     pid: process.pid,

package/src/manager/providers.mjs

@@ -669,7 +669,7 @@ export class ProviderRegistry extends EventEmitter {
       reporting: provider.reporting,
       reportingEnabled: this.reportingEnabled?.(provider) ?? null,
       accounts: provider.accounts.map((account) => ({ id: account.id, label: account.label })),
-      shells: shells?.shells.map((shell) => ({ id: shell.id, label: shell.label, path: shell.path })) ?? null,
+      shells: shells?.shells.map((shell) => ({ id: shell.id, label: shell.label, path: shell.path, multiplexer: Boolean(shell.multiplexer) })) ?? null,
       defaultShell: shells?.defaultId ?? null,
       modelPattern: provider.modelPattern,
       color: provider.color,

package/src/manager/server.mjs

@@ -306,8 +306,9 @@ export function createManagerServer({
       return sendJson(res, 201, { session: session.toJSON() });
     }
     if (route === '/shutdown' && method === 'POST') {
-      // Stopping the manager ends every session, so a client must say
-      // `force` while any is running. The same guard serves every front end.
+      // Stopping the manager ends every session but the tmux and herdr ones,
+      // so a client must say `force` while any of those is running. The same
+      // guard serves every front end.
       const body = await readJsonBody(req);
       const running = manager.runningCount();
       if (running > 0 && body.force !== true) {
@@ -328,7 +329,7 @@ export function createManagerServer({
       return undefined;
     }
 
-    const sessionMatch = route.match(/^\/sessions\/([a-f0-9]+)(\/stop)?$/);
+    const sessionMatch = route.match(/^\/sessions\/([a-f0-9]+)(\/stop|\/reattach)?$/);
     if (sessionMatch) {
       const [, id, action] = sessionMatch;
       if (!action && method === 'GET') return sendJson(res, 200, { session: manager.get(id).toJSON() });
@@ -348,6 +349,9 @@ export function createManagerServer({
       if (action === '/stop' && method === 'POST') {
         return sendJson(res, 200, { session: manager.stop(id).toJSON() });
       }
+      if (action === '/reattach' && method === 'POST') {
+        return sendJson(res, 200, { session: (await manager.reattach(id)).toJSON() });
+      }
     }
     throw new HttpError(404, `no route for ${method} ${url.pathname}`, 'not_found');
   }

package/src/manager/session-manager.mjs

@@ -8,6 +8,9 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { Session, newId, clampDimension, cleanName } from './session.mjs';
 import { prependPath } from './report-shims.mjs';
+import { buildSpawnSpec, runSpec } from './command-resolver.mjs';
+import { tmuxNewSession } from './shells.mjs';
+import { HerdrAgents, herdrAgentReports, herdrSocket } from './herdr.mjs';
 import { CHANNEL_LABELS } from './install-channels.mjs';
 import { SELF_PROVIDER } from './self-update.mjs';
 import { GITHUB_PROVIDER, dropsFromCloneEnv, parseRepo } from './github.mjs';
@@ -21,6 +24,10 @@ function httpError(status, message, code) {
   return Object.assign(new Error(message), { status, code });
 }
 
+function isFolder(dir) {
+  try { return fs.statSync(dir).isDirectory(); } catch { return false; }
+}
+
 /**
  * Layer environment objects. On Windows, variable names are
  * case-insensitive, so a later "PATH" must replace an inherited "Path"
@@ -54,7 +61,7 @@ export class SessionManager extends EventEmitter {
    * @param {import('./self-update.mjs').SelfUpdate|null} [opts.selfUpdate]  the manager's own upgrade
    * @param {import('./github.mjs').GitHub|null} [opts.github]
    */
-  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null, selfUpdate = null, github = null, sessionHooks = null }) {
+  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null, selfUpdate = null, github = null, sessionHooks = null, store = null }) {
     super();
     this.registry = registry;
     this.baseEnv = baseEnv;
@@ -70,6 +77,13 @@ export class SessionManager extends EventEmitter {
     /** True once shutdown has begun; no new session may start after that. */
     this.closing = false;
     this.installing = new Set();
+    /** Session id → how a tmux or herdr card attaches again, and whether its multiplexer session is still there. */
+    this.multiplexers = new Map();
+    /** Session id → the watcher that shows a running herdr card the agents herdr sees. */
+    this.watchers = new Map();
+    /** Keeps the tmux and herdr cards across restarts: { load(), save(cards) }, or null. */
+    this.store = store;
+    this.restoring = false;
   }
 
   list() {
@@ -110,19 +124,184 @@ export class SessionManager extends EventEmitter {
     if (this.installing.has(provider.id) || this.installsRunningFor(provider.id) > 0) {
       throw httpError(409, `${provider.tool} is being installed, updated or removed; start it once that finishes`, 'install_in_progress');
     }
-    const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId, hooks.args, runShell);
     this.prepareAccount(provider, signIn, { hooksSupplied: hooks.args.length > 0 });
     const sessionName = cleanName(name)
       || (provider.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null)
       || (runShell && this.registry.shellsFor(provider).shells.length > 1 ? `${provider.tool} · ${runShell.label}` : null);
-    const session = this._spawn({
-      provider, spawnSpec, cwd: workDir, cols, rows, name: sessionName, resume: resumeId, account: signIn, reporting: hooks.reporting, extraEnv: runShell?.env,
-    });
+    const options = { provider, cwd: workDir, cols, rows, name: sessionName, resume: resumeId, account: signIn, reporting: hooks.reporting, extraEnv: runShell?.env };
+    if (runShell?.multiplexer) return this._startMultiplexer(options, runShell, args || []);
+    const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId, hooks.args, runShell);
+    const session = this._spawn({ ...options, spawnSpec });
     const model = modelFromArgs([...provider.args, ...(args || [])]);
     if (model) session.setModel({ name: model }, 'args');
     return session;
   }
 
+  /**
+   * A Shell session in tmux or herdr. Its client is the session's process;
+   * the multiplexer's server outlives it and gives its own environment to
+   * every session it starts later, outside Agent Guild too, so the client
+   * never carries this session's identity. A tmux card gets a tmux session
+   * of its own, made first with that identity, so tools in it report to the
+   * card as they would in a shell. A herdr card shows the agents herdr sees.
+   */
+  async _startMultiplexer(options, shell, args) {
+    const { provider, account } = options;
+    const id = newId();
+    const reportToken = crypto.randomBytes(16).toString('hex');
+    // A name of its own, so the card can say how to reattach it.
+    const muxName = `guild-${newId(3)}`;
+    const mux = this._multiplexer({ provider, account, shell, id, reportToken, muxName });
+    const spawnSpec = this.registry.spawnSpec(provider, shell.id === 'tmux' ? [] : args, options.resume, [], mux.named);
+    if (shell.id === 'tmux') {
+      this._assertCanSpawn();
+      const own = this._sessionEnv({ id, reportToken, provider, account, extraEnv: shell.env });
+      const env = Object.fromEntries(Object.entries(own).filter(([key]) => mux.dropEnv(key) || key.toUpperCase() === 'PATH'));
+      const cols = clampDimension(options.cols, 120, 2, 1000);
+      const rows = clampDimension(options.rows, 32, 1, 500);
+      // Outside the try: a folder or argument tmux cannot take is the request's fault, refused before tmux runs.
+      const input = tmuxNewSession({ name: muxName, cwd: options.cwd, cols, rows, env, args });
+      try {
+        await mux.run(['-u', 'start-server', ';', 'source-file', '-'], { cwd: options.cwd, input });
+      } catch (err) {
+        throw httpError(500, `tmux could not make a session: ${(err.stderr || err.message).trim()}`, 'spawn_failed');
+      }
+    }
+    let session;
+    try {
+      session = this._spawn({
+        ...options, id, reportToken, spawnSpec, dropEnv: mux.dropEnv,
+        multiplexer: { label: shell.label, attach: shell.multiplexer.attach.replaceAll('{name}', muxName), reattachable: false },
+      });
+    } catch (err) {
+      if (shell.id === 'tmux') mux.run(['kill-session', '-t', `=${muxName}`]).catch(() => {});
+      throw err;
+    }
+    this._track(session, { spawnSpec, mux, shell, card: { id, reportToken, provider: provider.id, account: account.id, shell: shell.id, muxName, name: session.name, cwd: session.cwd, createdAt: session.createdAt } });
+    this._watchHerdr(session);
+    return session;
+  }
+
+  /** How to run a card's tmux or herdr client, and tell whether the multiplexer still has the card's session. */
+  _multiplexer({ provider, account, shell, id, reportToken, muxName }) {
+    const named = { ...shell, args: shell.args.map((arg) => arg.replaceAll('{name}', muxName)) };
+    const dropEnv = (key) => key.startsWith('AGENT_GUILD_');
+    const clientEnv = this._sessionEnv({ id, reportToken, provider, account, extraEnv: shell.env, dropEnv });
+    const run = (args, extra = {}) => runSpec(buildSpawnSpec(shell.path, args, clientEnv, this.registry.platform), { env: clientEnv, ...extra });
+    // tmux keeps the card's own session by name; a herdr card's session is herdr's, there while its server runs.
+    const alive = shell.id === 'tmux'
+      ? () => run(['has-session', '-t', `=${muxName}`]).then(() => true, () => false)
+      : () => run(['session', 'list', '--json']).then(({ stdout }) => herdrSocket(JSON.parse(stdout), clientEnv, this.registry.platform) !== null, () => false);
+    return { named, dropEnv, clientEnv, run, alive };
+  }
+
+  /** Keep a tmux or herdr card for Reattach, here and, through the store, across restarts. */
+  _track(session, { spawnSpec, mux, shell, card }) {
+    this.multiplexers.set(session.id, { spawnSpec, alive: mux.alive, herdr: shell.id === 'herdr' ? { path: shell.path, env: mux.clientEnv } : null, card });
+    this._saveCards();
+    session.on('exit', async () => {
+      session.multiplexer.reattachable = await mux.alive();
+      session._changed();
+    });
+    session.on('changed', () => {
+      if (card.name === session.name) return;
+      card.name = session.name;
+      this._saveCards();
+    });
+  }
+
+  _saveCards() {
+    // A stopping manager leaves the file as it is, for the next one to bring the cards back.
+    if (!this.store || this.restoring || this.closing) return;
+    try {
+      this.store.save([...this.multiplexers.values()].map(({ card }) => card));
+    } catch (err) {
+      console.warn(`[sessions] could not save the tmux and herdr cards: ${err.message}`);
+    }
+  }
+
+  /**
+   * Bring back the tmux and herdr cards the previous manager had, closed and
+   * ready to reattach, with their own ids and report tokens so whatever runs
+   * inside reports to them again. A card whose session is gone stays gone.
+   */
+  async restore() {
+    this.restoring = true;
+    try {
+      // All at once, so a multiplexer slow to answer holds up the start once, not once a card.
+      await Promise.all((this.store?.load() ?? []).map((card) => this._restoreCard(card).catch((err) => {
+        console.warn(`[sessions] did not bring back the card ${card?.name ?? card?.id}: ${err.message}`);
+      })));
+    } finally {
+      this.restoring = false;
+    }
+    this._saveCards();
+  }
+
+  async _restoreCard(card) {
+    if (typeof card?.id !== 'string' || !/^[a-f0-9]{1,32}$/.test(card.id) || this.sessions.has(card.id)) return;
+    if (typeof card.reportToken !== 'string' || !/^[a-f0-9]{32}$/.test(card.reportToken)) return;
+    if (typeof card.muxName !== 'string' || !/^guild-[0-9a-f]{6}$/.test(card.muxName)) return;
+    const provider = this.registry.get(String(card.provider));
+    const shell = provider && this.registry.shellsFor(provider)?.shells.find((s) => s.id === card.shell && s.multiplexer);
+    if (!shell) return;
+    const account = this.registry.account(provider, card.account);
+    const mux = this._multiplexer({ provider, account, shell, id: card.id, reportToken: card.reportToken, muxName: card.muxName });
+    if (!(await mux.alive()) || this.closing) return;
+    const spawnSpec = this.registry.spawnSpec(provider, [], null, [], mux.named);
+    const session = this._spawn({
+      provider, spawnSpec: null, cwd: typeof card.cwd === 'string' ? card.cwd : os.homedir(), name: card.name, account,
+      id: card.id, reportToken: card.reportToken, dropEnv: mux.dropEnv, extraEnv: shell.env,
+      createdAt: typeof card.createdAt === 'string' && !Number.isNaN(Date.parse(card.createdAt)) ? card.createdAt : undefined,
+      multiplexer: { label: shell.label, attach: shell.multiplexer.attach.replaceAll('{name}', card.muxName), reattachable: true },
+    });
+    this._track(session, { spawnSpec, mux, shell, card: { ...card, name: session.name, cwd: session.cwd, createdAt: session.createdAt } });
+  }
+
+  /** Attach a stopped tmux or herdr session's card to its multiplexer session again, keeping its id and report token. */
+  async reattach(id) {
+    const session = this.get(id);
+    const mux = this.multiplexers.get(id);
+    if (!mux) throw httpError(400, `${session.name} is not in tmux or herdr`, 'not_reattachable');
+    if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
+    if (session.status === 'running') throw httpError(409, `${session.name} is still attached`, 'session_running');
+    // As the page offers it: only once the manager has found, after the client closed or at a restart, that the multiplexer still has the session.
+    if (!session.multiplexer.reattachable) throw httpError(409, `${session.multiplexer.label} no longer has the session ${session.name} ran in`, 'multiplexer_session_gone');
+    const alive = await mux.alive();
+    if (this.sessions.get(id) !== session || session.status === 'running') throw httpError(409, `${session.name} changed meanwhile`, 'session_running');
+    if (!alive) {
+      session.multiplexer.reattachable = false;
+      session._changed();
+      throw httpError(409, `${session.multiplexer.label} no longer has the session ${session.name} ran in`, 'multiplexer_session_gone');
+    }
+    try {
+      // The client can run anywhere, and the card's folder may be gone by now.
+      session.reattach(mux.spawnSpec, { cwd: isFolder(session.cwd) ? session.cwd : os.homedir() });
+    } catch (err) {
+      throw httpError(500, `could not attach to ${session.multiplexer.label}: ${err.message}`, 'spawn_failed');
+    }
+    session.multiplexer.reattachable = false;
+    this._watchHerdr(session);
+    return session;
+  }
+
+  /** While a herdr card runs, its agents are the ones herdr reports. */
+  _watchHerdr(session) {
+    const herdr = this.multiplexers.get(session.id)?.herdr;
+    if (!herdr) return;
+    this.watchers.get(session.id)?.stop();
+    const watcher = new HerdrAgents({ herdr: herdr.path, env: herdr.env, platform: this.registry.platform, onAgents: (agents) => showHerdrAgents(session, agents) });
+    this.watchers.set(session.id, watcher);
+    // herdr's server may still be starting; each burst of output from the client tries again until connected.
+    const poke = () => { if (session.status === 'running') watcher.poke(); };
+    session.on('changed', poke);
+    session.once('exit', () => {
+      session.off('changed', poke);
+      watcher.stop();
+      if (this.watchers.get(session.id) === watcher) this.watchers.delete(session.id);
+    });
+  }
+
   prepareAccount(provider, account, { hooksSupplied = false } = {}) {
     if (!account.dir) return;
     try {
@@ -242,24 +421,26 @@ export class SessionManager extends EventEmitter {
     return n;
   }
 
-  /** Sessions whose process is still running, install sessions included. */
+  /**
+   * Sessions whose process is still running, install sessions included,
+   * except tmux and herdr ones: stopping the manager only detaches those,
+   * and their cards come back.
+   */
   runningCount() {
     let n = 0;
-    for (const s of this.sessions.values()) if (s.status === 'running') n++;
+    for (const s of this.sessions.values()) if (s.status === 'running' && !s.multiplexer) n++;
     return n;
   }
 
-  _spawn({
-    provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null, installPath = null, account = null,
-    extraEnv = null, dropEnv = null, clone = null, reporting = null,
-  }) {
+  _assertCanSpawn() {
     if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
     if (this.sessions.size >= MAX_SESSIONS) {
       throw httpError(429, `session limit reached (${MAX_SESSIONS}); remove finished sessions first`, 'too_many_sessions');
     }
-    const id = newId();
-    const reportToken = crypto.randomBytes(16).toString('hex');
+  }
 
+  /** The environment of a session's process. */
+  _sessionEnv({ id, reportToken, provider, account = null, extraEnv = null, dropEnv = null }) {
     // The tool's hooks run `agent-guild-report` by name, so the launchers
     // go first on PATH, after any provider PATH override.
     let env = prependPath(mergeEnv([this.baseEnv, provider.env, account?.env, {
@@ -274,11 +455,25 @@ export class SessionManager extends EventEmitter {
     }]), this.shimDir);
     // The tool runs in its own terminal, not in the terminal or multiplexer
     // the manager was started from: Claude Code would otherwise open
-    // agent-team panes in that tmux window, outside the page, and tools
-    // would tune their output to a terminal program that is not there.
-    for (const key of ['TMUX', 'TMUX_PANE', 'STY', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION', 'ZELLIJ', 'ZELLIJ_SESSION_NAME', 'ZELLIJ_PANE_ID']) delete env[key];
+    // agent-team panes in that tmux window, outside the page, tools would
+    // tune their output to a terminal program that is not there, and herdr
+    // would refuse to start, taking itself to be nested in a herdr pane.
+    for (const key of [
+      'TMUX', 'TMUX_PANE', 'STY', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION', 'ZELLIJ', 'ZELLIJ_SESSION_NAME', 'ZELLIJ_PANE_ID',
+      'HERDR_ENV', 'HERDR_PANE_ID', 'HERDR_TAB_ID', 'HERDR_WORKSPACE_ID', 'HERDR_SOCKET_PATH', 'HERDR_BIN_PATH',
+    ]) delete env[key];
     if (dropEnv) for (const key of Object.keys(env)) if (dropEnv(key)) delete env[key];
     if (extraEnv) env = mergeEnv([env, extraEnv]);
+    return env;
+  }
+
+  _spawn({
+    provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null, installPath = null, account = null,
+    extraEnv = null, dropEnv = null, clone = null, reporting = null, multiplexer = null,
+    id = newId(), reportToken = crypto.randomBytes(16).toString('hex'), createdAt,
+  }) {
+    this._assertCanSpawn();
+    const env = this._sessionEnv({ id, reportToken, provider, account, extraEnv, dropEnv });
 
     let session;
     try {
@@ -298,6 +493,8 @@ export class SessionManager extends EventEmitter {
         account: account ? { id: account.id, label: account.label } : null,
         clone,
         reporting,
+        multiplexer,
+        createdAt,
       });
     } catch (err) {
       throw httpError(500, `could not start ${provider.tool}: ${err.message}`, 'spawn_failed');
@@ -327,6 +524,9 @@ export class SessionManager extends EventEmitter {
   remove(id) {
     const session = this.get(id);
     this.sessions.delete(id);
+    if (this.multiplexers.delete(id)) this._saveCards();
+    this.watchers.get(id)?.stop();
+    this.watchers.delete(id);
     session._broadcast({ type: 'removed' });
     if (session.status === 'running') {
       this.exiting.add(session);
@@ -377,6 +577,8 @@ export class SessionManager extends EventEmitter {
    */
   async shutdown({ graceMs = 1500, timeoutMs = 5000 } = {}) {
     this.closing = true;
+    for (const watcher of this.watchers.values()) watcher.stop();
+    this.watchers.clear();
     const sessions = [...this.sessions.values()];
     this.sessions.clear();
     const pending = new Set([...sessions.filter((s) => s.status === 'running'), ...this.exiting]);
@@ -393,6 +595,17 @@ export class SessionManager extends EventEmitter {
   }
 }
 
+/** Show a herdr card the agents herdr lists, and drop the ones it no longer lists. */
+function showHerdrAgents(session, agents) {
+  if (session.status !== 'running') return;
+  const reports = herdrAgentReports(agents);
+  const listed = new Set(reports.map((report) => report.agentId));
+  for (const id of [...session.agents.keys()]) if (id.startsWith('herdr:') && !listed.has(id)) session.reportAgent({ agentId: id, remove: true }, 'herdr');
+  for (const report of reports) {
+    try { session.reportAgent(report, 'herdr'); } catch { /* more agents than a card holds */ }
+  }
+}
+
 /** The model named by a --model, --model=, or -m argument, or null. */
 export function modelFromArgs(args) {
   for (let i = 0; i < args.length; i++) {

package/src/manager/session.mjs

@@ -62,6 +62,8 @@ export class Session extends EventEmitter {
    * @param {string|null} [opts.task]    "install" for a package install, "upgrade" for the manager's own, "clone" for a GitHub clone, else null
    * @param {{id: string, label: string}|null} [opts.account]  the tool sign-in the session runs under
    * @param {{repo: string, path: string, accountId: number}|null} [opts.clone]  what a clone session clones, and where
+   * @param {{label: string, attach: string, reattachable: boolean}|null} [opts.multiplexer]  the multiplexer a Shell session runs in, and the command that reattaches it
+   * @param {string} [opts.createdAt]  when the card was first made; a restored tmux or herdr card keeps its own. With no spawnSpec, the session is such a card, closed
    * @param {string} opts.reportToken
    * @param {number} [opts.scrollback]
    * @param {number} [opts.activityIdleMs]
@@ -77,6 +79,7 @@ export class Session extends EventEmitter {
     this.task = opts.task ?? null;
     this.account = opts.account ?? null;
     this.clone = opts.clone ?? null;
+    this.multiplexer = opts.multiplexer ?? null;
     this.cwd = opts.cwd;
     this.cols = opts.cols;
     this.rows = opts.rows;
@@ -92,7 +95,9 @@ export class Session extends EventEmitter {
     this.shells = new Map();
     this._shellSeq = 0;
     this._endedTasks = new Set();
-    this.createdAt = new Date().toISOString();
+    this.createdAt = opts.createdAt ?? new Date().toISOString();
+    /** When the current process started; later than createdAt once a multiplexer session is reattached. */
+    this.startedAt = this.createdAt;
     this.exitedAt = null;
     this.status = 'running';
     this.exitCode = null;
@@ -144,21 +149,50 @@ export class Session extends EventEmitter {
     }
 
     this.disposed = false;
+    this.env = opts.env;
+    if (!opts.spawnSpec) {
+      // A tmux or herdr card brought back after the manager restarted: its
+      // multiplexer still runs the session, and the card is closed until reattached.
+      this.status = 'exited';
+      this.exitedAt = new Date().toISOString();
+      this.activity = 'quiet';
+      this._resolveExited();
+      const label = this.multiplexer?.label ?? 'The multiplexer';
+      this.term.write(`\x1b[2m[Agent Guild restarted. ${label} still runs this session; Reattach it from its card.]\x1b[0m\r\n`);
+      return;
+    }
     try {
-      this.pty = pty.spawn(opts.spawnSpec.file, opts.spawnSpec.args, {
-        name: 'xterm-256color',
-        cols: this.cols,
-        rows: this.rows,
-        cwd: this.cwd,
-        env: opts.env,
-        useConpty: true,
-      });
+      this._start(opts.spawnSpec);
     } catch (err) {
       this.term.dispose();
       throw err;
     }
-    this.pty.onData((data) => this._onData(data));
-    this.pty.onExit(({ exitCode, signal }) => this._onExit(exitCode, signal));
+  }
+
+  _start(spawnSpec, cwd = this.cwd) {
+    const proc = pty.spawn(spawnSpec.file, spawnSpec.args, {
+      name: 'xterm-256color',
+      cols: this.cols,
+      rows: this.rows,
+      cwd,
+      env: this.env,
+      useConpty: true,
+    });
+    this.pty = proc;
+    proc.onData((data) => { if (this.pty === proc) this._onData(data); });
+    proc.onExit(({ exitCode, signal }) => { if (this.pty === proc) this._onExit(exitCode, signal); });
+  }
+
+  /**
+   * Run a new process in an exited session, keeping its id, report token and
+   * screen: a multiplexer's client attaching to its session again, in `cwd`.
+   */
+  reattach(spawnSpec, { cwd = this.cwd } = {}) {
+    if (this.disposed || this.status !== 'exited') throw Object.assign(new Error('only an exited session can be reattached'), { status: 409 });
+    this._start(spawnSpec, cwd);
+    Object.assign(this, { status: 'running', exitCode: null, signal: null, exitedAt: null, activity: 'quiet', startedAt: new Date().toISOString() });
+    this.exited = new Promise((resolve) => { this._resolveExited = resolve; });
+    this._changed();
   }
 
   /**
@@ -307,9 +341,11 @@ export class Session extends EventEmitter {
 
   /**
    * End the process. On macOS and Linux: hang-up first, force after a grace
-   * period. On Windows: end the whole process tree at once. node-pty's own
-   * Windows kill first asks a helper process for the console's process list,
-   * and when that helper fails it waits a fixed five seconds.
+   * period. On Windows: end the whole process tree at once, except for a
+   * multiplexer's client, whose server is its child there and must outlive
+   * it. node-pty's own Windows kill first asks a helper process for the
+   * console's process list, and when that helper fails it waits a fixed
+   * five seconds.
    */
   kill({ graceMs = this.killGraceMs } = {}) {
     if (this.status !== 'running') return;
@@ -330,7 +366,7 @@ export class Session extends EventEmitter {
     };
     const pid = this.pty.pid;
     if (!pid) return fallback();
-    killWindowsTree(pid, (err) => { if (err) fallback(); });
+    killWindowsTree(pid, (err) => { if (err) fallback(); }, { tree: !this.multiplexer });
   }
 
   /**
@@ -682,6 +718,7 @@ export class Session extends EventEmitter {
       task: this.task,
       account: this.account,
       clone: this.clone,
+      multiplexer: this.multiplexer,
       pid: this.pid,
       status: this.status,
       exitCode: this.exitCode,
@@ -689,6 +726,7 @@ export class Session extends EventEmitter {
       activity: this.activity,
       lastOutputAt: this.lastOutputAt ? new Date(this.lastOutputAt).toISOString() : null,
       createdAt: this.createdAt,
+      startedAt: this.startedAt,
       exitedAt: this.exitedAt,
       cols: this.cols,
       rows: this.rows,

package/src/manager/shells.mjs

@@ -3,6 +3,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { resolveCommand } from './command-resolver.mjs';
 
 const UNIX_SHELLS = [
@@ -12,10 +13,34 @@ const UNIX_SHELLS = [
   { id: 'pwsh', label: 'PowerShell' },
 ];
 
+// Terminal multiplexers, offered after the shells. A session only ever ends
+// its client: the multiplexer's own session keeps running after the card
+// stops, so the card can attach to it again. {name} is that session's name.
+// A tmux card attaches to a tmux session made for it first (tmuxNewSession),
+// so the card's identity reaches that session only; that needs tmux 3.2.
+// tmux gets -u because the page's terminal is always UTF-8, whatever locale
+// the manager inherited; without it tmux draws other characters as "_".
+// A herdr card attaches to herdr's own persistent session; herdr runs on
+// Windows too, tmux does not.
+const TMUX = { id: 'tmux', label: 'tmux', args: ['-u', 'attach-session', '-t', '={name}'], multiplexer: { attach: 'tmux attach -t {name}' } };
+const HERDR = { id: 'herdr', label: 'herdr', args: [], multiplexer: { attach: 'herdr' } };
+
 function isFile(file) {
   try { return fs.statSync(file).isFile(); } catch { return false; }
 }
 
+/** The output of `<file> -V`, or '' when it cannot run. */
+function readVersion(file) {
+  try { return execFileSync(file, ['-V'], { encoding: 'utf8', timeout: 5000, windowsHide: true }); } catch { return ''; }
+}
+
+/** Whether `tmux -V` names 3.2 or later. A build without a number (master, a BSD's own) counts as recent. */
+export function tmuxSupported(versionText) {
+  if (!/^tmux /.test(versionText)) return false;
+  const [, major, minor] = versionText.match(/(\d+)\.(\d+)/) ?? [];
+  return major === undefined || Number(major) > 3 || (Number(major) === 3 && Number(minor) >= 2);
+}
+
 function envValue(env, name) {
   const key = Object.keys(env).find((k) => k.toUpperCase() === name.toUpperCase());
   return key ? env[key] : undefined;
@@ -45,7 +70,16 @@ export function fallbackShell(env, platform) {
   return env.SHELL || (platform === 'darwin' ? '/bin/zsh' : '/bin/bash');
 }
 
-function windowsShells(env, resolve, exists) {
+/** Add the installed multiplexers after the shells, unless a shell already has their id. */
+function withMultiplexers(shells, candidates, resolve, version) {
+  for (const { id, label, args, multiplexer } of candidates) {
+    const found = !shells.some((shell) => shell.id === id) && resolve(id);
+    if (found && (id !== 'tmux' || tmuxSupported(version(found)))) shells.push({ id, label, path: found, args, env: {}, multiplexer });
+  }
+  return shells;
+}
+
+function windowsShells(env, resolve, exists, version) {
   const installed = ['ProgramFiles', 'ProgramW6432'].map((name) => envValue(env, name)).filter(Boolean).map((base) => path.win32.join(base, 'PowerShell', '7', 'pwsh.exe'));
   const pwsh = resolve('pwsh') || installed.find(exists) || null;
   const gitBash = findGitBash(env, resolve, exists);
@@ -56,10 +90,11 @@ function windowsShells(env, resolve, exists) {
     // CHERE_INVOKING keeps a login bash in the session's folder instead of moving to HOME.
     gitBash && { id: 'git-bash', label: 'Git Bash', path: gitBash, args: ['--login', '-i'], env: { CHERE_INVOKING: '1' } },
   ].filter((shell) => shell?.path);
-  return { shells, defaultId: shells[0]?.id ?? null };
+  const defaultId = shells[0]?.id ?? null;
+  return { shells: withMultiplexers(shells, [HERDR], resolve, version), defaultId };
 }
 
-function unixShells(env, platform, resolve) {
+function unixShells(env, platform, resolve, version) {
   const name = (file) => path.posix.basename(file);
   const own = resolve(env.SHELL || '') || resolve(fallbackShell({}, platform));
   const shells = [];
@@ -72,11 +107,32 @@ function unixShells(env, platform, resolve) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/.test(defaultId)) defaultId = 'login';
     shells.unshift({ id: defaultId, label: name(own), path: own, args: [], env: {} });
   }
-  return { shells, defaultId: defaultId ?? shells[0]?.id ?? null };
+  defaultId ??= shells[0]?.id ?? null;
+  return { shells: withMultiplexers(shells, [TMUX, HERDR], resolve, version), defaultId };
 }
 
-/** The installed shells, as { id, label, path, args, env }, and the id of the default one. */
-export function detectShells(env = process.env, platform = process.platform, { exists = isFile, resolve: resolveWith = resolveCommand } = {}) {
+/** The installed shells, as { id, label, path, args, env, multiplexer? }, and the id of the default one. */
+export function detectShells(env = process.env, platform = process.platform, { exists = isFile, resolve: resolveWith = resolveCommand, version = readVersion } = {}) {
   const resolve = (command) => resolveWith(command, env, platform);
-  return platform === 'win32' ? windowsShells(env, resolve, exists) : unixShells(env, platform, resolve);
+  return platform === 'win32' ? windowsShells(env, resolve, exists, version) : unixShells(env, platform, resolve, version);
+}
+
+/** Quote one word for tmux's command parser: nothing inside single quotes is expanded. `code` names the field a line break came from. */
+function tmuxQuote(value, code = 'bad_request') {
+  const text = String(value);
+  if (/[\r\n]/.test(text)) throw Object.assign(new Error('tmux cannot take a value with a line break'), { status: 400, code });
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * The tmux commands, read from stdin, that make a card's own tmux session:
+ * detached, `cols` by `rows`, in `cwd`, with `env` as that session's own
+ * environment and `args`, if any, as its command. Stdin keeps the card's
+ * report token off the command line, where other users could read it.
+ */
+export function tmuxNewSession({ name, cwd, cols, rows, env, args = [] }) {
+  const words = ['new-session', '-d', '-s', tmuxQuote(name), '-x', String(cols), '-y', String(rows), '-c', tmuxQuote(cwd, 'bad_cwd')];
+  for (const [key, value] of Object.entries(env)) words.push('-e', tmuxQuote(`${key}=${value}`));
+  for (const arg of args) words.push(tmuxQuote(arg, 'bad_args'));
+  return `${words.join(' ')}\n`;
 }

package/web/app.js

@@ -580,7 +580,9 @@ function renderShells(card, provider) {
     const chip = host.children[i];
     chip.setAttribute('aria-selected', String(shell.id === selected));
     chip.textContent = shell.label;
-    chip.title = `Start new sessions in ${shell.label}${shell.id === provider.defaultShell ? ', used unless you pick another' : ''}\n${shell.path}`;
+    chip.title = shell.multiplexer
+      ? `Start new sessions inside ${shell.label}. Stopping or closing one detaches it; it keeps running in ${shell.label}.\n${shell.path}`
+      : `Start new sessions in ${shell.label}${shell.id === provider.defaultShell ? ', used unless you pick another' : ''}\n${shell.path}`;
   });
 }
 
@@ -2689,6 +2691,8 @@ function accountLabel(s) {
 
 function statusText(s) {
   if (s.status === 'exited') {
+    // A multiplexer's client exits 1 when detached by Stop: its exit code tells the user nothing.
+    if (s.multiplexer) return 'Closed';
     if (s.signal) return `Exited (${s.signal})`;
     return s.exitCode === 0 || s.exitCode === null ? 'Exited' : `Exited (${s.exitCode})`;
   }
@@ -2732,8 +2736,24 @@ function resumable(s) {
     && !runningOn(s.provider.id, s.account?.id ?? 'default', id));
 }
 
+/** A stopped tmux or herdr card whose multiplexer still has its session. */
+function reattachable(s) {
+  return Boolean(s.status === 'exited' && s.multiplexer?.reattachable);
+}
+
+async function reattachSession(id) {
+  try {
+    upsertSession((await api('POST', `/sessions/${id}/reattach`)).session);
+    openPanel(id);
+  } catch (err) {
+    if (err instanceof AuthError) return showAuth(err.message);
+    toast(err.message, 8000);
+  }
+}
+
 function resumeCard(id) {
   const s = state.sessions.get(id);
+  if (s && reattachable(s)) return reattachSession(id);
   if (!s || !resumable(s)) return;
   const provider = state.providers.find((p) => p.id === s.provider.id);
   const account = provider.accounts?.find((a) => a.id === s.account?.id)?.id;
@@ -2778,14 +2798,20 @@ function updateCard(node, s) {
   renderAgents(node.querySelector('.agents'), s.agents, s.shells || []);
   paintReporting(node.querySelector('.agents-row'), s);
   node.classList.toggle('exited', s.status === 'exited');
-  node.querySelector('.stop').hidden = s.status !== 'running';
+  const stop = node.querySelector('.stop');
+  stop.hidden = s.status !== 'running';
+  stop.textContent = s.multiplexer ? 'Detach' : 'Stop';
+  stop.title = s.multiplexer ? `Detach from ${s.multiplexer.label}; it keeps running. Reattach with: ${s.multiplexer.attach}` : '';
   node.querySelector('.remove').hidden = s.status === 'running';
   const useButton = node.querySelector('.use-folder');
   useButton.hidden = !clonedPath(s);
   useButton.title = clonedPath(s) ? `Make ${s.clone.path} the working folder, so new sessions start there` : '';
   const resume = node.querySelector('.resume');
-  resume.hidden = !resumable(s);
-  resume.title = `Start ${s.provider.tool} again on this session${id ? ` (${id})` : ''} in ${s.cwd}`;
+  resume.hidden = !resumable(s) && !reattachable(s);
+  resume.textContent = s.multiplexer ? 'Reattach' : 'Resume';
+  resume.title = s.multiplexer
+    ? `Attach this card to its ${s.multiplexer.label} session again, as ${s.multiplexer.attach} would`
+    : `Start ${s.provider.tool} again on this session${id ? ` (${id})` : ''} in ${s.cwd}`;
   const modelLabel = s.model ? `, model ${modelText(s)}` : '';
   const accountName = accountLabel(s) ? `, ${accountLabel(s)} account` : '';
   const shellCount = (s.shells || []).length;
@@ -2837,6 +2863,11 @@ function guardLeaving() {
 }
 
 function upsertSession(session) {
+  // An exit is final for the process it ended. A reply sent before it, such as Stop's, can
+  // arrive after the exit was announced and must not show the session running again; a
+  // reattached tmux or herdr session runs a newer process, started after that exit.
+  const known = state.sessions.get(session.id);
+  if (known?.status === 'exited' && session.status !== 'exited' && !(Date.parse(session.startedAt) > Date.parse(known.exitedAt))) return;
   state.sessions.set(session.id, session);
   renderSessions();
   noticeClone(session);
@@ -2850,17 +2881,25 @@ function dropSession(id) {
   renderSessions();
 }
 
+/** What happens to a running session when it is stopped, for the confirmation. */
+function stopNote(s) {
+  const mux = s.multiplexer;
+  return mux ? `${mux.label} keeps running it. Reattach it from its card, or in a terminal with: ${mux.attach}` : `The ${s.provider.tool} process will be ended.`;
+}
+
 async function stopSession(id) {
   const s = state.sessions.get(id);
   if (!s || s.status !== 'running') return;
-  if (!confirm(`Stop "${s.name}"? The ${s.provider.tool} process will be ended.`)) return;
+  if (!confirm(`${s.multiplexer ? 'Detach' : 'Stop'} "${s.name}"? ${stopNote(s)}`)) return;
   try { upsertSession((await api('POST', `/sessions/${id}/stop`)).session); } catch (err) { toast(err.message); }
 }
 
 async function removeSession(id) {
   const s = state.sessions.get(id);
   if (!s) return;
-  if (s.status === 'running' && !confirm(`"${s.name}" is still running. End it and remove it?`)) return;
+  // The card goes, so only the terminal can reattach it.
+  const question = s.multiplexer ? `Detach it and remove it? ${s.multiplexer.label} keeps running it. Reattach it in a terminal with: ${s.multiplexer.attach}` : 'End it and remove it?';
+  if (s.status === 'running' && !confirm(`"${s.name}" is still running. ${question}`)) return;
   try { await api('DELETE', `/sessions/${id}`); dropSession(id); } catch (err) { toast(err.message); }
 }
 
@@ -3131,6 +3170,23 @@ function suppressQueryReplies(term) {
   }
 }
 
+/** The text an OSC 52 sequence ("c;<base64>") asks to copy, or null for a clipboard query or anything unreadable. */
+function osc52Text(data) {
+  const payload = data.slice(data.indexOf(';') + 1);
+  if (!data.includes(';') || !payload || payload === '?' || payload.length > 4 * 1024 * 1024) return null;
+  try {
+    return new TextDecoder().decode(Uint8Array.from(atob(payload), (c) => c.charCodeAt(0)));
+  } catch {
+    return null;
+  }
+}
+
+/** The line a terminal shows when its process ends. A tmux or herdr client's exit code says nothing about the session it showed. */
+function exitLine(s, { exitCode, signal }) {
+  if (s?.multiplexer) return '[closed]';
+  return `[process exited with ${signal ? `signal ${signal}` : `code ${exitCode ?? 0}`}]`;
+}
+
 class TerminalView {
   constructor(sessionId) {
     this.id = sessionId;
@@ -3141,6 +3197,8 @@ class TerminalView {
       fontSize: coarsePointer.matches ? 14 : 13,
       scrollback: 5000,
       macOptionIsMeta: true,
+      // Option-drag selects text even while a program reads the mouse, as Shift-drag does elsewhere.
+      macOptionClickForcesSelection: true,
       theme: TERMINAL_THEME,
     });
     this.fit = new window.FitAddon.FitAddon();
@@ -3148,6 +3206,13 @@ class TerminalView {
     this.term.loadAddon(new window.WebLinksAddon.WebLinksAddon((_e, uri) => window.open(uri, '_blank', 'noopener,noreferrer')));
     this.term.attachCustomKeyEventHandler((e) => this.handleKey(e));
     suppressQueryReplies(this.term);
+    // Programs copy with OSC 52: tmux's copy mode, and herdr where it cannot reach the
+    // system clipboard itself. Only the open terminal may write it; nothing reads it.
+    this.term.parser.registerOscHandler(52, (data) => {
+      const text = osc52Text(data);
+      if (text !== null && state.activeId === this.id) navigator.clipboard?.writeText(text).catch(() => {});
+      return true;
+    });
     this.term.onData((data) => {
       this.send({ type: 'input', data });
     });
@@ -3198,11 +3263,9 @@ class TerminalView {
       case 'data':
         this.term.write(msg.data);
         break;
-      case 'exit': {
-        const how = msg.signal ? `signal ${msg.signal}` : `code ${msg.exitCode ?? 0}`;
-        this.term.write(`\r\n\x1b[2m[process exited with ${how}]\x1b[0m\r\n`);
+      case 'exit':
+        this.term.write(`\r\n\x1b[2m${exitLine(state.sessions.get(this.id), msg)}\x1b[0m\r\n`);
         break;
-      }
       default:
         break;
     }
@@ -3320,7 +3383,7 @@ function updatePanel() {
   $('panel-sub').title = modelTitle(s);
   renderAgents($('panel-agents'), s.agents, s.shells || []);
   const stop = $('panel-stop');
-  stop.textContent = s.status === 'running' ? 'Stop' : 'Remove';
+  stop.textContent = s.status !== 'running' ? 'Remove' : s.multiplexer ? 'Detach' : 'Stop';
 }
 
 // ---- stopping the manager -------------------------------------------------