@coulb/crux-cli 0.1.0

package/leads.config.json

@@ -0,0 +1,62 @@
+{
+  "$comment": [
+    "The DEFAULT leads config, shipped with the package. It is a TEMPLATE, and it ships empty on",
+    "purpose: crux reads the first of CRUX_LEADS_CONFIG, ~/.config/crux/leads.json, and this file, so",
+    "the moment you have one of your own this one stops being read. `crux discover` writes",
+    "~/.config/crux/leads.json for you. Every key here also has a working default in code — a config",
+    "pre-filled with somebody else's project names is not a default, it is a mess you clean up first.",
+    "",
+    "map — an explicit Solo-project-name -> crux-slug mapping, read by `crux leads` and `crux swarm`.",
+    "      You need an entry only where the two names are NOT equal; a Solo project whose name already",
+    "      IS a crux slug needs none, which is why this can be empty and still reconcile a whole fleet.",
+    "",
+    "      It is deliberately NOT string munging. In a fleet where `acme-search-index` is the slug",
+    "      `acme` and `status-page` is the slug `beacon`, no transformation derives either one. So an",
+    "      unmapped Solo project is reported as UNMAPPED and exits non-zero rather than being silently",
+    "      skipped — a project that quietly falls out of the reconciliation is the exact failure mode",
+    "      this command exists to catch.",
+    "",
+    "        \"map\": { \"acme-search-index\": \"acme\", \"status-page\": \"beacon\" }",
+    "",
+    "leadless    — projects configured to expect no lead. Reported as expected, never as an error.",
+    "leadProcess — override the Solo process name for a slug (the default is `lead-<slug>`)."
+  ],
+
+  "map": {},
+
+  "leadless": {
+    "personal": "Human-only project. Items are read on the dashboard, not routed to an agent lead."
+  },
+
+  "leadProcess": {},
+
+  "$swarm": [
+    "`crux swarm up` reads this. It is the whole configuration surface for spinning up a swarm.",
+    "",
+    "backend  — solo | exec. ABSENT ON PURPOSE, and that absence is load-bearing: with no backend set,",
+    "           crux looks at your PATH and picks one (solo, then tmux via exec), and `crux discover`",
+    "           writes its choice into your config so you can see and change it. A backend pinned here",
+    "           would hand every reader who does not run that orchestrator a first `crux swarm up` that",
+    "           dies on `could not run …` — and a default that is wrong for most of its readers is not",
+    "           a default, it is a trap. Set it here to PIN a backend; --backend and",
+    "           CRUX_SWARM_BACKEND override it for one run.",
+    "agent    — the command an `exec` lead runs. Solo names its own agent (see solo.agentToolId).",
+    "solo     — { agentToolId: 3 }  the Solo agent tool to spawn (3 = claude).",
+    "exec     — { command, stop }  templates. Placeholders: {slug} {name} {repo} {brief_path} {command}.",
+    "           Set `stop` whenever `command` forks (tmux, nohup) or crux is left holding a dead pid.",
+    "           Leave both out and crux derives the tmux pair — but only if tmux is really installed.",
+    "projects — per-slug { repo, brief }. `repo` is required for any project the backend cannot",
+    "           locate itself; Solo already records a path per project, so a Solo user needs none of",
+    "           this. `brief` is extra context pasted into the generated standing-lead brief.",
+    "",
+    "The projects map below is EMPTY on purpose. `crux discover` writes the repo for each project you",
+    "register, into your own config — baking one machine's paths into a shipped file is exactly what",
+    "`crux swarm` exists to stop doing."
+  ],
+
+  "swarm": {
+    "solo": { "agentToolId": 3 },
+    "exec": {},
+    "projects": {}
+  }
+}

package/lib/backends.js

@@ -0,0 +1,617 @@
+'use strict';
+
+/**
+ * The orchestration adapters — "bring your own orchestration, but ship our own opinions."
+ *
+ * ## The interface
+ *
+ * A backend is three methods. That is the whole contract, and keeping it this small is what makes
+ * the North Star true rather than a slogan:
+ *
+ *   start(lead)  → {ref, detail}   start one standing lead. `ref` is an opaque handle, meaningful
+ *                                  only to this backend, that crux records and hands back to stop().
+ *   stop(entry)  → 'stopped' | 'already-gone' | 'unknown'
+ *   list()       → [{slug, ref, running}]   what this backend can see running, right now.
+ *
+ * Plus one declaration, `addresses`, which is not a method because it does not vary per call:
+ *
+ *   'handle' — this backend can stop a lead from its ref alone, forever (Solo's process id; a tmux
+ *              session name). The recorded process being gone does not mean the lead is gone.
+ *   'pid'    — the ref IS an OS pid, and if that pid dies the backend has no other way to name the
+ *              lead. `planDown` refuses rather than pretend, because a lead that outlived the only
+ *              handle crux has on it must be reported, not quietly forgotten.
+ *
+ * ## What is deliberately NOT in the interface
+ *
+ * **Coverage.** A backend is never asked "is <slug> covered?", because a backend cannot be trusted
+ * to answer it — Solo's own status lies, and tmux has no idea what a crux slug is. Coverage is read
+ * off the OS process table, where the truth actually lives {@see ../lib/leads}: something, somewhere,
+ * is running `crux tail --project <slug>`. That is why `exec` gets working reconciliation for free.
+ *
+ * ## herdr
+ *
+ * The third backend {@see herdrBackend}, written against herdr 0.7.3 as actually installed and run —
+ * not against its website, which documents `workspace create` / `tab create` / `pane split` / `pane
+ * run` and shows neither of the two verbs an adapter most needs (how do you LIST agents, and how do
+ * you KILL one). The real surface has both, plus a better start verb than the docs suggest, and the
+ * adapter uses those. `herdr --help` and `herdr <verb> --help` are the source of truth; the day this
+ * stops matching, it is because herdr moved, and the fix is to re-read them.
+ */
+
+const { execFileSync, spawn: spawnChild } = require('child_process');
+const { DEFAULT_AGENT, agentCommand, execVars, leadName, renderTemplate } = require('./swarm');
+
+/** Solo's own agent-tool id for `claude --dangerously-skip-permissions`. */
+const DEFAULT_AGENT_TOOL_ID = 3;
+
+/** `solo … --json`, tolerantly: null on any failure. Mirrors lib/spawn's soloTry. */
+function soloTry(argv) {
+  try {
+    const raw = execFileSync(process.env.CRUX_SOLO_BIN || 'solo', [...argv, '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const doc = JSON.parse(raw);
+    return doc.ok ? doc.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/** `solo … --json` or throw. Starting a lead is load-bearing: if Solo cannot, we must not pretend. */
+function solo(argv) {
+  let raw;
+  try {
+    raw = execFileSync(process.env.CRUX_SOLO_BIN || 'solo', [...argv, '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    throw new Error(`could not run \`solo ${argv.join(' ')}\`: ${e.message.split('\n')[0]}`);
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    throw new Error(`\`solo ${argv.join(' ')}\` did not return JSON`);
+  }
+  if (!doc.ok) throw new Error(`\`solo ${argv.join(' ')}\` failed: ${doc.error || 'unknown error'}`);
+  return doc.data;
+}
+
+/** Every Solo process, following pagination — an unpaginated list looks complete and is not. */
+function soloProcesses() {
+  const all = [];
+  for (let offset = 0; ; ) {
+    const page = soloTry(['processes', 'list', '--limit', '200', '--offset', String(offset)]);
+    if (page === null) return all;
+    all.push(...(page.processes || []));
+    if (!page.hasMore || (page.processes || []).length === 0) return all;
+    offset = page.nextOffset ?? offset + page.processes.length;
+  }
+}
+
+/**
+ * The opinionated default: Solo.
+ *
+ * The one real difference from `crux leads --fix` is that this SPAWNS rather than starts. `--fix`
+ * can only start a `kind: command` row a human already declared in `solo.yml`, which is why it
+ * cannot build a swarm from nothing. This spawns a `kind: agent` process directly — the same call
+ * `crux spawn` makes for a worker — so no declaration has to exist first. And when the Solo project
+ * itself does not exist, it is created from the configured repo path, which is the last thing
+ * standing between a stranger and a running swarm.
+ */
+function soloBackend({ agentToolId = DEFAULT_AGENT_TOOL_ID } = {}) {
+  return {
+    name: 'solo',
+    addresses: 'handle',
+
+    /** Solo runs the agent in its project's directory, so the project IS the cwd. */
+    ensureProject(lead) {
+      if (lead.soloProject) return { project: lead.soloProject, created: false };
+
+      const created = solo(['projects', 'create', lead.slug, lead.repo]);
+      const project = created.project ?? created;
+      return { project: { id: project.id, name: project.name ?? lead.slug }, created: true };
+    },
+
+    start(lead) {
+      const { project, created } = this.ensureProject(lead);
+      const name = leadName(lead.slug);
+
+      // Each flag rides in as its own --arg: Solo appends them after the agent tool's own command
+      // (`claude --dangerously-skip-permissions`), exactly as lib/spawn.js does for a worker.
+      const data = solo([
+        'processes',
+        'spawn',
+        '--project-id',
+        String(project.id),
+        '--kind',
+        'agent',
+        '--agent-tool-id',
+        String(agentToolId),
+        '--name',
+        name,
+        '--arg',
+        '-n',
+        '--arg',
+        name,
+        '--arg',
+        lead.prompt,
+      ]);
+
+      const ref = data?.process?.id ?? data?.process ?? null;
+      if (ref === null) {
+        throw new Error(`Solo spawned the lead for "${lead.slug}" but reported no process id`);
+      }
+
+      return {
+        ref: String(ref),
+        detail:
+          `Solo process ${ref} in project ${project.id} (${project.name})` +
+          `${created ? ' — project created' : ''}`,
+      };
+    },
+
+    stop(entry) {
+      const data = soloTry(['processes', 'stop', String(entry.ref)]);
+      if (data === null) return 'unknown';
+      return data.changed === true ? 'stopped' : 'already-gone';
+    },
+
+    list() {
+      return soloProcesses()
+        .filter((p) => typeof p.name === 'string' && p.name.startsWith('lead-'))
+        .map((p) => ({
+          slug: p.name.slice('lead-'.length),
+          ref: String(p.id),
+          running: p.status === 'running',
+        }));
+    },
+  };
+}
+
+/**
+ * The escape hatch that makes "bring your own orchestration" true: run an arbitrary command.
+ *
+ * The user supplies a template and crux fills in the blanks:
+ *
+ *   {"backend": "exec", "exec": {"command": "tmux new-session -d -s {name} '{command}'",
+ *                                "stop":    "tmux kill-session -t {name}"}}
+ *
+ * If a user cannot run their swarm on their own orchestrator with this, the North Star is a lie —
+ * so the placeholders are documented, an unknown one is a hard failure {@see renderTemplate}, and
+ * nothing about crux's model of a lead is assumed beyond "a command starts it".
+ *
+ * `stop` is optional but strongly wanted, and the reason is the tmux example itself: `tmux
+ * new-session -d` FORKS — the process crux spawned exits immediately while the lead lives on inside
+ * the tmux server. The pid crux recorded is then a dead handle to a live lead. With a `stop`
+ * template crux can still address it by name; without one it cannot, and `planDown` says so out loud
+ * rather than reporting a lead it did not stop as stopped.
+ */
+function execBackend({ command, stop = null, state = {} } = {}) {
+  if (typeof command !== 'string' || command.trim() === '') {
+    throw new Error(
+      'the exec backend needs a command template — set `swarm.exec.command`, e.g. ' +
+        `"tmux new-session -d -s {name} '{command}'"`,
+    );
+  }
+
+  const alive = (pid) => {
+    const n = Number(pid);
+    if (!Number.isInteger(n) || n <= 0) return false;
+    try {
+      process.kill(n, 0);
+      return true;
+    } catch (e) {
+      return e.code === 'EPERM'; // Alive, just not ours to signal.
+    }
+  };
+
+  return {
+    name: 'exec',
+    // With a stop template the lead is addressable by name forever; without one, the pid is the
+    // only handle there is — and a pid is mortal in a way a name is not.
+    addresses: stop ? 'handle' : 'pid',
+
+    start(lead) {
+      const line = renderTemplate(command, execVars(lead));
+
+      // Detached, in its own process group, so it survives crux exiting — and so that a pid-based
+      // stop can signal the whole tree (the agent AND the tail it starts), not just the shell.
+      const child = spawnChild('sh', ['-c', line], {
+        cwd: lead.repo,
+        detached: true,
+        stdio: 'ignore',
+      });
+      child.unref();
+
+      if (typeof child.pid !== 'number') {
+        throw new Error(`could not start the lead for "${lead.slug}": \`${line}\` produced no pid`);
+      }
+
+      return { ref: String(child.pid), detail: `pid ${child.pid} — \`${line}\`` };
+    },
+
+    stop(entry) {
+      // The template is the user's own statement of how their orchestrator kills a lead. Prefer it:
+      // it addresses the lead by NAME, which still works after the spawned pid has forked away.
+      if (stop) {
+        const line = renderTemplate(stop, execVars({ ...entry, agent: entry.agent }));
+        try {
+          execFileSync('sh', ['-c', line], { stdio: ['ignore', 'pipe', 'pipe'] });
+          return 'stopped';
+        } catch {
+          return 'unknown';
+        }
+      }
+
+      const pid = Number(entry.ref);
+      if (!alive(pid)) return 'already-gone';
+
+      // Negative pid = the whole process group. The lead is a tree — the agent, and the `crux tail`
+      // it spawned — and killing only the shell would orphan the tail, which is the one thing that
+      // must not survive: an orphaned tail keeps consuming the stream with nobody to act on it.
+      try {
+        process.kill(-pid, 'SIGTERM');
+        return 'stopped';
+      } catch {
+        try {
+          process.kill(pid, 'SIGTERM');
+          return 'stopped';
+        } catch {
+          return 'unknown';
+        }
+      }
+    },
+
+    /**
+     * exec has no registry of its own — there is nothing to ask. `sh -c` does not remember what it
+     * ran, so the only leads this backend can see are the ones crux recorded when it started them.
+     * That is an honest answer, and it is why `list()` is used for liveness and display and never
+     * for ownership.
+     *
+     * ## What `running` can honestly mean, which depends entirely on the template
+     *
+     * With a `stop` template the command FORKS — that is the whole reason `stop` exists — so the pid
+     * crux spawned is dead within the second while the lead lives on inside tmux (or systemd, or
+     * whatever). `alive(ref)` therefore answers a question nobody asked: it reports on a shell that
+     * exited, not on the lead. Believing it says "not running" about a lead that is, and the damage
+     * is not cosmetic — it is what `planUp` reads to decide whether the slug is already being
+     * brought up. Caught by running the real thing twice:
+     *
+     *     $ crux swarm up --project mercury-billing     # tmux session created, agent booting
+     *     $ crux swarm up --project mercury-billing     # ...ten seconds later
+     *     START mercury-billing   started   pid 56908 — `tmux new-session -d -s lead-mercury-billing …`
+     *     1 started
+     *
+     * Nothing was started. tmux refused the duplicate session name, crux never looked at the exit
+     * status, and reported success — the precise lie this fleet exists to destroy. And tmux is the
+     * only reason it was merely a lie: a template that does NOT enforce unique names (`nohup … &`)
+     * would have started a second real lead, two tails on one stream, racing the cursor.
+     *
+     * So when the lead is addressable by name, `running` means what it means for herdr, and for the
+     * same reason: crux started this lead and has no way to watch it die, so it says so. The states
+     * that follow are the honest ones — the process table still decides coverage, so a lead that is
+     * really up reads as `covered`, and one that died before it ever tailed goes `stalled` after the
+     * grace window ({@see ../lib/swarm.planUp}) with `crux swarm down --project <slug>` as the
+     * remedy, which works precisely because the name still names it. Loud, and recoverable.
+     *
+     * Without a `stop` template the pid IS the only handle there is (`addresses: 'pid'`), and then it
+     * is the truest thing available — so it is used.
+     */
+    list() {
+      return Object.entries(state)
+        .filter(([, entry]) => entry.backend === 'exec')
+        .map(([slug, entry]) => ({
+          slug,
+          ref: String(entry.ref),
+          running: stop ? true : alive(entry.ref),
+        }));
+    },
+  };
+}
+
+/** Sleep without yielding, so `ensureServer` can poll inside a synchronous adapter method. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** `herdr …`, session-scoped. Every socket verb accepts `--session`, so it prefixes all of them. */
+function herdrArgv(session, argv) {
+  return session ? ['--session', session, ...argv] : argv;
+}
+
+/** herdr answers an error as a JSON envelope on stdout AND exits 1, so a throw still carries it. */
+function herdrErrorFrom(raw) {
+  try {
+    const doc = JSON.parse(raw);
+    return doc?.error ? `${doc.error.message} (${doc.error.code})` : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `herdr <verb>` → its `result`, or null on any failure.
+ *
+ * The most common failure is the interesting one: with no server running, the socket file does not
+ * exist and herdr exits 1 with a raw `Os { code: 2, kind: NotFound }` on stderr — not JSON. That is
+ * not a crux bug to be surfaced, it is simply "there are no panes", so it collapses to null here and
+ * every caller reads it as "nothing is running". Mirrors soloTry.
+ */
+function herdrTry(session, argv) {
+  try {
+    const raw = execFileSync(process.env.CRUX_HERDR_BIN || 'herdr', herdrArgv(session, argv), {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const doc = JSON.parse(raw);
+    return doc.error ? null : (doc.result ?? null);
+  } catch {
+    return null;
+  }
+}
+
+/** `herdr <verb>` or throw. Starting a lead is load-bearing: if herdr cannot, we must not pretend. */
+function herdrRun(session, argv) {
+  let raw;
+  try {
+    raw = execFileSync(process.env.CRUX_HERDR_BIN || 'herdr', herdrArgv(session, argv), {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    const detail =
+      herdrErrorFrom(e.stdout) || String(e.stderr || e.message).split('\n')[0] || 'unknown error';
+    throw new Error(`could not run \`herdr ${argv.join(' ')}\`: ${detail}`);
+  }
+
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    throw new Error(`\`herdr ${argv.join(' ')}\` did not return JSON`);
+  }
+  if (doc.error) {
+    throw new Error(`\`herdr ${argv.join(' ')}\` failed: ${doc.error.message} (${doc.error.code})`);
+  }
+  return doc.result ?? {};
+}
+
+/**
+ * herdr — a terminal multiplexer built for coding agents (herdr.dev).
+ *
+ * A standing lead is exactly what herdr exists to host: a long-lived agent pane, in a repo, that
+ * survives detach and can be reattached over ssh. The mapping, against the REAL 0.7.3 CLI:
+ *
+ *   start → `herdr agent start <name> --cwd <repo> -- <argv…>`   (undocumented on the site, which
+ *           shows the workspace/tab/pane-split dance instead; this one verb does all of it — it
+ *           creates the workspace, the tab and the pane, names the agent, and execs argv in <repo>)
+ *   stop  → `herdr pane close <pane_id>`   — there is NO `herdr agent stop`/`kill`. That verb does
+ *           not exist; closing the agent's PANE is how you kill an agent, and it does really kill it
+ *           (the child process dies with the pane, verified).
+ *   list  → `herdr agent list` → {agents:[{name, pane_id, workspace_id, terminal_id, agent_status}]}
+ *
+ * ## Why the ref is the NAME, and not the pane id
+ *
+ * `pane close` only accepts a `pane_id` ("w2:p3") — it rejects a terminal id outright. The lazy
+ * adapter therefore records the pane id at start and closes it at stop. That is a bug waiting to
+ * happen, and it is the kind that kills the WRONG pane: a pane id is positional and mutable — `herdr
+ * pane move` re-homes a pane into another tab or workspace and its id changes with it, so a user who
+ * rearranges their herdr layout would have crux close whatever now sits at the id it wrote down.
+ *
+ * So the ref is the agent's NAME (`lead-<slug>`), which is crux's own, unique by construction (one
+ * lead per project), and which herdr itself addresses agents by. `stop()` RESOLVES that name to a
+ * pane id at the moment it stops — never holding a positional id across time. It costs one extra
+ * call and it is the difference between closing the lead and closing whatever the user just moved
+ * into its old slot.
+ *
+ * herdr enforces name uniqueness at its own layer (a second `agent start lead-alpha` is refused with
+ * `agent_name_taken` rather than quietly creating a twin), which makes the name a sound handle AND
+ * gives idempotence a second floor beneath crux's state file: even with the state file deleted, herdr
+ * will not let `swarm up` start a second lead on a slug it is already hosting.
+ *
+ * That is `addresses: 'handle'` in the honest sense — the name still names the lead long after the
+ * process crux spawned has gone.
+ *
+ * ## Liveness: the process table, still — and this backend is the one that had a real alternative
+ *
+ * herdr is the first backend with genuine agent-status awareness (idle / working / blocked), so the
+ * tempting move is to let it answer "is this lead healthy?" and skip the process table. It is the
+ * wrong move, and the reason is precise rather than dogmatic:
+ *
+ *   A HEALTHY standing lead is parked on `crux tail` — blocked on a socket, burning nothing, doing
+ *   nothing. herdr reports that as `idle`. A lead STUCK at Claude Code's folder-trust prompt is also
+ *   doing nothing, and herdr reports that as `idle` too. The two states that matter most — the lead
+ *   that is working perfectly and the lead that is dead on its feet — are INDISTINGUISHABLE under
+ *   herdr status. Meanwhile the process table separates them cleanly, because one of them is running
+ *   `crux tail --project <slug>` and the other never got there.
+ *
+ * herdr status is more convenient and less truthful, so coverage stays where it lives for every other
+ * backend: the OS process table {@see ../lib/leads}. herdr's status rides along as DETAIL — it is
+ * genuinely useful for a human reading `swarm status` ("blocked" is a real signal) — and never as the
+ * thing crux believes.
+ *
+ * And herdr's view is unreliable in a second, sharper way, found by restarting a real server rather
+ * than by reasoning about one: **herdr restores its panes when its server restarts, keeping the agent
+ * NAME, but not the command.** The restored pane comes back running a bare login shell. So an agent
+ * can sit in `agent list`, named `lead-crux`, looking for all the world like a lead, with the claude
+ * process that made it a lead long dead. herdr's own registry outlives the thing it describes. Any
+ * adapter that had trusted `agent list` to mean "running" — the obvious reading, and the one the
+ * website's framing invites — would report that zombie as a healthy lead forever.
+ *
+ * `running` here therefore means only what it can honestly mean: the pane EXISTS. Which is exactly
+ * the question the planner is really asking it, and the reason a zombie is safe:
+ *
+ *   - COVERAGE is not asked of this method at all, so a zombie can never read as green. The process
+ *     table sees no `crux tail --project <slug>`, and `planUp` reports the slug as `stalled` — alive,
+ *     never tailed, past the grace window — with `crux swarm down --project <slug>` as the remedy,
+ *     which closes the pane and lets the next `up` start a real lead. Loud, and recoverable.
+ *   - Reporting the zombie as NOT running would be worse, not better: crux would try to start a
+ *     second lead, and herdr would refuse it with `agent_name_taken` because the zombie still holds
+ *     the name. The swarm would wedge instead of self-describing.
+ *
+ * The same presence rule is what makes the folder-trust trap detectable — a lead frozen at that
+ * prompt is alive with no tail, which is precisely `planUp`'s `stalled` refusal, and it would be
+ * invisible if `idle` were allowed to mean "not running".
+ */
+function herdrBackend({ session = null } = {}) {
+  return {
+    name: 'herdr',
+    addresses: 'handle',
+
+    /** True when a herdr server is up for this session. The one verb that answers without a socket. */
+    serverUp() {
+      try {
+        const out = execFileSync(
+          process.env.CRUX_HERDR_BIN || 'herdr',
+          herdrArgv(session, ['status', 'server']),
+          { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+        );
+        return /^status:\s*running/m.test(out);
+      } catch {
+        return false;
+      }
+    },
+
+    /**
+     * A herdr socket verb against no server is not an error worth reporting, it is a server that has
+     * not been started — so start one, exactly as the solo backend creates a missing project rather
+     * than refusing. Detached, because the swarm has to outlive the `crux swarm up` that made it.
+     */
+    ensureServer() {
+      if (this.serverUp()) return false;
+
+      const child = spawnChild(
+        process.env.CRUX_HERDR_BIN || 'herdr',
+        herdrArgv(session, ['server']),
+        { detached: true, stdio: 'ignore' },
+      );
+      child.unref();
+
+      // The server binds its socket a beat after exec. Poll rather than sleep-and-hope: a lead
+      // started against a socket that is not listening yet fails for a reason nobody could diagnose.
+      for (let i = 0; i < 50; i++) {
+        if (this.serverUp()) return true;
+        sleepSync(200);
+      }
+
+      throw new Error(
+        'started `herdr server` but it never began listening on its socket. Run `herdr status` to ' +
+          'see what it is doing.',
+      );
+    },
+
+    /**
+     * argv, not a shell line — and that is a real gain over `exec`, not a detail. `herdr agent start`
+     * execs its argv directly, so there is no shell to quote for: the apostrophe that `execVars`
+     * has to REFUSE (it would break out of the single-quoted `{command}` in the tmux template) is
+     * simply a character here. Same claude invocation as every other backend, minus the quoting trap.
+     */
+    argvFor(lead) {
+      const agent = String(lead.agent || DEFAULT_AGENT).trim();
+      return [...agent.split(/\s+/), '-n', leadName(lead.slug), lead.prompt];
+    },
+
+    start(lead) {
+      const created = this.ensureServer();
+      const name = leadName(lead.slug);
+
+      // --no-focus: `swarm up` starting eight leads must not yank the user's herdr focus eight times.
+      const data = herdrRun(session, [
+        'agent',
+        'start',
+        name,
+        '--cwd',
+        lead.repo,
+        '--no-focus',
+        '--',
+        ...this.argvFor(lead),
+      ]);
+
+      const agent = data?.agent;
+      if (!agent?.name) {
+        throw new Error(`herdr started the lead for "${lead.slug}" but reported no agent`);
+      }
+
+      return {
+        ref: agent.name,
+        detail:
+          `herdr agent ${agent.name} in pane ${agent.pane_id} (workspace ${agent.workspace_id})` +
+          `${created ? ' — herdr server started' : ''}` +
+          `${session ? ` — session ${session}` : ''}`,
+      };
+    },
+
+    /**
+     * Resolve the name to a pane id NOW, then close that pane — never the pane id crux wrote down at
+     * start. See the header: pane ids move, and a stale one closes a stranger's pane. There is no
+     * `herdr agent stop`; closing the agent's pane is how herdr kills an agent, and it does kill it.
+     */
+    stop(entry) {
+      const agents = this.agents();
+
+      if (agents === null) {
+        // Could not ask herdr at all. If its server is down, the lead is genuinely gone — herdr
+        // reaps every agent process when its server stops, so there is nothing left to kill and
+        // `already-gone` is a fact. But if the server is UP and the query still failed, we do not
+        // know what happened, and a stop crux did not make must never be reported as one.
+        return this.serverUp() ? 'unknown' : 'already-gone';
+      }
+
+      const found = agents.find((a) => a.name === String(entry.ref));
+      if (!found) return 'already-gone';
+
+      const closed = herdrTry(session, ['pane', 'close', found.pane_id]);
+      return closed === null ? 'unknown' : 'stopped';
+    },
+
+    /** Every agent herdr can see, or null when there is no server to ask. */
+    agents() {
+      const data = herdrTry(session, ['agent', 'list']);
+      if (data === null) return null;
+      return Array.isArray(data.agents) ? data.agents : [];
+    },
+
+    list() {
+      return (this.agents() ?? [])
+        .filter((a) => typeof a.name === 'string' && a.name.startsWith('lead-'))
+        .map((a) => ({
+          slug: a.name.slice('lead-'.length),
+          ref: a.name,
+          // Presence, and deliberately NOT `a.agent_status`. A healthy lead parked on `crux tail` is
+          // `idle` — parking IS doing nothing — and so is a lead frozen at a folder-trust prompt, so
+          // status cannot separate the two states that matter most. Presence is also all herdr can
+          // honestly support: a pane restored across a server restart keeps this name while running
+          // a bare shell. Coverage comes from the process table either way, so a zombie surfaces as
+          // `stalled` rather than as green. See the header.
+          running: true,
+          status: a.agent_status ?? 'unknown',
+          pane: a.pane_id,
+        }));
+    },
+  };
+}
+
+/**
+ * Build the backend named in config.
+ *
+ * An unknown name is refused with the list of what exists.
+ */
+function makeBackend(name, { config = {}, state = {} } = {}) {
+  if (name === 'solo') return soloBackend(config.solo || {});
+  if (name === 'exec') return execBackend({ ...(config.exec || {}), state });
+  if (name === 'herdr') return herdrBackend(config.herdr || {});
+
+  throw new Error(`unknown backend "${name}" (available: solo, exec, herdr)`);
+}
+
+module.exports = {
+  DEFAULT_AGENT_TOOL_ID,
+  execBackend,
+  herdrBackend,
+  makeBackend,
+  soloBackend,
+  soloProcesses,
+};