docs: document conchd status API, global --quiet flag, --json, and --min-rev options

Author: alien43

README.md

@@ -35,6 +35,9 @@ CONCH_TTL           lease TTL (default: 10s)
 
 Can also be passed as flags.
 
+Other global flags:
+- `--quiet`: suppress log output below `WARN` level.
+
 ---
 
 ## elect
@@ -54,6 +57,8 @@ conch elect <office> [flags] -- <cmd...>
 | `--on-acquire` | — | shell command run on winning the office |
 | `--on-lose` | — | shell command run on losing the office |
 | `--hook-timeout` | 30s | timeout for hook commands |
+| `--json` | off | print output as JSON (for `--who`, `--watch`, `--assert`) |
+| `--min-rev` | 0 | minimum create-revision for `--assert` |
 
 ```bash
 # Run a daemon, restart on failure
@@ -64,10 +69,15 @@ conch elect db-primary --on-acquire "pg_ctl promote" --on-lose "pg_ctl demote" -
 
 # Check who holds the office
 conch elect api-leader --who
+conch elect api-leader --who --json
+
+# Watch leadership changes
 conch elect api-leader --watch
+conch elect api-leader --watch --json
 
 # Assert this host holds the office (exit 0 yes, 1 no, 69 etcd unreachable)
 conch elect api-leader --assert
+conch elect api-leader --assert --min-rev 100 --json
 ```
 
 ---
@@ -86,6 +96,8 @@ conch sema <name> --max N [flags] -- <cmd...>
 | `--spread` | off | at most 1 slot per hostname |
 | `--wait` | forever | give up after this duration |
 | `--nonblock` | off | exit 75 immediately if no slot available |
+| `--kill-after` | 5s | grace period before SIGKILL |
+| `--json` | off | print output as JSON (for `--who`) |
 
 ```bash
 # At most 3 nodes run this at once
@@ -96,6 +108,7 @@ conch sema ingest --max 5 --spread -- /usr/local/bin/ingest
 
 # Check who holds slots
 conch sema heavy-jobs --max 3 --who
+conch sema heavy-jobs --max 3 --who --json
 ```
 
 ---
@@ -118,6 +131,9 @@ conch cron ls [--last] [--json]
 ```bash
 # Run conchd on each cluster node to execute scheduled jobs
 conch conchd
+
+# Run conchd status HTTP API server on port 9191 (can also use CONCH_STATUS_ADDR env var)
+conch conchd --status-addr :9191
 ```
 
 ---

docs/02_core.md

@@ -2,12 +2,13 @@
 
 Everything every tool inherits. This file is authoritative; `00_design.md` sketches.
 
-## 1. Connection
+## 1. Connection & Logging
 
 | Flag | Env | Default |
 | :--- | :--- | :--- |
 | `--endpoints` | `CONCH_ENDPOINTS` | `localhost:2379` |
 | `--dial-timeout` | `CONCH_DIAL_TIMEOUT` | `5s` |
+| `--quiet` | — | `false` |
 
 Plain HTTP (matches the cluster's etcd; no TLS until etcd itself grows it). If no
 endpoint is reachable within the dial timeout: exit **69** without side effects.

docs/05_cron.md

@@ -8,7 +8,7 @@ Distributed cron: a schedule executed by exactly one node per tick. Anyone sched
 conch cron add <name> --schedule '<cron expr>' [--run-ttl 10m] [--quiet] -- <cmd...>
 conch cron ls [--last] [--json]
 conch cron rm <name>
-conch conchd            # the per-node daemon (systemd unit; identical on every node)
+conch conchd [--status-addr :9191] # the per-node daemon (systemd unit; identical on every node)
 ```
 
 ## Job spec
@@ -76,6 +76,63 @@ output goes to the journal of the node that ran it (conchd logs child stdout/std
 slog). Keeping output out of etcd is deliberate: etcd is a coordination store, not a
 log pipeline.
 
+## `conchd` Status HTTP API
+
+When starting `conchd`, you can enable a local/cluster HTTP status server by passing the `--status-addr` flag or setting the `CONCH_STATUS_ADDR` environment variable:
+
+```sh
+conch conchd --status-addr :9191
+```
+
+The daemon will run an HTTP server exposing status endpoints in JSON format:
+
+* **`GET /cron`**: Lists all registered cron jobs with their current status, schedules, last execution details (including duration, exit code, and node), and the next scheduled execution time:
+  ```json
+  [
+    {
+      "name": "db-backup",
+      "schedule": "*/15 * * * *",
+      "next_tick": "2026-06-12T11:00:00Z",
+      "last_tick": "2026-06-12T10:45:00Z",
+      "node": "node3",
+      "exit": 0,
+      "duration": "4.2s"
+    }
+  ]
+  ```
+* **`GET /elect`**: Lists all active leader election offices, showing who currently holds the primary lease, the PID and start time of the supervised process:
+  ```json
+  [
+    {
+      "office": "db-primary",
+      "leader": "node1",
+      "pid": 12053,
+      "started": "2026-06-12T08:00:00Z",
+      "cmd": "postgres",
+      "create_revision": 4512
+    }
+  ]
+  ```
+* **`GET /sema`**: Lists all semaphores, indicating maximum capacities along with holders and queued nodes currently waiting on slot availability:
+  ```json
+  [
+    {
+      "name": "heavy-jobs",
+      "max": 2,
+      "holders": [
+        {
+          "host": "node2",
+          "pid": 9912,
+          "started": "2026-06-12T10:15:00Z",
+          "cmd": "/usr/local/bin/run-job.sh",
+          "create_revision": 8812
+        }
+      ],
+      "waitlist": []
+    }
+  ]
+  ```
+
 ## Failure behavior
 
 * **Clock skew**: a fast node claims tick `T` early by (skew − jitter); a slow node

docs/07_deployment.md

@@ -77,6 +77,13 @@ When deploying upgrades to the `conch` binary or `conchd`:
   ```sh
   conch elect monitor-probe --assert
   ```
+* **Status HTTP API**: If `conchd` has `--status-addr` enabled, query status or health directly via HTTP:
+  ```sh
+  # Query cron, election, or semaphore statuses
+  curl -fsS http://localhost:9191/cron
+  curl -fsS http://localhost:9191/elect
+  curl -fsS http://localhost:9191/sema
+  ```
 * **Dead Man's Snitch**: Register a simple heartbeat cron job to ping an external monitoring endpoint:
   ```sh
   conch cron add heartbeat --schedule '@every 5m' -- curl -fsS https://hchk.io/your-uuid