@coulb/crux-cli 0.1.0

package/crux.js

@@ -0,0 +1,2697 @@
+#!/usr/bin/env node
+/**
+ * crux — push items, report activity, and read the Crux feed from any agent.
+ *
+ * Usage:
+ *   crux push [--project <slug>] [--source <s>] "<text>"
+ *   crux push [--project <slug>] [--source <s>] < text-on-stdin
+ *   crux activity [--project <slug>] [--item <id>] [--actor <name>] [--type <t>]
+ *                 [--image <path>]… [--notify] "<text>"
+ *   crux decide < decision.json         # pipe a Decision (or array) to the decisions API
+ *   crux feed [--project <slug>] [--status <s>] [--limit <n>] [--json]
+ *   crux next [--claim] [--source <s>] [--project <slug>] [--actor <name>]
+ *   crux tail [--unrouted | --project <slug>] [--topics <t,…>] [--interval <s>] [--since <ts>]
+ *   crux route <id> --project <slug> [--actor <name>] [--note "<why>"]
+ *   crux done <id> [--note "<why>"] [--actor <name>]     # also stops the thread's agent
+ *   crux spawn <id> --project-id <n> [--brief "<t>"] [--wait] [--live]
+ *   crux projects [--json]
+ *   crux leads [--fix] [--json]          # reconcile the Solo lead fleet against running tails
+ *
+ * `crux next` drains the `unmatched` queue, oldest first, and prints ONE item as JSON.
+ * It exits 3 when the queue is empty, so a polling loop needs no jq:
+ *
+ *   crux next --claim --source capture --actor god-agent || exit 0   # nothing to do
+ *
+ * `--claim` takes an exclusive lease first (POST /api/items/{id}/claim), so overlapping
+ * pollers can't both act on the same capture. Prefer `--source capture` for consumers with
+ * local side effects: it restricts them to human-typed input from behind the web login.
+ *
+ * Auth/config resolution order:
+ *   1. env CRUX_API_URL / CRUX_API_TOKEN
+ *   2. ~/.config/crux/config.json  { "url": "...", "token": "..." }
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { randomUUID } = require('crypto');
+const { execFileSync, spawn: spawnChild } = require('child_process');
+const discoverLib = require('./lib/discover');
+const leadsLib = require('./lib/leads');
+const swarmLib = require('./lib/swarm');
+const orchestrator = require('./lib/orchestrator');
+const swarmState = require('./lib/swarm-state');
+const backends = require('./lib/backends');
+const { CURSOR_FILE, cursorKey, readCursors, saveCursor } = require('./lib/cursor');
+const { writeTombstone, takeTombstone } = require('./lib/cancel');
+const {
+  SOLO_TERMINAL,
+  spawnArgs,
+  threadName,
+  latestSessionId,
+  remoteControlUrl,
+  resultJson,
+  workerReport,
+  workerBrief,
+  soloTry,
+  soloStatus,
+  stopSoloProcess,
+} = require('./lib/spawn');
+
+/** Distinct from 1 (usage/transport error) so a poller can tell "empty" from "broken". */
+const EXIT_EMPTY = 3;
+
+function fail(msg) {
+  console.error(`crux: ${msg}`);
+  process.exit(1);
+}
+
+/**
+ * Flags that never take a value. Without this set, the next non-`--` token is read as the flag's
+ * value — so `crux activity --notify "shipped it"` would post an activity with NO description and
+ * a `notify` of "shipped it". The text a command exists to send must not be swallowable by a
+ * boolean sitting in front of it. Boolean-ness is a property of the flag NAME, and no name here
+ * takes a value in any other command, so one set covers the whole CLI.
+ */
+const BOOLEAN_FLAGS = new Set([
+  'yes',
+  'notify',
+  'claim',
+  'drop',
+  'json',
+  'fix',
+  'dry-run',
+  'unrouted',
+  'help',
+  'no-remote-control',
+  'live',
+  'wait',
+  'reopen',
+]);
+
+/**
+ * The statuses that mean the thread is CLOSED — mirroring Item::TERMINAL_STATUSES on the server.
+ *
+ * The live-work verbs refuse a thread in one of these (`crux accept`, `crux spawn`, `crux need`),
+ * because work on a closed thread is work nobody is watching: the board says finished, and the report
+ * lands where no one is looking. The refusals that matter are the server's — a guard only in the CLI
+ * is a guard a script walks around — but `crux spawn` checks here as well, because by the time the
+ * server could say no, the worker is already running.
+ */
+const CLOSED_STATUSES = ['done', 'dropped'];
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const next = argv[i + 1];
+      const takesValue = !BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith('--');
+      const value = takesValue ? argv[++i] : true;
+      // A repeated flag accumulates into an array — `--option A --option B` → ['A','B'] — which is
+      // how `crux need` collects a decide block's options. A flag given once stays a scalar, so
+      // every existing `typeof args.x === 'string'` check is unaffected.
+      if (Object.hasOwn(args, key)) {
+        args[key] = Array.isArray(args[key]) ? [...args[key], value] : [args[key], value];
+      } else {
+        args[key] = value;
+      }
+    } else {
+      args._.push(argv[i]);
+    }
+  }
+  return args;
+}
+
+function config() {
+  let url = process.env.CRUX_API_URL;
+  let token = process.env.CRUX_API_TOKEN;
+  if (!url || !token) {
+    const file = path.join(os.homedir(), '.config', 'crux', 'config.json');
+    if (fs.existsSync(file)) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+        url = url || cfg.url;
+        token = token || cfg.token;
+      } catch {
+        fail(`could not parse ${file}`);
+      }
+    }
+  }
+  if (!url) fail('no server URL — set CRUX_API_URL or ~/.config/crux/config.json');
+  if (!token) fail('no API token — set CRUX_API_TOKEN or ~/.config/crux/config.json');
+  return { url: url.replace(/\/$/, ''), token };
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** Raw request. Returns the status alongside the body so callers can handle 409 themselves. */
+async function request(method, endpoint, body, extraHeaders) {
+  const { url, token } = config();
+  const res = await fetch(`${url}${endpoint}`, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${token}`,
+      ...extraHeaders,
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  return { ok: res.ok, status: res.status, json, text };
+}
+
+/**
+ * Render a failed response as something an agent can act on.
+ *
+ * A 422 carries `errors: {field: [msg, …]}` alongside `message`, but `message` is only ever the
+ * *first* failure — the rest collapse into "(and 2 more errors)". Enumerating the map is the
+ * difference between a bare status line and knowing which field to shorten. `message` itself is
+ * redundant once the fields are listed, so it's dropped rather than printed twice.
+ */
+function describeError(status, json, text) {
+  if (json && json.errors && typeof json.errors === 'object') {
+    const lines = Object.entries(json.errors).flatMap(([field, msgs]) =>
+      (Array.isArray(msgs) ? msgs : [msgs]).map((m) => `  ${field}: ${m}`),
+    );
+    if (lines.length) return `${status}:\n${lines.join('\n')}`;
+  }
+  if (json && json.message) return `${status}: ${json.message}`;
+  return `${status}: ${text.slice(0, 500)}`;
+}
+
+/** Request that treats any non-2xx as fatal. */
+async function api(method, endpoint, body) {
+  const { ok, status, json, text } = await request(method, endpoint, body);
+  if (!ok) fail(`server returned ${describeError(status, json, text)}`);
+  return json;
+}
+
+// Text argument comes from the positional args, else stdin.
+function textArg(args, startIndex) {
+  const positional = args._.slice(startIndex).join(' ').trim();
+  if (positional) return positional;
+  const piped = readStdin().trim();
+  if (piped) return piped;
+  return null;
+}
+
+async function push(args) {
+  const content = textArg(args, 1);
+  if (!content) fail(usageFor('push'));
+
+  const payload = { content };
+  if (typeof args.project === 'string') payload.project = args.project;
+  if (typeof args.source === 'string') payload.source = args.source;
+
+  const item = await api('POST', '/api/items', payload);
+  const proj = item.project ? item.project.slug : item.status;
+  const reason = item.meta && item.meta.reason ? ` — ${item.meta.reason}` : '';
+  console.log(`pushed item #${item.id} → ${proj}${reason}`);
+}
+
+/**
+ * Read `--item <id>`, the link that turns a loose activity into a message on an item's thread.
+ *
+ * Validated here rather than trusted, because `parseArgs` yields the boolean `true` for a
+ * valueless flag and a raw string otherwise. Both would serialise to a JSON `item_id` the API
+ * rejects — but a silent `undefined` would be worse: the activity would post *unlinked*, which
+ * is precisely the failure that made 66 of 70 existing lead answers invisible. An unusable
+ * `--item` must stop the write, not quietly drop the thread.
+ */
+function itemIdArg(raw, command = 'activity') {
+  if (typeof raw !== 'string' || !/^\d+$/.test(raw)) fail(usageFor(command));
+  const id = Number.parseInt(raw, 10);
+  if (id < 1) fail(usageFor(command));
+  return id;
+}
+
+/**
+ * The image formats the API will accept, keyed by extension. Mirrors ActivityImage::ALLOWED_MIMES —
+ * raster only, and deliberately no SVG (an SVG is a document that can carry script). The server
+ * sniffs the real bytes with finfo rather than trusting what we declare here, so this map is not a
+ * security boundary; it exists so a wrong path fails on *this* side of the network with a sentence
+ * that names the problem, instead of coming back as a 422 about mimetypes.
+ */
+const IMAGE_MIMES = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+/** ActivityImage::MAX_KILOBYTES. Rejected outright over this — never truncated. */
+const MAX_IMAGE_BYTES = 10240 * 1024;
+
+/**
+ * Resolve `--image <path>` (repeatable) into a list of files ready to upload.
+ *
+ * Every check that can be made locally is made here, and it is deliberately called *before* the
+ * activity is posted. Uploading an image needs an activity id, so the write has to come first — which
+ * means a typo'd path discovered afterwards would leave a posted, permanently image-less activity on
+ * the thread, and no way to attach to it retroactively. Validating up front turns the overwhelmingly
+ * common failure (wrong path, wrong format, too big) into a clean exit that has written nothing.
+ */
+function imageArgs(raw) {
+  if (raw === undefined) return [];
+
+  const paths = Array.isArray(raw) ? raw : [raw];
+
+  return paths.map((p) => {
+    // `--image` with no value parses to `true`, which would otherwise stringify into a nonsense path.
+    if (typeof p !== 'string') fail('--image needs a path to an image file');
+
+    const file = path.resolve(p);
+    if (!fs.existsSync(file)) fail(`no such image: ${p}`);
+
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) fail(`not a file: ${p}`);
+    if (stat.size > MAX_IMAGE_BYTES) {
+      fail(`image too large: ${p} is ${Math.round(stat.size / 1024)}KB, limit is ${MAX_IMAGE_BYTES / 1024}KB`);
+    }
+
+    const mime = IMAGE_MIMES[path.extname(file).toLowerCase()];
+    if (!mime) fail(`unsupported image type: ${p} (accepts ${Object.keys(IMAGE_MIMES).join(', ')})`);
+
+    return { file, mime, name: path.basename(file) };
+  });
+}
+
+/**
+ * POST one image onto an activity — the same multipart endpoint, and the same `file` field, the phone
+ * uses when you attach a photo to a reply.
+ *
+ * Content-Type is conspicuously *not* set: fetch derives it from the FormData, and the multipart
+ * boundary it generates is part of that header. Setting it by hand produces a body the server cannot
+ * parse. `request()` is no use here for the same reason — it hard-codes a JSON content type.
+ */
+async function uploadActivityImage(activityId, image) {
+  const { url, token } = config();
+
+  const form = new FormData();
+  form.append('file', new Blob([fs.readFileSync(image.file)], { type: image.mime }), image.name);
+
+  const res = await fetch(`${url}/api/activities/${activityId}/images`, {
+    method: 'POST',
+    headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    let json;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      json = null;
+    }
+    throw new Error(describeError(res.status, json, text));
+  }
+}
+
+/**
+ * crux activity [--project <slug>] [--item <id>] [--actor <n>] [--type <t>] [--image <path>]…
+ *               [--notify] "<text>"
+ *
+ * `--notify` pushes this one activity to your phone. It is how a lead hands over the thing you
+ * asked for mid-thread — NOT how it says it is blocked. A block is `crux need`, and diluting that
+ * would wreck the escalations view. Without the flag the write is silent, exactly as before.
+ */
+async function activity(args) {
+  const description = textArg(args, 1);
+  if (!description) fail(usageFor('activity'));
+
+  // Before the write, so a bad path costs nothing. See imageArgs().
+  const images = imageArgs(args.image);
+
+  const payload = { description };
+  if (typeof args.project === 'string') payload.project = args.project;
+  if (typeof args.actor === 'string') payload.actor = args.actor;
+  if (typeof args.type === 'string') payload.type = args.type;
+  if (args.item !== undefined) payload.item_id = itemIdArg(args.item);
+  if (args.notify) payload.notify = true;
+  // The status line rides the report the lead was already writing — that is the entire design. The
+  // API refuses `--status` without `--item` (a status line belongs to a thread, not to a project).
+  if (typeof args.status === 'string') payload.status_line = args.status;
+
+  const a = await api('POST', '/api/activities', payload);
+  const onItem = a.item_id ? ` on item #${a.item_id}` : '';
+  console.log(`logged activity #${a.id} (${a.actor}: ${a.type})${onItem}${args.notify ? ' — pushed' : ''}`);
+
+  if (images.length === 0) return;
+
+  /*
+   * Serially, and never fatally. The activity is already on the thread and we have already said so —
+   * an image that fails to upload must not be reported as if the message itself were lost, because
+   * the agent's correct response to that would be to post it again. So each failure names itself and
+   * the run exits non-zero, but what was written stays written and what did upload is still reported.
+   */
+  let attached = 0;
+  const failures = [];
+
+  for (const image of images) {
+    try {
+      await uploadActivityImage(a.id, image);
+      attached++;
+    } catch (error) {
+      failures.push(`${image.name}: ${error.message}`);
+    }
+  }
+
+  if (attached > 0) {
+    console.log(`attached ${attached} ${attached === 1 ? 'image' : 'images'}`);
+  }
+
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(`crux: image failed — ${failure}`);
+    console.error(`crux: activity #${a.id} was logged; ${failures.length} of ${images.length} images did not attach`);
+    process.exit(1);
+  }
+}
+
+async function decide() {
+  const raw = readStdin().trim();
+  if (!raw) fail('crux decide reads a Decision JSON (or array) on stdin');
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    fail('stdin is not valid JSON');
+  }
+  const decisions = Array.isArray(doc) ? doc : [doc];
+  for (const d of decisions) {
+    const saved = await api('POST', '/api/decisions', d);
+    console.log(`decision ${saved.id} (${saved.status})`);
+  }
+}
+
+async function feed(args) {
+  const params = new URLSearchParams();
+  if (typeof args.project === 'string') params.set('project', args.project);
+  if (typeof args.status === 'string') params.set('status', args.status);
+  if (typeof args.limit === 'string') params.set('limit', args.limit);
+  const qs = params.toString();
+  const items = await api('GET', `/api/items${qs ? `?${qs}` : ''}`);
+
+  if (args.json) {
+    console.log(JSON.stringify(items, null, 2));
+    return;
+  }
+  if (!items.length) {
+    console.log('(no items)');
+    return;
+  }
+  for (const item of items) {
+    const proj = item.project ? item.project.slug : item.status;
+    const when = item.created_at ? new Date(item.created_at).toLocaleString() : '';
+    const oneLine = item.content.replace(/\s+/g, ' ').slice(0, 80);
+    console.log(`#${item.id}  [${proj}]  ${oneLine}${item.content.length > 80 ? '…' : ''}  ${when}`);
+  }
+}
+
+/**
+ * crux next [--claim] [--source <s>] [--project <slug>] [--actor <name>]
+ *
+ * Prints exactly one unmatched item as JSON, oldest first (FIFO — drain the
+ * longest-waiting capture, not the newest). Exits EXIT_EMPTY when the queue is
+ * empty, so a poller is just:
+ *
+ *   while :; do crux next --claim --source capture --actor god-agent | handle; sleep 30; done
+ *
+ * With --claim the item is leased via POST /api/items/{id}/claim before printing, so two
+ * overlapping pollers never both act on it. A 409 means someone else won the race — we
+ * simply move on to the next candidate rather than failing.
+ */
+async function next(args) {
+  const params = new URLSearchParams({ status: 'unmatched', order: 'oldest' });
+  if (typeof args.source === 'string') params.set('source', args.source);
+  if (typeof args.project === 'string') params.set('project', args.project);
+  // Without --claim we only need the head; with it, keep spares to survive lost races.
+  params.set('limit', args.claim ? '10' : '1');
+
+  const items = await api('GET', `/api/items?${params}`);
+
+  if (!items.length) process.exit(EXIT_EMPTY);
+
+  if (!args.claim) {
+    console.log(JSON.stringify(items[0], null, 2));
+    return;
+  }
+
+  const actor = typeof args.actor === 'string' ? args.actor : 'consumer';
+
+  for (const candidate of items) {
+    const res = await request('POST', `/api/items/${candidate.id}/claim`, { actor });
+
+    if (res.ok) {
+      console.log(JSON.stringify(res.json, null, 2));
+      return;
+    }
+    if (res.status !== 409) {
+      fail(`server returned ${describeError(res.status, res.json, res.text)}`);
+    }
+    // 409 — another consumer got there first. Try the next one.
+  }
+
+  // Everything we saw was claimed out from under us: the queue is effectively empty.
+  process.exit(EXIT_EMPTY);
+}
+
+/**
+ * crux route <id> --project <slug> [--actor <name>] [--note "<why>"]
+ *
+ * Triage verb: reassign an item to a project and re-enter the routed flow.
+ */
+async function route(args) {
+  const id = args._[1];
+  if (!id || typeof args.project !== 'string') fail(usageFor('route'));
+
+  const payload = { project: args.project };
+  if (typeof args.actor === 'string') payload.actor = args.actor;
+  if (typeof args.note === 'string') payload.note = args.note;
+
+  const item = await api('PATCH', `/api/items/${encodeURIComponent(id)}/route`, payload);
+  console.log(`routed item #${item.id} → ${item.project ? item.project.slug : '(none)'}`);
+}
+
+/**
+ * crux done <id> [--note "<why>"] [--actor <name>] [--drop]
+ *
+ * Triage verb: close an item. `--drop` records it as `dropped` rather than `done` —
+ * same terminal state to the queue, different meaning to whoever reads the feed later.
+ *
+ * Closing a thread also REAPS its agent. A headless worker has already exited by the time anyone
+ * runs this (its exit is what produced the report on the thread), but a `--live` one never exits on
+ * its own — and seven of them were found idling against threads that had been closed hours earlier,
+ * two still holding instructions nobody sent. An agent's life is bounded by its thread's, not by a
+ * human noticing, so the close is what kills it.
+ *
+ * Best-effort, and deliberately after the close: a thread whose process is already gone (or whose
+ * Solo is not there to ask) still closes cleanly. Reaping a corpse is a no-op, not an error.
+ */
+async function done(args) {
+  const id = args._[1];
+  if (!id) fail(usageFor('done'));
+
+  // Two different things called "status", and they must not be confused. The payload's `status` is the
+  // DISPOSITION (done | dropped) and comes from `--drop`. `--status` is the human status LINE, and it
+  // maps to `status_line` — here it is the thread's RESTING phrase ("merged, closed"), because a closed
+  // thread should say something true about being closed rather than keep announcing work that stopped.
+  // Omit it and the server writes the disposition itself; it never leaves the old line standing.
+  const payload = { status: args.drop ? 'dropped' : 'done' };
+  if (typeof args.note === 'string') payload.note = args.note;
+  if (typeof args.actor === 'string') payload.actor = args.actor;
+  if (typeof args.status === 'string') payload.status_line = args.status;
+
+  const item = await api('PATCH', `/api/items/${encodeURIComponent(id)}`, payload);
+  console.log(`item #${item.id} → ${item.status}`);
+
+  const procId = item.agent_process_id;
+  if (procId === null || procId === undefined) return;
+
+  const outcome = stopSoloProcess(procId);
+  if (outcome === 'stopped') console.log(`stopped its agent (Solo process ${procId})`);
+  else if (outcome === 'already-gone') console.log(`its agent (Solo process ${procId}) had already exited`);
+  else console.error(`crux: could not reach Solo to stop process ${procId} — check it by hand`);
+}
+
+/**
+ * crux cancel <id> [--note "<why>"] [--actor <name>] [--process <n>]
+ *
+ * Stop a thread's worker ON PURPOSE, and have that not look like a crash.
+ *
+ * The thread stays open — this is the verb for "the brief is now wrong": you change your mind
+ * mid-flight, the lead stops the worker, re-briefs, and spawns a new one. `crux done` is the other
+ * thing (the thread is finished, and its worker dies with it).
+ *
+ * A lead used to do this with `solo processes stop`, and the supervisor — which cannot see intent,
+ * only an ended process with an empty buffer — posted "**Worker failed** … it crashed, was killed,
+ * or never started" and pushed it to your phone. Nothing had failed. Every mid-flight re-brief
+ * did it, and a crash note that cries wolf is worse than none, because the real ones stop being read.
+ *
+ * So the kill leaves a note. The ORDER below is the whole mechanism and is not incidental:
+ *
+ *   1. TOMBSTONE, first, and fatally if it fails {@see ../lib/cancel}. The supervisor polls every 5s;
+ *      a tombstone written after the kill loses that race often enough to report a crash anyway. And
+ *      a kill whose tombstone never landed is a kill that WILL be reported as a crash — so if we
+ *      cannot write it, we stop here, having killed nothing, rather than proceed and lie about why.
+ *   2. STOP the process. The supervisor is already awake; it sees the exit, finds the tombstone, and
+ *      reports a cancellation instead of a death {@see workerReport}.
+ *   3. NOTE on the thread, plainly, with no push. Someone reading the thread later needs to know why
+ *      the worker stopped mid-sentence — but a deliberate act by a lead is not an escalation, and
+ *      putting it on your phone is the noise this ticket exists to remove.
+ */
+async function cancel(args) {
+  const id = args._[1];
+  if (!id) fail(usageFor('cancel'));
+
+  const itemId = itemIdArg(String(id), 'cancel');
+  const item = await api('GET', `/api/items/${itemId}`);
+
+  // `--process` is the escape hatch for a worker the item never recorded (a hand-spawned agent, an
+  // item whose accept never landed). Without either, there is nothing to cancel and nothing to
+  // excuse — and writing a tombstone for a process we cannot name would be a tombstone that excuses
+  // nobody, which is worse than a clean refusal.
+  const procId =
+    typeof args.process === 'string' ? args.process : (item.agent_process_id ?? null);
+  if (procId === null || procId === undefined) {
+    fail(`item #${itemId} has no agent process recorded — pass --process <n> if you know it`);
+  }
+
+  const note = typeof args.note === 'string' ? args.note : null;
+  const actor = typeof args.actor === 'string' ? args.actor : 'lead';
+
+  // Before the kill. Fatal if it fails — see above.
+  try {
+    writeTombstone({ item: itemId, process: procId, note, actor });
+  } catch (e) {
+    fail(`could not record the cancellation (${e.message}) — refusing to kill the worker, because ` +
+      'its supervisor would then report a crash that did not happen');
+  }
+
+  const outcome = stopSoloProcess(procId);
+  if (outcome === 'stopped') console.log(`cancelled the worker on thread #${itemId} (Solo process ${procId})`);
+  else if (outcome === 'already-gone') console.log(`its worker (Solo process ${procId}) had already exited`);
+  else console.error(`crux: could not reach Solo to stop process ${procId} — check it by hand`);
+
+  await api('POST', '/api/activities', {
+    item_id: itemId,
+    actor,
+    type: 'note',
+    description: `worker cancelled by lead: ${note ?? 'no reason given'}`,
+  });
+  console.log(`noted the cancellation on thread #${itemId}`);
+}
+
+const NEED_KINDS = ['decide', 'answer', 'secret', 'desk', 'world'];
+
+/**
+ * crux need --item <id> --kind decide|answer|secret|desk|world [flags] ["<question>"]
+ *
+ * Raise a needs-you block: the typed successor to the raw "NEEDS YOU: …" activity that the
+ * escalations view never rendered. A block is what makes a thread WAIT on you, so this IS the
+ * escalation verb — an open block is an escalation, no separate table to fall out of sync.
+ *
+ * The forcing function lives server-side and is surfaced here: a `decide` block needs `--option`s;
+ * every other kind needs a one-line framed question (positional text or stdin). A block may not
+ * wait on raw dumped context.
+ *
+ *   crux need --item 8 --kind decide --option Hourly --option "Twice daily" --recommendation "Twice daily"
+ *   crux need --item 8 --kind answer "What does 'term' mean for recurring subs?"
+ *   crux need --item 8 --kind secret "Slack app token (xapp-…)" --who an-agent
+ */
+async function need(args) {
+  const itemId = itemIdArg(args.item, 'need');
+  const kind = typeof args.kind === 'string' ? args.kind : null;
+  if (kind === null || !NEED_KINDS.includes(kind)) fail(usageFor('need'));
+
+  const payload = { kind };
+
+  const question = textArg(args, 1);
+  if (question) payload.question = question;
+  // --option is repeatable; a single one arrives as a scalar, several as an array.
+  if (args.option !== undefined) {
+    payload.options = Array.isArray(args.option) ? args.option : [args.option];
+  }
+  if (typeof args.recommendation === 'string') payload.recommendation = args.recommendation;
+  if (typeof args.where === 'string') payload.location = args.where; // phone-ok | desk-required
+  if (typeof args.when === 'string') payload.timing = args.when; // now | at-time | when-at-desk
+  if (typeof args.who === 'string') payload.waiting_on = args.who; // nobody | an-agent | an-external-person
+  if (typeof args.actor === 'string') payload.actor = args.actor;
+  // Blocking IS a status change: the thread just stopped, and the row should say so in the same breath.
+  if (typeof args.status === 'string') payload.status_line = args.status;
+
+  const item = await api('POST', `/api/items/${itemId}/needs`, payload);
+  const raised = item.open_need ? item.open_need.kind : kind;
+  console.log(`raised ${raised} block on item #${item.id} — now ${item.state}`);
+}
+
+/**
+ * crux accept <id> [--title "<short title>"] [--status "<phrase>"] [--actor <name>]
+ *                  [--agent-name <n>] [--agent-session-id <id>]
+ *
+ * Mark a thread accepted: who picked it up and when. With no open needs-you block that is what
+ * makes the thread read "working", and `accepted_at` powers the app's "time since pickup".
+ *
+ * `--title` is where a thread gets its NAME, and accept is the right moment for it: the lead has just
+ * read the thread and is about to work it, so it knows the answer already. Nothing on the server
+ * generates a title — a lead that never passes `--title` leaves the thread untitled forever, and the
+ * row goes on showing the captured text exactly as it does today. Keep it to a couple of words; it is
+ * a name, not a summary, and the row clips it to one line.
+ *
+ * `--agent-name` bakes the per-thread Claude session name spawned with `claude -n`; `--agent-session-id`
+ * stores the agent's local transcript uuid; `--remote-control-url` stores its claude.ai session — the
+ * one that is actually openable, and the one the thread view links to. `crux done` clears acceptance.
+ *
+ * A CLOSED thread (done | dropped) refuses to be accepted, and `--reopen` is how you mean it anyway.
+ * The server enforces both — see ItemController::accept — so this is not a CLI-side courtesy that a
+ * script can route around; the flag only carries the intent down.
+ */
+async function accept(args) {
+  const id = args._[1];
+  if (!id) fail(usageFor('accept'));
+
+  const payload = {};
+  if (args.reopen === true) payload.reopen = true;
+  if (typeof args.actor === 'string') payload.actor = args.actor;
+  if (typeof args['agent-name'] === 'string') payload.agent_name = args['agent-name'];
+  if (typeof args['agent-session-id'] === 'string') payload.agent_session_id = args['agent-session-id'];
+  if (typeof args['remote-control-url'] === 'string') {
+    payload.remote_control_url = args['remote-control-url'];
+  }
+  if (typeof args.title === 'string') payload.title = args.title;
+  if (typeof args.status === 'string') payload.status_line = args.status;
+
+  const item = await api('POST', `/api/items/${encodeURIComponent(id)}/accept`, payload);
+  // `reopened_from` is only on the payload when the thread really was closed — so a `--reopen` on an
+  // already-open thread says nothing, rather than announcing a resurrection that never happened.
+  if (item.reopened_from) {
+    console.log(`reopened item #${item.id} — it was ${item.reopened_from}, and is now ${item.status}`);
+  }
+  const by = item.accepted_by ? ` by ${item.accepted_by}` : '';
+  console.log(`accepted item #${item.id}${by} — now ${item.state}`);
+}
+
+/** How long `crux spawn` waits for the agent to register with claude.ai before giving up on a link. */
+const RC_TIMEOUT_MS = 90_000;
+const RC_POLL_MS = 1_500;
+
+/**
+ * Wait for a just-spawned agent to announce its Remote Control session, and return the URL.
+ *
+ * Remote Control connects a few seconds AFTER the process starts (it has to reach claude.ai), and it
+ * announces itself exactly once, as a toast drawn into the TUI — so there is nothing to look up and
+ * nothing on disk to read. We poll the agent's raw pty buffer until the toast shows up.
+ *
+ * Best-effort by contract: an agent with no claude.ai OAuth, or a Solo that will not cough up its
+ * buffer, means the thread has no link — never that the spawn failed. Returns null on timeout.
+ */
+async function waitForRemoteControlUrl(procId, timeoutMs = RC_TIMEOUT_MS) {
+  if (procId === undefined || procId === null) return null;
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    let raw = null;
+    try {
+      raw = execFileSync(
+        process.env.CRUX_SOLO_BIN || 'solo',
+        ['processes', 'output', String(procId), '--raw', '--lines', '2000', '--json'],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }
+      );
+    } catch {
+      // The process may not have a buffer yet. Keep waiting rather than treating this as terminal.
+    }
+
+    if (raw) {
+      let text = null;
+      try {
+        text = JSON.parse(raw)?.data?.text ?? null;
+      } catch {
+        text = null;
+      }
+      const url = remoteControlUrl(text);
+      if (url) return url;
+    }
+
+    await sleep(RC_POLL_MS);
+  }
+  return null;
+}
+
+/**
+ * crux spawn <id> --project-id <n> [--tool-id 3] [--brief "<text>"] [--actor <name>] [--wait]
+ *                 [--live [--no-remote-control] [--rc-timeout <seconds>]]
+ *
+ * Start the worker for a thread — and make sure it REPORTS and DIES, neither of which is left to the
+ * agent to remember. Two modes; reaping is structural in both, but bound to a different event.
+ *
+ * HEADLESS (default). `claude -p --output-format json` works the thread, prints one json object, and
+ * exits. Its own exit is the reap. A detached supervisor ({@see supervise}) outlives this command,
+ * waits for that exit, and posts the agent's final message to the thread as a note — success or
+ * failure, and a failure loudly. `crux spawn` itself returns as soon as the agent is up, because the
+ * lead that spawned it has other threads to run; `--wait` keeps the supervisor in the foreground
+ * instead (and exits non-zero if the worker failed), which is what makes it usable in a script.
+ *
+ * LIVE (`--live`). Interactive, with Remote Control on, so you can open the session from the
+ * Claude app and talk to it — the mode that shipped today, unchanged. Headless and Remote Control
+ * are mutually exclusive (`-p --remote-control` mints no URL), so this mode alone gets a link, and
+ * this mode alone cannot reap itself: an interactive agent never exits. Its life is instead bounded
+ * by its THREAD's, so the Solo process id goes on the item and `crux done` stops it {@see done}.
+ *
+ * Spawning is fast; LEARNING the URL is not — the agent has to reach claude.ai first, which is why
+ * live waits up to `--rc-timeout` seconds. `--no-remote-control` skips both the flag and the wait.
+ */
+async function spawn(args) {
+  const id = args._[1];
+  const projectId = args['project-id'];
+  if (!id || typeof projectId !== 'string') fail(usageFor('spawn'));
+
+  const live = args.live === true;
+  const item = await api('GET', `/api/items/${encodeURIComponent(id)}`);
+
+  // Refuse a CLOSED thread BEFORE anything is started. The accept at the end of this function would
+  // be refused by the server anyway (ItemController::accept), but by then the worker is already up —
+  // and an agent whose accept was rejected is exactly the orphan this guard exists to prevent: it
+  // works, it reports, and its report lands on a thread the board says is finished, where nobody is
+  // looking for it. So the check happens here, on the item we have already fetched, at zero cost.
+  if (CLOSED_STATUSES.includes(item.status)) {
+    if (args.reopen !== true) {
+      fail(
+        `thread #${id} is ${item.status} — a worker on a closed thread reports where nobody is looking.\n` +
+          `       pass --reopen to bring it back and spawn onto it, or push a new item for the follow-up work.`,
+      );
+    }
+    console.log(`thread #${id} is ${item.status} — reopening it, then spawning.`);
+  }
+
+  const subject = (item.content || '').replace(/\s+/g, ' ').trim();
+  const name = threadName(id, subject);
+  const remoteControl = live && args['no-remote-control'] !== true;
+
+  const task =
+    typeof args.brief === 'string'
+      ? args.brief
+      : "Read the thread (crux feed / the item's activities) and work it.";
+  const brief = workerBrief({ id, task, live });
+
+  // Headless picks its own session id rather than guessing at it afterwards, so the `claude --resume`
+  // handle we store is a fact. Live still learns it from disk: it is the mode that shipped today and
+  // `--session-id` is unproven against an interactive pty — not a risk worth taking for a nicety.
+  const sessionId = live ? null : randomUUID();
+
+  const argv = spawnArgs({
+    projectId,
+    toolId: typeof args['tool-id'] === 'string' ? args['tool-id'] : 3,
+    id,
+    subject,
+    brief,
+    live,
+    sessionId,
+    remoteControl,
+  });
+
+  // Actually spawn it (Solo speaks {ok, data}); a broken CLI is fatal here.
+  const proc = solo(argv);
+  const procId = proc?.process?.id ?? proc?.process ?? null;
+
+  let url = null;
+  if (remoteControl) {
+    console.log(`spawned "${name}" — waiting for Remote Control to connect…`);
+    const rcTimeoutMs =
+      typeof args['rc-timeout'] === 'string' ? Number(args['rc-timeout']) * 1000 : RC_TIMEOUT_MS;
+    url = await waitForRemoteControlUrl(procId, rcTimeoutMs);
+  }
+
+  const acceptPayload = {
+    actor: typeof args.actor === 'string' ? args.actor : 'dispatch',
+    agent_name: name,
+  };
+  // Spawning IS accepting, so a spawn that means to reopen says so on the same call — the server does
+  // the resurrection there, and the thread is routed + accepted + worked in one write rather than in
+  // two that could half-land. Harmless on an open thread: the server ignores it.
+  if (args.reopen === true) acceptPayload.reopen = true;
+  // The process id is what `crux done` reaps, so it has to be on the item BEFORE the agent can
+  // outlive its thread — that is the whole mechanism, not bookkeeping.
+  if (procId !== null) acceptPayload.agent_process_id = procId;
+  const resumeId = sessionId ?? latestSessionId();
+  if (resumeId) acceptPayload.agent_session_id = resumeId;
+  if (url) acceptPayload.remote_control_url = url;
+  // Spawning IS accepting — this posts to the same endpoint `crux accept` does — so a lead that hands
+  // a thread straight to a worker names it here instead, and never has to make a separate accept call
+  // just to give the row a title. `--status` here is the handoff itself ("worker on it").
+  if (typeof args.title === 'string') acceptPayload.title = args.title;
+  if (typeof args.status === 'string') acceptPayload.status_line = args.status;
+  await api('POST', `/api/items/${encodeURIComponent(id)}/accept`, acceptPayload);
+
+  const where = procId !== null ? ` (Solo process ${procId})` : '';
+  console.log(`spawned "${name}"${where}${resumeId ? ` — session ${resumeId}` : ''}`);
+
+  if (live) {
+    if (url) console.log(`open on your phone: ${url}`);
+    else if (remoteControl) console.log('no Remote Control link — the agent never announced one (it still spawned).');
+    console.log(`it will not exit on its own — \`crux done ${id}\` stops it.`);
+    return;
+  }
+
+  if (procId === null) {
+    fail('Solo did not report a process id — there is nothing to supervise, so the worker would report nothing');
+  }
+
+  const superviseArgs = [
+    'supervise',
+    String(id),
+    '--process',
+    String(procId),
+    '--project-id',
+    String(projectId),
+  ];
+
+  if (args.wait) {
+    console.log('waiting for the worker to finish — its report will be posted to the thread…');
+    return supervise(parseArgs(superviseArgs));
+  }
+
+  // Detached, so the lead that spawned this worker is free the moment it is up. The supervisor is
+  // now the only thing that will speak for the agent when it dies, which is why it must not be a
+  // child of this process — `crux spawn` is about to exit.
+  const child = spawnChild(process.execPath, [__filename, ...superviseArgs], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  console.log(`reporting to thread #${id} when it exits (supervisor pid ${child.pid}).`);
+}
+
+/** How often the supervisor asks Solo whether the worker is still alive. */
+const SUPERVISE_POLL_MS = 5_000;
+
+/** How long a headless worker may run before the harness declares it hung and says so on the thread. */
+const SUPERVISE_TIMEOUT_MS = 8 * 60 * 60 * 1000;
+
+/**
+ * crux supervise <id> --process <n> [--project-id <n>] [--actor <name>] [--timeout <seconds>]
+ *
+ * Wait for a headless worker to exit, then post its report to the thread. This is the mechanism that
+ * replaces "the agent remembers to report": the agent's final message is lifted onto the thread by
+ * the harness, and a worker that dies without one is announced as failed rather than vanishing.
+ *
+ * `crux spawn` starts this for you, detached — you should rarely type it. But it is a real command,
+ * and deliberately so: the supervisor is the one thing whose death would restore the old silence, so
+ * it has to be re-attachable. Solo keeps a dead process's output buffer, so re-running this against
+ * an already-exited worker still recovers its report and posts it, however late.
+ *
+ * Exits non-zero when the worker failed, so `crux spawn --wait` is usable in a script.
+ */
+async function supervise(args) {
+  const id = args._[1];
+  const procId = args.process;
+  if (!id || typeof procId !== 'string') fail(usageFor('supervise'));
+
+  const itemId = itemIdArg(id, 'supervise');
+  const projectId = typeof args['project-id'] === 'string' ? args['project-id'] : null;
+  const timeoutMs =
+    typeof args.timeout === 'string' ? Number(args.timeout) * 1000 : SUPERVISE_TIMEOUT_MS;
+
+  // Poll until the worker is no longer running. A process Solo has forgotten entirely counts as over
+  // — we still go and read whatever buffer it left behind rather than assume it said nothing. A Solo
+  // we cannot reach counts as nothing at all: keep waiting {@see soloStatus}.
+  const deadline = Date.now() + timeoutMs;
+  let status = null;
+  let timedOut = true;
+
+  while (Date.now() < deadline) {
+    const seen = soloStatus(procId, projectId);
+
+    if (seen !== null) {
+      status = seen;
+      if (status === 'gone' || SOLO_TERMINAL.has(status)) {
+        timedOut = false;
+        break;
+      }
+    }
+
+    await sleep(SUPERVISE_POLL_MS);
+  }
+
+  const raw = soloTry(['processes', 'output', String(procId), '--raw', '--lines', '5000'])?.text ?? null;
+
+  // Was this silence on purpose? Only a tombstone for THIS worker — this item, this Solo process —
+  // can say so, and only once. No tombstone means the worker died, which is still the loud answer.
+  const cancelled = timedOut ? null : takeTombstone(itemId, procId);
+  const report = workerReport({ result: resultJson(raw), status, timedOut, cancelled });
+
+  const actor = typeof args.actor === 'string' ? args.actor : `thread-${id}`;
+  await postReport(itemId, actor, report);
+
+  const ending = report.cancelled ? 'cancelled' : report.ok ? 'done' : 'FAILED';
+  console.log(`reported to thread #${itemId} (${ending})`);
+  if (!report.ok) process.exit(1);
+}
+
+/**
+ * Post a worker's report to its thread, retrying a transient failure.
+ *
+ * The only step with nothing behind it: the agent is gone, its final message exists nowhere but in
+ * this process's memory, and a dropped POST is precisely the silence the ticket exists to kill. So
+ * unlike everything else the supervisor does, this one does not shrug off a failure — it retries,
+ * and if it still cannot write it says so on stderr and exits non-zero rather than pretending.
+ */
+async function postReport(itemId, actor, report, attempts = 4) {
+  const payload = {
+    item_id: itemId,
+    actor,
+    type: 'note',
+    description: report.text,
+  };
+  // A dead worker pushes. A note nobody is told about is just a quieter silence.
+  if (report.notify) payload.notify = true;
+
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await api('POST', '/api/activities', payload);
+      return;
+    } catch (error) {
+      if (attempt >= attempts) {
+        fail(`could not post the worker's report to thread #${itemId}: ${error.message}`);
+      }
+      console.error(`crux: posting the report failed (${error.message}) — retrying…`);
+      await sleep(2_000 * attempt);
+    }
+  }
+}
+
+const TAIL_TOPICS = ['items', 'activities', 'decisions'];
+const TAIL_MAX_BACKOFF_MS = 300_000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Write one event and wait for it to actually leave the process.
+ *
+ * A Monitor consumer is woken by the line, not by the poll — if Node parks the write in its
+ * internal buffer (which it does as soon as stdout is a pipe rather than a tty), the event is
+ * silently swallowed until some later write happens to flush it. Awaiting `drain` is what
+ * makes "one flushed line per event" true.
+ */
+function emit(record) {
+  return new Promise((resolve) => {
+    if (process.stdout.write(`${JSON.stringify(record)}\n`)) resolve();
+    else process.stdout.once('drain', resolve);
+  });
+}
+
+
+/**
+ * Who this tail says it is, when `--actor` is not given.
+ *
+ * Deliberately NOT `lead-<slug>`. A human running `crux tail --project acme` to debug would
+ * otherwise adopt the dead lead's identity and light its status dot green — manufacturing the
+ * exact false "everything is fine" that the presence signal exists to destroy. A machine-local
+ * name is honest: someone is listening, and it isn't the lead.
+ */
+function defaultActor() {
+  let user = 'unknown';
+  try {
+    user = os.userInfo().username;
+  } catch {
+    /* no passwd entry (container); fall through */
+  }
+  return `${user}@${os.hostname()}`;
+}
+
+/**
+ * crux tail [--unrouted | --project <slug>] [--topics <t,…>] [--interval <s>] [--since <ts>]
+ *
+ * A long-running watcher that prints ONE single-line JSON record per new event, oldest
+ * first, flushed, and prints NOTHING otherwise. Silence always means "no new input" —
+ * transient API failures go to stderr and are retried with backoff, never to stdout.
+ *
+ * Each poll announces the actor and its poll interval (`X-Crux-Actor` / `X-Crux-Interval`), so
+ * the server can render a listener status dot whose freshness threshold tracks *this* tail's
+ * cadence rather than a hardcoded number of seconds. The identifier is self-asserted and
+ * advisory — see {@see \App\Http\Controllers\Api\UpdatesController}.
+ *
+ * Arm it under Claude Code's Monitor and an agent is woken push-style by real Crux input
+ * instead of burning tokens on an agentic poll:
+ *
+ *   crux tail --unrouted              # dispatch: the untriaged queue
+ *   crux tail --project crux          # a project lead: its own feed
+ *
+ * The cursor is durable (~/.config/crux/tail-cursor.json), so a restart resumes where it
+ * left off. Delivery is at-least-once — the cursor only advances over records already
+ * printed — so a consumer that acts on events must be idempotent.
+ *
+ * --interval defaults to 60s. crux-api runs with hibernation on, and a poll faster than
+ * that keeps the instance permanently awake for no benefit; events are not latency-critical.
+ */
+async function tail(args) {
+  if (args.unrouted && typeof args.project === 'string') {
+    fail('crux tail: --unrouted and --project are different queues; pass only one');
+  }
+
+  const topics = typeof args.topics === 'string' ? args.topics : 'items';
+  for (const topic of topics.split(',')) {
+    if (!TAIL_TOPICS.includes(topic.trim())) {
+      fail(`crux tail: unknown topic "${topic.trim()}" (valid: ${TAIL_TOPICS.join(', ')})`);
+    }
+  }
+
+  // --unrouted is the alias the triage consumer arms: everything the router couldn't place.
+  const status = args.unrouted ? 'unmatched' : typeof args.status === 'string' ? args.status : null;
+  const project = typeof args.project === 'string' ? args.project : null;
+
+  const intervalSeconds = Math.max(1, Number.parseInt(args.interval, 10) || 60);
+  const interval = intervalSeconds * 1000;
+
+  const actor = typeof args.actor === 'string' && args.actor.trim() !== '' ? args.actor.trim() : defaultActor();
+  const presence = { 'X-Crux-Actor': actor, 'X-Crux-Interval': String(intervalSeconds) };
+
+  const key = cursorKey({ url: config().url, topics, project, status });
+  // --since overrides a stored cursor; otherwise a first run starts from now (the server
+  // returns a cursor pinned to the newest row and replays no history).
+  let cursor = typeof args.since === 'string' ? args.since : readCursors()[key];
+
+  let failures = 0;
+  let running = true;
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+      running = false;
+      process.exit(0);
+    });
+  }
+
+  while (running) {
+    try {
+      const params = new URLSearchParams({ topics });
+      if (project) params.set('project', project);
+      if (status) params.set('status', status);
+      if (cursor) params.set('since', cursor);
+
+      const res = await request('GET', `/api/updates?${params}`, undefined, presence);
+
+      if (!res.ok) {
+        // 4xx won't fix itself — a bad cursor or a revoked token means stop, not spin.
+        if (res.status >= 400 && res.status < 500) {
+          fail(`server returned ${describeError(res.status, res.json, res.text)}`);
+        }
+        throw new Error(`server returned ${res.status}`);
+      }
+
+      for (const record of res.json.records || []) await emit(record);
+
+      // Persisted only after the lines are out: a crash in between replays, never drops.
+      if (res.json.next_cursor && res.json.next_cursor !== cursor) {
+        cursor = res.json.next_cursor;
+        saveCursor(key, cursor);
+      }
+      failures = 0;
+    } catch (e) {
+      failures++;
+      console.error(`crux tail: ${e.message} (retry ${failures})`);
+    }
+
+    const backoff = failures > 0 ? Math.min(interval * 2 ** (failures - 1), TAIL_MAX_BACKOFF_MS) : interval;
+    await sleep(backoff);
+  }
+}
+
+async function projects(args) {
+  const list = await api('GET', '/api/projects');
+  if (args.json) {
+    console.log(JSON.stringify(list, null, 2));
+    return;
+  }
+  if (!list.length) {
+    console.log('(no projects)');
+    return;
+  }
+  for (const p of list) {
+    const kw = (p.keywords || []).join(', ');
+    console.log(`${p.slug.padEnd(12)} ${p.name}${kw ? `  (${kw})` : ''}`);
+  }
+}
+
+/** `solo … --json` or a fatal error. Solo speaks `{ok, data}`; anything else is a broken CLI. */
+function solo(argv) {
+  let raw;
+  try {
+    raw = execFileSync(process.env.CRUX_SOLO_BIN || 'solo', [...argv, '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    fail(`could not run \`solo ${argv.join(' ')}\`: ${e.message.split('\n')[0]}`);
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    fail(`\`solo ${argv.join(' ')}\` did not return JSON`);
+  }
+  if (!doc.ok) fail(`\`solo ${argv.join(' ')}\` failed: ${doc.error || 'unknown error'}`);
+  return doc.data;
+}
+
+/**
+ * Every Solo process, following pagination.
+ *
+ * `solo processes list` defaults to 50 rows and there are more than that. The lead fleet lives
+ * in the `dispatch` project, whose rows sort last — so a single unpaginated call returns a list
+ * that looks complete and contains not one lead. Paginate, always.
+ */
+function soloProcesses() {
+  const all = [];
+  for (let offset = 0; ; ) {
+    const page = solo(['processes', 'list', '--limit', '200', '--offset', String(offset)]);
+    all.push(...page.processes);
+    if (!page.hasMore) return all;
+    offset = page.nextOffset ?? offset + page.processes.length;
+    if (page.processes.length === 0) return all; // Defensive: never spin on a broken cursor.
+  }
+}
+
+/**
+ * Is this orchestrator actually on the machine? The one I/O the backend resolver needs.
+ *
+ * The `CRUX_*_BIN` overrides are honoured first, and that is not a test affordance bolted on — it is
+ * the same seam `lib/backends.js` already runs every one of its commands through. If crux is going to
+ * invoke `$CRUX_SOLO_BIN`, then "is solo installed?" has to mean "does THAT exist", or the check and
+ * the thing it is checking are two different programs.
+ *
+ * tmux has no override because nothing shells out to a `CRUX_TMUX_BIN` — the exec template says
+ * `tmux`, so a plain PATH lookup for `tmux` is exactly the question. Which means a test proves it the
+ * way a user lives it: by putting a tmux on PATH.
+ */
+const BIN_OVERRIDE = { solo: 'CRUX_SOLO_BIN', herdr: 'CRUX_HERDR_BIN' };
+
+function installed(bin) {
+  const override = BIN_OVERRIDE[bin] ? process.env[BIN_OVERRIDE[bin]] : null;
+  const target = typeof override === 'string' && override !== '' ? override : bin;
+
+  const executable = (file) => {
+    try {
+      fs.accessSync(file, fs.constants.X_OK);
+      return fs.statSync(file).isFile();
+    } catch {
+      return false;
+    }
+  };
+
+  if (target.includes(path.sep)) return executable(target);
+  return (process.env.PATH || '').split(path.delimiter).some((dir) => dir && executable(path.join(dir, target)));
+}
+
+/** The leads config: env override, then ~/.config, then the copy shipped beside this script. */
+function leadsConfig() {
+  const candidates = [
+    process.env.CRUX_LEADS_CONFIG,
+    path.join(os.homedir(), '.config', 'crux', 'leads.json'),
+    path.join(__dirname, 'leads.config.json'),
+  ].filter((p) => typeof p === 'string' && p !== '');
+
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      const cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const swarm = cfg.swarm || {};
+      return {
+        file,
+        fleetProject: cfg.fleetProject || 'dispatch',
+        map: cfg.map || {},
+        leadless: cfg.leadless || {},
+        leadProcess: cfg.leadProcess || {},
+        swarm: {
+          // NOT `|| 'solo'`. An absent backend means "crux, look at my machine" — and defaulting it
+          // to Solo is what handed every stranger without Solo a first run that ended in `could not
+          // run \`solo projects list\``. Absent is a real state; it is resolved, not assumed.
+          // {@see ../lib/orchestrator}
+          backend: typeof swarm.backend === 'string' && swarm.backend !== '' ? swarm.backend : null,
+          agent: swarm.agent || swarmLib.DEFAULT_AGENT,
+          solo: swarm.solo || {},
+          exec: swarm.exec || {},
+          herdr: swarm.herdr || {},
+          projects: swarm.projects || {},
+        },
+      };
+    } catch (e) {
+      fail(`could not parse ${file}: ${e.message}`);
+    }
+  }
+  return fail(`no leads config found (looked in: ${candidates.join(', ')})`);
+}
+
+const LEAD_STATE_LABEL = {
+  covered: 'OK  ',
+  leadless: 'OK  ',
+  unmanaged: 'WARN',
+  uncovered: 'FAIL',
+  duplicate: 'FAIL',
+  orphan: 'FAIL',
+  unmapped: 'FAIL',
+};
+
+/**
+ * crux leads [--fix] [--json]
+ *
+ * Walk every Solo project and report whether a live lead is tailing its crux stream. Exits
+ * non-zero when anything is uncovered, so it works unattended as a health check.
+ */
+async function leads(args) {
+  const config = leadsConfig();
+
+  const registry = await api('GET', '/api/projects');
+  const cruxSlugs = registry.map((p) => p.slug);
+
+  const projects = solo(['projects', 'list']).projects;
+  const processes = soloProcesses();
+
+  const table = leadsLib.parseProcessTable(execFileSync('ps', ['-axo', 'pid=,ppid=,command='], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
+  const soloByPid = new Map(processes.filter((p) => typeof p.pid === 'number').map((p) => [p.pid, p]));
+  const tails = leadsLib.attributeOwners(leadsLib.findTails(table), table, soloByPid);
+
+  const report = leadsLib.reconcile({ soloProjects: projects, cruxSlugs, tails, config });
+  const plan = args.fix ? leadsLib.planFix(report, processes, config) : null;
+
+  const started = [];
+  if (plan) {
+    for (const { slug, process: proc } of plan.starts) {
+      if (args['dry-run']) {
+        started.push({ slug, process: proc.id, dryRun: true });
+        continue;
+      }
+      solo(['processes', 'start', String(proc.id)]);
+      started.push({ slug, process: proc.id, dryRun: false });
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ ok: report.ok, config: config.file, entries: report.entries, fix: plan ? { started, refusals: plan.refusals } : null }, null, 2));
+    process.exit(report.exitCode);
+  }
+
+  for (const entry of report.entries) {
+    const name = entry.slug ?? `(${entry.soloProject.name})`;
+    console.log(`${LEAD_STATE_LABEL[entry.state]}  ${name.padEnd(22)} ${entry.state.padEnd(10)} ${entry.detail}`);
+    if (entry.state === 'covered' && entry.unsupervised) {
+      console.log(`      ${''.padEnd(22)} ${''.padEnd(10)} ^ no Solo ancestor — supervised by nothing.`);
+    }
+  }
+
+  if (plan) {
+    for (const started_ of started) {
+      console.log(`\nstarted lead for "${started_.slug}" (Solo process ${started_.process})${started_.dryRun ? ' [dry-run]' : ''}`);
+    }
+    for (const refusal of plan.refusals) {
+      console.log(`\nrefused "${refusal.slug}": ${refusal.reason}`);
+    }
+  }
+
+  const counts = report.entries.reduce((acc, e) => ({ ...acc, [e.state]: (acc[e.state] || 0) + 1 }), {});
+  console.log(`\n${Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ')}`);
+  process.exit(report.exitCode);
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * crux discover — step zero.
+ *
+ * `crux swarm up` needs a crux project and a repo path. Until this command existed, HAVING one meant
+ * a stranger learning a config-file format and hand-editing JSON before the five-minute quickstart
+ * could even begin. The pure half of this lives in lib/discover.js; what is here is the I/O it is
+ * kept away from — git, the manifests, the questions, and the two writes.
+ * --------------------------------------------------------------------------------------------- */
+
+/** Run a git command in `dir`, or null. A repo with no remote is normal, not an error. */
+function git(dir, argv) {
+  try {
+    return execFileSync('git', ['-C', dir, ...argv], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a JSON manifest, or null. A malformed package.json must not take the command down. */
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readTextFile(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** The first README this repo has, under any of the names people give it. */
+function readReadme(repo) {
+  for (const name of ['README.md', 'readme.md', 'README', 'README.markdown']) {
+    const text = readTextFile(path.join(repo, name));
+    if (text !== null) return text;
+  }
+  return null;
+}
+
+/**
+ * Everything the repo can tell us without being asked. This is the whole point of the command:
+ * every field below is one a stranger would otherwise have had to type.
+ */
+function inspectRepo(dir) {
+  const root = git(dir, ['rev-parse', '--show-toplevel']);
+  if (!root) {
+    fail(
+      `${dir} is not a git repository — a lead has to have a repo to stand in, and crux will not ` +
+        'guess at one.\n' +
+        `       Run \`git init\` in it first, or point discover somewhere else: crux discover <path>`,
+    );
+  }
+
+  // The toplevel, realpath'd: run it from a subdirectory (or a worktree, or through /tmp on macOS)
+  // and the answer must still be the one path everything else in crux compares against.
+  const repo = fs.realpathSync(root);
+
+  const readme = readReadme(repo);
+  const stack = discoverLib.detectStack({
+    composer: readJsonFile(path.join(repo, 'composer.json')),
+    pkg: readJsonFile(path.join(repo, 'package.json')),
+    goMod: readTextFile(path.join(repo, 'go.mod')),
+    cargo: readTextFile(path.join(repo, 'Cargo.toml')),
+    gemfile: readTextFile(path.join(repo, 'Gemfile')),
+    python:
+      readTextFile(path.join(repo, 'pyproject.toml')) ?? readTextFile(path.join(repo, 'requirements.txt')),
+  });
+
+  const remote = git(repo, ['remote', 'get-url', 'origin']);
+  const manifest =
+    readJsonFile(path.join(repo, 'package.json'))?.name ??
+    readJsonFile(path.join(repo, 'composer.json'))?.name ??
+    null;
+
+  const name = discoverLib.deriveName({ remote, manifestName: manifest, dirName: path.basename(repo) });
+  const title = discoverLib.readmeTitle(readme);
+
+  return { repo, remote, stack, title, name, slug: discoverLib.slugify(name) };
+}
+
+/**
+ * Ask a question that always has an answer.
+ *
+ * `readline` is in core — this command adds no dependency, deliberately.
+ *
+ * Lines are PULLED, one per question, through readline's async iterator, and that is not a style
+ * choice. `rl.question()` registers interest in exactly the next line, but the interface goes on
+ * consuming the stream regardless — so when stdin is a pipe rather than a tty (a test, a script,
+ * `printf '…' | crux discover`) the whole input arrives in one chunk, readline emits every line of
+ * it immediately, and the four nobody is awaiting yet are dropped on the floor. The command would
+ * silently take defaults for questions the user had answered. The iterator pauses the stream between
+ * reads, so a line waits for its question.
+ *
+ * EOF (`done`) returns the default, which makes an input-less run behave exactly like `--yes` rather
+ * than hang forever at a prompt no one can see — the only honest reading of "there is nothing left
+ * to type".
+ */
+function prompter({ yes }) {
+  if (yes) return { ask: async (_q, fallback) => fallback, close() {} };
+
+  const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+  const lines = rl[Symbol.asyncIterator]();
+
+  return {
+    async ask(question, fallback) {
+      process.stdout.write(`${question} [${fallback}] `);
+      const { value, done } = await lines.next();
+      // A tty echoes the Enter the user pressed; a pipe does not, and without this every prompt in a
+      // scripted run runs into the next one on a single unreadable line.
+      if (!process.stdin.isTTY) process.stdout.write('\n');
+      if (done) return fallback;
+      const answer = String(value).trim();
+      return answer === '' ? fallback : answer;
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
+/**
+ * Which leads config discover WRITES to.
+ *
+ * It must be the file `leadsConfig()` will later READ, or `crux swarm up` looks somewhere else and
+ * the repo path this command just took from a human is never found. So: `CRUX_LEADS_CONFIG` if it is
+ * set, else `~/.config/crux/leads.json`.
+ *
+ * The subtle one is the third candidate, `cli/leads.config.json` — the copy shipped inside the
+ * package. `leadsConfig()` falls back to it, so on a machine with no user config it is the file in
+ * force, and creating an empty `~/.config/crux/leads.json` would SHADOW it: the shipped `map` and
+ * `leadless` entries would silently stop applying, and a fleet that was working would quietly lose
+ * its name mapping. Never write into the package (it is not the user's file, and an npm reinstall
+ * would erase it) — but seed the new user config from whatever is in force, so creating it changes
+ * exactly one thing: the project we are adding.
+ */
+function discoverConfigTarget() {
+  const env = process.env.CRUX_LEADS_CONFIG;
+  const file = typeof env === 'string' && env !== '' ? env : path.join(os.homedir(), '.config', 'crux', 'leads.json');
+
+  if (fs.existsSync(file)) return { file, created: false, seed: readJsonFile(file) ?? {} };
+
+  // Nothing of the user's own yet. Inherit what is currently in force rather than replace it.
+  const shipped = readJsonFile(path.join(__dirname, 'leads.config.json'));
+  return { file, created: true, seed: shipped ?? {} };
+}
+
+/** Fail now, with the fix, rather than after the project has been created in the API. */
+function assertWritable(file) {
+  const dir = path.dirname(file);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.accessSync(fs.existsSync(file) ? file : dir, fs.constants.W_OK);
+  } catch {
+    fail(
+      `cannot write the leads config at ${file} — the crux project would be created in the API with ` +
+        'no repo on this machine, and `crux swarm up` could not start its lead.\n' +
+        `       Fix the permissions (\`chmod u+w ${dir}\`), or point discover at a config you own ` +
+        'with CRUX_LEADS_CONFIG=/path/to/leads.json.',
+    );
+  }
+}
+
+/** Is a lead already tailing this slug? An honest "not started" needs a real look, not an assumption. */
+function tailFor(slug) {
+  try {
+    return runningTails().find((t) => t.slug === slug) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * crux discover [path] [--yes] [--json] [--slug <s>] [--name <n>] [--color <c>] [--keywords <a,b>]
+ *
+ * Turn a directory into a crux project: registered with the API (so it exists in the feed, the app
+ * and the web) and declared in the local swarm config (so `crux swarm up` knows where its lead runs).
+ * Both, or neither — a project with no repo cannot be led, and a repo with no project has nothing to
+ * lead. It is step zero, and until now it was a JSON file a stranger had to learn.
+ */
+async function discover(args) {
+  const yes = args.yes === true;
+  const target = path.resolve(typeof args._[1] === 'string' ? args._[1] : '.');
+
+  if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    fail(`no such directory: ${target}\n       usage: crux discover [path]`);
+  }
+
+  // 1. DISCOVER — everything that can be read is read, and never asked.
+  const found = inspectRepo(target);
+
+  // The config is opened (and checked writable) BEFORE the API is touched. Both writes must land or
+  // neither should, and the local one is the only one we can test in advance — so a config we cannot
+  // write fails here, having created nothing, rather than after a project exists in the feed with no
+  // repo behind it.
+  const config = discoverConfigTarget();
+  assertWritable(config.file);
+  const configProjects = config.seed?.swarm?.projects ?? {};
+
+  const registry = await api('GET', '/api/projects');
+
+  const defaults = {
+    slug: typeof args.slug === 'string' ? discoverLib.slugify(args.slug) : found.slug,
+    repo: found.repo,
+  };
+  if (!defaults.slug) {
+    fail(`could not derive a slug from ${found.repo} — pass one: crux discover --slug <slug>`);
+  }
+  defaults.name =
+    typeof args.name === 'string'
+      ? args.name
+      : discoverLib.deriveDisplayName({ name: found.name, title: found.title, slug: found.slug });
+  defaults.color = typeof args.color === 'string' ? args.color : discoverLib.colorFor(defaults.slug);
+  defaults.keywords =
+    typeof args.keywords === 'string'
+      ? args.keywords.split(',').map((k) => discoverLib.slugify(k)).filter(Boolean)
+      : discoverLib.deriveKeywords({ ...found, slug: defaults.slug, name: defaults.name });
+
+  // 2. ASK — only what could not be read, always with the derived answer as the default, so the
+  //    common case is Enter, Enter, Enter. `--yes` (and a stdin with nothing on it) takes them all.
+  const home = os.homedir();
+  const quiet = yes || args.json === true;
+  const rl = prompter({ yes: quiet });
+
+  if (!quiet) {
+    console.log(`Found ${discoverLib.tildify(found.repo, home)}${found.stack ? ` — ${found.stack.label}` : ''}.\n`);
+  }
+
+  const answers = {
+    slug: await rl.ask('slug', defaults.slug),
+    name: await rl.ask('name', defaults.name),
+    color: await rl.ask(`color (${discoverLib.PALETTE.join(' ')})`, defaults.color),
+    keywords: await rl.ask('keywords', defaults.keywords.join(',')),
+    repo: await rl.ask('repo', defaults.repo),
+  };
+
+  const slug = discoverLib.slugify(answers.slug);
+  if (!slug) fail(`"${answers.slug}" is not a usable slug — letters, numbers and dashes.`);
+
+  if (!discoverLib.PALETTE.includes(answers.color)) {
+    fail(
+      `"${answers.color}" is not a colour crux renders — the app would colour it and the web would ` +
+        'show it grey, which is worse than either.\n' +
+        `       Pick one of: ${discoverLib.PALETTE.join(', ')}`,
+    );
+  }
+
+  // A repo the user retyped is a repo we have not looked at. Check it like the first one.
+  const repo = fs.existsSync(answers.repo) ? fs.realpathSync(answers.repo) : path.resolve(answers.repo);
+  if (repo !== found.repo) inspectRepo(repo);
+
+  const keywords = String(answers.keywords)
+    .split(',')
+    .map((k) => discoverLib.slugify(k))
+    .filter(Boolean);
+
+  const payload = discoverLib.projectPayload({
+    slug,
+    name: answers.name,
+    color: answers.color,
+    description:
+      typeof args.description === 'string'
+        ? args.description
+        : discoverLib.describe({ name: answers.name, stack: found.stack, title: found.title }),
+    keywords,
+  });
+
+  // 3. WRITE — but decide first, so a second run neither duplicates anything nor lies about it.
+  const plan = discoverLib.planWrite({ slug, repo, payload, registry, configProjects, samePath });
+  if (plan.refusal) fail(plan.refusal);
+
+  // An existing project is never silently clobbered. Interactively it is a question — and one that
+  // names the fields, so nothing changes without being seen. Under `--yes` (a script) the intent is
+  // unambiguous: you asked for the repo's state to be the truth, so it is applied.
+  let action = plan.project;
+  if (plan.project === 'update' && !quiet) {
+    const answer = await rl.ask(
+      `\n"${slug}" is already a crux project. Update ${plan.changed.join(', ')}? (y/n)`,
+      'y',
+    );
+    if (!/^y(es)?$/i.test(answer)) action = 'unchanged';
+  }
+  rl.close();
+
+  let project = plan.existing;
+  if (action !== 'unchanged') {
+    project = await api('POST', '/api/projects', payload);
+  }
+  const did = action === 'create' ? 'created' : action === 'update' ? 'updated' : 'unchanged';
+
+  // 4. SETTLE THE ORCHESTRATOR — the step that was missing, and the reason the printed `Next:` used
+  //    to be a lie. Registering a project says WHERE the lead works; it never said what would RUN it,
+  //    so discover happily printed `crux swarm up` at a machine that had no way to start an agent.
+  //
+  //    This is squarely discover's business. It is already the command that settles the things a
+  //    stranger should not have to learn a JSON file to state — and "what starts a lead here" is the
+  //    last of them. It is DERIVED, never asked: adding a sixth prompt to the common path to ask a
+  //    question the PATH already answers would be the form-shaped tool this command exists not to be.
+  //
+  //    Resolved against the config discover is WRITING, not the one `leadsConfig()` reads. On a first
+  //    run those are different files — `leadsConfig()` is answering out of the shipped package copy
+  //    while discover is creating the user's own — and checking the wrong one would preflight a
+  //    backend that is not the one `crux swarm up` will pick up thirty seconds later.
+  const chosen = orchestrator.resolveBackend({
+    env: process.env.CRUX_SWARM_BACKEND || null,
+    configured: config.seed?.swarm?.backend ?? null,
+    exec: config.seed?.swarm?.exec ?? {},
+    has: installed,
+    file: discoverLib.tildify(config.file, home),
+  });
+
+  // The config write is last because it is the one that can be re-run safely. If it throws, the
+  // project exists in the API and this run is a half-write — so it says so, loudly, and exits
+  // non-zero. What it must never do is print the success block.
+  //
+  // One write, both facts. The repo, and — when crux had to work the backend out for itself — the
+  // backend it worked out. A derivation that lives only in crux's head is one the user cannot see,
+  // cannot edit, and cannot tell apart from their own choice; written down it is a starting point
+  // they own. Nothing already in the file is ever overwritten {@see mergeBackend}.
+  const wrote = [];
+  let merged = config.seed;
+  if (plan.config !== 'unchanged') {
+    merged = discoverLib.mergeConfig(merged, slug, repo);
+    wrote.push(`swarm.projects.${slug}.repo`);
+  }
+  if (chosen.ok && chosen.writes) {
+    const before = merged;
+    merged = discoverLib.mergeBackend(merged, chosen.writes);
+    if (merged !== before) wrote.push(...Object.keys(chosen.writes).map((k) => `swarm.${k}`));
+  }
+
+  if (wrote.length) {
+    try {
+      fs.writeFileSync(config.file, `${JSON.stringify(merged, null, 2)}\n`);
+    } catch (e) {
+      fail(
+        `the crux project "${slug}" was ${did}, but its repo could not be written to ${config.file} ` +
+          `(${e.message}) — so \`crux swarm up\` cannot start its lead yet.\n` +
+          `       Fix the file and run \`crux discover ${repo}\` again; it is idempotent.`,
+      );
+    }
+  }
+
+  const tail = tailFor(slug);
+  const next = tail
+    ? `crux push --project ${slug} "<something for it to do>"`
+    : `crux swarm up --project ${slug}`;
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          project: { action: did, changed: plan.changed, ...project },
+          config: { file: config.file, created: config.created, action: plan.config, repo, wrote },
+          lead: tail ? { tailing: true, pid: tail.pid } : { tailing: false },
+          backend: {
+            name: chosen.name,
+            source: chosen.source,
+            ok: chosen.ok,
+            exec: chosen.exec,
+            problem: chosen.problem,
+          },
+          // A machine that cannot start a lead gets no `next`. A caller that trusted this field and
+          // ran what it found would hit the same dead end a human did — so the field states the
+          // truth instead: there IS no next command yet, and `backend.problem` says why.
+          next: chosen.ok ? next : null,
+          blocked: chosen.ok ? null : next,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  // 5. TELL THEM WHAT IS NEXT. And say what actually happened — a run that changed nothing says so
+  //    in the same breath as the ✓, because "success" and "did something" are not the same claim.
+  const summary = action === 'update' ? `updated (${plan.changed.join(', ')})` : did;
+
+  console.log(`\n✓ ${slug} is a crux project — ${summary}.`);
+  console.log(`  repo    ${discoverLib.tildify(repo, home)}`);
+  console.log(
+    `  config  ${discoverLib.tildify(config.file, home)} — ` +
+      `${wrote.length ? `${wrote.join(', ')} added` : 'already had this repo'}` +
+      `${config.created ? ' (created)' : ''}`,
+  );
+  console.log(`  lead    ${tail ? `tailing "${slug}" (pid ${tail.pid})` : 'not started'}`);
+  console.log(
+    `  runs on ${chosen.ok ? backendLabel(chosen) : 'nothing yet — see below'}` +
+      `${chosen.ok && chosen.writes ? ' — written to the config above, edit it freely' : ''}`,
+  );
+
+  // The whole point of this thread. A `Next:` crux can SEE will fail is not printed — because a
+  // stranger who runs it and watches it die has had the failed first run, and the quality of the
+  // error message they die with is not what makes it one.
+  if (!chosen.ok) {
+    console.log(`\n  ✗ ${chosen.problem.reason}`);
+    for (const line of chosen.problem.fix) console.log(`    ${line}`);
+    console.log(`\n  Then:  ${next}\n`);
+    return;
+  }
+
+  console.log(`\n  Next:  ${next}\n`);
+}
+
+/**
+ * The three things a member of the public does not have, and `crux swarm` supplies.
+ *
+ * The first crux fleet ran for a year before anyone else could have reproduced it, and the reasons
+ * lived outside crux entirely: its leads were started from hand-written briefs in a private
+ * directory; each lead had to be hand-declared in Solo's `solo.yml` before `crux leads --fix` would
+ * start it; and there was no abstraction at all — `leads.js` shells out to `solo`. So `swarm`
+ * generates the brief
+ * {@see renderLeadBrief}, spawns the lead without any declaration, and does it through an adapter
+ * {@see ../lib/backends}. "Bring your own orchestration, but ship our own opinions."
+ */
+
+/** `~/src/crux` → `/Users/…/src/crux`. A config file written by a human will contain tildes. */
+function expandHome(p) {
+  if (typeof p !== 'string' || p === '') return null;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return path.resolve(p);
+}
+
+/**
+ * Every `crux tail` the OS can see. The truth about coverage, and the same source `crux leads` uses.
+ *
+ * `CRUX_PS_BIN` overrides the command, exactly as `CRUX_SOLO_BIN` overrides Solo. Coverage is the
+ * one input to `swarm` that comes from the whole machine rather than from crux's own config, so
+ * without a seam here a test would reconcile against whatever leads happen to be running on the
+ * developer's laptop — and pass or fail accordingly.
+ */
+function runningTails() {
+  const ps = execFileSync(process.env.CRUX_PS_BIN || 'ps', ['-axo', 'pid=,ppid=,command='], {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return leadsLib.findTails(leadsLib.parseProcessTable(ps));
+}
+
+/** `--project a --project b` → ['a','b']; absent → null (meaning "every project"). */
+function onlyArg(raw) {
+  if (raw === undefined) return null;
+  const list = (Array.isArray(raw) ? raw : [raw]).filter((p) => typeof p === 'string');
+  if (list.length === 0) fail('--project needs a slug');
+  return list;
+}
+
+/**
+ * Resolve every crux project into something the planner can decide about.
+ *
+ * The per-project facts are DELIBERATELY not baked in: the repo path and what the project *is* come
+ * from the crux registry and the user's own config, never from anybody else's machine. The repo falls back
+ * to the backend's own idea of where the project lives (Solo records a path per project), which is
+ * what lets an existing Solo user run `crux swarm up` with no configuration at all.
+ */
+function swarmCandidates({ registry, config, soloProjects }) {
+  const slugs = new Set(registry.map((p) => p.slug));
+  const soloBySlug = new Map();
+
+  for (const project of soloProjects) {
+    const mapped = config.map[project.name];
+    if (typeof mapped === 'string') {
+      soloBySlug.set(mapped, project);
+      continue;
+    }
+    // Not in the map, but its name IS a crux slug. That is not a guess — the names are equal — and
+    // it is what lets a stranger with Solo run `crux swarm up` having configured nothing at all.
+    // The explicit map exists for the cases where they are NOT equal (`acme-search-index` is the
+    // slug `acme`), and it still wins wherever it is set.
+    if (slugs.has(project.name) && !soloBySlug.has(project.name)) soloBySlug.set(project.name, project);
+  }
+
+  return registry.map((project) => {
+    const declared = config.swarm.projects[project.slug] || {};
+    const soloProject = soloBySlug.get(project.slug) ?? null;
+
+    // Where the BACKEND will actually run the lead, when the backend gets to decide. Solo runs an
+    // agent in its project's directory — the configured repo does not move it — so for a slug Solo
+    // already has a project for, Solo's path is the truth and `repo` is only a claim.
+    const backendRepo = soloProject ? soloProject.path : null;
+    const declaredRepo = expandHome(declared.repo);
+
+    return {
+      slug: project.slug,
+      description: project.description || null,
+      projectName: project.name || project.slug,
+      leadless: typeof config.leadless[project.slug] === 'string' ? config.leadless[project.slug] : null,
+      repo: backendRepo ?? declaredRepo,
+      extra: typeof declared.brief === 'string' ? declared.brief : null,
+      soloProject: soloProject ? { id: soloProject.id, name: soloProject.name } : null,
+      repoConflict:
+        backendRepo && declaredRepo && !samePath(backendRepo, declaredRepo)
+          ? { backend: backendRepo, declared: declaredRepo, project: soloProject }
+          : null,
+    };
+  });
+}
+
+/** Same directory? Resolved, because macOS hands you `/tmp` and `/private/tmp` for the same place. */
+function samePath(a, b) {
+  const real = (p) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  return real(a) === real(b);
+}
+
+/**
+ * Read the state file back as something both plans can use: is each remembered lead still alive, and
+ * how can the backend that started it name it?
+ *
+ * Liveness is asked of the backend that STARTED the lead, not the one selected today — a solo lead
+ * does not become unaddressable because the user passed `--backend exec` this morning.
+ */
+function startedLeads(state, backends) {
+  return Object.values(state).map((entry) => {
+    let alive = false;
+    let addresses = 'handle';
+    try {
+      const backend = backends(entry.backend);
+      addresses = backend.addresses;
+      alive = backend.list().some((l) => String(l.ref) === String(entry.ref) && l.running);
+    } catch {
+      // A backend we can no longer build (uninstalled, misconfigured) cannot vouch for its lead. Not
+      // alive, so `up` may restart it — and `down` will report it as already gone rather than claim
+      // a stop that never happened.
+      alive = false;
+    }
+    return { ...entry, alive, addresses, everTailed: Boolean(entry.first_tail_at) };
+  });
+}
+
+/**
+ * One place to build (and reuse) a backend by name, so `list()` is not re-shelled per lead.
+ *
+ * `swarm.exec` is the RESOLVED block, not the raw config one — so a lead crux started with a derived
+ * tmux template can still be stopped by a `swarm down` that derives the same one. Hand the raw config
+ * to `down` and the stop template vanishes, `addresses` drops to `pid`, and crux refuses to stop a
+ * lead it started ninety seconds ago. The resolution has to be the same on both sides of the round
+ * trip, or the round trip is not one.
+ */
+function backendCache(config, state, exec = null) {
+  const swarm = exec ? { ...config.swarm, exec } : config.swarm;
+  const cache = new Map();
+  return (name) => {
+    if (!cache.has(name)) cache.set(name, backends.makeBackend(name, { config: swarm, state }));
+    return cache.get(name);
+  };
+}
+
+/**
+ * Which backend this run uses, and whether it can run at all — the check that did not exist.
+ *
+ * The refusal here is the point. `makeBackend` would have thrown for a missing exec template anyway,
+ * but only for THAT one case, and only at the moment of use; a machine with no Solo installed sailed
+ * past it and died shelling out. One resolver, checked once, means `discover` can ask the identical
+ * question BEFORE it prints `Next:` — which is the difference between a first run that works and a
+ * first run that ends in a good error message.
+ */
+function resolveSwarmBackend(args, config) {
+  return orchestrator.resolveBackend({
+    requested: typeof args.backend === 'string' ? args.backend : null,
+    env: process.env.CRUX_SWARM_BACKEND || null,
+    configured: config.swarm.backend,
+    exec: config.swarm.exec,
+    has: installed,
+    file: discoverLib.tildify(config.file, os.homedir()),
+  });
+}
+
+/** A resolver problem, as the multi-line refusal a human can act on. */
+function backendProblem(problem) {
+  return [problem.reason, ...problem.fix.map((line) => `       ${line}`)].join('\n');
+}
+
+/**
+ * crux swarm up|status|down [--backend solo|exec|herdr] [--project <slug>]… [--dry-run] [--json]
+ *
+ * `up` is idempotent — run it twice and the second run starts nothing. That is not a nicety: two
+ * tails on one stream race the shared cursor file and deliver every item twice, so "start a lead"
+ * has to mean "make sure exactly one lead is running", which is a reconciliation, not a spawn.
+ *
+ * `--dry-run` prints the plan and starts nothing, and for a launch demo that matters more than it
+ * sounds — it is how a stranger builds trust before letting a tool spawn agents on their machine.
+ */
+async function swarm(args) {
+  const sub = args._[1];
+  if (!['up', 'status', 'down'].includes(sub || '')) fail(usageFor('swarm'));
+
+  const config = leadsConfig();
+  const only = onlyArg(args.project);
+  const dryRun = args['dry-run'] === true;
+
+  const state = swarmState.readState();
+
+  const chosen = resolveSwarmBackend(args, config);
+  if (!chosen.ok) fail(backendProblem(chosen.problem));
+  const name = chosen.name;
+
+  const backends_ = backendCache(config, state, chosen.exec);
+  let backend;
+  try {
+    backend = backends_(name);
+  } catch (e) {
+    fail(e.message);
+  }
+
+  const registry = await api('GET', '/api/projects');
+  const tails = runningTails();
+
+  // The first time we ever catch a lead tailing, write it down. That single fact separates the two
+  // ways a lead can be up-but-not-tailing, which look identical in a process table and could not be
+  // more different: one has never got there (stuck at boot — a trust prompt, a crashed agent) and is
+  // a dead swarm; the other tailed happily for hours and is between tail restarts. Without this,
+  // every healthy lead eventually trips the stall check simply by being old enough.
+  const tailing = new Set(tails.map((t) => t.slug));
+  for (const entry of Object.values(state)) {
+    if (!entry.first_tail_at && tailing.has(entry.slug)) {
+      entry.first_tail_at = new Date().toISOString();
+      swarmState.recordLead(entry.slug, entry);
+    }
+  }
+
+  const started = startedLeads(state, backends_);
+
+  // Solo is the only backend that knows where its projects live — it records a path per project, and
+  // that is what lets an existing Solo user bring a swarm up with no configuration at all. For every
+  // other backend the repo has to be declared, and a slug with no repo is refused, never guessed at.
+  const soloProjects = name === 'solo' ? solo(['projects', 'list']).projects : [];
+  const candidates = swarmCandidates({ registry, config, soloProjects });
+
+  if (sub === 'down') return swarmDown({ args, backends_, started, tails, only, dryRun });
+  return swarmUp({ args, backend, chosen, config, candidates, tails, started, only, dryRun, status: sub === 'status' });
+}
+
+/**
+ * How the backend was arrived at, in the header — because a DERIVED backend must never be a silent
+ * one. crux picking tmux for you is a convenience; crux picking tmux for you without saying so is a
+ * user who cannot find their agents.
+ */
+function backendLabel(chosen) {
+  const how = [];
+  if (chosen.source === 'detected') how.push('auto-detected');
+  if (chosen.execSource === 'tmux') how.push('tmux template');
+  return how.length ? `${chosen.name} (${how.join(', ')})` : chosen.name;
+}
+
+const SWARM_STATE_LABEL = {
+  covered: 'OK  ',
+  leadless: 'OK  ',
+  starting: 'OK  ',
+  'tail-down': 'WARN',
+  'not-ours': 'OK  ',
+  'already-gone': 'OK  ',
+  start: 'START',
+  refused: 'FAIL',
+};
+
+/** `swarm up`, and `swarm status` — the same reconciliation, one of which is allowed to act on it. */
+async function swarmUp({ args, backend, chosen, config, candidates, tails, started, only, dryRun, status }) {
+  const name = chosen.name;
+  const plan = swarmLib.planUp({ candidates, tails, started, only });
+
+  const acted = [];
+  const failures = [];
+
+  if (!status) {
+    for (const lead of plan.starts) {
+      const briefFile = swarmState.briefPath(lead.slug);
+      const prompt = swarmLib.leadPrompt(briefFile);
+
+      if (dryRun) {
+        acted.push({ slug: lead.slug, dryRun: true, brief: briefFile, repo: lead.repo, detail: null });
+        continue;
+      }
+
+      // The brief has to exist before the agent is told to read it. Written first, and never while
+      // a lead is already reading it — that is why nothing here rewrites a brief for a covered slug.
+      try {
+        fs.mkdirSync(swarmState.BRIEF_DIR, { recursive: true });
+        fs.writeFileSync(
+          briefFile,
+          swarmLib.renderLeadBrief({
+            slug: lead.slug,
+            projectName: lead.projectName,
+            description: lead.description,
+            repo: lead.repo,
+            extra: lead.extra,
+            spawn: lead.soloProject
+              ? `crux spawn <id> --project-id ${lead.soloProject.id} --brief "<self-contained task, incl. repo path + git worktree>"`
+              : null,
+          }),
+        );
+
+        const { ref, detail } = backend.start({ ...lead, prompt, briefPath: briefFile, agent: config.swarm.agent });
+        swarmState.recordLead(lead.slug, {
+          backend: name,
+          ref,
+          name: swarmLib.leadName(lead.slug),
+          repo: lead.repo,
+          brief: briefFile,
+          started_at: new Date().toISOString(),
+        });
+        acted.push({ slug: lead.slug, dryRun: false, brief: briefFile, repo: lead.repo, detail });
+      } catch (e) {
+        // One project failing to come up must not abort the others — but it must be LOUD, and the
+        // run must exit non-zero. A half-started swarm that reports success is the worst outcome.
+        failures.push({ slug: lead.slug, reason: e.message });
+      }
+    }
+  }
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        { ok: plan.refusals.length === 0 && failures.length === 0, backend: name,
+          backendSource: chosen.source, exec: chosen.exec, execSource: chosen.execSource,
+          dryRun, config: config.file,
+          started: acted, skipped: plan.skips, refused: [...plan.refusals, ...failures],
+          wouldStart: status ? plan.starts.map((s) => s.slug) : undefined },
+        null, 2,
+      ),
+    );
+    process.exit(plan.refusals.length || failures.length ? 1 : 0);
+  }
+
+  console.log(`backend: ${backendLabel(chosen)}  ·  config: ${config.file}${dryRun ? '  ·  DRY RUN — nothing will start' : ''}\n`);
+
+  for (const skip of plan.skips) {
+    console.log(`${SWARM_STATE_LABEL[skip.state] ?? 'OK  '}  ${skip.slug.padEnd(22)} ${skip.state.padEnd(10)} ${skip.detail}`);
+  }
+
+  if (status) {
+    for (const lead of plan.starts) {
+      console.log(`FAIL  ${lead.slug.padEnd(22)} ${'uncovered'.padEnd(10)} no lead is tailing "${lead.slug}". \`crux swarm up\` would start one.`);
+    }
+  }
+
+  for (const start of acted) {
+    console.log(
+      `START ${start.slug.padEnd(22)} ${(start.dryRun ? 'would start' : 'started').padEnd(10)} ` +
+        `${start.detail ?? `in ${start.repo}`}\n      ${''.padEnd(22)} ${''.padEnd(10)} brief: ${start.brief}`,
+    );
+  }
+
+  for (const refusal of [...plan.refusals, ...failures]) {
+    console.log(`FAIL  ${String(refusal.slug).padEnd(22)} ${'refused'.padEnd(10)} ${refusal.reason}`);
+  }
+
+  const parts = [];
+  if (acted.length) parts.push(`${acted.length} ${dryRun ? 'would start' : 'started'}`);
+  if (status && plan.starts.length) parts.push(`${plan.starts.length} uncovered`);
+  for (const [state, n] of Object.entries(
+    plan.skips.reduce((acc, s) => ({ ...acc, [s.state]: (acc[s.state] || 0) + 1 }), {}),
+  )) {
+    parts.push(`${n} ${state}`);
+  }
+  if (plan.refusals.length + failures.length) parts.push(`${plan.refusals.length + failures.length} refused`);
+  console.log(`\n${parts.length ? parts.join(', ') : 'nothing to do'}`);
+
+  // `status` is a health check: uncovered is a failure, exactly as `crux leads` treats it.
+  const bad = plan.refusals.length + failures.length + (status ? plan.starts.length : 0);
+  process.exit(bad ? 1 : 0);
+}
+
+/** `swarm down` — stops ONLY what `swarm up` started. A lead crux did not start is left alone. */
+async function swarmDown({ args, backends_, started, tails, only, dryRun }) {
+  const plan = swarmLib.planDown({ started, tails, only });
+
+  const stopped = [];
+  for (const entry of plan.stops) {
+    if (dryRun) {
+      stopped.push({ ...entry, outcome: 'would stop' });
+      continue;
+    }
+    let outcome;
+    try {
+      outcome = backends_(entry.backend).stop(entry);
+    } catch (e) {
+      plan.refusals.push({ slug: entry.slug, reason: `could not stop it: ${e.message}` });
+      continue;
+    }
+
+    // A stop crux could not make sense of — and the one signal that can settle it.
+    //
+    // `exec` is the backend that reaches this: it hands the user's own `stop` line to a shell, and a
+    // shell that exits non-zero does not say WHY. `tmux kill-session` fails identically whether the
+    // session is already gone or the template is broken, and those two need opposite answers: the
+    // first must be forgotten (or `down` refuses forever, and the state entry can never be cleared),
+    // the second must be refused (or crux reports a running lead as stopped, which is the one outcome
+    // worse than failing).
+    //
+    // So ask the OS, which is where coverage lives for every other question crux asks: is anything
+    // still running `crux tail --project <slug>`? Nothing tailing means there is no lead left to
+    // stop — that is an observation, not a guess. Something tailing means the lead outlived the stop,
+    // and THAT is refused, loudly, with the ref to go and look at.
+    if (outcome === 'unknown' && !tails.some((t) => t.slug === entry.slug)) outcome = 'already-gone';
+
+    // Forgotten only once it is actually down. A lead forgotten while still running is a lead crux
+    // can never stop again — and the next `up` would start a second one on top of it.
+    if (outcome === 'stopped' || outcome === 'already-gone') swarmState.forgetLead(entry.slug);
+    else plan.refusals.push({ slug: entry.slug, reason: `its backend could not stop ${entry.ref} — check it by hand.` });
+    if (outcome !== 'unknown') stopped.push({ ...entry, outcome });
+  }
+
+  if (!dryRun) {
+    for (const skip of plan.skips) {
+      if (skip.state === 'already-gone') swarmState.forgetLead(skip.slug);
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ ok: plan.refusals.length === 0, dryRun, stopped, skipped: plan.skips, refused: plan.refusals }, null, 2));
+    process.exit(plan.refusals.length ? 1 : 0);
+  }
+
+  if (dryRun) console.log('DRY RUN — nothing will be stopped\n');
+
+  for (const entry of stopped) {
+    console.log(`STOP  ${entry.slug.padEnd(22)} ${String(entry.outcome).padEnd(12)} ${entry.backend} ${entry.ref}`);
+  }
+  for (const skip of plan.skips) {
+    console.log(`OK    ${skip.slug.padEnd(22)} ${skip.state.padEnd(12)} ${skip.detail}`);
+  }
+  for (const refusal of plan.refusals) {
+    console.log(`FAIL  ${String(refusal.slug).padEnd(22)} ${'refused'.padEnd(12)} ${refusal.reason}`);
+  }
+
+  if (!stopped.length && !plan.skips.length && !plan.refusals.length) {
+    console.log('crux swarm has not started any leads — nothing to stop.');
+  }
+
+  process.exit(plan.refusals.length ? 1 : 0);
+}
+
+const USAGE = `crux — push items, report activity, read the feed.
+
+Commands:
+  discover [path] [--yes] [--json]                  turn a repo into a crux project — step zero.
+                                                    Reads what it can (name, stack, keywords),
+                                                    asks for the rest, and writes both the
+                                                    project and the local swarm config.
+                                                    Then: crux swarm up
+  push [--project <slug>] [--source <s>] "<text>"   POST an item (routes if no project)
+  activity [--project <slug>] [--item <id>]         log progress; --item posts it onto that
+           [--actor <n>] [--type <t>]                item's thread, where the app can read it;
+           [--image <path>]… [--notify] "<text>"     --image attaches a picture to it, and
+                                                    --notify pushes it to your phone
+  decide < decision.json                            pipe a Decision (or array) to the API
+  feed [--project <slug>] [--status <s>] [--json]   read the item feed
+  next [--claim] [--source <s>] [--actor <n>]       print one unmatched item as JSON,
+                                                    oldest first; --claim leases it.
+                                                    Exits ${EXIT_EMPTY} when the queue is empty.
+  tail [--unrouted | --project <slug>]              watch for new events; print one flushed
+       [--topics items,activities,decisions]        JSON line per record, silence otherwise.
+       [--interval 60] [--since <ts>]               Durable cursor; runs until killed.
+  route <id> --project <slug> [--note "<why>"]      reassign an item to a project
+  done <id> [--note "<why>"] [--drop]               close an item (--drop = dropped, not done)
+                                                    and stop its agent — a thread's death is
+                                                    its worker's
+  cancel <id> [--note "<why>"]                      stop a thread's worker ON PURPOSE, without
+                                                    the thread reading it as a crash. The verb
+                                                    for a mid-flight re-brief; the thread stays
+                                                    open, ready to spawn again.
+  need --item <id> --kind <k> [flags] ["<q>"]       raise a needs-you block (the escalation verb):
+                                                    decide|answer|secret|desk|world
+  accept <id> [--actor <n>] [--agent-name <n>]      mark a thread accepted → "working"
+  spawn <id> --project-id <n> [--brief "<t>"]       start the worker for a thread. It reports to
+        [--wait] [--live]                           the thread and exits, both mechanically.
+                                                    --live is interactive + Remote Control
+                                                    instead, openable from the Claude app.
+  supervise <id> --process <n>                      wait for a headless worker and post its
+                                                    report. crux spawn does this for you.
+  projects [--json]                                 list projects
+  leads [--fix] [--json]                            reconcile the Solo lead fleet against the
+                                                    running \`crux tail\` processes. Exits 1
+                                                    when anything is uncovered.
+  swarm up|status|down [--backend solo|exec|herdr]  spin up standing leads — one per project —
+        [--project <slug>]… [--dry-run]             on your own orchestrator. Writes the lead
+                                                    brief crux ships, starts a lead for every
+                                                    uncovered project, and is idempotent.
+                                                    \`down\` stops only what it started.
+
+Run \`crux <command> --help\` for a command's own flags.
+
+Config: env CRUX_API_URL / CRUX_API_TOKEN, then ~/.config/crux/config.json`;
+
+/**
+ * One entry per subcommand. `flags` is the source of truth for two things the dispatcher
+ * does before the handler ever runs: reject a flag the command doesn't understand, and
+ * print `usage` for --help/-h. A flag a handler reads must be listed here or the command
+ * refuses to start — the coupling is the point. `--help` is accepted everywhere implicitly.
+ */
+const COMMANDS = {
+  discover: {
+    run: discover,
+    flags: ['yes', 'json', 'slug', 'name', 'color', 'keywords', 'description'],
+    usage: `crux discover [path] [--yes] [--json]
+                     [--slug <s>] [--name <n>] [--color <c>] [--keywords <a,b>] [--description <d>]
+
+Turn a repo into a crux project. This is step zero: \`crux swarm up\` needs a project and a repo
+path, and before this command the only way to have one was to hand-edit a config file.
+
+  crux discover        # point it at a repo, answer a few questions
+  crux swarm up        # a standing lead is now working it
+  crux push "…"        # give it something to do
+
+It DISCOVERS what it can and only ASKS for the rest, so the common case is Enter, Enter, Enter:
+
+  the repo path      resolved from git (a subdirectory or a worktree still finds the root)
+  the name           the \`origin\` remote, else package.json / composer.json, else the directory
+  what it is         Laravel, a Node CLI, Rails, Go… read from the manifests. A lead that knows
+                     it is standing in a Laravel app writes better briefs.
+  keywords           derived from all of the above — this is what ROUTES a captured item here,
+                     so they matter more than they look
+
+Then it writes BOTH places, and both must land: the crux PROJECT (POST /api/projects — so it
+exists in the feed, the app and the web) and the local SWARM CONFIG (so \`crux swarm up\` knows
+which repo the lead runs in). A project with no repo cannot be led.
+
+IDEMPOTENT. Run it twice and you get one project and one config entry, not two. A slug already
+taken by a DIFFERENT repo is refused, and so is a repo that is already another project — one
+directory with two leads is two agents racing one codebase. It never reports success while doing
+nothing: a run that changes nothing says \`unchanged\`, and names what it compared.
+
+  --yes              take every default and ask nothing (scripts, and the impatient)
+  --json             machine output; implies --yes
+  --slug <s>         override the derived slug — also how you point at an existing project
+  --name <n>         override the derived display name
+  --color <c>        ${discoverLib.PALETTE.join(' | ')}
+  --keywords <a,b>   comma-separated, replacing the derived list
+  --description <d>  one line. The router renders it into its prompt, so keep it a summary.
+
+  crux discover                          # this repo, interactively
+  crux discover ~/src/acme --yes         # every default, no questions
+  crux discover ~/src/acme --slug orbit  # register it under a slug of your choosing`,
+  },
+  push: {
+    run: push,
+    flags: ['project', 'source'],
+    usage: `crux push [--project <slug>] [--source <s>] "<text>"
+       crux push [--project <slug>] [--source <s>] < text-on-stdin
+
+POST an item. Text comes from the positional args, else stdin.
+
+  --project <slug>   file it directly; omit to let the API route by keyword
+  --source <s>       where it came from (e.g. cli, capture, slack)`,
+  },
+  activity: {
+    run: activity,
+    flags: ['project', 'item', 'actor', 'type', 'image', 'notify', 'status'],
+    usage: `crux activity [--project <slug>] [--item <id>] [--actor <name>] [--type <t>]
+                     [--image <path>]… [--notify] [--status "<phrase>"] "<text>"
+
+Log progress against a project. Text comes from the positional args, else stdin.
+
+An activity with --item is a message on that item's thread: it is what the app renders when
+someone opens the item, and it is how a lead's answer reaches the person who asked. Without
+--item the activity is filed against the project only, and no item view will ever show it.
+
+--image attaches a picture to the message — a screenshot of what you built, a chart, the actual
+failure. Both the phone and the web chat render it inline in the bubble. Repeat it for several.
+The paths are checked before the activity is posted, so a wrong one costs nothing; a network
+failure afterwards is reported but never retracts the message, which is already on the thread.
+
+  --project <slug>   the project the work belongs to
+  --item <id>        the item this is about — answer the question on the thread it came from
+  --actor <name>     who did it (defaults server-side)
+  --type <t>         activity type (routed | progress | status | note | …)
+  --image <path>     attach an image (jpg | png | webp | gif, ≤10MB) — repeatable
+  --notify           push this one activity to your phone. For handing over the thing you
+                     asked for — an answer, a result, a link — not for saying you are blocked.
+                     Blocked is \`crux need\`, and that distinction is what the escalations view
+                     is built on. Without the flag, an activity is silent.
+  --status "<phrase>"  set the thread's STATUS LINE — one short phrase, what is happening NOW
+                     ("running the migration"). It shows under the title on the row, small and
+                     grey. Nothing generates it: the row says what you last said it says, so
+                     carry it on the reports you are already writing and it can never go stale.
+                     Requires --item; a status line belongs to a thread, not to a project.`,
+  },
+  decide: {
+    run: decide,
+    flags: [],
+    usage: `crux decide < decision.json
+
+Pipe a Decision object — or an array of them — to the decisions API.
+Takes no flags; the document is read from stdin.`,
+  },
+  feed: {
+    run: feed,
+    flags: ['project', 'status', 'limit', 'json'],
+    usage: `crux feed [--project <slug>] [--status <s>] [--limit <n>] [--json]
+
+Read the item feed, newest first.
+
+  --project <slug>   only this project's items
+  --status <s>       only items in this status (e.g. unmatched, done)
+  --limit <n>        cap the number of items returned
+  --json             print the raw API response instead of one line per item`,
+  },
+  next: {
+    run: next,
+    flags: ['claim', 'source', 'project', 'actor'],
+    usage: `crux next [--claim] [--source <s>] [--project <slug>] [--actor <name>]
+
+Print exactly ONE unmatched item as JSON, oldest first. Exits ${EXIT_EMPTY} when the
+queue is empty, so a polling loop needs no jq:
+
+  crux next --claim --source capture --actor god-agent || exit 0
+
+  --claim            take an exclusive lease first, so two overlapping pollers
+                     never both act on the same item
+  --source <s>       only items from this source; prefer --source capture for
+                     consumers with local side effects (human-typed input only)
+  --project <slug>   only this project's items
+  --actor <name>     recorded on the claim (default: consumer)`,
+  },
+  tail: {
+    run: tail,
+    flags: ['unrouted', 'project', 'topics', 'interval', 'since', 'status', 'actor'],
+    usage: `crux tail [--unrouted | --project <slug>] [--topics <t,…>] [--interval <s>] [--since <ts>]
+
+Watch for new events. Prints ONE flushed single-line JSON record per new event,
+oldest first, and nothing otherwise — silence always means "no new input".
+Runs until killed. The cursor is durable (${CURSOR_FILE.replace(os.homedir(), '~')}),
+so a restart resumes where it left off; delivery is at-least-once.
+
+  --unrouted         the untriaged queue — everything the router couldn't place
+  --project <slug>   one project's feed (mutually exclusive with --unrouted)
+  --topics <t,…>     comma-separated, from: ${TAIL_TOPICS.join(', ')} (default: items)
+  --interval <s>     seconds between polls (default: 60)
+  --since <ts>       start from this cursor/timestamp, overriding the stored one
+  --status <s>       raw status filter, if --unrouted is too blunt
+  --actor <name>     who is listening, announced on every poll and shown as the project's
+                     listener status dot (default: <user>@<host>). Self-asserted, not
+                     authenticated — it is a health signal, not a credential.
+
+  crux tail --unrouted
+  crux tail --project crux --topics items,activities,decisions --actor lead-crux`,
+  },
+  route: {
+    run: route,
+    flags: ['project', 'actor', 'note'],
+    usage: `crux route <id> --project <slug> [--actor <name>] [--note "<why>"]
+
+Triage verb: reassign an item to a project and re-enter the routed flow.
+
+  --project <slug>   destination project (required)
+  --actor <name>     who routed it
+  --note "<why>"     recorded on the activity the route logs`,
+  },
+  done: {
+    run: done,
+    flags: ['note', 'actor', 'drop', 'status'],
+    usage: `crux done <id> [--note "<why>"] [--actor <name>] [--drop] [--status "<phrase>"]
+
+Triage verb: close an item.
+
+Closing a thread you are actually in — one you captured from the app or the web bar, or one you
+have replied on — pushes "Done" to your phone. Fleet housekeeping (a thread you never touched, a
+lead channel) closes silently, and --drop never pushes: dropped is abandoned, not delivered.
+
+  --drop             record it as dropped rather than done — same terminal state
+                     to the queue, different meaning to whoever reads the feed
+  --note "<why>"     recorded on the activity the close logs
+  --actor <name>     who closed it
+  --status "<phrase>"  the thread's RESTING status line — what is true about it now that it is
+                     closed ("merged, closed"), not what it was last doing. Omit it and the
+                     close writes "done" (or "dropped") itself. Closing ALWAYS rewrites the
+                     line, so a finished thread can never sit there still announcing work that
+                     has stopped. (Not to be confused with --drop, which sets the disposition.)`,
+  },
+  cancel: {
+    run: cancel,
+    flags: ['note', 'actor', 'process'],
+    usage: `crux cancel <id> [--note "<why>"] [--actor <name>] [--process <n>]
+
+Stop a thread's worker deliberately — and have the thread say so, instead of announcing a crash.
+
+This is the verb for "the brief is now wrong": the plan changes mid-flight, you stop the
+worker, re-brief, and \`crux spawn\` a new one. The thread stays open. (\`crux done\` is the other
+thing: the thread is finished, and its worker dies with it.)
+
+Stopping a worker by hand with \`solo processes stop\` does NOT do this. Its supervisor cannot see
+intent — only a process that ended having printed nothing, which is exactly what a crash looks like
+— so it posts "Worker failed … it crashed, was killed, or never started" and pushes that to your
+phone. This command leaves a tombstone for that exact worker BEFORE killing it, so the supervisor
+reports a cancellation instead. A worker killed any other way is still reported as dead, loudly, and
+that is on purpose: silence with nobody claiming it remains the bug.
+
+  --note "<why>"     why you stopped it — goes on the thread, and into the supervisor's note.
+                     Worth writing: it is what the next reader (and the next worker) sees.
+  --actor <name>     who cancelled it (default: lead)
+  --process <n>      the Solo process to stop, if the item has none recorded
+
+  crux cancel 74 --note "the approach changed — re-briefing" --actor lead-crux`,
+  },
+  need: {
+    run: need,
+    flags: ['item', 'kind', 'option', 'recommendation', 'where', 'when', 'who', 'actor', 'status'],
+    usage: `crux need --item <id> --kind decide|answer|secret|desk|world [flags] ["<question>"]
+
+Raise a needs-you block on a thread — the typed successor to the raw "NEEDS YOU: …" activity
+the escalations view never rendered. An open block is what makes a thread wait on you, so this
+is the escalation verb. The forcing function: a block may not wait on raw dumped context.
+
+  --item <id>            the thread the block is on (required)
+  --kind <k>             decide | answer | secret | desk | world (required)
+  --option "<label>"     a decide choice — repeat for each option (decide needs ≥1)
+  --recommendation <r>   the suggested option (decide)
+  "<question>"           a one-line framed question (required for every non-decide kind;
+                         positional text, else stdin)
+  --where <w>            phone-ok | desk-required (desk is always desk-required)
+  --when <t>             now | at-time | when-at-desk
+  --who <p>              nobody | an-agent | an-external-person (external trips the
+                         client-comms rule — never auto-answer a client)
+  --actor <name>         the lead/agent raising it
+  --status "<phrase>"    the thread's status line while it waits ("blocked on the DNS answer").
+                         Blocking IS a status change; say so in the same call.
+
+  crux need --item 8 --kind decide --option Hourly --option "Twice daily" --recommendation "Twice daily"
+  crux need --item 8 --kind answer "What does 'term' mean for recurring subs?"`,
+  },
+  accept: {
+    run: accept,
+    flags: ['actor', 'agent-name', 'agent-session-id', 'remote-control-url', 'title', 'status', 'reopen'],
+    usage: `crux accept <id> [--title "<short title>"] [--status "<phrase>"] [--actor <name>] [--reopen]
+                 [--agent-name <n>] [--agent-session-id <id>] [--remote-control-url <url>]
+
+Mark a thread accepted — who picked it up and when. With no open block that is what makes the
+thread read "working"; \`crux done\` clears acceptance again.
+
+This is also where a thread gets its NAME. You have just read it and you are about to work it, so
+you already know what it is called — nothing on the server generates a title, and a thread you
+accept without --title stays untitled forever (its row goes on showing the raw captured text).
+
+A CLOSED thread (done | dropped) is REFUSED. Accepting one used to report success and change
+nothing anyone could see — the board went on saying finished while the thread was worked — so it
+is now an error, and --reopen is how you say you meant it.
+
+  --title "<short title>"     name the thread. A COUPLE OF WORDS ("auth timeout", "invoice
+                              rounding") — it is a name, not a summary, and the row clips it to
+                              one line. This is the row's main line from now on.
+  --status "<phrase>"         the status line under the title — what is happening NOW, one short
+                              phrase ("reading the failing test"). Update it as you work by
+                              passing --status to activity / need / done.
+  --reopen                    bring a done/dropped thread BACK: status → routed, un-archived, and a
+                              "reopened" line on the thread so it records that it came back. Say it
+                              on purpose — for follow-up work on a closed thread, the other honest
+                              answer is a NEW item that links to it.
+  --actor <name>              who (or what) accepted it (default: consumer)
+  --agent-name <n>            the per-thread Claude session name baked in with \`claude -n\`
+  --agent-session-id <id>     the agent's local transcript uuid on this machine
+  --remote-control-url <url>  the agent's claude.ai session — the link crux surfaces
+
+  crux accept 214 --title "auth timeout" --status "reading the failing test" --actor lead-orbit
+  crux accept 100 --reopen --title "hero phone" --status "worker on the follow-up"`,
+  },
+  spawn: {
+    run: spawn,
+    flags: ['project-id', 'tool-id', 'brief', 'actor', 'rc-timeout', 'live', 'wait', 'title', 'status', 'reopen'],
+    usage: `crux spawn <id> --project-id <n> [--tool-id 3] [--brief "<text>"] [--actor <name>] [--wait]
+                [--title "<short title>"] [--status "<phrase>"] [--reopen]
+                [--live [--no-remote-control] [--rc-timeout <seconds>]]
+
+Start the worker for a thread — and make it report and die, rather than trusting it to remember.
+Two modes; the worker is reaped in both.
+
+HEADLESS (default). The agent works the thread, prints its result, and EXITS — its own exit is
+the reap. Its final message is then posted to the thread automatically, by crux, whether the run
+succeeded or died. A worker that fails is announced just as loudly as one that finishes: silence
+is the failure mode this exists to kill.
+
+LIVE (--live). Interactive, with Remote Control on, so you can open the session from the Claude
+app and talk to it. This agent never exits on its own, so its life is bounded by its thread's:
+\`crux done <id>\` stops it. Only this mode gets a claude.ai link (headless mints none).
+
+  --project-id <n>       the Solo project to spawn the agent in (required)
+  --tool-id <n>          Solo agent-tool id (default: 3 — claude --dangerously-skip-permissions)
+  --brief "<text>"       the task. crux wraps it with how the run must end (report / crux need)
+  --actor <name>         recorded as who accepted the thread (default: dispatch)
+  --title "<short title>"  name the thread — a couple of words. Spawning IS accepting (it posts to
+                         the same endpoint), so title it here and you need no separate accept.
+  --status "<phrase>"    the status line while the worker runs ("worker on it")
+  --reopen               spawn onto a done/dropped thread, reopening it first. Without it, a closed
+                         thread is REFUSED before anything is started: a worker whose thread says
+                         "finished" reports where nobody is looking for it.
+  --wait                 (headless) stay in the foreground until the worker reports; exit
+                         non-zero if it failed. Otherwise crux returns as soon as it is up and
+                         a detached supervisor posts the report.
+  --live                 interactive + Remote Control instead of headless
+  --no-remote-control    (live) local-only agent: no claude.ai session, no link, no waiting
+  --rc-timeout <s>       (live) how long to wait for the link before giving up (default: 90)`,
+  },
+  supervise: {
+    run: supervise,
+    flags: ['process', 'project-id', 'actor', 'timeout'],
+    usage: `crux supervise <id> --process <n> [--project-id <n>] [--actor <name>] [--timeout <s>]
+
+Wait for a headless worker to exit, then post its report to the thread. \`crux spawn\` starts this
+for you, detached — you should rarely need to type it.
+
+It exists as a real command because it is the one process whose death would restore the old
+silence. Solo keeps a dead process's output, so pointing this at an already-exited worker still
+recovers its report and posts it, however late.
+
+  --process <n>          the Solo process id of the worker (required)
+  --project-id <n>       narrows the Solo lookup
+  --actor <name>         who the report is attributed to (default: thread-<id>)
+  --timeout <s>          give up waiting and report it hung (default: 28800 — 8h)`,
+  },
+  projects: {
+    run: projects,
+    flags: ['json'],
+    usage: `crux projects [--json]
+
+List projects and their routing keywords.
+
+  --json             print the raw API response`,
+  },
+  leads: {
+    run: leads,
+    flags: ['fix', 'json', 'dry-run'],
+    usage: `crux leads [--fix] [--dry-run] [--json]
+
+Reconcile the standing lead fleet: walk every Solo project and report whether a
+live lead is tailing its crux stream. Coverage is read off the running
+\`crux tail --project <slug>\` command line, never a process name.
+
+Reports three failure classes, not just the happy path:
+
+  uncovered   a Solo project with no lead tailing it
+  orphan      a lead tailing a slug that has no Solo project
+  duplicate   two leads on one slug — the stream is double-processed
+
+plus \`unmapped\` (a Solo project missing from the name→slug map, which is never
+silently skipped) and \`unmanaged\` (registry drift). Exits 1 if any of those
+appear, so it works unattended as a health check.
+
+  --fix              start the solo.yml command for each uncovered project.
+                     Refuses to start a second tail on an already-covered slug.
+  --dry-run          with --fix, print what would start without starting it
+  --json             machine-readable report
+
+The Solo-name→crux-slug mapping is explicit config, not string munging
+(\`acme-search-index\` is \`acme\`; \`status-page\` is \`beacon\`). Override with
+CRUX_LEADS_CONFIG, or ~/.config/crux/leads.json.`,
+  },
+  swarm: {
+    run: swarm,
+    flags: ['backend', 'project', 'dry-run', 'json'],
+    usage: `crux swarm up     [--backend solo|exec|herdr] [--project <slug>]… [--dry-run] [--json]
+       crux swarm status [--backend solo|exec|herdr] [--project <slug>]… [--json]
+       crux swarm down   [--project <slug>]… [--dry-run] [--json]
+
+Spin up standing leads — one per crux project — on your own orchestrator.
+
+A lead is a durable agent that parks on \`crux tail\`, acks each thread that arrives, answers what
+it can, spawns workers for real work, escalates with \`crux need\`, and never exits. \`swarm up\`
+writes the brief that says so (${swarmState.BRIEF_DIR.replace(os.homedir(), '~')}/<slug>.md — read
+it, edit it, it is yours) and starts one lead per uncovered project.
+
+  up        start a lead for every project that has none
+  status    what is covered and what is not (exits 1 if anything is uncovered)
+  down      stop the leads crux started — and ONLY those
+
+BACKENDS ("bring your own orchestration, but ship our own opinions")
+
+Set none of this and crux LOOKS: Solo, then herdr, then tmux (as \`exec\`). \`crux discover\` writes
+what it found into your config, so you can see it and change it. Nothing on your PATH at all is
+said out loud at step zero — never one command later, with a lead you were told to start.
+
+  solo      preferred when installed. Spawns a Solo agent process per lead, creating the Solo
+            project from the repo path if it does not exist. No solo.yml declaration needed.
+  exec      run any command you like — the escape hatch that makes "bring your own" true. With
+            tmux on your PATH and no template set, crux derives this pair for you:
+
+              "swarm": {
+                "backend": "exec",
+                "exec": {
+                  "command": "tmux new-session -d -s {name} '{command}'",
+                  "stop":    "tmux kill-session -t {name}"
+                }
+              }
+
+            Placeholders: ${swarmLib.EXEC_PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}.
+            An unknown one is refused, never expanded to nothing. Set \`stop\` whenever your
+            command forks (tmux, nohup): crux is otherwise left holding a dead pid, and it will
+            tell you so rather than report a lead it did not stop as stopped.
+
+  herdr     herdr.dev — a terminal multiplexer built for coding agents. Each lead becomes a named
+            agent pane you can attach to (\`herdr\`), read, and reattach over ssh after a detach:
+
+              "swarm": { "backend": "herdr", "projects": { "crux": { "repo": "~/src/crux" } } }
+
+            Needs \`herdr\` on PATH and a \`repo\` per project. Starts a headless \`herdr server\`
+            if none is running. Optional \`"herdr": { "session": "crux" }\` puts the leads in a
+            named session, isolated from your own; omit it and they land in the default session,
+            where a bare \`herdr\` shows you the whole swarm.
+
+IDEMPOTENT. \`up\` twice starts nothing the second time. Coverage is read off the OS process
+table (who is really running \`crux tail --project <slug>\`), plus the leads crux started whose
+tail has not appeared yet — two tails on one stream race the cursor and double-deliver every item.
+
+  --backend <b>      solo | exec | herdr. Default: CRUX_SWARM_BACKEND, else config \`swarm.backend\`,
+                     else whatever crux finds on your PATH.
+  --project <slug>   only this project — repeatable. Default: every project.
+  --dry-run          print the plan and start (or stop) NOTHING
+  --json             machine-readable report
+
+Per-project config lives under \`swarm.projects.<slug>\` in the leads config:
+
+  "swarm": { "projects": { "crux": { "repo": "~/src/crux", "brief": "extra context for the lead" } } }
+
+\`repo\` is required for any project your backend cannot locate itself (Solo already knows). A
+project with no repo is REFUSED, loudly — never silently skipped.
+
+  crux swarm up --dry-run                 # see the plan before it touches anything
+  crux swarm up --project crux            # just this one
+  crux swarm status                       # health check, exits 1 if a project has no lead
+  crux swarm down                         # stop what crux started; leave everything else alone`,
+  },
+};
+
+/** Handlers call this so their usage line and `--help` can never drift apart. */
+function usageFor(name) {
+  return `usage: ${COMMANDS[name].usage}`;
+}
+
+/**
+ * `-h` never reaches parseArgs as a key — it isn't `--`-prefixed — so it lands in the
+ * positionals. Both spellings have to be checked, and both before the handler runs: a
+ * handler like tail() would otherwise swallow the flag and drop into its polling loop.
+ */
+function wantsHelp(args) {
+  return 'help' in args || args._.includes('-h');
+}
+
+/**
+ * An unrecognized flag is a typo or a stale invocation, and silently ignoring it is how
+ * `crux tail --help` came to hang. Fail loudly instead.
+ */
+function rejectUnknownFlags(name, args) {
+  const allowed = COMMANDS[name].flags;
+  for (const key of Object.keys(args)) {
+    if (key === '_' || key === 'help' || allowed.includes(key)) continue;
+    fail(`unknown flag "--${key}" for "crux ${name}"\n\n${usageFor(name)}`);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  // `crux`, `crux help`, `crux --help`, `crux -h`
+  if (command === undefined || command === 'help' || (!COMMANDS[command] && wantsHelp(args))) {
+    // `crux help tail` — the same page as `crux tail --help`.
+    const topic = command === 'help' ? args._[1] : undefined;
+    if (topic && COMMANDS[topic]) console.log(COMMANDS[topic].usage);
+    else if (topic) fail(`unknown command "${topic}"\n\n${USAGE}`);
+    else console.log(USAGE);
+    return;
+  }
+
+  const spec = COMMANDS[command];
+  if (!spec) fail(`unknown command "${command}"\n\n${USAGE}`);
+
+  if (wantsHelp(args)) {
+    console.log(spec.usage);
+    return;
+  }
+  rejectUnknownFlags(command, args);
+
+  return spec.run(args);
+}
+
+main().catch((e) => fail(e && e.message ? e.message : String(e)));