yamine 0.15.2 → 0.16.0

data/lib/yamine/cli/worktree.rb

@@ -25,9 +25,24 @@ module Yamine
       module_function
 
       # Per-checkout config that git does not carry: a fresh worktree
-      # boots without these (missing secrets, no proxy config) — the
-      # single largest follow-up cost of a new worktree.
-      LOCAL_CONFIG_FILES = %w[config/local.yml config/local.secrets].freeze
+      # boots without these — missing secrets, no proxy config, and (for
+      # credentials apps) no decryption key, which stops Rails before it
+      # can even read database.yml. The single largest follow-up cost of
+      # a new worktree, now carried automatically.
+      LOCAL_CONFIG_FILES = %w[config/local.yml config/local.secrets config/master.key].freeze
+      # Rails 7.1+ per-env credentials: development.key & co are
+      # gitignored exactly like master.key and equally fatal without.
+      CREDENTIALS_KEY_GLOB = "config/credentials/*.key"
+
+      # The static list plus whatever key files this checkout has, plus
+      # the worktree marker: everything yamine writes or copies that
+      # must never read as uncommitted work.
+      def local_config_files(dir)
+        keys = Dir.glob(File.join(dir, CREDENTIALS_KEY_GLOB)).map do |path|
+          path.sub(%r{\A#{Regexp.escape(dir.chomp("/"))}/?}, "")
+        end
+        LOCAL_CONFIG_FILES + keys + [Database::MARKER_FILE]
+      end
 
       def run(ctx, args)
         sub = args.first
@@ -52,7 +67,10 @@ module Yamine
           default_branch = Worktrees.default_branch(repo)
           Worktrees.list(repo).each do |entry|
             next if entry.bare
-            puts "  #{entry_line(entry, claim_for(map, entry.path), repo, default_branch)}"
+
+            claim = claim_for(map, entry.path)
+            puts "  #{entry_line(entry, claim, repo, default_branch)}"
+            print_claim_databases(claim)
             printed = true
           end
         end
@@ -66,14 +84,17 @@ module Yamine
       def entry_line(entry, claim, repo, default_branch)
         name = entry.main? ? "main" : (entry.branch || "(detached)")
         line = "#{name}  #{entry.path}"
-        line += "  db #{claim[0]}" if claim
+        if claim
+          names = claim[1].is_a?(Hash) ? claim[1]["names"] : nil
+          line += names && !names.empty? ? "  db #{names.size} databases" : "  db #{claim[0]}"
+        end
 
         flags = []
         flags << "main checkout" if entry.main?
         flags << "detached" if entry.detached && !entry.main?
         flags << "dir gone" unless entry.exists?
         if !entry.main? && entry.exists?
-          flags << "dirty" if Worktrees.dirty?(entry.path, ignore: LOCAL_CONFIG_FILES)
+          flags << "dirty" if Worktrees.dirty?(entry.path, ignore: local_config_files(entry.path))
           if entry.detached
             flags << "unmerged"
           else
@@ -85,6 +106,18 @@ module Yamine
         line
       end
 
+      # Every database a claim stands for, one per line under the row —
+      # five names inline would unreadable, and hiding them would
+      # re-create the "which database is this worktree even using"
+      # question the claim exists to answer.
+      def print_claim_databases(claim)
+        info = claim && claim[1]
+        names = info.is_a?(Hash) ? info["names"] : nil
+        return unless names.is_a?(Hash) && !names.empty?
+
+        names.each_value { |db| puts "      db: #{db}" }
+      end
+
       # yamine worktree add <name> [--dir <path>] [--no-install]
       #
       # `name` is the branch (feature/login stays feature/login — the
@@ -135,13 +168,16 @@ module Yamine
 
       def copy_local_config(from_dir, to_dir)
         copied = []
-        LOCAL_CONFIG_FILES.each do |rel|
+        local_config_files(from_dir).each do |rel|
           src = File.join(from_dir, rel)
           next unless File.file?(src)
 
           dst = File.join(to_dir, rel)
           FileUtils.mkdir_p(File.dirname(dst))
           FileUtils.cp(src, dst)
+          # Decryption keys stay as private in the worktree as they
+          # were in the checkout — FileUtils.cp does not carry modes.
+          File.chmod(0o600, dst) if rel.end_with?(".key")
           copied << rel
         end
         copied
@@ -158,27 +194,36 @@ module Yamine
         puts "  bundle install did not finish — run it in #{dir} before booting" unless $?.success?
       end
 
-      # Claim the per-worktree database and create it now (with the
+      # Claim this worktree's databases and create them now (with the
       # app's schema) so server problems surface at creation time, not
-      # at first boot. Boot reuses an existing database idempotently, so
-      # this is never wasted work. SQLite and template-less apps need
-      # nothing; setup_database says so itself.
+      # at first boot. Rails apps are ASKED what they have (the probe
+      # resolves database.yml + credentials inside the app itself) and
+      # get the whole suffixed set — claim, marker file, databases,
+      # schema. Boot reuses an existing set idempotently, so this is
+      # never wasted work. SQLite and non-Rails apps fall through to
+      # the single-database path, which setup_database narrates.
       def prepare_database(ctx, dir)
         return nil unless Config.load(dir)
 
-        db_name = Database.name_for(dir, env: BootCommand.rails_env,
+        claim_key = Database.name_for(dir, env: BootCommand.rails_env,
           state_dir: ctx.store.dir)
-        Dir.chdir(dir) do
-          BootCommand.setup_database(ctx, Resolver.resolve(dir), db_name)
+        rows = Probe.rails_databases(dir)
+        server = rows && Probe.server_backed(rows)
+        if server && !server.empty?
+          BootCommand.provision_multidb(ctx, dir, claim_key, server)
+        else
+          Dir.chdir(dir) do
+            BootCommand.setup_database(ctx, Resolver.resolve(dir), claim_key)
+          end
         end
-        db_name
+        claim_key
       end
 
-      def say_ready(ctx, dir, name, db_name)
+      def say_ready(ctx, dir, name, db_key)
         puts "Worktree ready:"
         puts "  dir      #{dir}"
         puts "  branch   #{name}"
-        puts "  db       #{db_name}" if db_name
+        print_ready_databases(ctx, db_key)
         if (resolved = resolved_quietly(dir))
           Resolver.urls(resolved, port: ctx.proxy_port, tls: ctx.proxy_tls)
             .each { |u| puts "  url      #{u}" }
@@ -186,6 +231,18 @@ module Yamine
         puts "  boot it: cd #{dir} && yamine start"
       end
 
+      def print_ready_databases(ctx, db_key)
+        return unless db_key
+
+        names = Database.load_map(ctx.store.dir).dig(db_key, "names")
+        if names.is_a?(Hash) && !names.empty?
+          puts "  db       #{names.size} databases:"
+          names.each_value { |db| puts "             #{db}" }
+        else
+          puts "  db       #{db_key}"
+        end
+      end
+
       def resolved_quietly(dir)
         Resolver.resolve(dir)
       rescue StandardError
@@ -214,7 +271,7 @@ module Yamine
           return
         end
 
-        if Worktrees.dirty?(entry.path, ignore: LOCAL_CONFIG_FILES) && !opts[:force]
+        if Worktrees.dirty?(entry.path, ignore: local_config_files(entry.path)) && !opts[:force]
           $stderr.puts "Error: #{entry.path} has uncommitted changes."
           $stderr.puts "  Commit or stash them, or re-run with --force to discard them."
           exit 1
@@ -309,7 +366,7 @@ module Yamine
             plan << Plan.new(:prune, entry)
             next
           end
-          if Worktrees.dirty?(entry.path, ignore: LOCAL_CONFIG_FILES)
+          if Worktrees.dirty?(entry.path, ignore: local_config_files(entry.path))
             plan << Plan.new(:keep, entry.path, "uncommitted changes are never cleaned automatically")
             next
           end
@@ -328,29 +385,55 @@ module Yamine
       end
 
       # An admin entry whose directory vanished (rm -rf, a crashed
-      # agent): drop the database it claimed, forget the claim. The git
-      # entry itself is cleared by the trailing prune. A template with
-      # no server behind it (sqlite) means there is nothing to drop and
-      # no retry that could help — the claim is simply forgotten.
+      # agent): drop every database it claimed, forget the claim. The
+      # git entry itself is cleared by the trailing prune. The claim
+      # itself carries the names AND the server coordinates — an
+      # orphan's config is unreadable by definition, and the app must
+      # not have to boot (or even still bundle) for cleanup to work.
+      # A claim with no server behind it (sqlite) means there is
+      # nothing to drop and no retry that could help — the claim is
+      # simply forgotten. A LEGACY claim with no reachable template
+      # anywhere (credentials apps pre-multi-database never declared
+      # one) is also forgotten, with the database name said out loud:
+      # erroring forever would leave `clean` permanently red for a
+      # claim no future command can ever resolve.
       def drop_orphan(ctx, name, _dir)
+        info = Database.load_map(ctx.store.dir)[name]
+        pairs = Database.claim_pairs(info)
         template = orphan_template(ctx)
-        unless template
-          $stderr.puts "Error: no DATABASE_URL template found (ENV or env.clear in " \
-            "config/local.yml) — cannot drop #{name}."
-          return false
+
+        if pairs.nil?
+          unless template
+            warn "  no DATABASE_URL template found (ENV or env.clear in config/local.yml) — " \
+                 "cannot reach #{name}; claim forgotten."
+            warn "    If a database named #{name} still exists on a server, drop it manually."
+            forget_claim(ctx, name)
+            return true
+          end
+          pairs = [[name, template]]
+        else
+          pairs = pairs.map { |db, tmpl| [db, (tmpl || template)] }
         end
-        unless %i[postgres mysql].include?(Database.adapter_for(template))
+
+        first_url = pairs.first&.[](1)
+        unless %i[postgres mysql].include?(first_url && Database.adapter_for(first_url))
           puts "  #{name} has no server database (sqlite/unknown adapter) — claim forgotten"
           forget_claim(ctx, name)
           return true
         end
-        case Database.drop(name, template)
-        when :dropped then puts "  dropped #{name}"
-        when :missing then puts "  #{name} did not exist — nothing to drop"
-        when :failed
-          warn "  could not drop #{name} — is the server running? Claim kept for a retry."
-          return false
+
+        failed = false
+        pairs.each do |db, tmpl|
+          case Database.drop(db, tmpl)
+          when :dropped then puts "  dropped #{db}"
+          when :missing then puts "  #{db} did not exist — nothing to drop"
+          when :failed
+            warn "  could not drop #{db} — is the server running? Claim kept for a retry."
+            failed = true
+          end
         end
+        return false if failed
+
         forget_claim(ctx, name)
         true
       end
@@ -419,7 +502,7 @@ module Yamine
         stop_routes(ctx, dir)
 
         if claim
-          outcome = drop_database(repo, dir, claim[0])
+          outcome = drop_database(repo, dir, claim[0], claim[1])
           if outcome == :failed
             warn "  kept #{dir} — database drop failed; fix the server and re-run"
             return false
@@ -476,22 +559,35 @@ module Yamine
         end
       end
 
-      def drop_database(repo, dir, name)
-        template = drop_template_for(repo, dir)
-        adapter = template && Database.adapter_for(template)
-        unless %i[postgres mysql].include?(adapter)
+      # Drop every database a claim stands for: the whole suffixed set
+      # for a multi claim, the one key-named database for a legacy
+      # single claim. Any :failed aborts the whole teardown (kept for
+      # a retry) — a half-dropped set with a removed worktree is
+      # orphan territory, and orphans are the bug this guards.
+      def drop_database(repo, dir, name, info = nil)
+        fallback = drop_template_for(repo, dir)
+        pairs = Database.claim_pairs(info) || [[name, fallback]]
+        pairs = pairs.map { |db, tmpl| [db, (tmpl || fallback)] }
+
+        first_url = pairs.first&.[](1)
+        unless %i[postgres mysql].include?(first_url && Database.adapter_for(first_url))
           puts "  no server database to drop for #{name} " \
-            "(#{template ? "sqlite/unknown adapter" : "no DATABASE_URL template"})"
+            "(#{first_url ? "sqlite/unknown adapter" : "no DATABASE_URL template"})"
           return :missing
         end
 
-        outcome = Database.drop(name, template)
-        case outcome
-        when :dropped then puts "  dropped #{name}"
-        when :missing then puts "  #{name} did not exist — nothing to drop"
-        when :failed then puts "  could not drop #{name} — is the database server running?"
+        outcomes = pairs.map do |db, tmpl|
+          outcome = Database.drop(db, tmpl)
+          case outcome
+          when :dropped then puts "  dropped #{db}"
+          when :missing then puts "  #{db} did not exist — nothing to drop"
+          when :failed then puts "  could not drop #{db} — is the database server running?"
+          end
+          outcome
         end
-        outcome
+        return :failed if outcomes.include?(:failed)
+
+        outcomes.include?(:dropped) ? :dropped : :missing
       end
 
       # Reach the database server from the worktree's own config (read

data/lib/yamine/cli.rb

@@ -94,7 +94,7 @@ module Yamine
           yamine trust                  Add local CA to trust store
           yamine clean                  Remove state and hosts entries
           yamine prune                  Remove stale routes
-          yamine db list|create|drop      Per-worktree databases
+          yamine db list|create|drop|describe   Per-worktree databases (multi-database aware)
           yamine worktree list|add|remove|clean   Worktrees: create, inspect, full cleanup
           yamine skills install           Install yamine skill into ~/.agents/skills/ (or --local)
           yamine proxy start|stop       Control the proxy

data/lib/yamine/database.rb

@@ -32,6 +32,12 @@ module Yamine
 
     MAX_IDENTIFIER_BYTES = 63
     STATE_FILE = "databases.json"
+    # Written into a worktree at add time; the app's database.yml
+    # reads it and suffixes every database URL, so hand-run commands
+    # (console, test, db:migrate) land on the worktree's own
+    # databases too — env injection only ever reaches processes
+    # yamine spawns.
+    MARKER_FILE = ".yamine-db-suffix"
 
     # Database name for a worktree dir + env (development/test).
     # Main checkout (no worktree marker) keeps the bare name.
@@ -77,7 +83,12 @@ module Yamine
       if map.key?(name) && map[name]["dir"] != dir
         return nil
       end
-      map[name] = { "dir" => dir, "claimed_at" => Time.now.utc.iso8601 }
+      # Merge, don't replace: boot re-claims on every run, and a
+      # multi-database claim's suffix/names/bases are stored under
+      # this key — a fresh hash would erase them and orphan the whole
+      # set on the next drop.
+      map[name] = (map[name] || {}).merge("dir" => dir,
+        "claimed_at" => Time.now.utc.iso8601)
       save_map(state_dir, map)
       name
     rescue SystemCallError
@@ -93,13 +104,99 @@ module Yamine
       {}
     end
 
+    # Claim URLs carry database passwords (the app's own resolved
+    # config, probed at worktree-add time), so the state file is
+    # private — it held no secrets before multi-database claims.
     def save_map(state_dir, map)
       FileUtils.mkdir_p(state_dir)
-      File.write(File.join(state_dir, STATE_FILE), JSON.pretty_generate(map))
+      path = File.join(state_dir, STATE_FILE)
+      File.write(path, JSON.pretty_generate(map))
+      File.chmod(0o600, path)
     rescue SystemCallError
       nil
     end
 
+    # ── multi-database claims ─────────────────────────────────────
+    #
+    # A multi-database claim carries the whole set beside the usual
+    # dir/claimed_at:
+    #   suffix  the token every database name gains — also the marker
+    #           file's contents, the one string yamine and the app's
+    #           database.yml must agree on, byte for byte
+    #   names   config name -> actual database name
+    #   bases   config name -> the app's own URL (server coordinates
+    #           for create/drop; where the suffix gets inserted)
+    # Single-database claims predate this and have none of the three;
+    # every reader falls back to the claim key as the one name.
+
+    # The suffix for a worktree: the claim key minus the env. Base
+    # names already carry the environment (myrr_markdown_development),
+    # so appending "_development" a second time only burns identifier
+    # budget. The claim key keeps the env (and the collision guard);
+    # the suffix is what has to fit inside a database name.
+    def suffix_for(claim_name, env)
+      stripped = claim_name.delete_suffix("_#{env}")
+      stripped.empty? ? claim_name : stripped
+    end
+
+    # Fit the suffix so `base + "_" + suffix` stays within the
+    # identifier cap for ANY base: budget against the longest one.
+    # Fitting happens once, here, because the marker file holds the
+    # suffix and the app only concatenates — a hand-run `rails
+    # console` must arrive at byte-identical names with no truncation
+    # logic of its own. Returns nil when even a hash-shortened suffix
+    # cannot fit (a base name so long no suffix follows it); callers
+    # name the problem instead of guessing.
+    def fit_suffix(suffix, dir, base_databases)
+      longest = base_databases.map { |d| d.to_s.bytesize }.max || 0
+      budget = MAX_IDENTIFIER_BYTES - longest - 1
+      return suffix if budget.positive? && suffix.bytesize <= budget
+      return nil if budget < 8
+
+      keep = budget - 7
+      "#{suffix.byteslice(0, keep).gsub(/_+\z/, "")}_#{short_hash(dir)}"
+    end
+
+    # The actual database name for one base under a suffix. Raises
+    # rather than truncating: silent truncation would diverge from
+    # what the marker file produces inside the app, and yamine names
+    # and app names disagreeing is exactly the bug this prevents.
+    # fit_suffix makes this unreachable for fitted suffixes; the
+    # raise guards programmatic misuse.
+    def multiname(base_database, suffix)
+      name = "#{base_database}_#{suffix}"
+      raise ArgumentError,
+        "database name exceeds #{MAX_IDENTIFIER_BYTES} bytes: #{name}" if name.bytesize > MAX_IDENTIFIER_BYTES
+
+      name
+    end
+
+    def write_marker(dir, suffix)
+      File.write(File.join(dir, MARKER_FILE), "#{suffix}\n")
+    end
+
+    def read_marker(dir)
+      path = File.join(dir, MARKER_FILE)
+      File.file?(path) ? File.read(path).strip : nil
+    end
+
+    # Keep the marker out of `git status` without touching the
+    # committed .gitignore: git's exclude file lives in the shared
+    # git dir, so one entry covers every worktree of the repo.
+    def exclude_marker(dir)
+      out, status = Open3.capture2("git", "-C", dir, "rev-parse", "--git-path", "info/exclude")
+      return unless status.success?
+
+      path = out.strip
+      path = File.expand_path(path, dir) unless path.start_with?("/")
+      return if File.file?(path) && File.read(path).lines.any? { |l| l.strip == MARKER_FILE }
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "a") { |f| f.puts MARKER_FILE }
+    rescue SystemCallError, IOError
+      nil
+    end
+
     # The DATABASE_URL template per-worktree names derive from: ENV
     # first, then the config's top-level env.clear, then per-process
     # env.clear (configs written before top-level env existed). Shared
@@ -127,6 +224,29 @@ module Yamine
       load_map(state_dir).select { |_, v| !File.directory?(v["dir"]) }
     end
 
+    # The multi-database claim under `key`, or nil — single-database
+    # claims (and foreign keys) simply have no names, and every reader
+    # falls back to the key itself as the one database name.
+    def multi_claim(state_dir, key)
+      info = load_map(state_dir)[key]
+      info if info.is_a?(Hash) && info["names"].is_a?(Hash) && !info["names"].empty?
+    end
+
+    # Every [database_name, server_url] pair a claim stands for: N
+    # pairs for a multi claim, nil for a legacy single claim (caller
+    # falls back to the key + its own template lookup). bases may lag
+    # names on older claims; a missing base falls back to the first —
+    # all of an app's databases live on one server in every layout
+    # yamine has seen.
+    def claim_pairs(info)
+      names = info.is_a?(Hash) ? info["names"] : nil
+      return nil if names.nil? || names.empty?
+
+      bases = info["bases"] || {}
+      default = bases.values.first
+      names.filter_map { |cfg, db| [db, (bases[cfg] || default)] }
+    end
+
     # Adapter detection from DATABASE_URL scheme. Returns :postgres,
     # :mysql, :sqlite, or :unknown. Only postgres/mysql get create +
     # DATABASE_URL treatment; sqlite is left alone (relative paths
@@ -189,7 +309,11 @@ module Yamine
       return :failed unless reachable
 
       uri = URI.parse(database_url)
-      _out, status = Open3.capture2("dropdb", name, env: pg_env(uri))
+      # env as the FIRST positional (like ensure_postgres): Open3
+      # forwards kwargs to spawn, and spawn has no env: option — as a
+      # kwarg this raised ArgumentError on every real drop, crashing
+      # teardown after the routes were already stopped.
+      _out, status = Open3.capture2(pg_env(uri), "dropdb", name)
       return :dropped if status.success?
 
       reachable, exists = pg_state(name, database_url)
@@ -293,9 +417,12 @@ module Yamine
       args
     end
 
+    # PGHOST only when the URL names a host: an empty authority
+    # (postgres:///dbname) means the unix socket, and forcing
+    # 127.0.0.1 there would reach the wrong server — or none.
     def pg_env(uri)
       {
-        "PGHOST" => uri.host || "127.0.0.1",
+        "PGHOST" => (uri.host unless uri.host.to_s.empty?),
         "PGPORT" => (uri.port || 5432).to_s,
         "PGUSER" => URI.decode_www_form_component(uri.user || ENV["USER"].to_s),
         "PGPASSWORD" => uri.password ? URI.decode_www_form_component(uri.password) : nil

data/lib/yamine/probe.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+
+module Yamine
+  # What databases an app actually has — asked, never guessed.
+  #
+  # A Rails multi-database app keeps its per-database URLs wherever it
+  # likes (credentials, ENV, hard-coded); yamine must not parse
+  # database.yml or touch decryption keys to learn them. The app
+  # itself answers: `bin/rails runner` prints the resolved
+  # configuration for the environment, so whatever the app would
+  # really connect to is exactly what yamine provisions, names, and
+  # drops. Credentials decrypt inside that process — the probe never
+  # sees a key.
+  #
+  # The runner emits one `YAMINE_DBS=<json>` line; Rails boot noise
+  # shares stdout, so the marker (never the last line) finds the
+  # payload. Any failure — no bin/rails, boot error, timeout — returns
+  # nil: the caller falls back to the single-database path. A probe is
+  # an enhancement, not a requirement, and it must never take a boot
+  # down with it.
+  module Probe
+    module_function
+
+    MARKER = "YAMINE_DBS="
+    TIMEOUT = 90
+
+    # Runs inside the app (bin/rails runner), so configuration_hash is
+    # fully resolved: Rails has already parsed any `url:` into
+    # components and decrypted credentials. The URL is rebuilt here
+    # from those components — a password travels from credentials to
+    # the claim file without yamine ever parsing config itself.
+    # SQLite-family adapters keep their scheme and skip the host part;
+    # relative paths already isolate per-worktree, so they never enter
+    # the multi-database claim.
+    SCRIPT = <<~'RUBY'
+      require "json"
+      require "uri"
+      rows = ActiveRecord::Base.configurations
+        .configs_for(env_name: ENV.fetch("RAILS_ENV", "development"))
+        .map do |c|
+          h = c.configuration_hash
+          db = h[:database].to_s
+          url = h[:url].to_s
+          if url.empty?
+            scheme = { "postgresql" => "postgres", "postgres" => "postgres",
+                       "postgis" => "postgres", "mysql2" => "mysql",
+                       "trilogy" => "mysql" }[h[:adapter].to_s]
+            if scheme
+              info = +""
+              if h[:username]
+                info << URI.encode_www_form_component(h[:username].to_s)
+                if h[:password]
+                  info << ":" << URI.encode_www_form_component(h[:password].to_s)
+                end
+                info << "@"
+              end
+              host = h[:host].to_s
+              authority = host.empty? ? "#{info}" : "#{info}#{host}#{h[:port] ? ":#{h[:port]}" : ""}"
+              url = "#{scheme}://#{authority}/#{db}"
+            else
+              url = "#{h[:adapter]}:#{db}"
+            end
+          end
+          { "name" => c.name, "database" => db, "url" => url }
+        end
+      puts "YAMINE_DBS=#{JSON.generate(rows)}"
+    RUBY
+
+    # [{ "name", "database", "url" }, ...] for the environment, or nil
+    # when the app cannot answer (not Rails, boot failure, timeout).
+    def rails_databases(dir, env: nil)
+      env ||= ENV.fetch("RAILS_ENV", "development")
+      bin = File.join(dir, "bin", "rails")
+      return nil unless File.file?(bin)
+
+      out = +""
+      status = nil
+      # A stray DATABASE_URL (or NAME_DATABASE_URL) in the caller's
+      # environment would win over database.yml inside the resolver —
+      # the probe must see the app's own configuration. spawn MERGES
+      # the env hash over the inherited one, so merely omitting the
+      # keys would leave them in place: pass them as nil to unset.
+      scrub = ENV.keys
+        .select { |k| k == "DATABASE_URL" || k.end_with?("_DATABASE_URL") }
+        .to_h { |k| [k, nil] }
+      child_env = scrub.merge("RAILS_ENV" => env)
+      Open3.popen2e(child_env, bin, "runner", SCRIPT, chdir: dir) do |stdin, stdout, wait|
+        stdin.close
+        begin
+          Timeout.timeout(TIMEOUT) { out = stdout.read }
+        rescue Timeout::Error
+          Process.kill("KILL", wait.pid) rescue nil
+          wait.value rescue nil
+          return nil
+        end
+        status = wait.value
+      end
+      return nil unless status&.success?
+
+      parse(out)
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    # The marker line amidst whatever the boot printed. JSON parse
+    # failure returns nil rather than raising: garbage in, "cannot
+    # probe" out.
+    def parse(output)
+      line = output.to_s.lines.find { |l| l.start_with?(MARKER) }
+      return nil unless line
+
+      rows = JSON.parse(line.delete_prefix(MARKER).strip)
+      return nil unless rows.is_a?(Array)
+
+      rows.select { |r| r.is_a?(Hash) && r["name"] && r["url"] && r["database"] }
+        .then { |r| r.empty? ? nil : r }
+    rescue JSON::ParserError
+      nil
+    end
+
+    # The subset that lives on a server (postgres/mysql). SQLite and
+    # friends need no provisioning — their relative paths are already
+    # per-worktree — so they never enter a claim.
+    def server_backed(rows)
+      rows.select { |r| %i[postgres mysql].include?(Yamine::Database.adapter_for(r["url"])) }
+    end
+  end
+end

data/lib/yamine/proxy.rb

@@ -485,7 +485,12 @@ module Yamine
       items = routes.map { |r| "<li>#{escape(r["hostname"])}</li>" }.join
       body = "<h1>No app registered for #{escape(bare)}</h1>" \
              "#{hint}<ul>#{items}</ul>"
-      respond(sock, 404, body)
+      # 503, not 404: 404 says the app answered and has nothing at that path,
+      # and a client that believes it goes looking for a bug in the app. This
+      # is the proxy saying the app is not there — the same answer a dead
+      # backend gets (502 Bad Gateway), so no caller has to read the body to
+      # tell "not running" from "the app said no".
+      respond(sock, 503, body)
     end
 
     def render_bad_gateway(sock)