@tridha643/hestia 1.0.0 → 1.0.1

package/package.json

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

package/skills/hestia/SKILL.md

@@ -100,10 +100,71 @@ 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.
+
+## 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,8 +200,8 @@ 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 |