@coulb/crux-cli 0.1.0

package/lib/swarm.js

@@ -0,0 +1,628 @@
+'use strict';
+
+/**
+ * `crux swarm` — take a user from "I have crux projects" to "I have standing leads working my
+ * threads", on whatever orchestrator they already run.
+ *
+ * Everything in this file is PURE: no processes, no network, no clock, no filesystem. It decides
+ * what *should* happen; `lib/backends.js` is the only thing allowed to make it happen, and crux.js
+ * does the I/O that feeds this. That split is what makes the refusals testable, and the refusals
+ * are the product.
+ *
+ * ## Why a swarm is not just `crux leads --fix`
+ *
+ * `--fix` can only *start* a lead that a human already hand-declared as a `kind: command` row in
+ * Solo's `solo.yml` — read `planFix()`: every state that is not `uncovered` is an explicit refusal,
+ * and a project with no declaration is refused too. That is correct for a fleet that already exists
+ * and wrong for a member of the public, who has no declarations, no `~/dispatch/leads/*.md`, and
+ * possibly no Solo. `swarm up` builds the missing three things itself: it GENERATES the standing-lead
+ * brief (below), SPAWNS the lead process directly rather than starting a declared one, and does both
+ * through an adapter so the orchestrator is the user's choice.
+ *
+ * ## Coverage is an OS fact, not a backend's opinion
+ *
+ * A lead's identity is not its process name — the name is a label anyone can reuse, and Solo's own
+ * status lies (see the header of `lib/leads.js`). What actually matters is whether *something* is
+ * running `crux tail --project <slug>`, because that is the thing that consumes the stream. So
+ * coverage is read off the OS process table for every backend, and the adapter is never asked. This
+ * is why the `exec` backend gets working reconciliation for free: crux does not need to understand
+ * tmux to see the tail tmux started.
+ *
+ * The one thing the process table cannot tell us is the few seconds between "the agent process is
+ * up" and "the agent has got as far as running its tail". A second `swarm up` inside that window
+ * would see no tail, conclude `uncovered`, and start a SECOND lead — two tails on one stream, racing
+ * the shared cursor file and double-delivering every item. So a lead crux started is also remembered
+ * ({@see ../lib/swarm-state}), and a remembered lead whose process is still alive counts as covered
+ * (`starting`) even before its tail appears. Idempotence needs both halves: the process table alone
+ * misses the boot window, and the state file alone misses every lead crux did not start.
+ */
+
+/** Placeholders an `exec` command template may use. Anything else is a typo, and typos are refused. */
+const EXEC_PLACEHOLDERS = ['slug', 'name', 'repo', 'brief_path', 'command'];
+
+/**
+ * How long a lead may be "up but not yet tailing" before crux calls it STUCK rather than starting.
+ *
+ * There is a real gap between the agent process existing and the agent having got as far as running
+ * `crux tail`, and during it the slug looks uncovered — {@see planUp} treats that as `starting` so a
+ * second `swarm up` cannot double-tail the stream. But "starting" must be able to EXPIRE, because a
+ * lead that never tails is exactly as dead as one that never started, and a state that is green
+ * forever is the silence this whole fleet exists to destroy.
+ *
+ * The failure this caught, live, on the first real run: a lead whose repo is a directory Claude Code
+ * has not seen before sits at the folder-trust prompt indefinitely. `--dangerously-skip-permissions`
+ * does not bypass it. `swarm up` said "1 started", the process was alive, and the swarm was dead —
+ * the precise outcome a stranger would hit on their first run and blame crux for. Generous, because
+ * a slow boot is not a fault: a real lead reaches its tail in well under a minute.
+ */
+const STALL_AFTER_MS = 3 * 60 * 1000;
+
+/** The agent crux runs for a lead when the config does not say otherwise. */
+const DEFAULT_AGENT = 'claude --dangerously-skip-permissions';
+
+/** The lead process name for a slug. Solo names the process this; tmux names the session this. */
+function leadName(slug) {
+  return `lead-${slug}`;
+}
+
+/** The actor a lead announces itself as — its presence dot on /projects, and its byline on replies. */
+function leadActor(slug) {
+  return `lead-${slug}`;
+}
+
+/**
+ * The prompt the lead agent is started with — deliberately tiny, because the CONTRACT lives in the
+ * generated brief on disk {@see renderLeadBrief} where a human can read it, diff it, and edit it.
+ *
+ * It contains no single quote, and that is load-bearing rather than stylistic: an `exec` template
+ * embeds `{command}` inside a single-quoted shell word in the documented tmux example
+ * (`tmux new-session -d -s {name} '{command}'`). One apostrophe here would end that word early and
+ * hand the user a broken shell line. {@see execCommand}, which refuses rather than emit one.
+ */
+function leadPrompt(briefPath) {
+  return (
+    `Read ${briefPath} and follow it exactly. ` +
+    'You are the standing project lead — park on crux tail, handle items, never exit.'
+  );
+}
+
+/**
+ * The full shell command that starts one lead: the user's agent, named, handed the prompt.
+ *
+ * This is what `{command}` expands to in an `exec` template, and what the `solo` backend passes as
+ * `--arg`s. Both backends run the SAME command, which is the point — swapping the orchestrator must
+ * not quietly swap what gets run.
+ */
+function agentCommand({ agent = DEFAULT_AGENT, slug, briefPath }) {
+  return `${agent} -n ${leadName(slug)} "${leadPrompt(briefPath)}"`;
+}
+
+/**
+ * Expand an `exec` template.
+ *
+ * An unknown placeholder is a hard failure, never an empty string. `{brief}` instead of
+ * `{brief_path}` would otherwise start a lead with a truncated command line and no explanation —
+ * and a swarm that silently half-starts is precisely the ambiguity this whole feature exists to
+ * remove. Refuse rather than guess.
+ */
+function renderTemplate(template, vars) {
+  const unknown = [];
+  const out = template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (!Object.hasOwn(vars, key)) {
+      unknown.push(key);
+      return match;
+    }
+    return vars[key];
+  });
+
+  if (unknown.length) {
+    throw new Error(
+      `unknown placeholder${unknown.length > 1 ? 's' : ''} ${unknown.map((u) => `{${u}}`).join(', ')} ` +
+        `in the exec template (valid: ${EXEC_PLACEHOLDERS.map((p) => `{${p}}`).join(', ')})`,
+    );
+  }
+  return out;
+}
+
+/**
+ * The variables an `exec` template may interpolate, for one lead.
+ *
+ * Refuses to build a command containing a single quote. The documented template wraps `{command}` in
+ * a single-quoted shell word, so an apostrophe — reachable only through a configured `agent` or a
+ * repo path — would silently terminate that word and produce a command line that is not the one
+ * anybody wrote. Better to say so than to spawn it.
+ */
+function execVars(lead) {
+  const command = agentCommand({ agent: lead.agent, slug: lead.slug, briefPath: lead.briefPath });
+
+  if (command.includes("'")) {
+    throw new Error(
+      `the command for "${lead.slug}" contains a single quote (${command}) — it cannot be safely ` +
+        "embedded in an exec template, which quotes {command} as '{command}'. Remove the apostrophe " +
+        'from the agent command or the brief path.',
+    );
+  }
+
+  return {
+    slug: lead.slug,
+    name: leadName(lead.slug),
+    repo: lead.repo,
+    brief_path: lead.briefPath,
+    command,
+  };
+}
+
+/**
+ * The standing-lead brief crux ships — the actual product opinion, written down.
+ *
+ * Until now this was folklore: each lead was hand-started with "Read ~/leads/<slug>.md and follow it
+ * exactly", those files were hand-written, they lived outside the repo, and they encoded the entire
+ * operating contract. Nobody but their author could reproduce a swarm from them. So crux generates it, and the generic contract below is the distillation — every
+ * line is here because getting it wrong broke something real:
+ *
+ *   - THE THREE TOPICS. `--topics items,activities,decisions` is not a default worth overriding. A
+ *     human's reply arrives as an *activity* and the answer to a `crux need` arrives as a *decision*;
+ *     an items-only tail hears the question it asked and never the answer, and the thread is one-way.
+ *   - ACK ON RECEIPT, before the work, or the thread reads as idle while it is being worked.
+ *   - `--type note`, because that is what the app renders as a chat bubble; and `--item <id>`, or the
+ *     reply is filed against the project and no item view ever shows it (this made 66 of 70 lead
+ *     answers invisible).
+ *   - `crux need`, never a raw "NEEDS YOU" note — the escalations view never rendered those, and
+ *     a typed block is the only thing that reaches a phone.
+ *   - `crux cancel`, never a bare kill: a killed worker is indistinguishable from a crashed one, and
+ *     a crash note that cries wolf gets the real ones ignored (see briefs/WORKER-CONTRACT.md).
+ *   - NEVER EXIT. A lead that returns is a lead that stops listening, silently.
+ *
+ * What is deliberately NOT here: anybody's projects, private brief directories, or anything about a
+ * particular machine. The per-project facts (repo, what the project is, how to spawn a worker) are
+ * arguments.
+ */
+function renderLeadBrief({ slug, projectName, description, repo, spawn = null, extra = null }) {
+  const actor = leadActor(slug);
+  const title = projectName || slug;
+
+  const lines = [
+    `# Standing lead: ${slug}`,
+    '',
+    `You are the durable PROJECT LEAD for **${title}** (crux slug \`${slug}\`), working in \`${repo}\`.`,
+    'You run forever.',
+    '',
+  ];
+
+  if (description) lines.push(`${description}`, '');
+  if (extra) lines.push(extra, '');
+
+  lines.push(
+    '## Your loop (never exit)',
+    '',
+    '1. Park on the tail. It prints one JSON line per event you should wake on, and NOTHING',
+    '   otherwise — silence is your zero-token parked state, not a reason to poll:',
+    '',
+    `       crux tail --project ${slug} --topics items,activities,decisions --interval 60 --actor ${actor}`,
+    '',
+    '   All three topics are required. A human reply arrives as an **activity**, and the answer to a',
+    '   `crux need` block arrives as a **decision**. On `items` alone you would hear the question and',
+    '   never the answer, and the thread is one-way.',
+    '',
+    `   \`--actor ${actor}\` registers your live presence, so the dashboard can tell "no items" apart`,
+    '   from "the lead is dead" — the failure that once went unnoticed for hours.',
+    '',
+    '2. **PARK DURABLY — read this twice.** Your harness will kill a long-running foreground command',
+    '   when its timeout expires. That is normal, it is not an error, and it is **not the end of your',
+    '   job**: the moment the tail returns, START IT AGAIN. Forever.',
+    '',
+    '   - If you have a persistent monitor/watch facility (Claude Code: the `Monitor` tool), arm it on',
+    '     the command above and let it wake you. That is the cheap, correct way to park.',
+    '   - Otherwise run the tail with the longest timeout your harness allows (e.g. 600000 ms) and',
+    '     re-run it immediately every time it exits.',
+    '',
+    '   A lead whose tail is not running is not a lead. Nothing is consuming the stream, and from the',
+    '   outside that is indistinguishable from "there is no work" — which is exactly how a dead fleet',
+    '   goes unnoticed for hours. Your tail being up IS the job.',
+    '',
+    '3. When a line arrives, handle it (below), then go back to waiting. **Never exit.**',
+    '',
+    '   Delivery is at-least-once — the cursor is durable, so a restart replays rather than drops. An',
+    '   item can therefore repeat. Before acting on an item id, check whether you already logged a',
+    '   `crux activity` for it.',
+    '',
+    '## Handling an item',
+    '',
+    `- **Ack on receipt, and NAME IT.** The instant a thread arrives:`,
+    '',
+    `      crux accept <id> --actor ${actor} --title "<2-3 words>" --status "<what you are doing>"`,
+    '',
+    '  Accept flips the thread out of idle into "working" — do it BEFORE the work, not after, or the',
+    '  thread reads as untouched while you are busy on it.',
+    '',
+    '  `--title` is the thread\'s NAME and it is the row\'s main line from now on. **Nothing generates',
+    '  it but you.** There is no model on the server deriving titles from the captured text — you have',
+    '  just read the thread and you are about to work it, so you already know what it is called, and a',
+    '  thread you accept without `--title` stays untitled forever (its row goes on showing the raw',
+    '  captured text, which is what every unaccepted thread shows). Two or three words: "auth timeout",',
+    '  "invoice rounding". It is a name, not a summary — the row clips it to one line.',
+    '- **Answerable from what you know** → reply as chat:',
+    '',
+    `      crux activity --item <id> --project ${slug} --actor ${actor} --type note "<your answer>" \\`,
+    '          --status "<what is happening now>"',
+    '',
+    '  Always pass `--item <id>`, or the reply is filed against the project and the item view never',
+    '  shows it. `--type note` is what renders as a chat bubble.',
+    '- **Real code or task work** → spawn a worker; do not do long work inside your own loop, or you',
+    '  stop listening while you do it.',
+  );
+
+  if (spawn) {
+    lines.push(
+      '',
+      `      ${spawn}`,
+      '',
+      '  The worker runs HEADLESS: it works the thread, exits, and crux posts its final message back',
+      '  onto this thread automatically — plus a failure note and a push if it crashes or says nothing.',
+      '  Its report wakes you. Relay it, or act on it.',
+    );
+  } else {
+    lines.push(
+      '',
+      '  NOTE: `crux spawn` needs a Solo project id and this swarm is not running on Solo, so worker',
+      '  spawning is unavailable to you. Do the work yourself in the repo above, and keep it short —',
+      '  every minute you spend working is a minute you are not listening.',
+    );
+  }
+
+  lines.push(
+    `- **The human's call** (scope, money, client-facing, irreversible) → raise a typed block:`,
+    '',
+    `      crux need --item <id> --kind decide|answer|secret|desk|world "<one-line question>" \\`,
+    `          --actor ${actor} --status "<why it stopped>"`,
+    '',
+    '  A typed block is the ONLY thing that reaches their phone. A plain activity does not, and a raw',
+    '  "NEEDS YOU:" note is not an escalation — the escalations view cannot render it.',
+    '- **Misrouted** → `crux route <id> --project <other-slug> --note "<why>"`.',
+    '',
+    '## The row is yours to write',
+    '',
+    'Every thread shows up as a ROW: a short **title** on the main line, and under it, smaller and in',
+    'grey, a **status line** — one phrase saying what is happening to it right now.',
+    '',
+    '**You write both. Nothing else does.** The server does not generate them; there is no model on the',
+    'write path re-reading the captured text to guess a title. There does not need to be one — you are',
+    'already an LLM, you have already read the thread, and you already know what you are doing to it.',
+    'Deriving that a second time, from less, would cost more and know less.',
+    '',
+    'So the rule is: **you never make a separate call to update the row.** You carry `--status` on the',
+    'request you were already sending. It is one flag on the verbs you already run:',
+    '',
+    '```',
+    'crux accept  <id> --title "<name>" --status "<phrase>"   # name it as you pick it up',
+    'crux activity --item <id> --status "<phrase>" "<text>"   # ...as you report progress',
+    'crux spawn   <id> --title "<name>" --status "worker on it"',
+    'crux need    --item <id> --status "blocked on the DNS answer" ...',
+    'crux done    <id> --status "merged, closed"              # a RESTING phrase — see below',
+    '```',
+    '',
+    'That is why a status line cannot go stale: you set it AS you work, so it always says what you last',
+    'said it says. A status line the server derived would be wrong the moment you did the next thing.',
+    '',
+    'Keep it short and keep it TRUE-NOW ("running the migration", not "will fix the migration"). On',
+    '`crux done` the status line should describe REST, not work — "merged, closed", "shipped", "not',
+    'reproducible". Omit it there and crux writes "done" (or "dropped") itself; either way a closed',
+    'thread never sits there still announcing work that stopped hours ago.',
+    '',
+    '## A closed thread refuses to be worked',
+    '',
+    '`crux done` is a real ending. A `done` or `dropped` thread will not let you `accept` it, `spawn`',
+    'onto it, or raise a `need` on it — all three exit non-zero and tell you so. This is not pedantry:',
+    'accepting a closed thread used to report success and change nothing anyone could see, so the board',
+    'went on saying **finished** while a worker built on it and reported into a thread nobody reads.',
+    '',
+    'Follow-up work on a thread you already closed is one of two things, and you say which:',
+    '',
+    '```',
+    'crux push --project <slug> "…follow-up, from #<id>"   # usually this: new work, new thread',
+    'crux accept <id> --reopen --title "…" --status "…"    # or bring the old one back, on purpose',
+    'crux spawn  <id> --reopen --project-id <n> --brief …  # same flag, if a worker goes straight on',
+    '```',
+    '',
+    '`--reopen` flips the thread back to `routed`, un-archives it, drops the resting status line, and',
+    'writes a **reopened** line onto the thread — so it reads `done` → `reopened` → `accepted`, and',
+    'never "finished, with a worker attached".',
+    '',
+    '## Hard rules',
+    '',
+    '- **Finish means CLOSED.** The moment a thread is handled:',
+    '  `crux done <id> --note "<why>" --status "<resting phrase>"` (`--drop` for won\'t-do). An unclosed',
+    '  thread reads as still-in-progress forever.',
+    '- **Do not work a closed thread.** Push a new item, or `accept --reopen` and mean it. See above.',
+    '- **Stop a worker with `crux cancel <id> --note "<why>"`, never a bare kill.** A killed worker is',
+    '  indistinguishable from a crashed one — the supervisor sees a process that ended having printed',
+    '  nothing, and posts "Worker failed" to the thread with a push. `crux cancel` leaves a tombstone',
+    '  first, so the death is reported as deliberate. A crash note that cries wolf gets the real ones',
+    '  ignored.',
+    '- **A blocked worker must block LOUDLY.** Headless means nobody is watching its prompt. If it is',
+    '  stuck it must `crux need`; waiting silently is death, not patience.',
+    '- **Never post to external services** (Slack, email, GitHub comments). `crux activity` is your',
+    '  reporting channel. Client-facing asks are always human-in-the-loop: escalate, never answer.',
+    `- **Stay inside \`${repo}\`** (worktrees included). Never commit secrets.`,
+    '- **Never exit.** You are a standing lead. Returning is the one thing you may not do.',
+    '',
+    '---',
+    '',
+    'Generated by `crux swarm up`. Edit this file and restart the lead to change the contract.',
+    '',
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Decide what `swarm up` starts, and what it refuses.
+ *
+ * The refusals are not an error path, they are the feature. A project that cannot be brought up is
+ * NAMED and EXPLAINED, never silently skipped — a project that quietly falls out of the plan is the
+ * exact failure `crux leads` was built to catch, and re-introducing it here would be worse, because
+ * `swarm up` is what a stranger runs on their first day and believes.
+ *
+ * @param {object} input
+ * @param {Array<{slug, repo, description, leadless, extra}>} input.candidates resolved projects
+ * @param {Array<{pid, slug}>} input.tails every `crux tail` the OS reports, from lib/leads
+ * @param {Array<{slug, ref, alive, started_at}>} input.started what crux swarm previously started,
+ *   and whether that process is still alive per its backend
+ * @param {string[]|null} input.only restrict to these slugs (`--project`)
+ * @param {number} input.now epoch ms — injected, so a stalled lead is testable without waiting
+ */
+function planUp({ candidates, tails, started = [], only = null, now = Date.now() }) {
+  const starts = [];
+  const refusals = [];
+  const skips = [];
+
+  const bySlug = new Map();
+  for (const tail of tails) {
+    if (typeof tail.slug !== 'string' || tail.slug === '') continue;
+    if (!bySlug.has(tail.slug)) bySlug.set(tail.slug, []);
+    bySlug.get(tail.slug).push(tail);
+  }
+
+  const aliveStart = new Map(started.filter((s) => s.alive).map((s) => [s.slug, s]));
+
+  const wanted = only ? candidates.filter((c) => only.includes(c.slug)) : candidates;
+
+  // `--project nope` must not quietly do nothing and report success.
+  if (only) {
+    for (const slug of only) {
+      if (!candidates.some((c) => c.slug === slug)) {
+        refusals.push({
+          slug,
+          reason: `no crux project "${slug}" — \`crux projects\` lists the slugs that exist.`,
+        });
+      }
+    }
+  }
+
+  for (const candidate of wanted) {
+    const { slug } = candidate;
+    const own = bySlug.get(slug) ?? [];
+
+    if (typeof candidate.leadless === 'string') {
+      skips.push({ slug, state: 'leadless', detail: candidate.leadless });
+      continue;
+    }
+
+    if (own.length > 1) {
+      refusals.push({
+        slug,
+        reason:
+          `${own.length} tails are already on "${slug}" (pids ${own.map((t) => t.pid).join(', ')}) — ` +
+          'the stream is being double-read. Starting a third would make it worse. Investigate first.',
+      });
+      continue;
+    }
+
+    if (own.length === 1) {
+      skips.push({
+        slug,
+        state: 'covered',
+        detail: `pid ${own[0].pid} is already tailing "${slug}". Nothing to do.`,
+      });
+      continue;
+    }
+
+    // No tail yet — but if WE started this lead and its process is still up, it may simply still be
+    // booting. Starting another one here is how you get two tails on one stream.
+    const booting = aliveStart.get(slug);
+    if (booting) {
+      // A lead that HAS tailed before and is not tailing this second is between restarts, not stuck:
+      // its harness kills the foreground tail at a timeout and the brief tells it to start another.
+      // Never start a second lead here — the live one owns this slug and will bring its own tail
+      // back. But never call it green either, because a lead that stops restarting its tail looks
+      // exactly like this, and "the tail is down" is the one thing that must not pass unremarked.
+      if (booting.everTailed) {
+        skips.push({
+          slug,
+          state: 'tail-down',
+          detail:
+            `the lead (${booting.ref}) is alive and HAS tailed before, but nothing is tailing "${slug}" ` +
+            'right now — it is most likely between tail restarts. Not starting a second lead. If this ' +
+            'persists, read the lead\'s output: it has stopped restarting its tail.',
+        });
+        continue;
+      }
+
+      const age = now - Date.parse(booting.started_at ?? '');
+      const stalled = Number.isFinite(age) && age > STALL_AFTER_MS;
+
+      if (!stalled) {
+        skips.push({
+          slug,
+          state: 'starting',
+          detail:
+            `crux started this lead (${booting.ref}) and its backend still reports it up, but its ` +
+            'tail has not appeared yet. Leaving it alone rather than starting a second one.',
+        });
+        continue;
+      }
+
+      // Alive, but it has never reached its tail. It is stuck BEFORE the thing it exists to do, and
+      // a lead that is not tailing is not a lead. Do not start a second one — it would stall in
+      // exactly the same place — and above all do not keep calling this green.
+      refusals.push({
+        slug,
+        state: 'stalled',
+        reason:
+          `its lead (${booting.ref}) has been up for ${Math.round(age / 60000)}m and has NEVER started ` +
+          `its tail — it is stuck before \`crux tail --project ${slug}\`, so nothing is consuming the ` +
+          'stream. The usual cause is the agent sitting at a prompt: Claude Code asks you to trust a ' +
+          "directory it has not seen before, and `--dangerously-skip-permissions` does NOT skip that " +
+          `one. Read its output, or run \`claude\` once in the repo and accept the folder. Not starting ` +
+          `a second lead (it would stall too) — \`crux swarm down --project ${slug}\` clears it.`,
+      });
+      continue;
+    }
+
+    if (!candidate.repo) {
+      refusals.push({
+        slug,
+        reason:
+          `no repo path for "${slug}" — a lead has to run somewhere. Add ` +
+          `\`swarm.projects.${slug}.repo\` to the config, or give it a project on your backend.`,
+      });
+      continue;
+    }
+
+    // The config says the lead works in one place; the backend would run it in another. A lead whose
+    // brief names a repo it is not actually standing in will read the wrong code, write to the wrong
+    // tree, and report on work it never did — and every symptom of that points somewhere other than
+    // the config line that caused it. Say it now, plainly, rather than start it wrong.
+    if (candidate.repoConflict) {
+      const { backend, declared, project } = candidate.repoConflict;
+      refusals.push({
+        slug,
+        state: 'repo-conflict',
+        reason:
+          `your backend already has a project for "${slug}"${project ? ` (id ${project.id})` : ''} and ` +
+          `runs its agents in ${backend}, but \`swarm.projects.${slug}.repo\` says ${declared}. The ` +
+          'backend decides the working directory, so the lead would run in the first path while its ' +
+          'brief tells it the second — point both at the same place, or drop the backend project and ' +
+          'let `crux swarm up` recreate it from your repo.',
+      });
+      continue;
+    }
+
+    starts.push(candidate);
+  }
+
+  return { starts, refusals, skips };
+}
+
+/**
+ * Decide what `swarm down` stops.
+ *
+ * It stops ONLY what `swarm up` started, and that restraint is the whole design. The machine this
+ * runs on may already have a hand-rolled fleet on it, and a `down` that swept every
+ * `crux tail` it could find would take out leads it knows nothing about, cannot restart, and was
+ * never asked to touch. So a running lead that is not in crux's state file is reported and left
+ * alone, loudly, rather than either killed or ignored.
+ *
+ * Each entry carries its OWN `addresses`, rather than the plan taking one for the whole run: the
+ * state file can legitimately hold leads from more than one backend (a user who moved from solo to
+ * exec, mid-swarm), and how a lead can be named is a property of the backend that started it — not
+ * of the backend that happens to be selected today.
+ *
+ * @param {object} input
+ * @param {Array<{slug, ref, backend, alive, addresses}>} input.started state file, liveness resolved
+ * @param {Array<{pid, slug}>} input.tails every `crux tail` the OS reports
+ * @param {string[]|null} input.only restrict to these slugs (`--project`)
+ */
+function planDown({ started, tails, only = null }) {
+  const stops = [];
+  const refusals = [];
+  const skips = [];
+
+  const mine = new Set(started.map((s) => s.slug));
+  const tailed = new Set(tails.filter((t) => typeof t.slug === 'string').map((t) => t.slug));
+  const wanted = only ? started.filter((s) => only.includes(s.slug)) : started;
+
+  if (only) {
+    for (const slug of only) {
+      if (!mine.has(slug)) {
+        refusals.push({
+          slug,
+          reason:
+            `crux swarm did not start a lead for "${slug}" — it is not in the state file, so there ` +
+            'is nothing here to stop. Refusing to guess at a process crux does not own.',
+        });
+      }
+    }
+  }
+
+  for (const entry of wanted) {
+    if (entry.alive) {
+      stops.push(entry);
+      continue;
+    }
+
+    // The process crux started is gone. Whether that means the LEAD is gone depends entirely on how
+    // the backend can name it.
+    const stillTailing = tailed.has(entry.slug);
+
+    if (!stillTailing) {
+      skips.push({
+        slug: entry.slug,
+        state: 'already-gone',
+        detail: `its ${entry.backend} process (${entry.ref}) has already exited. Forgetting it.`,
+      });
+      continue;
+    }
+
+    // A durable handle (a Solo process id, a tmux session name) still addresses a live lead even
+    // when the pid crux happened to spawn has moved on. Stop it.
+    if (entry.addresses === 'handle') {
+      stops.push(entry);
+      continue;
+    }
+
+    // A pid is the only handle this backend has, and it is dead — yet the lead is demonstrably still
+    // running, because its tail is. This is exactly what a forking template (`tmux new-session -d`)
+    // does. crux cannot address it, and reporting an un-stopped lead as stopped is the one outcome
+    // worse than failing: the user would walk away believing the swarm is down.
+    refusals.push({
+      slug: entry.slug,
+      reason:
+        `the ${entry.backend} process crux started (pid ${entry.ref}) has exited, but "${entry.slug}" ` +
+        'is still being tailed — the lead outlived it. That is what a forking command template ' +
+        '(`tmux new-session -d`, `nohup … &`) does: crux is left holding a dead pid. Set ' +
+        '`swarm.exec.stop` (e.g. "tmux kill-session -t {name}") so crux can name the lead instead ' +
+        'of the process, then run `crux swarm down` again. Nothing was stopped.',
+    });
+  }
+
+  // A tail crux did not start is somebody else's lead. Say so; never kill it.
+  if (!only) {
+    for (const tail of tails) {
+      if (typeof tail.slug !== 'string' || tail.slug === '') continue;
+      if (mine.has(tail.slug)) continue;
+      skips.push({
+        slug: tail.slug,
+        state: 'not-ours',
+        detail: `pid ${tail.pid} tails "${tail.slug}" but crux swarm did not start it — left running.`,
+      });
+    }
+  }
+
+  return { stops, refusals, skips };
+}
+
+module.exports = {
+  DEFAULT_AGENT,
+  EXEC_PLACEHOLDERS,
+  STALL_AFTER_MS,
+  agentCommand,
+  execVars,
+  leadActor,
+  leadName,
+  leadPrompt,
+  planDown,
+  planUp,
+  renderLeadBrief,
+  renderTemplate,
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@coulb/crux-cli",
+  "version": "0.1.0",
+  "description": "Run a swarm of standing agent leads from the terminal — capture work, route it, brief a worker, and get told when it needs you.",
+  "keywords": [
+    "crux",
+    "agents",
+    "ai",
+    "claude",
+    "swarm",
+    "orchestration",
+    "cli"
+  ],
+  "homepage": "https://github.com/DanielCoulbourne/crux-cli#readme",
+  "bugs": "https://github.com/DanielCoulbourne/crux-cli/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanielCoulbourne/crux-cli.git"
+  },
+  "license": "MIT",
+  "author": "Daniel Coulbourne",
+  "bin": { "crux": "./crux.js" },
+  "files": [
+    "crux.js",
+    "lib/",
+    "leads.config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {}
+}