yamine 0.21.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e920f5f6d29a92e0a6e81ca671bccf62e0a264ec453f9b5bc4d42d4e56980d3
-  data.tar.gz: cc06342930ee7c882cf30fd2818f1a60495c8a59e44ec6779cc666f569493ac0
+  metadata.gz: 69848a3d38cd9997ca18e52ea892aa57962524e0cd41df16199a651409e86b76
+  data.tar.gz: aebe3dd18c4bab95865491850bb940ca9a7e42c83f53d851b4d3ddd691f80305
 SHA512:
-  metadata.gz: 4164dabf9bd5537023ad59d426a958a5e284a90f0226cc83e0533cf635edf0c65acc16dd311d58a88df83d7abdcdfb92034703ecda06d89af08bb5ec96c73635
-  data.tar.gz: 1e3af2b55e54885fe8aeed98856c4371eab280ec981cd2644ebb75aba0206752ae44307c0252f51188a778426efbb882ef2285c63f142def39f4e876f77302d6
+  metadata.gz: 7c1bb5ef1104c29a53c8e4274a5b4a42f7231f895f40bb7d12defc97dee72232944340c24b4bec62b9a736d29bdab01d975b32cf6e1af7aaf7f1b643ec0ac602
+  data.tar.gz: 66ef5d87789c27a94994c0d24f1567c1a762d592ecbfb00b3d95db8a7f538f3c6868be3703a9870a88d0101aabb37dcfaba8f6db85b2e4a74799b4a4381c7280

data/CHANGELOG.md

@@ -2,6 +2,172 @@
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-09-29
+
+### Added
+
+- **`yamine start --detach` — boot in the background and get your prompt
+  back.** An agent (or a script) that needs an app running had one
+  option: block, or reach for `nohup` — which leaves a process tree
+  whose owner the first Ctrl-C cannot reach. `--detach` forks the boot:
+  the child takes its own session, records its pid in
+  `~/.yamine/start-<hostname>.pid`, sends its own output to
+  `~/.yamine/start-<hostname>.log`, boots, keeps the tree supervised and
+  outlives the shell that started it. The parent waits for the app to
+  answer, prints the URL, that pid and the log path, and exits 0.
+  The boot happens in the child on purpose: `add_route` records
+  `Process.pid`, and `load_routes` prunes any route whose pid is dead, so
+  a parent that registered the routes and exited would have its own route
+  pruned on the next read and the proxy would 503 an app that is running
+  perfectly well. It is idempotent — a tree already running for the
+  directory (detached, or foreground) is reported, not started again —
+  and a boot that never becomes healthy exits 1 with the log instead of
+  a tree that is not there. `--json` gets the same three facts
+  as a payload. `--no-wait` is ignored with `--detach`: returning before
+  the app answers is the lie this flag exists to stop.
+
+### Fixed
+
+- **`yamine list` and `yamine get --all` report the app, not the CLI
+  that started it.** A route's `pid` is the yamine process that
+  registered it, and it outlives the app it booted, so `alive_state` was
+  asking the wrong process whether the app was alive: every crashed
+  backend read as `running`, in the one command an agent would reach for
+  to find out. Liveness now comes from the sidecar the boot already
+  writes (`backend-<hostname>.pid`, the same file `yamine stop` reads),
+  and the vocabulary says what it knows:
+  `running` (the app's process is there), `backend-gone` (the CLI is
+  still up, the app it booted is not), `owner-gone` (nothing is there
+  and no app pid was recorded), `unknown` (no app pid recorded, and the
+  route's own process is — a route written before sidecars existed, or
+  by a boot that died between registering the route and writing the
+  file: `unknown`, never "down", so no pre-existing route reads as
+  broken after an upgrade), and `reachable` / `unreachable` for a static
+  alias, which names no process and keeps reporting the probe.
+  `list --json` gained `backend_pid` beside `pid` so the state and the
+  process it is about travel together, and the human line prints the
+  backend's pid rather than the owner's.
+- **`yamine restart` works for the apps yamine started.** Supervision
+  required `kind == "socket"`, and `yamine start` registers `kind
+  "tcp"`, so a `yamine start` tree was invisible to the daemon:
+  `yamine restart` touched `tmp/restart.txt`, printed "managed app
+  restarts on next request", and nothing was watching the file. Any
+  route carrying a spec is now watched, so restart.txt and crash
+  detection reach both kinds. Two things that were broken *inside* the
+  socket case went with it: the restart baseline was re-derived while
+  `restart.txt` did not exist, so the *first* `yamine restart` an app
+  ever got was absorbed as the new baseline and did nothing; and the
+  "restarting" latch was never cleared, so a route was supervised for
+  exactly one event in the life of the daemon. The kill now signals the
+  process group when the pid leads one, because a tcp route's sidecar
+  names the `sh -c` shell the boot wrapped the app in.
+- **A child that dies no longer ends `yamine start` with exit 0.**
+  `supervise_tree` exited 0 with the routes already removed and the rest
+  of the tree being killed, so a zero read as "the app came up" to
+  anything scripted — which then blamed the app for the 503 it was
+  about to get. It exits 1, the same code `--wait` already uses for a
+  boot that never became healthy, and the message names the process, its
+  exit status (or the signal that took it down — a reaped child is the
+  only place that answer exists, so the reaper keeps it) and the tail of
+  the app log. `--json` gets the same as
+  `{"ok": false, "error": "child-exited", …}`. `yamine stop`'s
+  0/2/3/4 are untouched: those answer "what did the stop do", and this
+  answers "is the app up".
+- **`yamine restart` no longer promises a reboot it cannot perform.**
+  A managed socket app is rebooted on the next request; a `yamine start`
+  app is stopped and has to be started again, because the daemon cannot
+  rebuild a tcp backend (its port is a free port chosen at boot and the
+  route records no command to re-run). The command and the daemon's own
+  events now say which one you have.
+- **A boot that started nothing no longer reports `ready:` and hangs.**
+  A process whose `cmd` is a compound line is refused with an error and
+  leaves the spawn plan empty; the boot then printed `ready:` and sat in
+  the supervision loop for ever with nothing to watch — a hang that looks
+  exactly like a healthy start. It exits 1 instead, naming the error
+  above it.
+
+### Changed
+
+- **A `yamine start` app is watched by the proxy daemon, but is not
+  idle-killed.** This is the one visible consequence of the supervision
+  fix above, so it is called out rather than buried: previously *no*
+  `yamine start` app was ever idle-killed, and now restart.txt and crash
+  detection work — but the idle clock still does not touch them, because
+  idle-kill is the half of puma-dev that depends on the other half
+  ("stopped, boots on next request"), and the daemon cannot keep that
+  promise for a tcp route. Killing one would take a developer's app down
+  for an afternoon and leave a 503 where it was. Set `YAMINE_IDLE_TCP=1`
+  for the puma-dev behaviour on `yamine start` apps, with the same
+  `YAMINE_IDLE_TIMEOUT` clock (15 minutes by default; that is the
+  supervisor's clock, distinct from the proxy's own
+  `YAMINE_PROXY_IDLE_TIMEOUT`). For the same reason `yamine proxy stop`
+  no longer stops `yamine start` apps along with the socket ones the
+  daemon booted: those have a supervising process of their own.
+
+### Fixed
+
+- **A slow app and a dead app no longer come back as the same useless
+  502.** Waiting for the backend's response *head* and waiting for body
+  bytes shared one clock, and `read_head` swallowed its own timeout into
+  the same `[nil, ...]` a dead backend returns — so `pipe_request` could
+  not tell them apart and every one of them got the same 60-byte page,
+  "The target app is not responding." A font request that took 60,068ms
+  came back with no hostname, no target, no owner, no directory and no
+  next step. The head now has its own budget
+  (`YAMINE_PROXY_HEAD_TIMEOUT`, default 60s — the same bound it already
+  got, so nothing that works today starts failing), the body keeps
+  `YAMINE_PROXY_IDLE_TIMEOUT` untouched, and a silent backend is reported
+  as what it is: *the backend at 127.0.0.1:3000 accepted the connection,
+  then sent no response for 60 seconds*, with the owning agent, the app's
+  own directory (`spec.dir`, not the proxy's cwd — inside a worktree that
+  is the wrong checkout), the path to its `log/development.log`, and the
+  `cd <dir> && yamine start` that fixes it. Machines get the same split
+  in a header: `x-yamine-error: backend-refused` or `backend-silent`.
+  A body clock that was tuned tight for one and a head clock that is not
+  are no longer the same dial, so a streaming response that goes quiet
+  between bytes still runs indefinitely.
+- **A request that was merely slow now gets a second attempt.** One
+  retry, and only where a retry cannot duplicate work: a refused dial
+  never reached the app, so any method replays; a head timeout means the
+  head *did* arrive, so only bodiless GET, HEAD and OPTIONS replay. A
+  GET that takes 61 seconds to answer now serves instead of 502ing. A
+  POST never replays — the body is already consumed off the client socket
+  and cannot be resent faithfully, and a duplicated message is worse than
+  a slow page.
+## [0.21.2] — 2026-09-29
+
+### Fixed
+
+- **Linux no longer orphans the app behind a boot's shell.** Every
+  process is spawned as `["sh", "-c", cmd]`, so the pid yamine tracks
+  is the *shell* — and on Linux a TERM to that shell does not reach the
+  app behind it, which reparents to init and keeps running. Every stop
+  path inherited the hole: `yamine stop` printed "Stopped <host>" and
+  left the app serving, Ctrl-C left the whole tree up, and
+  `yamine worktree remove` deleted the directory under a live process.
+  (macOS forwards the signal, which is why the unit suite never saw
+  it.) Each process now spawns as its own process-group leader and
+  stop signals the *group*, so one syscall reaches the shell and
+  everything below it. Only a pid that actually leads a group is
+  signalled by group id — the kernel is asked first — so the paths that
+  never had a shell in front of them (a directly-spawned puma, a pid
+  that is already gone) keep signalling exactly as before.
+- **A stop that lands while the tree is still being built no longer
+  leaves a live process behind.** The group signal reaches the members
+  that exist at the instant it is sent, and a `sh -c` shell that has
+  not forked its app yet forks it *after* that sweep — so the app never
+  hears the TERM, reparents to init, and goes on serving with its
+  directory already on the way out. Measured on linux: TERM the group a
+  few milliseconds after the spawn and the shell dies while the app
+  comes up behind it and stays up. Asking was never the same as
+  stopping, and every caller that goes on to report "Stopped", drop the
+  route, or delete the worktree was exposed. Stops now ask and then
+  insist: TERM the group, let it leave on its own terms briefly, and
+  KILL whatever is still in it — liveness asked of the *group*, since a
+  dead leader that is a zombie still answers to its own pid while a live
+  tree behind it does not. The signal-trap path keeps the single-shot
+  signal, because a trap handler must not sleep.
+
 ## [0.21.1] — 2026-09-29
 
 ### Fixed

data/README.md

@@ -355,11 +355,12 @@ as the app answering 404. `yamine status` reports which mode an app is in.
 
 ```bash
 yamine                        # boot app (waits until healthy, then supervises)
+yamine start --detach         # boot in the background; returns once healthy, prints url/pid/log
 yamine start --no-wait        # fire-and-forget (register routes immediately)
 yamine start --json           # machine-readable wait result (--wait default)
 yamine get <name>             # print URL for cross-service wiring
 yamine alias <name> <port>    # static route (e.g. Docker)
-yamine list [--json]          # show active routes (+ backend liveness)
+yamine list [--json]          # show active routes (+ the APP's liveness)
 yamine status [--json]        # show effective naming context here
 yamine doctor [--json]        # machine-readable health checks
 yamine open [name]            # open the app URL in a browser
@@ -369,7 +370,7 @@ yamine prune                  # remove stale routes
 yamine db list|create|drop|describe    # per-worktree databases (multi-database aware)
 yamine worktree list|add|remove|clean   # worktree lifecycle
 yamine stop                   # stop this app's backend + routes
-yamine restart                # touch tmp/restart.txt (managed apps reboot)
+yamine restart                # touch tmp/restart.txt (a supervised app's backend is stopped)
 yamine log [-F] [n]           # tail (or follow) log/development.log
 yamine proxy start|stop       # control the proxy
 yamine service install|status|uninstall   # root-owned OS startup service
@@ -413,7 +414,19 @@ in-process). Hostnames that fall outside the configured TLDs get a bare
 (healthcheck path when declared, TCP accept otherwise). On failure it
 exits 1 with the failed process, its phase, and the tail of its own log
 — no guessing, no polling, no half-booted routes. `--no-wait` keeps the
-old fire-and-forget path.
+old fire-and-forget path. A child that dies later ends the run the same
+way: exit 1, naming the process, its exit status (or the signal that
+took it down) and the tail of its log. Zero means the app is up.
+
+`yamine start --detach` boots the same tree into the background and
+returns once it is healthy, printing the URL, the pid that owns the tree
+and its log path under the state dir (`start-<hostname>.pid` /
+`start-<hostname>.log`). The boot runs in the child, so that pid is the
+one recorded in `routes.json` — the route outlives the command. It is
+idempotent (a tree already running for the directory is reported, not
+restarted), it ignores `--no-wait` (returning before the app answers is
+the thing it exists to prevent), and `--json` returns
+`{ok, url, pid, log_path, started}`.
 
 ## Log rotation
 
@@ -424,15 +437,29 @@ lose the tail. `doctor` warns when the state dir passes 100MB.
 
 ## Supervision
 
-Managed apps are supervised by the proxy daemon, not the CLI:
-
-- idle backends stop after 15 minutes (`YAMINE_IDLE_TIMEOUT`
-  seconds; `0` disables) and boot transparently on the next request
-- touching `tmp/restart.txt` stops the backend; next request reboots it
-- crashed backends are detected and rebooted on the next request
-- daemon shutdown stops every supervised backend (no orphans)
-
-Run-mode (TCP) routes and static aliases are never supervised.
+Apps are supervised by the proxy daemon, not the CLI. A route is
+supervised when it names a directory to boot from (`spec.dir`), which
+is every app yamine boots — managed socket apps *and* `yamine start`
+trees. Static aliases are not.
+
+- touching `tmp/restart.txt` stops the backend. A managed socket app
+  then reboots on the next request; a `yamine start` app has to be
+  started again (`yamine restart` says which one you have)
+- crashed backends are detected, and a managed app is rebooted on the
+  next request
+- a managed app idle-kills after 15 minutes (`YAMINE_IDLE_TIMEOUT`
+  seconds; `0` disables) and boots transparently on the next request
+- daemon shutdown stops the backends the daemon booted (no orphans)
+
+A `yamine start` app is **watched but not idle-killed**, and is not
+stopped when the proxy stops. Idle-kill is the half of puma-dev that
+depends on the other half — "stopped, boots on next request" — and the
+daemon can only keep that promise for a socket app: a tcp route's port
+is a free port chosen at boot and the route records no command to
+re-run, so nothing could bring it back. Set `YAMINE_IDLE_TCP=1` to get
+the puma-dev behaviour for `yamine start` apps too (same
+`YAMINE_IDLE_TIMEOUT` clock — the supervisor's, distinct from the
+proxy's own `YAMINE_PROXY_IDLE_TIMEOUT`).
 
 ## Ask ecosystem integration
 

data/lib/ask/skills/yamine/SKILL.md

@@ -36,6 +36,7 @@ no extra gem — the proxied hostname is allowed automatically via
 yamine start              # setup if needed, then boot every process (waits until healthy)
 yamine start --no-wait   # fire-and-forget (register routes immediately)
 yamine start --json       # machine-readable wait result (--wait default)
+yamine start --detach    # boot in the background; returns once healthy, prints url/pid/log
 yamine                    # same as start
 yamine stop               # stop this app's backend + routes
 yamine status             # show service, processes, and URLs
@@ -44,7 +45,16 @@ yamine log [-F]           # tail log/development.log (every process)
 
 `$PORT` and `YAMINE_URL` are injected per process; HTTP processes get
 stable URLs, background ones are supervised without routes. A process
-that exits cleans up the whole tree.
+that exits cleans up the whole tree — and ends the run with exit 1,
+naming that process, its exit status and the tail of its log. Zero from
+`yamine start` means the app is up.
+
+`--detach` is the one to use from a tool: it forks the boot, so the
+command returns with the URL, the pid that owns the tree (recorded in
+`routes.json`, so the route outlives the command) and that tree's log
+path under `~/.yamine/`. Run it again and it reports the running tree
+instead of starting a second one; `yamine stop` stops it. Do not reach
+for `nohup` — the tree yamine starts is the one `yamine stop` can reach.
 
 The boot narrates every phase — deps, db, schema, and each process's
 healthcheck — one line per phase, so a slow boot is never a black box:
@@ -193,6 +203,15 @@ yamine prune                  # clear stale routes from crashed sessions
 yamine start --json           # boot readiness payload (pass/fail + log tail)
 ```
 
+`yamine list` reports the state of the **app**, not of the yamine
+process that started it: `running`, `backend-gone` (the app died, the
+process that booted it is still there), `owner-gone` (both gone),
+`unknown` (no backend pid recorded — nothing is known, it is not a
+failure), and `reachable` / `unreachable` for a `yamine alias`, which
+points at a port rather than a process. `yamine restart` stops the
+backend; a managed app reboots on the next request, a `yamine start` app
+has to be started again.
+
 If a hostname does not resolve — or boot/doctor report it as not in
 `/etc/hosts` and you use clients that read only that file (CGO-disabled
 Go binaries): `yamine hosts sync`. If the browser warns about TLS: