coatepec 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 550a60896b3c267b12b5db85b787c52d93b97dd2b95409c8bf78943ea63a27d0
-  data.tar.gz: '09c6cbbc7c00dd604d2cb5dfbabbb0101aea3cadf5d24070f3254a144bb45012'
+  metadata.gz: 72a7dae3c61c36718da0a815ac037c9a50b1a2ae76e282e67d6533131d21c28f
+  data.tar.gz: 99c4c1bd193cffe81e49d711f6bedfebd5cb1552ab91f4455ab7b4d31fbabda5
 SHA512:
-  metadata.gz: 484557dd0635d21f7669a12b6accab0684e4850e4ac91b6718b733bd23372aceaa5b903f387facb22fdc6b0c2d0a09dfb4805ace67e6b24c66f95c482240d69b
-  data.tar.gz: e3fcc83c1f752dfba27b1260584b2ee1d0df5707e36163d049015babe269290a2467b3018c0e3696d8d6c4d4fcaf5bf8b2e325a3792ac7d3bcb085cad433e73c
+  metadata.gz: 845750211ab96287bccd73b1108451357453925cd0113e92d4251dacca836437783cf78288fa8ca63de5fdbaa772e1ed1f1fc8ce2afbcb346ff9e2f55c1be85a
+  data.tar.gz: '04698525bb87f82b589a6d50a61a18edbbd4b8e1520fcdf41d3c9e682b75af664480e4dd5adc2cea54be1f8c6afbe71defc4d8157949e954e90c63d60d9e935c'

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.9.0
+
+- `rails_spec_run` results always carry `execution_mode`: `fork` (Linux, or
+  a macOS guarded fork that ran), `spawn` (macOS with `macos_fork: false`),
+  `spawn_fallback` (the guard declined to fork) or `spawn_after_crash` (the
+  forked child crashed and the run was retried). The key used to appear
+  only when the guarded fork was in play.
+- Behaviour change on macOS: projects that never set `macos_fork: true` now
+  fork the warm worker by default, the way it always has on Linux, using
+  the guarded fork shipped in 0.7.0 (thread-count and gem-denylist checks,
+  a spawn retry if the child crashes). Set `macos_fork: false` in
+  `.coatepec.yml` to keep a fresh spawn per call. Measured on a Rails
+  8.2.0.alpha app: 966 ms saved per run, no fallbacks across nine runs.
+  `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` is now a recommendation for
+  projects that see `spawn_after_crash`, not a requirement.
+- `.coatepec.yml` gains a `defaults` map: `spec_run.include_passing`,
+  `spec_run.include_stdout`, `spec_run.timeout_seconds` and `routes.engines`
+  set project-wide defaults for those inputs. A call argument always wins;
+  an omitted key means the built-in default; an unknown key or an
+  out-of-range value fails the call with `invalid_config` naming it. The
+  file is re-read on every call.
+- `rails_runtime_status` reports `spec_strategy` (`fork`, `guarded_fork` or
+  `spawn`), `fallbacks` (how many guarded-fork runs fell back to spawn in
+  this worker's lifetime; `null` unless the guarded fork is in use) and
+  `defaults` (the effective `rails_spec_run` and `rails_routes` defaults
+  after `.coatepec.yml`), so an agent can see every default in one call.
+  `fallbacks` also counts `rails_spec_flaky_check` rounds, which run through
+  the same strategy.
+
 ## 0.8.0
 
 - Tool responses are now compact JSON rather than pretty-printed (22-32%

data/README.md

@@ -58,8 +58,8 @@ MCP client
 Coatepec parent (Rails-free)
     `-- private NDJSON --> test worker (Rails "test", booted lazily, kept warm)
                               |-- Linux:  Process.fork  --> isolated RSpec/Minitest child
-                              `-- macOS:  Process.spawn --> fresh RSpec/Minitest process (default)
-                                          Process.fork, guarded --> opt-in, see Configuration
+                              `-- macOS:  Process.fork, guarded --> isolated RSpec/Minitest child (default)
+                                          Process.spawn --> fresh process, see Configuration (macos_fork: false)
 ```
 
 ## Configuration
@@ -68,28 +68,43 @@ An optional `.coatepec.yml` at the target Rails app's root enables
 per-project settings:
 
 ```yaml
-macos_fork: true                     # opt into forking on macOS (see below)
+macos_fork: false                    # opt out of forking on macOS (default true; see below)
 macos_fork_unsafe_gems: [some_gem]   # extends the built-in fork-unsafe denylist
+
+defaults:
+  spec_run:
+    include_passing: true            # true or false (default false)
+    include_stdout: always           # failures (default), always, never
+    timeout_seconds: 300             # 1..900 (default 120)
+  routes:
+    engines: include                 # include, exclude (default), only
 ```
 
 A missing file means every setting takes its default -- this file is never
 required.
 
+`defaults` sets project-wide values for those four inputs; a call argument
+always wins, an omitted key falls back to the built-in default, and an
+unknown key or value fails the call with `invalid_config` naming it. The
+file is re-read on every call, so edits apply immediately.
+`defaults.spec_run` applies to `rails_spec_run` only; `rails_spec_flaky_check`
+keeps its own per-round budget.
+
 Tool responses are compact JSON -- no indentation, nothing downstream reads
 it. Set `COATEPEC_PRETTY=1` in the MCP server's `env` (the same place as
 `OBJC_DISABLE_INITIALIZE_FORK_SAFETY` in the JSON example below) to
 pretty-print them when you are reading the sidecar by hand.
 
-### macOS fork (experimental, opt-in)
+### macOS fork (default since 0.9.0)
 
-On macOS, `rails_spec_run` normally spawns a fresh `bundle exec rspec`
-process per call, re-booting Rails every time -- the warm-worker speedup
-described above only applies on Linux by default. Setting `macos_fork:
-true` lets Coatepec attempt `Process.fork` on macOS too, reusing the warm
-boot the way Linux does.
+On macOS, `rails_spec_run` forks the warm worker for each call, reusing the
+boot the way it always has on Linux. Setting `macos_fork: false` in
+`.coatepec.yml` opts the project out: every call then spawns a fresh
+`bundle exec rspec` process and re-boots Rails, so only the Linux lane
+gets the warm-worker speedup described above.
 
-This is opt-in because forking a process with native extensions loaded
-isn't universally safe. Before each fork, Coatepec checks the worker's
+The fork is guarded, because forking a process with native extensions
+loaded isn't universally safe. Before each fork, Coatepec checks the worker's
 live thread count against its post-boot baseline and its loaded gems
 against a denylist, falling back to a fresh spawn for that one call if
 either check looks risky. The built-in denylist ships empty -- no single
@@ -98,17 +113,17 @@ thread-count-only until a project adds its own
 `macos_fork_unsafe_gems`. If a fork is attempted and the child crashes
 anyway, Coatepec transparently retries via spawn and returns that result
 -- fork stays enabled for later calls. Every `rails_spec_run` result
-includes an `execution_mode` field (`fork`, `spawn_fallback`, or
-`spawn_after_crash`) so you can see which path actually ran for a given
+includes an `execution_mode` field (`fork`, `spawn`, `spawn_fallback`,
+or `spawn_after_crash`) so you can see which path actually ran for a given
 call; `spawn_after_crash` results also carry the crashed fork's own stderr
 under `crashed_fork_stderr` so the crash can be diagnosed.
 
-`macos_fork: true` also effectively requires
-`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` in Coatepec's own environment.
-Without it, a forked child that touches an Objective-C-initialized class
-aborts -- Coatepec retries via spawn, so it degrades silently to the slow
-path (no crash, no error surfaced) rather than failing loudly, and you
-simply never get the speedup. Set it on the MCP server process itself:
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` in Coatepec's own environment is
+recommended if you ever see `spawn_after_crash`. Without it, a forked child
+that touches an Objective-C-initialized class aborts -- Coatepec retries via
+spawn, so it degrades to the slow path for that call (no crash, no error
+surfaced) rather than failing loudly, and you simply never get the speedup.
+Set it on the MCP server process itself:
 
 ```json
 {
@@ -130,10 +145,10 @@ a no-op.
 
 | Tool | Input | Notes |
 |---|---|---|
-| `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120), `include_passing?`, `include_stdout?` (`failures` default, `always`, `never`) | RSpec (`spec/**/*_spec.rb`) or Minitest (`test/**/*_test.rb`), chosen from the paths; isolated per run; output capped at 256 KiB per stream; failure blocks in `stdout` that repeat an earlier block's error verbatim are replaced by a roll-up line naming the tests; returns `summary` counts (`example_count`, `failure_count`, `error_count`, `pending_count`, `assertion_count`, `duration`; the error and assertion counts come from Minitest and are `null` for RSpec) plus only the failed/pending `examples`, pass `include_passing: true` for the full roster (still capped at 500 examples); `stdout` is returned only for failing runs by default; `include_stdout: "always"` keeps it for green runs, `"never"` drops it always (the key stays, `null`); `stderr` is always returned; `child_pid`/`signaled`/`termsig`/`stopsig`/`coredump` appear only when the child did not exit normally (a timeout kill or a crash) |
-| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state, and the project root (`project_root`) |
-| `rails_runtime_restart` | `{}` | Unconditionally respawns the worker, discarding its warm boot |
-| `rails_routes` | `query?`, `limit?` (1..200, default 100), `offset?`, `engines?` (`exclude` default, `include`, `only`) | Returns `columns` (`name`, `verb`, `path`, `controller`, `action`, `engine`) and `rows` in that order; paths omit the `(.:format)` suffix Rails appends. Case-insensitive filter across name/verb/path/controller/action/engine. Application routes only by default; `engines: "include"` adds the routes of mounted engines (one level deep, paths prefixed with the mount point, `engine` naming the engine class; `null` for an application route), `"only"` returns just those. Every response carries `engines` (the filter applied) and `engines_excluded` (how many routes matching `query` the filter withheld), so nothing is hidden silently. The filter applies after `query` and before paging, so `matched`/`next_offset` describe the kept set. The engine's mount route counts as an application route. Routes Rails marks `internal` are omitted, like `bin/rails routes`. `next_offset` is the offset of the next page, or `null` on the last one |
+| `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120), `include_passing?`, `include_stdout?` (`failures` default, `always`, `never`) (all three default-able in `.coatepec.yml`) | RSpec (`spec/**/*_spec.rb`) or Minitest (`test/**/*_test.rb`), chosen from the paths; isolated per run; output capped at 256 KiB per stream; failure blocks in `stdout` that repeat an earlier block's error verbatim are replaced by a roll-up line naming the tests; returns `summary` counts (`example_count`, `failure_count`, `error_count`, `pending_count`, `assertion_count`, `duration`; the error and assertion counts come from Minitest and are `null` for RSpec) plus only the failed/pending `examples`, pass `include_passing: true` for the full roster (still capped at 500 examples); `stdout` is returned only for failing runs by default; `include_stdout: "always"` keeps it for green runs, `"never"` drops it always (the key stays, `null`); `stderr` is always returned; `child_pid`/`signaled`/`termsig`/`stopsig`/`coredump` appear only when the child did not exit normally (a timeout kill or a crash); every result carries `execution_mode` (`fork`, `spawn`, `spawn_fallback`, `spawn_after_crash`) |
+| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state, the project root, `spec_strategy` (`fork`, `guarded_fork`, `spawn`), `fallbacks` (guarded-fork runs that fell back to spawn; `null` unless guarded) and `defaults` (the effective `rails_spec_run`/`rails_routes` defaults after `.coatepec.yml`) |
+| `rails_runtime_restart` | `{}` | Unconditionally respawns the worker, discarding its warm boot; returns the fresh worker's status, including `spec_strategy` and `fallbacks` |
+| `rails_routes` | `query?`, `limit?` (1..200, default 100), `offset?`, `engines?` (`exclude` default, `include`, `only`) (default-able in `.coatepec.yml`) | Returns `columns` (`name`, `verb`, `path`, `controller`, `action`, `engine`) and `rows` in that order; paths omit the `(.:format)` suffix Rails appends. Case-insensitive filter across name/verb/path/controller/action/engine. Application routes only by default; `engines: "include"` adds the routes of mounted engines (one level deep, paths prefixed with the mount point, `engine` naming the engine class; `null` for an application route), `"only"` returns just those. Every response carries `engines` (the filter applied) and `engines_excluded` (how many routes matching `query` the filter withheld), so nothing is hidden silently. The filter applies after `query` and before paging, so `matched`/`next_offset` describe the kept set. The engine's mount route counts as an application route. Routes Rails marks `internal` are omitted, like `bin/rails routes`. `next_offset` is the offset of the next page, or `null` on the last one |
 | `rails_model` | `name` (constant path, e.g. `Widget` or `Admin::Widget`), `fields?` (any of `columns`, `associations`, `validators`, `enums`; omitted or `[]` means none) | Returns `name`, `table_name`, `primary_key`, `abstract_class` and `counts` (the size of each of the four lists, each capped at 200) by default and only the lists named in `fields` -- so a how-many question costs a few dozen bytes and `fields: ["columns"]` asks for the one list you need; ActiveRecord models only; columns, associations, validators, enums -- no row data; validators are de-duplicated by class, attributes and options (a concern and the model body declaring the same validation count once), so the count can be lower than `klass.validators.size`; an array-valued validator option longer than 20 entries (a country-code `inclusion` list, say) is cut to its first 20 with `<option>_count` and `<option>_truncated: true` beside it |
 | `rails_controller` | `name` (constant path, e.g. `WidgetsController` or `Admin::ReportsController`) | Actions, action callbacks, concerns, and the routes reaching each action -- no request dispatch |
 | `rails_spec_flaky_check` | `paths`, `example?`, `timeout_seconds?` (per round, 1..900), `runs?` (2..20, default 5) | Runs the selection `runs` times with a fresh random seed each round; reports tests whose status was inconsistent across runs; RSpec or Minitest, chosen from the paths |
@@ -161,6 +176,18 @@ a no-op.
   routes mounted from it. Application routes always sort before engine routes,
   so an unfiltered listing (with `engines: "include"`) reads the way
   `bin/rails routes` does.
+- `engines_excluded` is a correctness signal, not only a saving. Engine
+  routes print their paths relative to the mount point, so
+  `bin/rails routes -g admin` cannot find an admin engine's routes at all: it
+  matches the mount line and answers "one admin route" with no hint that
+  anything is missing. `rails_routes(query: "admin")` returns that one row
+  plus `engines_excluded: 243`, so the reader knows the rest exists.
+- Opting in is the expensive path, and it paginates. A broad query with
+  `engines: "include"` on an app with a mounted admin engine costs several
+  times the default response and can still stop at the 100-row page of a
+  larger match (`next_offset` says so), where the default returned the
+  application's routes complete. Reach for `engines: "only"` with the
+  engine's class name when the engine's routes are the question.
 - An engine route's `name` is relative to its engine, not a top-level url
   helper: the row `["audits", "GET", "/widget_admin/audits",
   "widget_admin/audits", "index", "WidgetAdmin::Engine"]` is reached as
@@ -369,7 +396,7 @@ structure without ever handing it a REPL.
 Ruby `>= 3.2`, Rails `>= 7.1, < 8.2`, Minitest 5.x and 6.x (the fixture
 apps pin 6.0.6; the 5.x name-filter flag is unit-tested). CI tests three
 lanes: Rails 8.1 on Linux (primary), Rails 7.1 on Linux (compat), and Rails
-8.1 on macOS (which is where the guarded-fork path above actually forks).
+8.1 on macOS (the lane that exercises the guarded-fork path above).
 
 ## Development
 

data/ROADMAP.md

@@ -39,8 +39,9 @@ root-cause writeup and the fix options considered (forcing `SpawnStrategy`
 for profiled runs specifically, vs. detecting and raising a clear error on
 non-spawn strategies, vs. a Linux-only opt-out config knob). Paused
 specifically to wait for real signal on how coatepec is actually used
-(Linux vs. macOS, `macos_fork` adoption) before picking a fix, rather than
-guessing.
+(Linux vs. macOS, `macos_fork` adoption) -- `macos_fork` is the default from
+0.9.0, so the fork path is now the common case on both platforms -- before
+picking a fix, rather than guessing.
 
 ## Run Rails 8.1's built-in CI (`bin/ci`)
 

data/lib/coatepec/mcp/defaults.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../../coatepec"
+
+module Coatepec
+  module MCP
+    # Fills a tool's omitted inputs: call argument first, then .coatepec.yml, then the built-in.
+    module Defaults
+      BUILTIN = {
+        spec_run: { include_passing: false, include_stdout: "failures", timeout_seconds: 120 },
+        routes: { engines: Introspection::Routes::DEFAULT_ENGINES }
+      }.freeze
+
+      module_function
+
+      # Re-reads the file each call: a few hundred bytes, and an edit then applies to the next call.
+      def resolve(tool, project_root, **given)
+        configured = ProjectConfig.new(project_root).defaults_for(tool)
+        BUILTIN.fetch(tool).to_h do |key, builtin|
+          [key, given[key].nil? ? configured.fetch(key, builtin) : given[key]]
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/mcp/tools.rb

@@ -33,18 +33,21 @@ module Coatepec
                   "paths; there is no separate Minitest tool#{RSPEC_VOCABULARY}" \
                   "; returns only failed and pending examples unless include_passing is true" \
                   "; failure blocks in stdout that repeat an earlier error are rolled up into one line" \
-                  "; stdout is returned only for failing runs unless include_stdout is \"always\" or \"never\""
+                  "; stdout is returned only for failing runs unless include_stdout is \"always\" or \"never\"" \
+                  "; defaults for include_passing, include_stdout and timeout_seconds can be set project-wide " \
+                  "in .coatepec.yml"
       annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: true)
       input_schema(**INPUT_SCHEMA)
 
       class << self
-        def call(paths:, server_context:, example: nil, seed: nil, fail_fast: false, timeout_seconds: 120,
-                 include_passing: false, include_stdout: "failures")
+        def call(paths:, server_context:, example: nil, seed: nil, fail_fast: false, timeout_seconds: nil,
+                 include_passing: nil, include_stdout: nil)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          data = server_context[:worker_manager].run_spec(
-            paths: paths, example: example, seed: seed, fail_fast: fail_fast, timeout_seconds: timeout_seconds,
-            include_passing: include_passing, include_stdout: include_stdout
-          )
+          inputs = Defaults.resolve(:spec_run, server_context[:project_root], timeout_seconds: timeout_seconds,
+                                                                              include_passing: include_passing,
+                                                                              include_stdout: include_stdout)
+          data = server_context[:worker_manager].run_spec(paths: paths, example: example, seed: seed,
+                                                          fail_fast: fail_fast, **inputs)
           Response.ok(data: data, meta: Response.meta(started_at))
         rescue Coatepec::Error => e
           Response.error(e)
@@ -53,21 +56,28 @@ module Coatepec
     end
 
     # The `rails_runtime_status` MCP tool: reports the test worker's
-    # Ruby/Rails versions, PID, boot_id, lifecycle state and the project
-    # root. Worker::Server#handle boots the Rails runtime before dispatching
-    # any command, so the first call to this tool starts (and blocks on) a
-    # full Rails boot just like a spec run.
+    # Ruby/Rails versions, PID, boot_id, lifecycle state, the spec strategy
+    # and its fallback count, the project root and the effective tool
+    # defaults. Worker::Server#handle boots the Rails runtime before
+    # dispatching any command, so the first call to this tool starts (and
+    # blocks on) a full Rails boot just like a spec run.
     class RuntimeStatusTool < ::MCP::Tool
       tool_name "rails_runtime_status"
-      description "Report the Coatepec test worker's identity and boot status " \
-                  "(boots the warm worker if it is not up yet); includes the project root as project_root"
+      description "Report the Coatepec test worker's identity and boot status (boots the warm worker if it is " \
+                  "not up yet); includes project_root, spec_strategy (fork, guarded_fork or spawn), fallbacks " \
+                  "(how many guarded-fork runs fell back to spawn; null unless guarded_fork) and defaults (the " \
+                  "effective rails_spec_run and rails_routes defaults after .coatepec.yml)"
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
       input_schema(properties: {}, required: [], additionalProperties: false)
 
       class << self
         def call(server_context:)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          data = server_context[:worker_manager].status.merge(project_root: server_context[:project_root])
+          root = server_context[:project_root]
+          data = server_context[:worker_manager].status.merge(
+            project_root: root,
+            defaults: { spec_run: Defaults.resolve(:spec_run, root), routes: Defaults.resolve(:routes, root) }
+          )
           Response.ok(data: data, meta: Response.meta(started_at))
         rescue Coatepec::Error => e
           Response.error(e)
@@ -147,7 +157,8 @@ module Coatepec
                   "engine field (null for an application route; query also matches that field); returns columns " \
                   "(name, verb, path, controller, action, engine) and up to limit rows (default 100) in that " \
                   "order, paths without the (.:format) suffix Rails appends, with next_offset -- the offset to " \
-                  "pass back for the next page, null on the last one"
+                  "pass back for the next page, null on the last one" \
+                  "; the engines default can be set project-wide in .coatepec.yml"
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
       input_schema(
         properties: {
@@ -161,9 +172,10 @@ module Coatepec
       )
 
       class << self
-        def call(server_context:, query: nil, limit: 100, offset: 0, engines: Introspection::Routes::DEFAULT_ENGINES)
+        def call(server_context:, query: nil, limit: 100, offset: 0, engines: nil)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          data = server_context[:worker_manager].routes(query: query, limit: limit, offset: offset, engines: engines)
+          inputs = Defaults.resolve(:routes, server_context[:project_root], engines: engines)
+          data = server_context[:worker_manager].routes(query: query, limit: limit, offset: offset, **inputs)
           Response.ok(data: data, meta: Response.meta(started_at))
         rescue Coatepec::Error => e
           Response.error(e)

data/lib/coatepec/mcp.rb

@@ -9,6 +9,7 @@ end
 
 require "coatepec"
 require_relative "mcp/response"
+require_relative "mcp/defaults"
 require_relative "mcp/tools"
 
 module Coatepec

data/lib/coatepec/project_config.rb

@@ -7,12 +7,28 @@ module Coatepec
   # project root. A missing file means every setting takes its default --
   # this file has never been required for Coatepec to work.
   class ProjectConfig
+    # Mirrors the MCP input schemas so a value the file accepts is one the tool accepts.
+    DEFAULT_KEYS = {
+      "spec_run" => {
+        "include_passing" => { boolean: true },
+        "include_stdout" => { enum: %w[failures always never] },
+        "timeout_seconds" => { range: 1..900 }
+      },
+      "routes" => { "engines" => { enum: %w[include exclude only] } }
+    }.freeze
+
     def initialize(root)
       @data = load(root)
+      @defaults = validate_defaults!(@data["defaults"] || {}) # a bare `defaults:` key means none
+    end
+
+    def defaults_for(tool)
+      @defaults.fetch(tool.to_s, {}).transform_keys(&:to_sym)
     end
 
+    # Forking is the macOS default since 0.9.0; `macos_fork: false` opts a project out.
     def macos_fork?
-      !!@data["macos_fork"]
+      @data.fetch("macos_fork", true) ? true : false
     end
 
     def macos_fork_unsafe_gems
@@ -21,6 +37,29 @@ module Coatepec
 
     private
 
+    def validate_defaults!(defaults)
+      invalid!("defaults must be a mapping of tool names") unless defaults.is_a?(Hash)
+      defaults.each do |tool, keys|
+        rules = DEFAULT_KEYS[tool.to_s] || invalid!("defaults.#{tool} is not a configurable tool")
+        invalid!("defaults.#{tool} must be a mapping") unless keys.is_a?(Hash)
+        keys.each { |key, value| validate_default!(tool, key, value, rules[key.to_s]) }
+      end
+      defaults
+    end
+
+    def validate_default!(tool, key, value, rule)
+      invalid!("defaults.#{tool}.#{key} is not a configurable input") unless rule
+      ok = if rule[:boolean] then [true, false].include?(value)
+           elsif rule[:enum] then rule[:enum].include?(value)
+           else value.is_a?(Integer) && rule[:range].cover?(value)
+           end
+      invalid!("defaults.#{tool}.#{key}: #{value.inspect} is not allowed") unless ok
+    end
+
+    def invalid!(message)
+      raise Coatepec::Error.new(:invalid_config, "Invalid .coatepec.yml: #{message}")
+    end
+
     def load(root)
       path = File.join(root, ".coatepec.yml")
       return {} unless File.exist?(path)

data/lib/coatepec/spec/fork_strategy.rb

@@ -8,6 +8,8 @@ module Coatepec
     class ForkStrategy < ProcessStrategy
       private
 
+      def execution_mode = "fork"
+
       def start(full_args, out_w, err_w, json_path)
         Process.fork do
           Process.setpgid(0, 0)

data/lib/coatepec/spec/guarded_fork_strategy.rb

@@ -2,11 +2,12 @@
 
 module Coatepec
   module Spec
-    # Opt-in macOS fork strategy: attempts Process.fork like ForkStrategy
-    # (reusing the warm worker's boot), but only after two cheap guard
-    # checks pass, and transparently falls back to a fresh SpawnStrategy
-    # run -- for this call only -- when a guard fails or the forked child
-    # crashes. See docs/superpowers/specs/2026-07-31-macos-guarded-fork-design.md.
+    # The macOS fork strategy (the default since 0.9.0; macos_fork: false
+    # opts out): attempts Process.fork like ForkStrategy (reusing the warm
+    # worker's boot), but only after two cheap guard checks pass, and
+    # transparently falls back to a fresh SpawnStrategy run -- for this call
+    # only -- when a guard fails or the forked child crashes. See
+    # docs/superpowers/specs/2026-07-31-macos-guarded-fork-design.md.
     class GuardedForkStrategy < ForkStrategy
       # Intentionally empty at ship time: the one documented crash this
       # guards against didn't name a specific culprit gem, just "something
@@ -52,11 +53,11 @@ module Coatepec
           # Process.fork itself failed (Errno::EAGAIN/ENOMEM under
           # process-table pressure), so no child was ever produced -- from the
           # caller's side that is indistinguishable from a failed guard, hence
-          # the same mode. Opting into macos_fork must never surface an error
-          # that plain SpawnStrategy wouldn't have.
+          # the same mode. Forking on macOS must never surface an error that
+          # plain SpawnStrategy wouldn't have.
           return fallback_result(args, timeout_seconds, "spawn_fallback", result_options)
         end
-        return result.merge(execution_mode: "fork") unless crashed?(result)
+        return result unless crashed?(result)
 
         retry_after_crash(args, timeout_seconds, started_at, result, result_options)
       end

data/lib/coatepec/spec/process_strategy.rb

@@ -29,10 +29,16 @@ module Coatepec
 
         reap(pid, [out_r, err_r], timeout_seconds, json_path,
              { include_passing: include_passing, include_stdout: include_stdout })
+          .merge(execution_mode: execution_mode)
       end
 
       private
 
+      # Every result says how it ran, so an absent key can never be mistaken for "the guard fell back".
+      def execution_mode
+        raise NotImplementedError, "#{self.class} must implement #execution_mode"
+      end
+
       # Subclasses start a process and return its pid; the test framework's
       # own output must be wired to out_w/err_w. json_path is where the
       # adapter's structured per-example output must land.

data/lib/coatepec/spec/runner.rb

@@ -4,9 +4,9 @@ module Coatepec
   module Spec
     # Validates a `rails_spec_run` request's paths, picks the RSpec or
     # Minitest adapter from their shape, builds the CLI args, and delegates
-    # to the platform-appropriate process strategy (fork on Linux, spawn on
-    # macOS, or a guarded fork on macOS when the project opts in via
-    # .coatepec.yml).
+    # to the platform-appropriate process strategy (fork on Linux, and a
+    # guarded fork on macOS unless the project opts out via .coatepec.yml,
+    # which selects a fresh spawn per call).
     class Runner
       DEFAULT_TIMEOUT = 120
 
@@ -24,8 +24,17 @@ module Coatepec
         adapter.require_framework!
         args = adapter.build_args(validated[:selectors], example, seed, fail_fast)
 
-        strategy_class.new(@project_root, adapter: adapter, project: @project, rails_runtime: @rails_runtime)
-                      .run(args, timeout_seconds, include_passing: include_passing, include_stdout: include_stdout)
+        result = strategy_class
+                 .new(@project_root, adapter: adapter, project: @project, rails_runtime: @rails_runtime)
+                 .run(args, timeout_seconds, include_passing: include_passing, include_stdout: include_stdout)
+        @rails_runtime&.record_execution_mode(result[:execution_mode])
+        result
+      end
+
+      # Reported by rails_runtime_status so a caller can see which path a run will take.
+      def strategy_name
+        { ForkStrategy => "fork", GuardedForkStrategy => "guarded_fork", SpawnStrategy => "spawn" }
+          .fetch(strategy_class)
       end
 
       private
@@ -49,9 +58,8 @@ module Coatepec
         end
       end
 
-      # Reading @project.config here means an invalid .coatepec.yml only
-      # raises :invalid_config on macOS -- the Linux branch never touches it.
-      # Accepted asymmetry: the file exists to configure this branch.
+      # Forking is the default; only an explicit `macos_fork: false` spawns. Only the macOS
+      # branch reads the file here; the MCP layer reads it on every call for `defaults`.
       def macos_strategy_class
         @project.config.macos_fork? ? GuardedForkStrategy : SpawnStrategy
       end

data/lib/coatepec/spec/spawn_strategy.rb

@@ -9,6 +9,8 @@ module Coatepec
     class SpawnStrategy < ProcessStrategy
       private
 
+      def execution_mode = "spawn"
+
       def start(full_args, out_w, err_w, json_path)
         env, argv = @adapter.spawn_command(full_args, json_path)
         Process.spawn(env, *argv, chdir: @project_root, out: out_w, err: err_w, pgroup: true)

data/lib/coatepec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coatepec
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/coatepec/worker/rails_runtime.rb

@@ -8,17 +8,26 @@ module Coatepec
     # per worker process and reports its identity (pid, boot_id, versions,
     # lifecycle state) for rails_runtime_status.
     class RailsRuntime
-      attr_reader :pid, :boot_id, :boot_duration_ms, :ruby_version, :rails_version, :post_boot_thread_count
+      attr_reader :pid, :boot_id, :boot_duration_ms, :ruby_version, :rails_version, :post_boot_thread_count,
+                  :fallback_count
+
+      FALLBACK_MODES = %w[spawn_fallback spawn_after_crash].freeze
 
       def initialize(project_root)
         @project_root = project_root
         @booted = false
+        @fallback_count = 0
       end
 
       def booted?
         @booted
       end
 
+      # A guarded fork that declined or crashed ran via spawn; rails_runtime_status reports how often.
+      def record_execution_mode(mode)
+        @fallback_count += 1 if FALLBACK_MODES.include?(mode)
+      end
+
       def boot!
         started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         ENV["RAILS_ENV"] = "test"

data/lib/coatepec/worker/server.rb

@@ -40,7 +40,7 @@ module Coatepec
 
       def execute_command(command, args)
         case command
-        when "status" then @runtime.status
+        when "status" then handle_status
         when "spec_run" then handle_spec_run(args)
         when "flaky_check" then handle_flaky_check(args)
         when "routes" then handle_routes(args)
@@ -51,6 +51,12 @@ module Coatepec
         end
       end
 
+      # spec_strategy and fallbacks are the worker's to report: it owns the platform check and the counter.
+      def handle_status
+        name = Spec::Runner.new(@project_root, rails_runtime: @runtime).strategy_name
+        @runtime.status.merge(spec_strategy: name, fallbacks: name == "guarded_fork" ? @runtime.fallback_count : nil)
+      end
+
       def handle_spec_run(args)
         Spec::Runner.new(@project_root, rails_runtime: @runtime).run(**args.transform_keys(&:to_sym))
       end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: coatepec
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Enrique Mogollan
 bindir: exe
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -75,6 +75,7 @@ files:
 - lib/coatepec/introspection/routes.rb
 - lib/coatepec/introspection/safe_options.rb
 - lib/coatepec/mcp.rb
+- lib/coatepec/mcp/defaults.rb
 - lib/coatepec/mcp/response.rb
 - lib/coatepec/mcp/tools.rb
 - lib/coatepec/project.rb