yamine 0.21.2 → 0.22.1

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

data/lib/yamine/cli/routes.rb

@@ -36,14 +36,7 @@ module Yamine
         routes = ctx.store.load_routes
         port = ctx.proxy_port
         tls = ctx.proxy_tls
-        entries = routes.map do |r|
-          { hostname: r["hostname"],
-            url: Hostname.url(r["hostname"], port: port, tls: tls),
-            target: r["target"], kind: r["kind"],
-            pid: r["pid"], agent: r["agent"],
-            supervised: !r["spec"].nil?,
-            alive: alive_state(ctx, r) }
-        end
+        entries = routes.map { |r| entry_for(ctx, r, port: port, tls: tls) }
         if json
           require "json"
           puts JSON.generate({ routes: entries, proxy_port: port, tls: tls })
@@ -61,6 +54,25 @@ module Yamine
         puts
       end
 
+      # One route as `yamine list` reports it.
+      #
+      # `pid` stays the route's recorded owner (the yamine process that
+      # registered it — that is what routes.json holds and what
+      # `yamine stop` and the ownership gate compare), and `backend_pid`
+      # is added beside it because `alive` is now the app's state: an
+      # agent reading `alive: running` next to a `pid` that has since
+      # exited could not tell which process the verdict was about. Both
+      # are in the payload, so nothing that was readable is lost.
+      def entry_for(ctx, route, port:, tls:)
+        { hostname: route["hostname"],
+          url: Hostname.url(route["hostname"], port: port, tls: tls),
+          target: route["target"], kind: route["kind"],
+          pid: route["pid"], backend_pid: ctx.backend_pid_for(route),
+          agent: route["agent"],
+          supervised: !route["spec"].nil?,
+          alive: alive_state(ctx, route) }
+      end
+
       # Shared discovery: `get --all` lists every live route (any owner)
       # with its URL and agent, so one agent can find another's services
       # without coupling. `--json` emits the same stable keys as list.
@@ -89,24 +101,64 @@ module Yamine
         end
       end
 
+      # Liveness of the APP, not of the yamine process that registered
+      # the route. `route["pid"]` is that process's own pid — Runner
+      # passes Process.pid at every add_route call site — and it outlives
+      # the app it booted, so asking it whether the app is alive answered
+      # a different question. Every crashed backend read as "running",
+      # in the one command an agent would reach for to find out. The
+      # app's pid is in the sidecar the boot wrote
+      # (state_dir/backend-<hostname>.pid), the same file `yamine stop`
+      # reads for exactly this reason.
+      #
+      # Five states, and the split that matters is running vs
+      # backend-gone:
+      #
+      #   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 — unknowable, deliberately not "down"
+      #   reachable /   a static alias (pid 0) names no process at all,
+      #   unreachable   so it reports the probe and nothing else
+      #
+      # `unknown` is the honest answer for a route with no sidecar: one
+      # written by a yamine old enough not to write sidecars, or by a
+      # boot that died between registering the route and writing the
+      # file. There is no evidence of a dead app there, and calling it
+      # down would have every pre-existing route on the machine read as
+      # broken after an upgrade.
       def alive_state(ctx, route)
-        if route["pid"] == 0
-          ctx.backend_alive?(route) ? "reachable" : "unreachable"
-        elsif ProxyControl.pid_alive?(route["pid"])
-          "running"
-        else
-          "owner-gone"
-        end
+        return ctx.backend_alive?(route) ? "reachable" : "unreachable" if route["pid"] == 0
+
+        backend = ctx.backend_pid_for(route)
+        return owner_state(ctx, route) if backend.nil?
+
+        ProxyControl.pid_alive?(backend) ? "running" : "backend-gone"
       rescue StandardError
         "unknown"
       end
 
+      # What we know with no app pid to ask: whether the process that
+      # registered the route is still there. `owner-gone` keeps the
+      # meaning it has always had — the route outlived its owner, which
+      # is the case load_routes leaves behind for `yamine prune`.
+      def owner_state(ctx, route)
+        ProxyControl.pid_alive?(route["pid"]) ? "unknown" : "owner-gone"
+      end
+
+      # The human line. The pid shown next to the state is the one the
+      # state is about: the app's, when there is one. Printing the route
+      # owner's pid beside "running" is how a dead app kept reading as a
+      # healthy one.
       def label_for(entry)
         owner = entry[:agent] ? " #{entry[:agent]}" : ""
         if entry[:pid] == 0
           "(alias, #{entry[:alive]}#{owner})"
+        elsif entry[:backend_pid]
+          "(backend #{entry[:backend_pid]}, #{entry[:alive]}#{owner})"
         else
-          "(pid #{entry[:pid]}, #{entry[:alive]}#{owner})"
+          "(owner #{entry[:pid]}, #{entry[:alive]}#{owner})"
         end
       end
 
@@ -115,6 +167,7 @@ module Yamine
       # report the probe, not a process.
       def route_label(ctx, route)
         entry = { pid: route["pid"], alive: alive_state(ctx, route) }
+        entry[:backend_pid] = ctx.backend_pid_for(route)
         label_for(entry)
       end
 
@@ -247,13 +300,37 @@ module Yamine
         2
       end
 
-      # Touch tmp/restart.txt so a supervised managed app reboots.
-      def restart(_ctx, _args)
+      # Touch tmp/restart.txt so a supervised app's backend is stopped.
+      #
+      # What happens next is not the same for every route, so it is said
+      # rather than assumed: a managed socket app is rebooted on the next
+      # request, while a `yamine start` app is stopped and has to be
+      # started again (the daemon cannot rebuild a tcp backend — see
+      # Supervisor#rebootable?). The old one-liner promised a reboot for
+      # both, and for a tcp route nothing was even watching the file.
+      def restart(ctx, _args)
         path = File.join(Dir.pwd, "tmp", "restart.txt")
         require "fileutils"
         FileUtils.mkdir_p(File.dirname(path))
         FileUtils.touch(path)
-        puts "Touched #{path} — managed app restarts on next request."
+        puts "Touched #{path}."
+        # The routes this directory registered, found by spec.dir rather
+        # than by resolving the app: the file was written either way, and
+        # a directory with no config/local.yml must not turn a no-op into
+        # a config error.
+        here = File.expand_path(Dir.pwd)
+        entries = ctx.store.load_routes.select { |r| r.dig("spec", "dir") == here }
+        if entries.empty?
+          puts "No yamine app is registered for this directory — nothing will be restarted."
+          return
+        end
+        entries.each do |entry|
+          if entry["kind"] == "socket"
+            puts "#{entry["hostname"]} reboots on the next request."
+          else
+            puts "#{entry["hostname"]} will be stopped; start it again with `yamine start`."
+          end
+        end
       end
 
       # Tail the shared app log (default 50 lines); --follow streams.

data/lib/yamine/cli/system.rb

@@ -517,15 +517,15 @@ module Yamine
       # expiring, or renamed.
       #
       # The ordering is the whole point, so it lives in one place rather
-      # than at each call site. `trusted?` compares a marker against the
-      # fingerprint of the certificate ON DISK, and a proxy regenerates
-      # the CA at boot when the name changes. Checking the marker before
-      # the CA is current therefore reads a stale match, skips trust, and
-      # lets the proxy come up serving a CA the keychain does not trust —
-      # breaking TLS for every route.
+      # than at each call site. The state-dir marker is only half of it
+      # (`Trust.trusted?` also asks the OS): a marker that says "we
+      # trusted this" survives a keychain that never took the setting,
+      # so checking it before the CA is current — or on its own — reads
+      # a stale match, skips trust, and lets the proxy come up serving a
+      # CA no browser trusts.
       def ca_current_and_trusted?(dir = Certs.state_dir)
         Certs.ensure_ca(dir)
-        Certs.trusted?(dir)
+        Trust.trusted?(dir)
       end
 
       # Root-only CA trust: the System keychain (all users, no prompt).
@@ -946,23 +946,33 @@ module Yamine
 
               yamine start              # block until every route is healthy, then supervise
               yamine start --no-wait   # fire-and-forget (register routes immediately)
+              yamine start --detach    # boot in the background, return once the app is healthy
               yamine start --json       # machine-readable result payload (--wait only)
               yamine start -- --help   # pass --help to the app, not here
 
             Options are passed through to the boot path:
               --variant <v> --tld <tld> --force --app-port <port>
-              --wait (alias, default) --no-wait --json
+              --wait (alias, default) --no-wait --json --detach
 
             Default waits: every process is spawned concurrently, each
             healthcheck (or TCP accept when none is declared) is polled,
             routes are registered only when all are healthy, and `ready:`
             is printed with exit 0. On failure everything spawned is
             killed, the failed process + its log tail is printed, and
-            the CLI exits 1 — no half-booted routes. `--no-wait` keeps
-            the old fire-and-forget path.
+            the CLI exits 1 — no half-booted routes. `--no-wait` keeps the
+            old fire-and-forget path.
+
+            --detach forks the boot: the child owns the tree, its pid is
+            the one recorded in routes.json, and this process waits for
+            the app to answer, prints the URL, that pid and the log path
+            under the state dir, then exits 0. It is idempotent — a tree
+            already running for this directory is reported, not started
+            again. --no-wait is ignored with it: the point of detaching is
+            that the command returns once the app is actually serving.
 
             Setup failures become hard errors pointing at `yamine setup`;
             non-interactive CI without a running proxy exits immediately.
+
           HELP
           return
         end

data/lib/yamine/cli.rb

@@ -83,6 +83,7 @@ module Yamine
 
         Usage:
           yamine start                 One-setup-and-go: setup if needed, then boot -> https://<app>.localhost
+          yamine start --detach        Same, in the background; returns once the app is healthy
           yamine setup                One-shot workstation setup without booting (run once)
           yamine                        Bare form of `start` — boots every process in config/local.yml
           yamine get <name>             Print URL for a service
@@ -103,10 +104,10 @@ module Yamine
           yamine hosts sync|clean       Manage /etc/hosts entries
           yamine kamal <variant>        Preview-deploy snippet for Kamal
           yamine stop                   Stop this app's backend + routes
-          yamine restart                Touch tmp/restart.txt
+          yamine restart                Touch tmp/restart.txt (a supervised app is stopped)
           yamine log [-F] [n]           Tail (or follow) log/development.log
 
-        Flags: --variant, --tld, --force, --app-port, --wait (default), --no-wait, --json, --branch
+        Flags: --variant, --tld, --force, --app-port, --wait (default), --no-wait, --detach, --json, --branch
         Env: YAMINE_VARIANT/TLD/PORT/STATE_DIR/AGENT, YAMINE_BRANCH=1
       HELP
     end

data/lib/yamine/doctor.rb

@@ -192,6 +192,15 @@ module Yamine
       unless Certs.trusted?(dir)
         return Check.new(name: "ca", ok: false, message: "CA not trusted — run: yamine trust")
       end
+      # The marker says WE trusted this certificate; it says nothing about
+      # whether the OS recorded a trust setting for it. A CA sitting in
+      # the keychain with no trust setting is the state that produced
+      # ERR_CERT_AUTHORITY_INVALID on every route, with the marker
+      # cheerfully reporting success.
+      unless Trust.trusted?(dir)
+        return Check.new(name: "ca", ok: false,
+          message: "CA is installed but macOS does not trust it — run: yamine trust")
+      end
 
       # Trusted CAs that are not the one now on disk. They accumulate from
       # CA regeneration (missing, expiring, or renamed — the ask-local