@coulb/crux-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Coulbourne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,405 @@
+# crux
+
+**Agent orchestration for one operator (with a life).**
+
+Crux runs a **standing lead** on every project you give it — a durable agent that parks on the
+project's stream, picks up each thread as it arrives, answers what it can, spawns a headless worker
+for the code, and reaches your phone only when the call is actually yours.
+
+This is the CLI. It is the interface: every verb below is one an agent (or you) drives crux with.
+
+## Install
+
+```bash
+npm install -g @coulb/crux-cli
+```
+
+Node 18+. Zero dependencies. The installed command is `crux`.
+
+## Config
+
+Point the CLI at your Crux API and give it a token. Resolution order:
+
+1. env `CRUX_API_URL` / `CRUX_API_TOKEN`
+2. `~/.config/crux/config.json`:
+
+```json
+{ "url": "https://crux.coulb.com", "token": "…" }
+```
+
+The token is your API bearer token — never commit it.
+
+## First run — three commands
+
+```bash
+cd ~/src/acme
+crux discover              # this repo is now a crux project
+crux swarm up              # a standing lead is now working it
+crux push "the importer keeps timing out"    # give it something to do
+```
+
+That is the whole loop: a project, a lead on it, and work going in. Everything below is detail.
+
+## `crux discover` — step zero
+
+A repo becomes a crux project. Run this before anything else on this page:
+
+```bash
+cd ~/src/acme
+crux discover              # Enter, Enter, Enter
+crux swarm up              # a standing lead is now working it
+crux push "…"              # give it something to do
+```
+
+```console
+$ crux discover
+Found ~/src/acme — a Laravel app.
+
+slug [acme]
+name [Acme]
+color (emerald violet sky amber rose pink zinc) [emerald]
+keywords [acme,laravel,php]
+repo [/Users/you/src/acme]
+
+✓ acme is a crux project — created.
+  repo    ~/src/acme
+  config  ~/.config/crux/leads.json — swarm.projects.acme.repo added
+  lead    not started
+
+  Next:  crux swarm up --project acme
+```
+
+**It does not ask what it can read.** The repo path comes from git (a subdirectory still finds the
+root). The name comes from the `origin` remote, then `package.json` / `composer.json`, then the
+directory. The framework comes from the manifests — a lead that knows it is standing in a Laravel app
+writes better briefs, and "laravel" becomes a routing keyword. The **keywords** are what route a
+captured item to this project, so they are the line worth reading before you press Enter.
+
+It writes **both** places, and needs both: the project (`POST /api/projects` — so it exists in the
+feed, the app and the web) and `swarm.projects.<slug>.repo` in the leads config, so that `crux swarm
+up` knows which repo the lead runs in. A project with no repo cannot be led. If the config is not
+writable it says so and creates neither.
+
+**Idempotent.** Run it twice and you get one project and one config entry. A second run reports
+`unchanged` — and means it; `created` and `updated` name what actually changed. 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). Every refusal names its fix.
+
+```bash
+crux discover ~/src/acme --yes            # every default, no questions
+crux discover ~/src/acme --slug orbit     # register it under a slug of your choosing
+crux discover ~/src/acme --json           # machine output (implies --yes)
+```
+
+## Usage
+
+```bash
+crux push "The acme importer keeps timing out — bump the worker timeout?"    # auto-routes
+crux push --project crux --source agent "CLI smoke test from lead agent"     # explicit project
+crux activity --project crux --actor lead "Shipped items API + CLI"
+echo '{ "source":"github", "title":"…", "format":"quick" }' | crux decide
+crux feed --project crux
+crux projects
+```
+
+`push` returns the item id and the project it routed to. When `--project` is omitted the API
+routes by keyword (or Haiku, if `ANTHROPIC_API_KEY` is set on the server).
+
+## Draining the unrouted queue
+
+```bash
+crux next --claim --actor god-agent || exit 0   # exits 3 when the queue is empty
+crux route <id> --project <slug> [--note "why"] # reassign; re-enters the routed flow
+crux done  <id> [--note "why"] [--drop]         # close it (--drop = dropped, not done)
+```
+
+`--claim` takes an exclusive lease first, so two overlapping pollers never both act on the
+same item. `--actor` is recorded on the claim and on every activity the verbs log.
+
+## `--title` and `--status` — the row a thread shows up as
+
+A thread renders as a **row**: a short **title** on the main line, and under it, smaller and grey, a
+**status line** — one phrase saying what is happening to it *right now*.
+
+**The lead sets both. Nothing generates them.** There is no model on the write path deriving a title
+from the captured text, and there is not going to be one: the lead is already an LLM, it has already
+read the thread, and it already knows what it is doing to it. Re-deriving that server-side would pay
+twice for worse information — and a *derived* status line goes stale the instant the lead does the
+next thing, which a set one cannot, because the lead sets it **as it works**.
+
+So there is no "update the row" call. `--status` rides the request the lead was already making:
+
+```bash
+crux accept  214 --title "auth timeout" --status "reading the failing test" --actor lead-orbit
+crux activity --item 214 --project orbit --type note "found it — the retry has no ceiling" \
+     --status "patching the retry loop"
+crux spawn   214 --project-id 7 --title "auth timeout" --status "worker on it" --brief "…"
+crux need    --item 214 --kind decide --status "blocked on the retry policy" --option … --option …
+crux done    214 --note "shipped in #91" --status "merged, closed"
+```
+
+| flag | on | is |
+|---|---|---|
+| `--title "<2-3 words>"` | `accept`, `spawn` | the thread's **name** — the row's main line. Set it once, when you pick the thread up. It is a name, not a summary; the row clips it to one line. |
+| `--status "<phrase>"` | `accept`, `activity`, `need`, `spawn`, `done` | what is happening **now**. Carried on whatever you were already sending. |
+
+Two rules worth knowing:
+
+- **`--status` on `activity` needs `--item`.** A status line belongs to a *thread*, and an activity
+  without `--item` is filed against the project as a whole — so there is nothing to set it on. That is
+  refused (422) rather than silently dropped, because it is exactly the shape of a lead that forgot
+  `--item`, and a quietly discarded status line would leave it thinking the row had updated.
+- **`crux done` always rewrites the status line.** A closed thread must not sit there still announcing
+  work that stopped hours ago — nothing will ever correct it, since a closed thread gets no more
+  writes. Pass a **resting** phrase (`--status "merged, closed"`); omit it and the close writes `done`
+  (or `dropped`) itself. Note this `--status` is the status *line*, not the disposition — `--drop` is
+  what makes it dropped.
+
+**Untitled threads render exactly as they always have.** Every thread that predates this feature has
+no title, and no thread has one before a lead accepts it — those rows go on showing the captured text,
+and a thread with no status line shows no second line at all (never a blank grey strip). A lead that
+never passes `--title` is not broken, it is just leaving its rows unnamed.
+
+## `crux spawn` — a worker that reports and dies
+
+```bash
+crux spawn <id> --project-id <n> --brief "<the task>"   # headless: reports, then exits
+crux spawn <id> --project-id <n> --live                 # interactive + Remote Control
+```
+
+Headless is the default. The worker runs under `claude -p`, so **its final message IS its report** —
+`crux supervise` (started for you, detached) waits for it to exit and posts that message to the
+thread. The agent does not choose to report and cannot forget to.
+
+**A run ends in exactly one of three ways** — full contract in [the worker contract](https://crux.coulb.com/docs/worker-contract):
+
+| Ending | Thread gets | Pushes to you? |
+|---|---|---|
+| **reported** | the agent's final message, verbatim | no |
+| **died** | **Worker failed — …** | **yes** |
+| **cancelled by lead** | **Worker cancelled by … Not a crash.** | no |
+
+**Silence is the bug.** A worker whose process ends having printed nothing gets a loud failure note
+and a phone push — otherwise the thread waits on a dead agent forever.
+
+## `crux cancel` — stop a worker on purpose
+
+```bash
+crux cancel <id> --note "the approach changed" --actor lead-crux
+```
+
+Use this — **never `solo processes stop`** — when you need to stop a worker mid-flight (the brief
+turned out to be wrong, the approach changed). The supervisor cannot see intent, only a process that
+ended having printed nothing, *which is exactly what a crash looks like*. Killing a worker by hand
+therefore posts "Worker failed … it crashed, was killed, or never started" and pushes it to your
+phone, for a run in which nothing failed.
+
+`crux cancel` writes a **tombstone** — keyed by item id **and** Solo process id — *before* it stops
+the process, so the supervisor reports a cancellation rather than a death, silently. The thread stays
+**open**: re-brief and `crux spawn` again. (`crux done` is the other thing — the thread closes and
+its worker dies with it.)
+
+A worker killed with no tombstone is still reported as a crash. That is deliberate: an unclaimed
+silence is the one thing the supervisor exists to catch.
+
+## `crux tail` — push-style events
+
+A long-running watcher. It prints **one flushed single-line JSON record per new event**,
+oldest first, and **nothing at all** otherwise — silence always means "no new input". Arm it
+under Claude Code's Monitor and an agent is woken by real Crux input instead of burning
+tokens on an agentic poll.
+
+```bash
+crux tail --unrouted            # triage: everything the router couldn't place
+crux tail --project crux        # a project lead: its own feed
+crux tail --topics items,activities --project crux --interval 30
+```
+
+```json
+{"topic":"item.created","id":8,"project":null,"summary":"the faucet is dripping again","ts":"2026-07-09T01:31:05+00:00","cursor":9,"status":"unmatched","source":"cli"}
+```
+
+The record is a **pointer, not a payload** — fetch details with `crux feed --json` or the API.
+Items carry `status` and `source`; activities carry `actor` and `type`, so a consumer can skip
+the events it caused itself rather than wake on its own echo.
+
+- **Durable cursor.** Position is saved to `~/.config/crux/tail-cursor.json`, keyed by
+  (server, topics, project, status), so a restart resumes exactly where it left off and two
+  tails never fight. Every read-modify-write of that shared file is serialised under a lock, so
+  concurrent tails cannot lose each other's advances. Written after the lines are flushed, so
+  delivery is **at-least-once** — a consumer that acts on events must be idempotent.
+- **First run starts from now.** No history is replayed. Pass `--since <timestamp>` to start
+  from an instant instead.
+- **Errors never reach stdout.** Transient API failures are retried with backoff and logged to
+  stderr; a 4xx (bad cursor, revoked token) exits rather than spinning.
+- **`--interval` defaults to 60s.** See the hibernation note in `STATUS-cli.md`.
+- **Every poll announces the listener.** `--actor <name>` (default `<user>@<host>`) and the poll
+  interval ride along as headers, and the dashboard turns them into a per-project status dot.
+  The name is **self-asserted and advisory, not a credential** — it is a health signal, nothing
+  is authorised on it. Set it to the lead's name in `solo.yml`: `--actor lead-mercury`.
+
+## `crux leads` — is the fleet actually alive?
+
+A dead lead and an idle one both produce silence. This tells them apart: it walks every Solo
+project and reports whether a live lead is tailing its crux stream.
+
+```bash
+crux leads                # report; exits 1 if anything is uncovered
+crux leads --json         # machine-readable, for a health check
+crux leads --fix          # start the solo.yml command for each uncovered project
+crux leads --fix --dry-run
+```
+
+Coverage is read off the running `crux tail --project <slug>` command line, found by walking the
+process tree beneath each Solo process — **never** off a process name. Names lie: the stopped
+`kind: agent` rows are named exactly like the new `kind: command` ones.
+
+It reports three failure classes, not just the happy path:
+
+| state | meaning |
+|---|---|
+| `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 |
+| `unmapped` | a Solo project missing from the name→slug map, never silently skipped |
+| `unmanaged` | a crux slug with no Solo project and no lead (registry drift; a warning) |
+| `leadless` | configured to expect no lead, e.g. `personal`. Expected, not an error. |
+
+`--fix` only ever starts leads for `uncovered` projects, and **refuses** to start a second tail on
+a slug that is already covered.
+
+The Solo-name→crux-slug mapping is explicit config, not string munging (`acme-search-index` is
+`acme`; `status-page` is `beacon` — no transformation derives either one, which is why the map is
+explicit and an unmapped project is reported rather than guessed at). It lives in
+`~/.config/crux/leads.json`, or wherever `CRUX_LEADS_CONFIG` points.
+
+## `crux swarm` — go from "I have crux projects" to "I have leads working them"
+
+> **The full guide is [Running a swarm](https://crux.coulb.com/docs/swarm)** — what a swarm is, getting one up, the
+> backends, the config, and the traps. What follows is the CLI-level summary.
+
+`crux leads` tells you whether a fleet is alive. `crux swarm` **creates one**, on whatever
+orchestrator you already run.
+
+```bash
+crux swarm up --dry-run     # print the plan; start nothing
+crux swarm up               # start a lead for every project that has none
+crux swarm status           # what's covered, what isn't (exits 1 if anything is uncovered)
+crux swarm down             # stop the leads crux started — and only those
+```
+
+A **lead** is a durable agent that parks on `crux tail`, acks each thread the moment it arrives,
+answers what it can as chat, spawns workers for real work, escalates with `crux need`, and never
+exits. `swarm up` writes the brief that says all of that (`~/.config/crux/leads/<slug>.md` — read
+it, edit it, it's yours) and starts one lead per uncovered project.
+
+That brief is the actual product. It used to be folklore: hand-written files in a private
+directory, encoding the whole operating contract, that nobody but their author could reproduce.
+Now crux generates it, from your project registry and your config — no private brief directory, no
+baked-in paths, nothing of anyone else's machine in it.
+
+### Backends — bring your own orchestration
+
+| backend | what it does |
+|---|---|
+| `solo` | **the default.** Spawns a [Solo](https://soloterm.com) agent per lead, *creating the Solo project from your repo path if it doesn't exist*. No declaration needed — this is what `crux leads --fix` cannot do. |
+| `exec` | **the escape hatch.** Runs any command you give it. This is what makes "bring your own orchestration" true rather than a slogan. |
+
+**Solo is the one we run.** [Solo](https://soloterm.com) is a terminal workspace for the processes
+and agents you already keep running, and on it the entire swarm config is:
+
+```json
+"swarm": { "backend": "solo" }
+```
+
+No repo paths, no declarations. Solo already records a path per project, so `crux swarm up` works
+with nothing configured at all — and when the Solo project doesn't exist yet, the backend creates it
+from your repo path rather than refusing. Each lead lands as a named agent process (`lead-acme`) you
+can open, read, and talk to.
+
+`exec` takes a command template and fills in the blanks:
+
+```json
+"swarm": {
+  "backend": "exec",
+  "exec": {
+    "command": "tmux new-session -d -s {name} '{command}'",
+    "stop":    "tmux kill-session -t {name}"
+  },
+  "projects": { "crux": { "repo": "~/src/crux", "brief": "extra context for this lead" } }
+}
+```
+
+Placeholders: `{slug}` `{name}` `{repo}` `{brief_path}` `{command}`. An unknown one is **refused**,
+never expanded to nothing — a swarm that silently half-starts is worse than one that won't start.
+
+**Set `stop` whenever your command forks** (`tmux new-session -d`, `nohup … &`). Those exit
+immediately, so the pid crux recorded is a dead handle to a live lead. With `stop`, crux addresses
+the lead by name and can still kill it; without it, `crux swarm down` tells you it could not, rather
+than reporting a lead it never stopped as stopped.
+
+### It is idempotent, and that is the whole design
+
+Run `swarm up` twice and the second run starts nothing. 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" — a reconciliation, not a spawn.
+
+Coverage is read off the **OS process table** (who is really running `crux tail --project <slug>`),
+never off a backend's opinion — Solo's own status lies, and tmux has no idea what a crux slug is.
+That's why `exec` gets working reconciliation for free. Plus one thing the process table can't see:
+a lead crux started whose tail hasn't come up *yet*. Without that, a second `up` inside the boot
+window would double-tail the stream.
+
+An agent multiplexer *could* have answered instead — the good ones track real agent status (idle /
+working / blocked) — and one still doesn't get asked, for a precise reason. A healthy lead parked on
+`crux tail` is doing nothing, so it gets called `idle`; a lead frozen at Claude Code's folder-trust
+prompt is *also* doing nothing, so that gets called `idle` too. The two states that matter most are
+indistinguishable to it, and the process table separates them cleanly. A backend's own status is
+shown as detail; it is never what crux believes.
+
+| state | meaning |
+|---|---|
+| `covered` | something is tailing this slug. Nothing to do. |
+| `starting` | crux started this lead; its process is alive but its tail hasn't appeared yet. |
+| `tail-down` | it's alive and has tailed before — it's between tail restarts. Not a new lead. |
+| `stalled` | **alive, but it has NEVER tailed.** A dead swarm that looks alive. See below. |
+| `leadless` | configured to expect no lead. Expected, not an error. |
+| refusals | no repo path; a duplicate tail; a repo that disagrees with the backend's. |
+
+Nothing is ever silently skipped. Every project crux won't bring up is named, with the reason.
+
+### The one thing that will bite you first
+
+Claude Code asks you to trust a directory it has never seen — and
+`--dangerously-skip-permissions` **does not skip that prompt**. A lead started in an untrusted repo
+sits at it forever: the agent is alive, the swarm is dead, and the only symptom is silence.
+
+So crux watches for it. A lead that has been up for three minutes and has never started its tail is
+reported `stalled`, with the cause, and `swarm up` refuses to start a second one on top of it
+(it would stall in exactly the same place). To fix: run `claude` once in the repo and accept the
+folder, then `crux swarm down --project <slug>` and `up` again.
+
+### Config
+
+Everything lives under `swarm` in the leads config (`~/.config/crux/leads.json`, or
+`CRUX_LEADS_CONFIG`, or the template that ships with the package):
+
+| key | |
+|---|---|
+| `backend` | `solo` (default) or `exec`. Override per-run with `--backend`, or `CRUX_SWARM_BACKEND`. |
+| `agent` | the command an `exec` lead runs. Default `claude --dangerously-skip-permissions`. |
+| `solo.agentToolId` | the Solo agent tool to spawn. Default `3` (claude). |
+| `exec.command` / `exec.stop` | the templates above. |
+| `projects.<slug>.repo` | where that lead works. **Required** for any project your backend can't locate itself — Solo already records a path per project, so a Solo user needs none of this. |
+| `projects.<slug>.brief` | extra context pasted into that lead's generated brief. |
+
+`crux swarm down` stops **only** what `crux swarm up` started (it's tracked in
+`~/.config/crux/swarm.json`). A lead you started by hand is reported and left running — crux will
+not kill a process it did not start and cannot restart.
+
+## Tests
+
+```bash
+npm test      # node:test — the reconciliation classifiers, the cursor lock, and `crux swarm`
+              # end-to-end against a stub Solo and a stub API
+```