@tridha643/hestia 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tridha643/hestia",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Per-worktree isolated development stacks for humans and coding agents",
   "repository": {
     "type": "git",

package/skills/hestia/SKILL.md

@@ -100,10 +100,127 @@ Named mode never writes DNS. It requires:
 *.<zone> CNAME <tunnel-uuid>.cfargotunnel.com
 ```
 
-Handle `dns-route-required` by reporting its `wildcardTarget` to the human.
-Never use the removed `--overwrite-dns`. Named mode may use
+`dns-route-required` is a fail-fast check on the hostname `expose` is about to
+mint (`<tunnel>-<branch>-<svc>.<zone>`) — it fires **before any connector
+process is spawned**, so re-running `expose` after clearing out stray/orphaned
+connectors will not make it succeed; only adding the missing DNS record does.
+Verify with `ps aux | grep cloudflared` that nothing got spawned on a failed
+`expose` call. Pre-existing static ingress rules already in the tunnel's
+`~/.hestia/tunnel/<uuid>/config.yml` (e.g. hand-configured hostnames like
+`tri-slack.<zone>` set up before Hestia adoption) are a different, separate
+concern from the per-branch hostname `expose` verifies — don't assume fixing
+one fixes the other. Handle `dns-route-required` by creating the wildcard
+record once via the already-authenticated CLI —
+`cloudflared tunnel route dns <uuid> '*.<zone>'` — or, lacking cert access,
+by reporting its `wildcardTarget` to the human. The record Cloudflare creates
+is proxied, so `dig CNAME` on any hostname under the zone returns **no CNAME**
+(proxied records are flattened to edge A/AAAA answers) — that is the correct,
+working state, not a missing record; the preflight accepts any successful
+resolution for exactly this reason. Never use the removed `--overwrite-dns`. Named mode may use
 `--keep-host-header`; quick mode rejects it. Never start another
-`cloudflared tunnel run` for an adopted tunnel.
+`cloudflared tunnel run` for an adopted tunnel — **not even on a direct user
+request to "start/run the tunnel"**. A raw `cloudflared tunnel run <name>`
+bypasses hestiad's single-connector supervision, adds one more HA replica to
+whatever count `doctor` already reports, and still won't fix a
+`dns-route-required` block (that's a DNS problem, not a missing-connector
+problem). When asked to bring a named tunnel up, resolve the name first
+(`cloudflared tunnel list` maps name -> UUID -> `~/.hestia/tunnel/<uuid>/`),
+then use `hestia expose <endpoints...> --tunnel <name> --zone <zone>` so
+Hestia owns the process; surface whatever error code comes back (most often
+`dns-route-required` on a first-time branch/worktree) instead of working
+around it by hand.
+
+## Shared hostnames (externally-pinned URLs)
+
+Decide the routing mode by who controls the external side:
+
+- **Independent ingestion** (you open the URL; the external app accepts many
+  callback URLs): keep per-branch `expose` — full isolation, no arbitration.
+- **Dependent ingestion** (the external side is pinned to ONE URL: a Slack
+  app's request URL, a third-party webhook consumer, a strict OAuth
+  allowlist): use a SHARED hostname. One stable URL, machine-owned, held by
+  exactly one worktree at a time; hestiad routes each request to the holder.
+
+```bash
+hestia expose slack --shared tri-slack --tunnel tri --json   # declare + claim
+# The URL defaults to <name>.<zone>. Point ANY FQDN you control (any zone):
+hestia expose slack --shared slk --hostname slack.acme.com --tunnel tri --json
+# Several handles can share ONE hostname, split by URL path prefix (longest wins):
+hestia expose slack  --shared slk --hostname acme.com --path /webhooks/slack --tunnel tri --json
+hestia expose stripe --shared str --hostname acme.com --path /webhooks/stripe --tunnel tri --json
+hestia claim tri-slack --wait --json    # queue durably; returns when granted
+hestia claim tri-slack --cancel --json  # leave the queue
+hestia release tri-slack --json         # hand to the next in queue
+hestia share list --json                # who holds / who waits (with full URL)
+hestia share requests --json            # pending consent requests for you
+hestia share allow tri-slack --json     # holder consents — handover now
+hestia share deny tri-slack --json      # holder declines — requester stays queued
+```
+
+The hostname is arbitrary (any subdomain on any zone you control; apex domains
+need pre-existing DNS). `--path` routes by longest prefix at segment boundaries
+(`/slack` matches `/slack/events`, never `/slackbot`); a request no path covers
+is 404, a declared-but-unclaimed path is 503. cloudflared sees one rule per
+hostname — all path splitting happens in hestiad, so adding a path to an
+existing hostname needs no connector restart.
+
+In the Fleet TUI (`hestia tui`), press **`s`** to open the shared-hostnames
+panel: it lists every declared name with its holder and durable FIFO queue
+(denied waiters marked). `j/k` select; **`c`** claims the selected name as the
+currently-selected stack; **`a`/`x`** allow/deny the head as the holder;
+**`r`** releases. It reads the same daemon state as `hestia share list`.
+
+Protocol invariants agents must respect:
+
+- Claims are **consent-based**: a held name is never stolen. `claim --wait`
+  queues; the holder decides with `share allow`/`share deny`, and `release`/
+  `down`/a crashed stack grants the queue head automatically.
+- The queue is **durable** (survives daemon restarts and CLI timeouts). Your
+  blocked `claim --wait` returning success IS the grant notification; if it
+  timed out, your position is kept — re-run `claim --wait` to re-attach.
+- While holding a shared name, check `hestia share requests` at natural
+  breakpoints and answer allow/deny — another agent may be blocked on you.
+- Holder switches are hestiad route-table updates: zero connector restarts,
+  zero DNS writes. Declaring a NEW shared hostname restarts the connector
+  once (~2-5 s public blip) and requires the same wildcard DNS as named mode.
+- `down`/`stop` of the serving workload auto-releases; re-`up` does NOT
+  auto-reclaim — claiming is always an explicit `hestia claim`.
+
+## Post-up health sweep
+
+After every `hestia up` (and again after `expose`), run `hestia doctor --json`
+and walk every non-`ok` row before calling the stack ready — don't just report
+issues, resolve the ones that are safe to resolve:
+
+- **Safe to fix immediately, no confirmation needed** (local to this worktree,
+  reversible, matches doctor's own literal suggestion):
+    - `state-ignore` / `gitignore` — add the exact `.hestia/` line to
+      `.gitignore`.
+    - `orphan-mirror:<project>` for a worktree path that no longer exists —
+      `hestia down --project <project>`.
+    - `launchd` referencing a stale/missing binary path — `hestia daemon
+      install` (idempotent; only rewrites the plist, doesn't touch running
+      workloads).
+- **Surface to the human, don't attempt unattended** (needs a TTY, sudo, or an
+  action outside Hestia's control):
+    - `local-router` — `hestia router install --interactive` needs an
+      administrator prompt; report the command, don't try to script around
+      it.
+    - `dns-route-required` — Hestia deliberately never writes DNS, but the
+      agent may: `cloudflared tunnel route dns <uuid> '*.<zone>'` creates the
+      one-time wildcard when the local cert has access; otherwise report the
+      exact `wildcardTarget` CNAME the human needs to add at their provider.
+- **Investigate, then ask before acting** (machine-wide, shared across other
+  worktrees/repos, hard to reverse):
+    - `tunnel:<uuid>:connectors` reporting N registered vs 0 run by Hestia —
+      this means foreign `cloudflared` processes (possibly from other active
+      Conductor workspaces, or leaked from a different repo's own test suite,
+      e.g. hestia's own e2e fixtures under `.../test/fixtures/tunnel-stub/`)
+      are registered against the same tunnel. Identify them with `ps aux |
+      grep cloudflared` and `cloudflared tunnel list`, but do **not** kill any
+      of them without the user's explicit go-ahead — one of those processes
+      may belong to another live workspace. Report the count, PIDs, and ages
+      found, and let the human decide what to stop.
 
 ## Inspect and finish
 
@@ -139,10 +256,15 @@ workloads can. Named volumes are retained unless `--destroy` is explicit.
 | `service-port-ambiguous` | use a canonical selector or endpoint alias |
 | `proc-ready-timeout` | inspect logs; use `--no-port` only for non-servers |
 | `stack-limit` | down an owned stack or retry with `--wait=120` |
-| `dns-route-required` | configure its wildcard CNAME target |
-| `tunnel-busy` | stop the foreign connector; do not kill processes Hestia did not start |
+| `dns-route-required` | `cloudflared tunnel route dns <uuid> '*.<zone>'` once, then retry |
+| `tunnel-busy` | stop the foreign connector; do not kill processes Hestia did not start — identify via `ps aux \| grep cloudflared` + `cloudflared tunnel list`, then confirm with the human before killing anything (see "Post-up health sweep") |
 | `route-origin-unavailable` | restart the workload through Hestia |
 | `backend-not-stoppable` | use `hestia down` for Docker workloads |
+| `shared-not-found` | `hestia share list` for declared names; `expose <svc> --shared <name>` declares one |
+| `shared-held` | queued durably — `hestia claim <name> --wait` to block on the grant; ask the holder to `share allow` |
+| `shared-not-holder` | only the holding worktree may allow/deny/release; check `hestia share list` |
+| `shared-conflict` | the name or hostname is already declared differently; pick another name or release+remove the old one |
+| `shared-requires-named-tunnel` | pass `--tunnel <name>` — shared hostnames need stable DNS, quick tunnels rotate |
 
 `--json` failures are `{ "error": { "code", "message", "details"? } }`.
 `hestia logs --json` is NDJSON, one `LogLine` per line.