quorum-orchestrator 0.1.0__tar.gz

quorum_orchestrator-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check .
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --all-extras
+      # Unit tests only; test_sandbox.py covers the nono glue with a fake
+      # nono_py (fail-closed behavior, capability derivation, exec mapping).
+      - run: uv run pytest -m "not nono_integration"
+
+  # Real sandbox enforcement: installs the actual nono-py wheel and verifies
+  # the kernel enforces the capability set quorum derives — allowed writes
+  # succeed, out-of-capability writes fail, project dirs are read-only, and
+  # Mode 2/3 work end-to-end. GitHub's ubuntu runners have Landlock enabled,
+  # and the support gate below fails loudly if that ever changes, so these
+  # tests can never silently self-skip in CI.
+  nono-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --locked --extra nono
+      - name: Assert sandbox support on this runner
+        run: |
+          uv run python - <<'EOF'
+          import sys
+          import nono_py
+          info = nono_py.support_info()
+          print(info)
+          sys.exit(0 if info.is_supported else 1)
+          EOF
+      - run: uv run pytest -m nono_integration -v -ra

quorum_orchestrator-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed. Auth is PyPI "trusted
+# publishing" (OIDC): the quorum-orchestrator project on PyPI trusts this
+# repo + workflow + environment, so no API token is stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run pytest -m "not nono_integration"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

quorum_orchestrator-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+quorum-home/

quorum_orchestrator-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

quorum_orchestrator-0.1.0/CLAUDE.md

@@ -0,0 +1,224 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+uv sync --all-extras            # dev setup (extras: web, nono; the TUI is a core dep)
+uv run pytest                   # full suite
+uv run pytest tests/test_tasks.py::test_run_creates_worktree_and_streams_transcript
+uv run pytest -m "not nono_integration"   # what CI's unit-test matrix runs
+uv run pytest -m nono_integration -v      # real kernel sandbox tests (need [nono] + Landlock/Seatbelt)
+QUORUM_HARNESS_TESTS=1 uv run pytest -m "codex_integration or opencode_integration" -v
+                                # real codex/opencode adoption tests (binaries + auth; spend tokens)
+uv run ruff check .             # lint (line-length 100; E4,E7,E9,F,I,UP,B)
+uv run quorum <cmd>             # run the CLI from a checkout
+```
+
+The PyPI distribution is `quorum-orchestrator` (plain `quorum` was taken); the
+import name and CLI command stay `quorum`. Releases: bump `version` in
+pyproject.toml, tag `vX.Y.Z`, push the tag — `.github/workflows/release.yml`
+builds with uv and publishes to PyPI via trusted publishing (OIDC, no token).
+
+`tests/test_nono_integration.py` self-skips when nono-py is missing or the platform
+lacks Landlock/Seatbelt; a dedicated CI job asserts support so it can never silently
+skip there. `test_web.py` needs the `web` extra (it `importorskip`s FastAPI).
+
+## What quorum is
+
+Bring-your-own-harness orchestration for long-running coding tasks: the user
+registers projects, queues tasks in plain English, and a configured harness CLI
+(claude / codex / opencode / anything) executes each task as a sequence of *runs*
+in a per-task git worktree. Supervision is **itself harness-driven**: the one
+built-in agent (the manager) runs the same harness over a situation digest and
+acts through the quorum CLI. Quorum ships the manager and the comms substrate
+(file-based board + inboxes), **not** prescriptive worker agents, and supervision
+policy lives in `prompts/manager.md`, not Python.
+
+Read `docs/architecture.md` first — it is the design record. The three invariants
+below govern nearly every change:
+
+1. **No privileged infrastructure.** `quorum up` is one ordinary process hosting an
+   APScheduler `BackgroundScheduler` — foreground by default, or detached with
+   `up --detach` the same way task runs detach (`quorum down` SIGTERMs it and polls
+   the lock). Task runs are detached child processes (they survive supervisor
+   restarts). No cron, systemd, daemonization frameworks, root, or open ports (the
+   web dashboard is opt-in, localhost-only).
+2. **All state is plain files** under `QUORUM_HOME` (resolution: `--home` > `$QUORUM_HOME`
+   > `./quorum-home` if present > `~/.quorum`). No database. Adding new durable state
+   means adding a file layout, documented in `docs/architecture.md`.
+3. **Fail loudly, recover automatically.** Views/dashboards degrade gracefully (pure
+   file readers; work with the supervisor stopped) and a harness that ignores the
+   report protocol is still observed passively — but supervision has **no no-LLM
+   fallback by design**: without a working harness the manager's tick raises every
+   time, and its `auto_pause = false` config keeps the schedule firing so it
+   self-recovers when the LLM service returns. Do not add degraded supervision paths.
+
+These are the project's *current* design commitments, not gospel. Quorum is
+evolving: any recorded stance — including the big three above and smaller ones
+noted per-layer below (e.g. the TUI/web being pure readers) — is open to
+deliberate revision when a change is worth it. Don't contort a feature to fit
+an old rule; propose breaking the rule, and when it changes, update this file
+and `docs/architecture.md` in the same commit so the record stays true.
+
+### Layers
+
+- `fsio.py` — the primitives everything else stands on: `atomic_write_*` (dot-prefixed
+  tmp in the same dir + fsync + rename), `append_jsonl`, ULID generation, `sorted_entries`
+  (skips dotfiles), and a pid-lock built on `O_EXCL` rather than `flock` so it behaves
+  identically under any sandbox-granted filesystem. **Never write state with plain
+  `open(...,'w')`** — readers must never observe a partial file.
+- `messages.py` — one `Message` schema over two channels: an append-only board
+  (`messages/board/<topic>/`, filenames `<utc-compact>-<ULID>.json` so lexicographic
+  order is chronological) and maildir-style inboxes (`new/` → `cur/` claimed by
+  `os.rename`, so exactly one claimant wins). Task guidance (`task-<id>` inboxes) and
+  the supervisor control channel both ride this; no new transports.
+- `tasks.py` — the task substrate: `Task`/`TaskStore` over `tasks/<id>/task.json`,
+  `report()` (the harness's return channel), path helpers shared by runner/manager/
+  views/CLI. **Status is a free-form reported string**; only `TERMINAL_STATUSES`
+  (`done`/`blocked`/`cancelled`) mean anything to quorum. `short_id` is the ULID's
+  random *tail* (the head is a same-instant-shared timestamp); `resolve()` accepts
+  unique prefixes or suffixes. `workdir_git_state` is the stranded-work probe
+  (dirty/unpushed in a task's workdir) surfaced by views and the manager digest —
+  the preamble tells harnesses to commit+push with plain git before reporting done.
+  `attached = true` marks an *adopted* live interactive session (`quorum task
+  adopt`): workdir = the user's checkout, no worktree, liveness from
+  `tasks/<id>/attached.json` (rewritten by `task hook-session-start`/
+  `hook-stop`/`hook-session-end`, which also learn the session id by cwd
+  match and deliver pending inbox guidance — as the Stop-hook block-protocol
+  JSON, or bare text via `hook-stop --format text` for shims that inject the
+  continuation themselves); `task detach` reverts it. One adapter per
+  harness under `integrations/` (claude-code, codex, opencode — the last is
+  a fail-soft JS plugin, kept a dumb pipe over the same CLI entry points),
+  kept true by `tests/test_integrations.py` (the opencode plugin is driven
+  for real under node, skipped when node is absent). The adapters ship
+  inside the wheel (hatch force-include → `quorum/integrations`) so
+  `quorum integration list|install` works from a package install;
+  `cli._integrations_root()` falls back to the repo dir in a checkout.
+- `runner.py` — one harness run: `runner.lock` pid-lock → git worktree under
+  `worktrees/<id>` (branch `quorum/<short-id>`) → claim task inbox → compose prompt
+  (preamble + task + guidance) → substitute `{prompt}`/`{session}` into the
+  `[harness.<name>]` argv template → stream stdout to `transcript.jsonl`, capturing
+  `session_id`/`thread_id`. A harness with `inject = "stream-json"` also gets
+  mid-run guidance: `GuidancePump` holds stdin open, forwards inbox messages as
+  stream-json user turns, and closes stdin at the first idle `result` event (the
+  manager reuses the pump over the `manager` inbox). The runner **never sets task
+  status**, and refuses attached tasks outright — a substrate rail (same class as
+  `runner.lock`, a deliberate narrow bend of "the cap is the only rail") protecting
+  the user's live checkout. `launch_detached` spawns `python -m quorum task run`
+  in a new session.
+- `agents/manager.py` — the flagship builtin, and it makes **no decisions in Python**:
+  its tick builds a situation digest (`build_digest`, pure over files — task
+  statuses, runner liveness, quiet time, report/transcript tails, the manager's own
+  action journal with then-vs-now outcomes, user directives from the `manager`
+  inbox), renders `prompts/manager.md`, and runs the configured harness
+  synchronously (cwd=home, tagged with the `actor.py` env protocol —
+  `QUORUM_ACTOR=manager`, per-run `QUORUM_ACTOR_RUN`, the resolved cap in
+  `QUORUM_ACTOR_CAP` — bounded by `run_timeout_seconds`, stdout →
+  `state/manager/transcript.jsonl`).
+  The harness acts via the quorum CLI; the CLI's `_actor_guard` auto-journals
+  every mutating action to the acting agent's journal and enforces the per-run
+  action cap (`max_actions_per_run`) — the only rail, a rate limit, never a veto.
+  Failures raise; directives are rejected back to `new/` on crash.
+  `agents/harness_run.py` holds the extracted run mechanics (`run_agent_harness`)
+  shared with `agents/prompt_agent.py::PromptAgent` (builtin `prompt`) — the
+  generic sibling: renders `prompts/<name>.md` (no digest, no wake condition;
+  conditional behavior belongs in the prompt) and runs the harness with the
+  same journal/cap rails under `state/agents/<name>/`. Prompt agents are
+  usually file-defined and created by `quorum agent create` or the web form.
+- `agent.py` — `Agent` (synchronous, idempotent `tick()`) plus `AgentContext`, the single
+  seam through which agents touch the world: `ctx.bus`, `ctx.projects`, `ctx.llm`,
+  `ctx.prompt()`, `ctx.load_state()/save_state()`, `ctx.log_action()`, `ctx.now()`.
+  Agents take a clock as a callable — use `ctx.now()`, never `datetime.now()`.
+  `tick_lock_path` is held by both the supervisor wrapper and `agent run-once`.
+- `supervisor.py` — one scheduler job per enabled agent, wrapped by `run_agent_tick`
+  for crash isolation: heartbeat files, an `agent.error` post to the `system` topic,
+  auto-pause after `MAX_CONSECUTIVE_FAILURES` (5). A 15s `_control` job claims the
+  `supervisor` inbox (`quorum agent pause|resume|run-now|reload`); `agent.reload`
+  is the hot-add/edit/remove path for file-defined agents (re-reads config, one
+  message for all mutations — handled *before* the job-exists guard). Pause is
+  durable: `_schedule_agent` creates the job paused when the heartbeat says
+  `paused`. An hourly janitor archives expired board messages and returns
+  crash-orphaned `cur/` claims to `new/`.
+- `views.py` — the shared read-model assembled purely from files (`overview` includes
+  `attention_summary`, a time-windowed read of the `attention` topic that `status`,
+  the TUI banner, and the web header all surface — the board has no read-state, so
+  "needs a look" is time-bounded, not tracked); `quorum status`, the
+  web app, and the TUI are all pure readers of it. `agent_rows` estimates a stale
+  `next_run` from the schedule (`next_run_estimated`); `agent_detail` adds journal +
+  per-agent actions. Write affordances stay thin bus/config calls shared with the
+  CLI: nudging a task (TUI+web), and in the web only, board posts, project edits,
+  agent create (via `config.create_agent`) and pause/resume/run-now/reload.
+- `actor.py` — the actor-identity env protocol: who a quorum CLI call is acting
+  as, name-generic over harness-driven agents. An agent tags the harness it
+  spawns (`actor_env(name, run_id, cap)`), the CLI resolves `current_actor()`
+  for journaling and message attribution, and the runner `strip_actor_env`s
+  spawned children so they act as themselves. Also owns `journal_path`/
+  `transcript_path` (manager at `state/manager/`, others at `state/agents/<name>/`).
+- `registry.py` — resolves an agent `type` string: builtin short name (`manager`,
+  `prompt`), else `module:Class` with `QUORUM_HOME/plugins` prepended to `sys.path`.
+- `llm/` — `LLMBackend` is a one-method protocol for *plugin agents'* small
+  completions — neither task harnesses nor the manager go through it. `LLMClient.complete()`
+  **never raises**; `None` means "no LLM today". No module outside `llm/` may assume
+  the `cli` backend (`proxy` is a reserved seam).
+- `sandbox.py` — the *only* module that imports `nono_py`, always lazily and inside
+  functions. It **fails closed**. `build_capabilities` (supervisor/LLM) blocks network
+  unless `[llm]` is set; `build_task_capabilities` (per-run) grants the worktree, the
+  project's `.git` (shared object store), and `[sandbox].task_read/task_write` extras,
+  with network open.
+- `herdr.py` — the *only* module that talks to a herdr server (terminal
+  multiplexer with agent-aware panes), over its unix-socket newline-JSON API.
+  **Fails soft** — the deliberate opposite of sandbox.py's fail-closed: herdr
+  absent/broken degrades every call to `None`/`False`, never breaking a digest
+  or nudge. Two narrow uses, both for attached tasks with a `herdr_pane`:
+  `agent_state` (pane status into the digest) and `ring_doorbell` (a
+  `task nudge` pokes the pane that guidance is waiting — the payload stays in
+  the maildir inbox; herdr is a doorbell, never a second transport). Optional
+  `[herdr]` table (`socket` override, `enabled`).
+- `config.py` — `config.toml` is user-owned and **quorum never writes it back**; machine
+  state goes to JSON. The one config location quorum may write is `agents/<name>.toml`
+  (file-defined agents, atomic whole-file writes via `write_agent_file`/`create_agent`;
+  merged over `[agents.*]` at load, file wins; names validated + reserved-checked).
+  `[harness.<name>]` tables are argv templates; `[tasks]` holds
+  worktree/default-harness; `AgentConfig.auto_pause=false` exempts an agent from the
+  5-failure auto-pause (the manager uses it). Schedules are validated by regex and
+  translated to APScheduler trigger kwargs by `parse_schedule`.
+- `projects.py` — `projects/<slug>.json` is canonical, but a `.quorum.toml` marker inside
+  the project directory merges over it at read time. Agents and views must go through
+  `ProjectRegistry` and must only ever *read* project dirs — task writes happen in
+  worktrees.
+- `prompts.py` — `QUORUM_HOME/prompts/<name>.md` overrides the packaged
+  `default_prompts/` (`task-preamble`, `manager`); deleting a file restores the
+  default. `format_map` with a missing-key-preserving dict. Re-running `quorum
+  init` upgrades seeded-but-never-edited copies, recognized by hash — **when you
+  change a file in `default_prompts/`, append the replaced version's sha256 to
+  `home.py::SUPERSEDED_PROMPT_HASHES`** (`git show HEAD:src/quorum/default_prompts/<name> | shasum -a 256`).
+- `examples/steward.py` — the one shipped example plugin (file organizer with undo),
+  loaded by path in `tests/test_example_steward.py` so the docs' worked example stays
+  true. Not a builtin; users copy it into `plugins/`.
+
+### Adding an agent
+
+Builtins live in `agents/__init__.py::BUILTIN_NAMES` (`manager`, `prompt`) —
+prefer plugins unless quorum itself needs the behavior. The user-facing contract is
+`docs/guide.md#writing-your-own-agents`: idempotent `tick()`, dedupe repeat
+announcements through `load_state()/save_state()`, raising is safe.
+
+### Testing idioms
+
+`tests/conftest.py` provides `home` (scaffolded `QUORUM_HOME` in `tmp_path`, exported via
+`$QUORUM_HOME`), `clock` (a `FakeClock` passed as `AgentContext(now=...)`), and `fake_llm`.
+`tests/bin/fake_harness.py` is a fake coding harness (echoes argv/prompt, emits a
+`session_id`; `report` mode calls `python -m quorum task report`; `manager_act` /
+`manager_flood` modes act like a manager — each `[harness.*]` table pins its mode via
+its `env` field, so a fake task harness and a fake manager harness coexist). Runner and
+manager tests build real git repos and run the loop for real; when a test needs a
+"live" runner, its lock holds pid 1 — never `os.getpid()`, which same-process lock
+takeover treats as stale.
+`test_sandbox.py` injects a fake `nono_py` via `sys.modules`; `test_nono_integration.py`
+exercises real kernel enforcement.
+
+Docs are part of the deliverable here: a change to the file layout, message protocol,
+task/run lifecycle, or sandbox modes should update `docs/architecture.md` (and the
+user-facing `docs/guide.md`) in the same commit.

quorum_orchestrator-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: quorum-orchestrator
+Version: 0.1.0
+Summary: Bring-your-own-harness orchestration for long-running coding tasks: file-based, sandboxable, monitored.
+Author: Kevin Doherty
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: apscheduler<4,>=3.10
+Requires-Dist: pydantic>=2
+Requires-Dist: textual>=0.60
+Requires-Dist: typer>=0.12
+Provides-Extra: nono
+Requires-Dist: nono-py; extra == 'nono'
+Provides-Extra: tui
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: uvicorn>=0.29; extra == 'web'
+Description-Content-Type: text/markdown
+
+# quorum
+
+**Orchestrate long-running coding tasks with the harness you already use —
+supervised by that same harness.** Point quorum at your repos, queue tasks
+in plain English, and let your coding agent CLI — `claude`, `codex`,
+`opencode`, anything that takes a prompt — do the work in isolated git
+worktrees. The supervisor is an agent too: quorum's **manager** periodically
+hands your harness a digest of everything happening (every task's status,
+output, and liveness, plus its own past actions and their outcomes) and lets
+it decide — launch, nudge, relaunch, spin up follow-up work, or escalate to
+you. Supervision policy is a prompt you can edit, not code. One process, no
+root, no cron, no database; everything is a plain file you can `cat`.
+
+```
+quorum task add my-api "add rate limiting to the public endpoints, then open a PR"
+        │
+┌─ quorum up ─────────────────────────────────────────────────────┐
+│  manager    your harness, reading the whole situation and       │
+│             acting: launch, nudge, relaunch, task add,          │
+│             escalate — every action journaled and auditable     │
+│                                                                 │
+│  task runs  your harness (claude/codex/opencode/...) working    │
+│             in worktrees/<task>/, reporting progress back       │
+│             through `quorum task report` and reading guidance   │
+│             from `quorum task inbox`                            │
+└──────────────────── all state in ~/.quorum ─────────────────────┘
+        ▲                    ▲                    ▲
+   quorum status        quorum tui           quorum web
+   quorum manager tell  (steer with `n`)     (localhost only)
+```
+
+## Install
+
+Needs Python 3.11+.
+
+```bash
+uv tool install quorum-orchestrator              # includes the TUI dashboard
+uv tool install "quorum-orchestrator[web]"       # + the localhost web dashboard
+uvx --from quorum-orchestrator quorum --help     # zero-install trial run
+```
+
+(or `pip install "quorum-orchestrator[web]"` if you don't use uv.)
+
+The PyPI distribution is `quorum-orchestrator`; the command it installs is
+plain `quorum` (and the import name is `quorum` too).
+
+From a checkout: `uv sync --all-extras`, then prefix commands with `uv run`.
+
+## Five minutes to a running task
+
+```bash
+quorum init                             # scaffold ~/.quorum
+```
+
+Tell quorum how to invoke your harness: the scaffolded
+`~/.quorum/config.toml` ships ready-to-uncomment blocks for claude, codex,
+and opencode, plus a template for any custom agentic binary — uncomment one
+and set `default_harness`. (Runs are unattended, so the harness needs
+permission to act without asking; the shipped blocks use a scoped tool
+allowlist, not a blanket bypass.)
+
+Register a repo and queue work:
+
+```bash
+quorum doctor                           # verify the setup end to end
+quorum project add ~/work/my-api
+quorum task add my-api "fix the flaky auth tests and open a PR"
+quorum up --detach                      # supervisor in the background (`quorum down` stops it)
+```
+
+(`quorum up` without `--detach` runs it in the foreground — Ctrl-C stops.)
+Then:
+
+```bash
+quorum status                # supervisor, agents, tasks, deadlines
+quorum task tail a3f2k9 -f   # live harness transcript
+quorum task nudge a3f2k9 "prefer the retry approach over sleeps"
+quorum manager tell "the api task is urgent; park everything else"
+quorum manager journal       # what the manager did, and why
+quorum tui                   # dashboard; select a task, press n to steer
+quorum web                   # http://127.0.0.1:8787
+```
+
+## What it looks like
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kvndhrty/quorum/main/docs/images/web-dark.png">
+  <img alt="quorum web dashboard" src="https://raw.githubusercontent.com/kvndhrty/quorum/main/docs/images/web-light.png">
+</picture>
+
+![quorum terminal dashboard](https://raw.githubusercontent.com/kvndhrty/quorum/main/docs/images/tui.png)
+
+## Adopt a live session
+
+The work is already underway in an interactive session? Don't re-queue it —
+adopt it:
+
+```bash
+quorum integration install codex     # once per harness (also: opencode, claude-code)
+quorum task adopt "refactoring the auth flow"    # from the session's directory
+```
+
+The session becomes an *attached* task: the manager observes it (liveness,
+git state, reports) but never runs it — your nudges and the manager's pokes
+are delivered *inside* the live session by the harness's hook the next time
+it stops. `quorum task detach` hands it back to the headless runner. See
+[docs/guide.md#adopting-a-live-session](https://github.com/kvndhrty/quorum/blob/main/docs/guide.md#adopting-a-live-session)
+and the per-harness adapters under
+[integrations/](https://github.com/kvndhrty/quorum/tree/main/integrations).
+
+## How it works
+
+- **A task is a sequence of harness runs.** Each run executes in the task's
+  own git worktree (`~/.quorum/worktrees/<id>`), so parallel tasks on one
+  repo never collide and your checkout stays clean. Session ids are captured
+  from the harness's output so follow-up runs can `--resume`.
+- **Status is the harness's own words.** The run prompt teaches a simple
+  protocol — report progress with `quorum task report`, check guidance with
+  `quorum task inbox` — and the conventional flow is
+  `planning → executing → reviewing → pr → done`. Quorum records what the
+  harness says; it never enforces a state machine.
+- **The manager is an agent, not a ruleset.** Each cycle it compiles a
+  situation digest — including its own recent actions and whether they
+  changed anything — and your harness decides what to do, with real
+  authority: `task run`, `task nudge`, `task add`, `task cancel`, escalate.
+  Every action is auto-journaled (`quorum manager journal`); the journal
+  feeds back into the next digest so the manager never loops on an
+  intervention that isn't working. Steer it with `quorum manager tell`.
+- **Guidance is a message, not a keystroke.** Your nudges and the manager's
+  pokes travel the same file-based inbox; the next run starts with them in
+  its prompt, and a cooperative harness picks them up mid-run.
+- **Failure is loud and recovery is automatic.** If your LLM service goes
+  down, every harness-driven tick fails visibly — and keeps being scheduled,
+  so the first tick after service returns reads the world from files and
+  relaunches whatever died. No degraded fallback mode to babysit.
+- **All state is files** under `QUORUM_HOME` (default `~/.quorum`): task
+  records, transcripts, a message board, inboxes — written with atomic
+  tmp+rename. The TUI and web dashboard are pure readers and work even when
+  the supervisor is down. Copy the directory and your whole setup moves.
+
+## Supervision policy is a prompt
+
+`~/.quorum/prompts/manager.md` is the manager's constitution: how patient it
+is, when it escalates, how it words its pokes, when creating follow-up work
+is warranted. Edit it to retune your manager; delete it to restore the
+default. (An optional `[llm]` section separately gives *plugin* agents a
+small-completion client — the manager and tasks run your full harness
+directly.)
+
+## Optional sandbox
+
+Quorum pairs naturally with [nono](https://github.com/nolabs-ai/nono)
+(kernel-enforced sandboxing via Landlock/Seatbelt): wrap the whole thing with
+`nono run --profile quorum -- quorum up`, or set `[sandbox] use_nono = true`
+to confine each task run to its worktree plus `QUORUM_HOME`. Fails closed:
+if sandboxing was requested and nono-py is missing, nothing runs unsandboxed.
+See [docs/guide.md](https://github.com/kvndhrty/quorum/blob/main/docs/guide.md#sandboxing).
+
+## Customizing
+
+- **Configure** harnesses, schedules, and the manager's action budget in
+  `config.toml` — quorum never rewrites that file.
+- **Retune** the task preamble and the manager's policy by editing
+  `~/.quorum/prompts/*.md`; delete a file to restore the default.
+- **Extend** with your own agents: drop a ~20-line Python file into
+  `~/.quorum/plugins/` — [examples/steward.py](https://github.com/kvndhrty/quorum/blob/main/examples/steward.py) is a
+  complete worked example (a rule-based file organizer with undo).
+
+Everything above, in depth: **[docs/guide.md](https://github.com/kvndhrty/quorum/blob/main/docs/guide.md)**.
+Design record: [docs/architecture.md](https://github.com/kvndhrty/quorum/blob/main/docs/architecture.md).
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+```
+
+Repo conventions and the layer-by-layer map live in
+[CLAUDE.md](https://github.com/kvndhrty/quorum/blob/main/CLAUDE.md).