yamine 0.21.2 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 618e529eeea12aa43397e084455136a4062bd55a546e904a1cb4170e3fc1466f
-  data.tar.gz: aa598da83330345ca84a60b168539262aa516df7440d6d91611b5cc853c584ec
+  metadata.gz: 69848a3d38cd9997ca18e52ea892aa57962524e0cd41df16199a651409e86b76
+  data.tar.gz: aebe3dd18c4bab95865491850bb940ca9a7e42c83f53d851b4d3ddd691f80305
 SHA512:
-  metadata.gz: 848bb6e6cced84dc132e38dc2ce4828c3514b4fca2c4596e796e9e938b1b2f23d164aadea56e14aed9e8c13d7f732723ede5b377f443db068f74bfd7a9e88410
-  data.tar.gz: 453dd9432df8527eace777b7894abf8540b60f103243ce4917593cd021c38506a0aa76614ca0eb926caea5ebfca6f25177729148e5342f22e1b571f7571d104a
+  metadata.gz: 7c1bb5ef1104c29a53c8e4274a5b4a42f7231f895f40bb7d12defc97dee72232944340c24b4bec62b9a736d29bdab01d975b32cf6e1af7aaf7f1b643ec0ac602
+  data.tar.gz: 66ef5d87789c27a94994c0d24f1567c1a762d592ecbfb00b3d95db8a7f538f3c6868be3703a9870a88d0101aabb37dcfaba8f6db85b2e4a74799b4a4381c7280

data/CHANGELOG.md

@@ -2,6 +2,138 @@
 
 ## [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

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:

data/lib/yamine/cli/boot.rb

@@ -8,6 +8,13 @@ module Yamine
     # No inference, no Procfile at boot, no single-process default.
     module BootCommand
       PORT_IGNORING = %w[jekyll middleman bridgetown].freeze
+      # How long the detaching process waits for the app to answer before
+      # it reports that it did not. Generous on purpose: the boot running
+      # inside the child has its own budget per phase (Readiness's, 45s a
+      # process, plus deps/db/schema), and this is the parent giving up
+      # on a child still doing legitimate work. A boot that fails ends
+      # the wait on its own, long before this.
+      DETACH_TIMEOUT = 300
 
       module_function
 
@@ -16,12 +23,14 @@ module Yamine
       # boots every process, supervises the tree, cleans up on exit.
       def run_inferred(ctx, args)
         variant = ENV["YAMINE_VARIANT"]
-        opts = ctx.parse_flags(args, %i[variant tld force app_port wait no_wait json branch])
+        opts = ctx.parse_flags(args, %i[variant tld force app_port wait no_wait json branch detach])
         resolved = resolve!(ctx, variant: opts[:variant] || variant, tld: opts[:tld],
           use_branch: opts[:branch])
         # Ownership gate before any side effects: no proxy spawn, no
         # port allocation when we'd refuse anyway.
         check_worktree_ownership!(ctx, resolved, force: opts[:force])
+        return detach_boot(ctx, resolved, opts) if opts[:detach]
+
         ensure_proxy!(ctx, json: opts[:json])
         boot_all(ctx, resolved, opts)
       end
@@ -163,8 +172,19 @@ module Yamine
         routes_registered.each { |r| named_pids[r[:app].pid] = r[:app].name }
         children.each { |c| named_pids[c[:pid]] = c[:name] }
         all_hostnames = routes_registered.flat_map { |r| r[:hostnames] }
+        # Nothing to supervise is not a boot. collect_spawns refuses a
+        # compound cmd line with an error and leaves the plan empty, and
+        # the boot then printed `ready: ` and sat in supervise_tree for
+        # ever with an empty pid map — a hang indistinguishable from a
+        # healthy start, and one `--detach` would have made its caller
+        # wait out. The errors above it name the process it refused.
+        if named_pids.empty?
+          $stderr.puts "Error: no process was started — see the errors above."
+          exit 1
+        end
         trap_cleanup(ctx, all_hostnames, named_pids.keys)
-        supervise_tree(ctx, all_hostnames, named_pids, reporter: events)
+        supervise_tree(ctx, all_hostnames, named_pids, reporter: events,
+          json: opts[:json])
       end
 
       # TERM the old server and make sure the pidfile no longer names
@@ -332,13 +352,10 @@ module Yamine
       end
 
       def tail_for(failure, apps)
-        name = failure[:name]
-        slot = apps[name]
-        path = slot ? File.expand_path(File.join(Dir.pwd, "log", "development.log")) : nil
-        lines = path && File.file?(path) ? File.readlines(path).last(20).join : "(no log file)"
-        { path: path, tail: lines }
-      rescue SystemCallError
-        { path: path, tail: "(unreadable log)" }
+        # Every process appends to the same file, so the app slot only
+        # decides whether there is a process to blame for it.
+        path = apps[failure[:name]] ? app_log_path : nil
+        { path: path, tail: path ? log_tail(path) : "(no log file)" }
       end
 
       def stop_spawned(app)
@@ -845,30 +862,278 @@ module Yamine
         File.file?(File.join(Dir.pwd, "config", "application.rb"))
       end
 
+      # `yamine start --detach`: boot into the background and hand control
+      # back, so an agent gets its prompt (and its exit code) without
+      # reaching for nohup.
+      #
+      # The route's recorded owner pid is the thing this has to get
+      # right, and it is why the boot happens in the child and never in
+      # the parent: `add_route` records `Process.pid`, and
+      # RouteStore#load_routes prunes every route whose pid is dead. 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. So the child boots — its pid is
+      # what lands in routes.json — keeps the tree supervised, and
+      # outlives this process. The parent only waits and reports.
+      def detach_boot(ctx, resolved, opts)
+        hostname = Resolver.hostname_for(resolved, Resolver.primary_proc(resolved))
+        raise Error, "no HTTP process (proxy: true) in config/local.yml to detach" unless hostname
+
+        url = Hostname.url(hostname, port: ctx.proxy_port, tls: ctx.proxy_tls)
+        pidfile, log = detach_paths(ctx.store, hostname)
+        running = detached_pid(pidfile) || foreground_owner(ctx, hostname)
+        return report_detached(hostname, url, log, running, opts, started: false) if running
+
+        # Ensured here, in the process still attached to the caller: a
+        # sudo prompt, a port clash or a missing setup has to be reported
+        # by something whose exit code and output the caller can see.
+        ensure_proxy!(ctx, json: opts[:json])
+        pid = fork { detached_child(ctx, resolved, opts, hostname, pidfile, log) }
+        await_detached(ctx, hostname, url, log, pid, opts)
+      end
+
+      # Detach bookkeeping under the state dir, beside the routes the
+      # tree owns. The pidfile is the only record of WHICH process
+      # supervises a detached tree (routes.json holds the app's route and
+      # `yamine stop` reaches the backend through the sidecar), which is
+      # also what makes a second `--detach` a no-op instead of a second
+      # app fighting over the same hostname.
+      def detach_paths(store, hostname)
+        [File.join(store.dir, "start-#{hostname}.pid"),
+         File.join(store.dir, "start-#{hostname}.log")]
+      end
+
+      # The pid of a detached tree, or nil. A pidfile whose process is
+      # gone is not a tree — it is a crash or a stop that never got to
+      # clean up — and reading it as one would make `--detach` refuse to
+      # start anything on that hostname again.
+      def detached_pid(pidfile)
+        return nil unless File.file?(pidfile)
+
+        pid = File.read(pidfile).strip.to_i
+        pid.positive? && ProxyControl.pid_alive?(pid) ? pid : nil
+      rescue SystemCallError, ArgumentError
+        nil
+      end
+
+      # A foreground `yamine start` in this directory has no pidfile, so
+      # the route it registered is the other record of a tree already
+      # running here. Without this, `--detach` beside a live foreground
+      # boot would fork, lose the race for the route, and report a boot
+      # failure for an app that is up and serving.
+      def foreground_owner(ctx, hostname)
+        entry = ctx.store.find(hostname)
+        return nil unless entry && entry["pid"] != 0
+        return nil unless entry["agent"] == Agent.name
+        return nil unless entry.dig("spec", "dir") == File.expand_path(Dir.pwd)
+
+        ProxyControl.pid_alive?(entry["pid"]) ? entry["pid"] : nil
+      end
+
+      # The detached half: its own session, its own stdio, and the whole
+      # boot. `setsid` so the tree outlives the shell that started it and
+      # takes no SIGHUP from a terminal about to close; the log file so
+      # the boot's narration, and the message that ends the run, have
+      # somewhere to land once this process is gone.
+      def detached_child(ctx, resolved, opts, hostname, pidfile, log)
+        Process.setsid
+        redirect_detached_io(log)
+        File.write(pidfile, "#{Process.pid}\n")
+        # `--no-wait` has nothing left to say here: the promise of
+        # detaching is that the command returns once the app answers, so
+        # the child always takes the health-gated path.
+        boot_all(ctx, resolved, opts.merge(no_wait: nil, detach: nil))
+      rescue SystemExit => e
+        # The boot exits on purpose — a failed health wait, a child that
+        # died, a signal from `yamine stop` — and that status is the only
+        # report there will ever be. `exit!` rather than `exit` because a
+        # forked block turns a raise into a generic failure, and rather
+        # than a normal exit because the pidfile is ours to remove: a
+        # dead tree must not leave a pidfile claiming one is running.
+        detach_forget(pidfile)
+        exit!(e.status)
+      rescue StandardError => e
+        $stderr.puts "[yamine] detached boot failed: #{e.message.lines.first&.strip}"
+        detach_forget(pidfile)
+        exit!(1)
+      end
+
+      # stdin from /dev/null so a read never blocks on a terminal that
+      # has gone away; both streams into the log; sync, because a
+      # buffered stream in a process that may live for hours is a log
+      # that shows nothing until it exits.
+      def redirect_detached_io(log)
+        io = Log.open_append(log)
+        $stdin.reopen(File::NULL)
+        $stdout.reopen(io)
+        $stderr.reopen(io)
+        $stdout.sync = $stderr.sync = true
+      ensure
+        io&.close
+      end
+
+      # Remove the pidfile, but only while it is still ours: a second
+      # `--detach` that already replaced the file must not have its
+      # record deleted by the first tree's cleanup.
+      def detach_forget(pidfile)
+        return unless File.read(pidfile).strip.to_i == Process.pid
+
+        FileUtils.rm_f(pidfile)
+      rescue SystemCallError
+        nil
+      end
+
+      # Wait for the app to answer, then say what happened. Two things
+      # end the wait: the route appears — which on the health-gated path
+      # means every process passed its check, since the child registers
+      # nothing until they all do — or the child exits, which is a boot
+      # that failed and has already written why into the log.
+      #
+      # The route's recorded pid is what proves it is THIS child's: a
+      # route left over from an earlier run would otherwise pass for a
+      # successful boot of one that never happened.
+      def await_detached(ctx, hostname, url, log, pid, opts)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + DETACH_TIMEOUT
+        status = nil
+        loop do
+          entry = ctx.store.find(hostname)
+          return report_detached(hostname, url, log, pid, opts, started: true) if
+            entry && entry["pid"] == pid
+          # WNOHANG, and it has to be a wait: the child is this
+          # process's own child, so a dead one sits in the process table
+          # as a zombie until it is reaped and `kill(0, pid)` would
+          # report it alive for as long as we sat here waiting.
+          _waited, status = Process.waitpid2(pid, Process::WNOHANG)
+          break if status
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            status = :timeout
+            break
+          end
+
+          sleep 0.25
+        end
+        detach_failed(hostname, url, log, status, opts)
+      end
+
+      # The report on success, and the report on "was already up": the
+      # URL, the pid that owns the tree, and where its output goes.
+      # `--json` gets the same three as a payload, because an agent's
+      # next move is `yamine list` and "started" with no pid to stop
+      # again is not a usable answer.
+      def report_detached(hostname, url, log, pid, opts, started:)
+        payload = { ok: true, url: url, hostnames: [hostname], pid: pid,
+          log_path: log, started: started }
+        if opts[:json]
+          puts JSON.generate(payload)
+          return
+        end
+        if started
+          puts "Detached: #{url}"
+        else
+          puts "Already running: #{url} (pid #{pid})"
+          puts "  Nothing was started; `yamine stop` stops this one."
+          return
+        end
+        puts "  pid  #{pid}"
+        puts "  log  #{log}"
+      end
+
+      # Never zero, and never "started". The reason it is not serving is
+      # in the log and nowhere else, so that is where the report points.
+      def detach_failed(hostname, url, log, status, opts)
+        reason =
+          case status
+          when :timeout then "did not become healthy within #{DETACH_TIMEOUT}s"
+          when nil then "was killed before serving"
+          else "exited (#{describe_status(status)})"
+          end
+        payload = { ok: false, url: url, hostnames: [hostname], reason: reason,
+          log_path: log, log_tail: log_tail(log) }
+        if opts[:json]
+          $stderr.puts "Error: yamine start --detach: #{hostname} #{reason}."
+          puts JSON.generate(payload)
+        else
+          $stderr.puts "Error: yamine start --detach: #{hostname} #{reason}."
+          $stderr.puts log_tail(log, lines: 10)
+          $stderr.puts "  log: #{log}"
+        end
+        exit 1
+      end
+
+      # The one log every process in a tree appends to (Runner#log_path),
+      # so it is also the one log worth reading when a child dies.
+      def app_log_path
+        File.expand_path(File.join(Dir.pwd, "log", "development.log"))
+      end
+
+      # Last lines of the app log, for failure payloads and for the
+      # message that ends a run. Never raises: a missing or unreadable
+      # log is part of the failure being reported, not a second failure.
+      def log_tail(path = app_log_path, lines: 20)
+        return "(no log file)" unless File.file?(path)
+
+        File.readlines(path).last(lines).join
+      rescue SystemCallError
+        "(unreadable log)"
+      end
+
+      # What a pid we spawned exited with, in words an agent can read:
+      # a code, or the signal that took it down. A pid with no status to
+      # report (never ours, not yet reaped) says so rather than guessing
+      # a code.
+      def describe_status(status)
+        return "status unknown" unless status
+        return "signal #{status.termsig}" if status.signaled?
+
+        "exit #{status.exitstatus}"
+      end
+
       # Supervise the booted tree: the first child to exit ends the run,
       # because a half-stack is worse than no stack — a dead jobs worker
       # with a live web process looks healthy until someone wonders why
-      # nothing is being processed. Name the casualty and its log: "a
-      # process exited" left the user to guess which one, and the log
-      # worth reading is per-process.
-      def supervise_tree(ctx, hostnames, named_pids, reporter: nil)
+      # nothing is being processed. Name the casualty, its status and its
+      # log: "a process exited" left the user to guess which one, and the
+      # log worth reading is the one every process appends to.
+      #
+      # The status is 1, never 0. `yamine start` is how an agent decides
+      # whether the app came up, and a zero here reads as "healthy": the
+      # routes are already removed, the rest of the tree is being killed,
+      # and the app is not serving. An agent that trusted it would go on
+      # to curl a URL that answers 503 and blame the app. It is the code
+      # the --wait path already uses for a boot that never became
+      # healthy, so "the app is not up" stays one meaning — and it is a
+      # different question from the one `yamine stop` answers with its
+      # 0/2/3/4, which is about what a stop did.
+      def supervise_tree(ctx, hostnames, named_pids, reporter: nil, json: false)
         loop do
           sleep 0.5
           dead = named_pids.find { |pid, _| !ProxyControl.pid_alive?(pid) }
-          if dead
-            pid, name = dead
-            $stderr.puts "\n[#{name}] exited (pid #{pid}) — stopping the whole tree."
-            log = File.join(Dir.pwd, "log", "development.log")
-            $stderr.puts "  log: #{log}" if File.file?(log)
-            reporter&.note("#{name} exited; cleaning up routes")
-            cleanup_routes(ctx, hostnames)
-            # Kill remaining children — by group, so a `sh -c` backend's
-            # process dies with the shell we hold a pid for.
-            named_pids.each_key do |other|
-              ProcessTree.term(other)
-            end
-            exit 0
+          next unless dead
+
+          pid, name = dead
+          status = ProcessTree.status(pid)
+          log = app_log_path
+          $stderr.puts "\n[#{name}] exited (pid #{pid}, #{describe_status(status)}) " \
+            "— stopping the whole tree."
+          reporter&.note("#{name} exited; cleaning up routes")
+          if json
+            # stdout stays the machine stream: the event lines above it,
+            # this payload last, exactly as the --wait failure reads.
+            puts JSON.generate({ ok: false, error: "child-exited", name: name,
+              pid: pid, status: status&.exitstatus, signal: status&.termsig,
+              log_path: File.file?(log) ? log : nil,
+              log_tail: log_tail(log) }.compact)
+          elsif File.file?(log)
+            $stderr.puts log_tail(log, lines: 10)
+            $stderr.puts "  log: #{log}"
+          end
+          cleanup_routes(ctx, hostnames)
+          # Kill remaining children — by group, so a `sh -c` backend's
+          # process dies with the shell we hold a pid for.
+          named_pids.each_key do |other|
+            ProcessTree.term(other)
           end
+          exit 1
         end
       end
 

data/lib/yamine/cli/context.rb

@@ -104,7 +104,7 @@ module Yamine
           elsif arg.start_with?("--")
             key = arg.sub(/\A--/, "").tr("-", "_").to_sym
             if known.include?(key)
-              if %i[branch force wait no_wait json].include?(key)
+              if %i[branch force wait no_wait json detach].include?(key)
                 opts[key] = true
                 i += 1
               else