xeno 0.0.1 → 0.0.2

data/lib/xeno/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   # Gem-level runtime knobs, set from an initializer:
   #
@@ -6,77 +8,66 @@ module Xeno
   #   end
   #
   class Configuration
-    # Per-turn model-call budget (RubyLLM's own loop is unbounded; ours is not).
+    # Per-turn model-call budget: a turn must bound its model calls.
     attr_accessor :max_steps
 
-    # A turn whose claim ledger reaches this many attempts is poison — it
-    # fails instead of retrying forever.
+    # A turn whose claim ledger reaches this many attempts is poison — it fails instead of retrying
+    # forever.
     attr_accessor :max_turn_attempts
 
-    # A running turn whose heartbeat is older than this is presumed dead and
-    # reclaimable. Checkpoint replay makes takeover safe; a too-short window
-    # risks overlap with a live-but-slow owner, a too-long one stalls the
-    # session after a hard crash.
+    # A running turn whose heartbeat is older than this is presumed dead and reclaimable. Checkpoint
+    # replay makes takeover safe; a too-short window risks overlap with a live-but-slow owner, a
+    # too-long one stalls the session after a hard crash.
     attr_accessor :turn_stale_after
 
-    # How often the background heartbeat beats while the runner is inside a
-    # model call or a tool body (the calls that can outlast turn_stale_after).
-    # nil (default) = a quarter of turn_stale_after, so a live owner always
-    # beats several times per staleness window.
+    # How often the background heartbeat beats while the runner is inside a model call or a tool
+    # body (the calls that can outlast turn_stale_after). nil (default) = a quarter of
+    # turn_stale_after, so a live owner always beats several times per staleness window.
     attr_writer :heartbeat_interval
 
-    # Per-session token budgets, enforced BEFORE each model call from the
-    # persisted usage columns (the provider's own counts). Checked
-    # independently per axis; the call that crosses is allowed to finish —
-    # the NEXT call trips. Exceeded → deterministic turn failure with a
-    # budget.exceeded event; the session recovers via reset. nil =
-    # unlimited. Per-agent override: `limits input_tokens:, output_tokens:`
-    # in agent.rb (false disables an axis).
+    # Per-session token budgets, enforced before each model call from the persisted usage counts,
+    # independently per axis. The call that crosses a cap finishes; the next call fails the turn
+    # with a budget.exceeded event, and the session recovers via reset. nil = unlimited. Per-agent
+    # override: `limits` in agent.rb.
     attr_accessor :max_input_tokens_per_session, :max_output_tokens_per_session
 
-    # Compaction triggers when the last model call's context usage crosses
-    # this fraction of the model's context window. nil/false
-    # disables automatic compaction (manual stays available).
+    # Compaction triggers when the last model call's context usage crosses this fraction of the
+    # model's context window. nil/false disables automatic compaction (manual stays available).
     attr_accessor :compaction_threshold
 
-    # Fallback context window (tokens) for models the registry doesn't know
-    # (assume_model_exists). nil = automatic compaction never triggers for
-    # unknown-window models.
+    # Fallback context window (tokens) for models the registry doesn't know (assume_model_exists).
+    # nil = automatic compaction never triggers for unknown-window models.
     attr_accessor :compaction_context_window
 
-    # How many of the most recent user-message-anchored turns survive a
-    # compaction verbatim (the "recent tail"). Everything earlier is
-    # summarized and replaced.
+    # How many of the most recent user-message-anchored turns survive a compaction verbatim (the
+    # "recent tail"). Everything earlier is summarized and replaced.
     attr_accessor :compaction_tail_turns
 
-    # Optional lambda answering "is the worker shutting down?" — probed by
-    # the runner between steps; when true the turn releases its claim and
-    # re-enqueues itself so a deploy-style stop resumes promptly on the next
-    # worker instead of waiting out stale-heartbeat reclaim. nil = ask the
-    # queue adapter (`queue_adapter.stopping?` — Solid Queue flips it on
-    # worker shutdown; adapters that don't implement it just return false).
+    # Optional lambda answering "is the worker shutting down?", probed between steps. When true the
+    # turn releases its claim and re-enqueues itself, so a deploy-style stop resumes on the next
+    # worker instead of waiting out stale-heartbeat reclaim. nil = ask the queue adapter's
+    # `stopping?` (Solid Queue implements it; adapters that don't return false).
     attr_accessor :stopping_check
 
-    # Fail-closed HTTP auth lambda. Receives the request; a falsy return is
-    # a 401; a truthy return becomes the request principal.
+    # Fail-closed HTTP auth lambda. Receives the request; a falsy return is a 401; a truthy return
+    # becomes the request principal.
     attr_accessor :authenticate
 
     # How often the SSE stream polls for new events, in seconds.
     attr_accessor :stream_poll_interval
 
-    # How many events one stream poll reads at most. Bounds the catch-up
-    # read on long sessions (a reconnect from index 0 pages through history
-    # in batches instead of loading every row in one query).
+    # How many events one stream poll reads at most. Bounds the catch-up read on long sessions (a
+    # reconnect from index 0 pages through history in batches instead of loading every row in one
+    # query).
     attr_accessor :stream_catch_up_batch
 
-    # Optional hard cap on how long one SSE connection is served (seconds).
-    # nil = until the session reaches a terminal status.
+    # Optional hard cap on how long one SSE connection is served (seconds). nil = until the session
+    # reaches a terminal status.
     attr_accessor :stream_max_duration
 
-    # Optional lambda answering "is the server shutting down?" — when true,
-    # open SSE streams close themselves so a graceful stop doesn't wait out
-    # the in-flight-request window (Ctrl-C stays near-instant with tabs
-    # open). nil = detect Puma's graceful stop automatically.
+    # Optional lambda answering "is the server shutting down?" — when true, open SSE streams close
+    # themselves so a graceful stop doesn't wait out the in-flight-request window (Ctrl-C stays
+    # near-instant with tabs open). nil = detect Puma's graceful stop automatically.
     attr_accessor :stream_shutdown_check
 
     def initialize

data/lib/xeno/engine.rb

@@ -1,12 +1,13 @@
+# frozen_string_literal: true
+
 module Xeno
   class Engine < ::Rails::Engine
     isolate_namespace Xeno
 
-    # agent/ is a Zeitwerk root namespaced under Xeno with per-slot
-    # submodules: agent/tools/get_weather.rb defines Xeno::Tools::GetWeather.
-    # Non-constant files are xeno's to load: agent.rb is a config DSL,
-    # schedules/ holds markdown, channels/ is a DSL slot in v0.1, lib/ is
-    # plain shared Ruby (required manually by the author).
+    # agent/ is a Zeitwerk root namespaced under Xeno with per-slot submodules:
+    # agent/tools/get_weather.rb defines Xeno::Tools::GetWeather. Non-constant files are xeno's to
+    # load: agent.rb is a config DSL, schedules/ holds markdown, channels/ is a DSL slot, lib/ is
+    # plain shared Ruby required by the author.
     initializer "xeno.agent_autoload", before: :setup_main_autoloader do |app|
       agent_root = Xeno.agent_root
       if agent_root&.directory?
@@ -20,8 +21,8 @@ module Xeno
       end
     end
 
-    # The cached definition holds tool classes; drop it whenever the app
-    # reloads so dev picks up edits under agent/.
+    # The cached definition holds tool classes; drop it whenever the app reloads so dev picks up
+    # edits under agent/.
     config.to_prepare do
       Xeno.reset_definition!
     end

data/lib/xeno/errors.rb

@@ -1,12 +1,14 @@
+# frozen_string_literal: true
+
 module Xeno
   class Error < StandardError; end
 
-  # Raised when a fenced write discovers its claim was reaped — the runner
-  # is a zombie and must abort without touching anything else.
+  # Raised when a fenced write discovers its claim was reaped — the runner is a zombie and must
+  # abort without touching anything else.
   class Fenced < Error; end
 
-  # Raised (internally) to park the turn: pending actions need human input.
-  # Never RubyLLM's cancel! — its cleanup destroys in-flight rows.
+  # Raised (internally) to park the turn: pending actions need human input. Never RubyLLM's cancel!
+  # — its cleanup destroys in-flight rows.
   class Parked < Error
     attr_reader :actions
 
@@ -19,8 +21,8 @@ module Xeno
   # The per-turn runaway guard tripped.
   class MaxStepsExceeded < Error; end
 
-  # A session token budget is spent: raised BEFORE the model call that
-  # would overspend. Deterministic turn failure; reset recovers the session.
+  # A session token budget is spent: raised BEFORE the model call that would overspend.
+  # Deterministic turn failure; reset recovers the session.
   class BudgetExceeded < Error
     attr_reader :axis, :used, :limit
 
@@ -32,9 +34,8 @@ module Xeno
     end
   end
 
-  # Raised (internally) between runner steps when the worker is shutting
-  # down gracefully: the turn releases its claim and re-enqueues itself so
-  # the next worker resumes it promptly (the AJ Continuation checkpoint
-  # pattern). Not a failure — it never counts against the poison ladder.
+  # Raised between runner steps when the worker is shutting down gracefully: the turn releases its
+  # claim and re-enqueues itself so the next worker resumes it promptly. Not a failure — it never
+  # counts against the poison ladder.
   class Interrupted < Error; end
 end

data/lib/xeno/hooks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   # Observe-only event handlers from agent/hooks/*.rb:
   #
@@ -7,16 +9,11 @@ module Xeno
   #
   #   Xeno.hook "*" do |event| ... end   # every event
   #
-  # Semantics:
-  # - Handlers fire AFTER the event row is durably committed (after_commit),
-  #   typed handlers first, then the wildcard. The block receives the
-  #   Xeno::Event record (event_type, data, index, session).
-  # - Observe-only: return values are ignored; hooks cannot veto anything
-  #   or inject model context. A raising handler is logged and skipped — a
-  #   hook can never break the runtime or fail the turn.
-  # - AT-LEAST-ONCE: replayed steps re-emit new events with new indexes.
-  #   Key once-per-step side effects on (turn_id, step) from the data; key
-  #   stored content on (session_id, index).
+  # Handlers fire after the event row commits, typed handlers before the wildcard, with the
+  # Xeno::Event record as the argument. Return values are ignored and a raising handler is logged
+  # and skipped — a hook can never veto, inject context, or fail the turn. Delivery is
+  # at-least-once: replayed steps re-emit events, so key side effects on (turn_id, step) and stored
+  # content on (session_id, index).
   module Hooks
     module_function
 

data/lib/xeno/info.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Renders the resolved agent for `rake xeno:info` — the discovery
-  # diagnostics surface.
+  # Renders the resolved agent for `rake xeno:info` — the discovery diagnostics surface.
   module Info
     module_function
 

data/lib/xeno/inputs.rb

@@ -1,15 +1,16 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Resolving parked work: approvals, denials, and question answers. Each
-  # resolution updates the action and — once no other action on the turn is
-  # still awaiting input — flips the turn back to pending and enqueues the
-  # resume job. A parked session holds zero compute; this is the only way
-  # back in.
-  module Inputs
+  # Resolves parked work: approvals, denials, and question answers. Each resolution updates its
+  # action; when nothing on the turn still awaits input, the turn flips back to pending and the
+  # resume job enqueues. A parked session holds no process — this is the only way back in.
+  module Inputs # :nodoc:
     module_function
 
     def approve!(action, principal: nil)
       resolve(action) do
         action.update!(status: "approved", resolved_at: Time.current, resolved_by: principal)
+        mirror_decision(action, "approved")
       end
     end
 
@@ -22,6 +23,7 @@ module Xeno
           resolved_at: Time.current,
           resolved_by: principal
         )
+        mirror_decision(action, "denied")
       end
     end
 
@@ -38,14 +40,20 @@ module Xeno
       end
     end
 
-    # Shared plumbing: guard the state, apply the resolution, resume when
-    # the turn has nothing else to wait for. Resolution, status flip, and
-    # the resume enqueue commit in ONE transaction: on a DB-backed queue
-    # (Solid Queue shares the app database, and ActiveJob 8.1 enqueues
-    # in-transaction by default) a crash can never separate "approved" from
-    # "job exists" — either everything landed or the input is still pending
-    # and the human just retries. Backends that defer or lose the enqueue
-    # fall back to the reaper's sweeps.
+    # The action row stays authoritative (kind, payload, who, when); the decision is mirrored onto
+    # the standard tool-call column so any RubyLLM-aware tooling reads it natively. Questions have
+    # no place there and are not mirrored.
+    def mirror_decision(action, decision)
+      return unless action.kind == "tool"
+
+      record = RubyLLM::ActiveRecord::ToolCall.find_by(tool_call_id: action.tool_call_id)
+      record&.update!(approval: decision)
+    end
+
+    # Guards the state, applies the resolution, and resumes when the turn has nothing left to wait
+    # for. Resolution, status flip, and resume enqueue commit in one transaction, so on a DB-backed
+    # queue a crash cannot separate "approved" from "job exists". Backends that defer or lose the
+    # enqueue fall back to the reaper.
     def resolve(action)
       unless action.status == "pending_approval"
         raise Xeno::Error, "action #{action.id} is not awaiting input (status: #{action.status})"
@@ -58,14 +66,13 @@ module Xeno
       action
     end
 
-    # Resuming with unanswered inputs would generate against partial tool
-    # results (an invalid provider state) — the runner would just re-park,
-    # so don't bother waking it until everything is resolved.
+    # Resuming with unanswered inputs would generate against partial tool results — an invalid
+    # provider state the runner would re-park on. Wake it only when everything is resolved.
     def resume_turn(turn)
       return if turn.actions.where(status: "pending_approval").exists?
 
-      # Resumes are human-driven and unbounded — counted apart from the
-      # failure `attempts` so approvals can never poison the turn (H2).
+      # Resumes are human-driven and unbounded — counted apart from the failure `attempts` so
+      # approvals can never poison the turn.
       resumed = Turn.where(id: turn.id, status: "waiting")
                     .update_all("status = 'pending', resumes = resumes + 1")
       return unless resumed == 1

data/lib/xeno/reaper.rb

@@ -1,26 +1,22 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The second half of the failure matrix: nothing else owns turns that
-  # fall out of the retry ladder. The reaper finds work that SHOULD be
-  # running but has no live owner and re-enqueues it. Duplicate-safe by
-  # construction — the claim CAS means a redundant TurnJob exits quietly,
-  # and a poisoned turn fails properly at claim time.
+  # Finds turns that should be running but have no live owner and re-enqueues them. Duplicate-safe:
+  # the claim CAS makes a redundant TurnJob exit quietly, and a poisoned turn fails at claim time.
   #
-  # Wiring: ReaperJob rides Solid Queue's recurring machinery (a managed
-  # entry written by Schedules.sync! in mounted mode, storage/recurring.yml
-  # in standalone mode). Other queue backends trigger it however they run
-  # periodic work: `Xeno::ReaperJob.perform_later` or `bin/rails xeno:reap`.
-  module Reaper
+  # ReaperJob rides Solid Queue's recurring machinery. Other queue backends trigger it however they
+  # run periodic work: Xeno::ReaperJob.perform_later or `bin/rails xeno:reap`.
+  module Reaper # :nodoc:
     module_function
 
     # One sweep. Rescues, in order:
-    # 1. running turns with a stale heartbeat — the owner died mid-step
-    #    (kill -9) or the queue exhausted its retries with the job in the
-    #    failed set; claim! reclaims these directly.
-    # 2. stale pending turns — staged or released-for-retry, but no job
-    #    ever came back (lost/discarded job).
+    # 1. running turns with a stale heartbeat — the owner died or the
+    #    queue exhausted its retries; claim! reclaims these directly.
+    # 2. stale pending turns — staged or released for retry, but the job
+    #    never came back.
     # 3. waiting turns with nothing left to wait for — every action
-    #    resolved but the resume enqueue never happened (crash between
-    #    resolve and enqueue). Genuinely parked turns are never touched.
+    #    resolved but the resume enqueue never happened.
+    # Genuinely parked turns are never touched.
     def sweep!(stale_before: Xeno.config.turn_stale_after.ago)
       rescued = []
 

data/lib/xeno/schedules.rb

@@ -1,17 +1,16 @@
+# frozen_string_literal: true
+
 require "yaml"
 
 module Xeno
-  # Compiles agent/schedules/*.md into Solid Queue recurring entries —
-  # compile-to-the-queue's-native-scheduler, not a dispatcher. No polling
+  # Compiles agent/schedules/*.md into Solid Queue recurring entries. There is no polling
   # dispatcher: the queue's own recurring machinery fires ScheduleJob.
   #
-  # Only keys under the managed prefix are touched; hand-written recurring
-  # entries survive a sync. Dev servers never fire user schedules on
-  # cadence — those are written for every environment section EXCEPT
-  # development, where the dispatch endpoint triggers by name. The REAPER
-  # entry is different: it's runtime infrastructure (turns with no live
-  # owner), so it goes into every section including development.
-  module Schedules
+  # Only keys under the managed prefix are touched, so hand-written entries survive a sync. User
+  # schedules are written for every environment except development, where the dispatch endpoint
+  # triggers them by name. The reaper entry is runtime infrastructure and goes into every
+  # environment.
+  module Schedules # :nodoc:
     MANAGED_PREFIX = "xeno_".freeze
     REAPER_KEY = "#{MANAGED_PREFIX}runtime_reaper".freeze
 

data/lib/xeno/session_state.rb

@@ -1,11 +1,10 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The per-session KV store: working state for
-  # ONE conversation. JSON-typed — values round-trip through JSON, so
-  # symbols become strings and anything unserializable is rejected up
-  # front. Reads always hit the database (a tool in a fresh worker sees
-  # what the last worker wrote); writes take the session row lock, so
-  # read-modify-write merges never lose entries. Cleared by `reset`; it is
-  # NOT long-term memory — durable knowledge belongs in your own models.
+  # The per-session KV store: working state for one conversation, not long-term memory. Values
+  # round-trip through JSON (symbols become strings; unserializable values are rejected up front).
+  # Reads always hit the database, and writes take the session row lock so read-modify-write merges
+  # never lose entries. Cleared by `reset`.
   class SessionState
     def initialize(session)
       @session = session
@@ -20,8 +19,8 @@ module Xeno
       current
     end
 
-    # Merges the entries in one locked write. Keys stringify; values must
-    # be JSON-serializable (Xeno::Error otherwise).
+    # Merges the entries in one locked write. Keys stringify; values must be JSON-serializable
+    # (Xeno::Error otherwise).
     def update(entries)
       normalized = normalize(entries)
       @session.with_lock do

data/lib/xeno/standalone/local_secret.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "securerandom"
 require "fileutils"
 
@@ -5,13 +7,12 @@ module Xeno
   module Standalone
     module_function
 
-    # A persisted local secret so sessions survive restarts without asking
-    # anyone to manage SECRET_KEY_BASE for a dev-grade standalone app.
-    # Owner-only (0600) — it signs cookies/sessions (S6); pre-existing
-    # looser files are tightened on read.
+    # A persisted local secret so standalone sessions survive restarts without anyone managing
+    # SECRET_KEY_BASE. Owner-only (0600) — it signs cookies/sessions; looser pre-existing files are
+    # tightened on read.
     #
-    # Lives apart from xeno/standalone so tests can exercise it without
-    # defining the Rails::Application (which self-registers on inheritance).
+    # Lives apart from xeno/standalone so tests can exercise it without defining the
+    # Rails::Application (which self-registers on inheritance).
     def local_secret(root)
       path = root.join("storage", ".local_secret")
       FileUtils.mkdir_p(path.dirname)

data/lib/xeno/standalone/model_refresh.rb

@@ -1,13 +1,13 @@
+# frozen_string_literal: true
+
 module Xeno
   module Standalone
     module_function
 
-    # First boot only (the registry table is empty): pull the live model
-    # catalog from the configured providers so current model ids resolve
-    # without a manual RubyLLM.models.refresh!. Loading the definition first
-    # runs agent.rb's RubyLLM.configure — the refresh needs those provider
-    # keys. Never fatal, never repeated once the table has rows; skippable
-    # with XENO_SKIP_MODEL_REFRESH=1 (deterministic scripts, offline boots).
+    # First boot only (the registry table is empty): pulls the live model catalog so current model
+    # ids resolve without a manual refresh. The definition loads first because agent.rb's
+    # RubyLLM.configure sets the provider keys. Never fatal, never repeated once the table has rows;
+    # XENO_SKIP_MODEL_REFRESH=1 skips it.
     def refresh_models!
       return if ENV["XENO_SKIP_MODEL_REFRESH"]
 

data/lib/xeno/standalone/puma.rb

@@ -1,17 +1,17 @@
-# Gem-owned puma config for standalone mode (`xeno server`): the whole
-# stack — web + Solid Queue supervisor — inside one Puma process.
+# frozen_string_literal: true
+
+# Gem-owned puma config for standalone mode (`xeno server`): the whole stack — web + Solid Queue
+# supervisor — inside one Puma process.
 threads_count = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
 threads threads_count, threads_count
 
-# Loopback by default: development runs with the dev auth bypass, and an
-# unauthenticated dev UI must not be exposed to the LAN. Opt out with
-# HOST=0.0.0.0 for containers/proxies that need it.
+# Loopback by default: development runs with the dev auth bypass, and an unauthenticated dev UI must
+# not be exposed to the LAN. Opt out with HOST=0.0.0.0 for containers/proxies that need it.
 bind "tcp://#{ENV.fetch("HOST", "127.0.0.1")}:#{ENV.fetch("PORT", 3000)}"
 
 plugin :solid_queue if ENV.fetch("SOLID_QUEUE_IN_PUMA", "1") != "0"
 
-# Ctrl-C must win. Live SSE streams (the dev UI's EventSource) are in-flight
-# requests, and Puma's default is to wait for in-flight requests :forever —
-# an open browser tab made shutdown hang (found by the first manual run).
-# Hard-stop leftover streams after 5s; xeno's state is rows, nothing is lost.
+# Ctrl-C must win. Live SSE streams are in-flight requests and Puma waits for in-flight requests
+# forever by default — an open browser tab made shutdown hang. Hard-stop leftover streams after 5s;
+# state is rows, nothing is lost.
 force_shutdown_after ENV.fetch("XENO_FORCE_SHUTDOWN_AFTER", 5).to_i

data/lib/xeno/standalone.rb

@@ -1,13 +1,18 @@
-# Standalone mode: Rails as an implementation detail. A scaffolded app is
-# a handful of visible files (agent/, Gemfile, config.ru, .gitignore); the
-# entire Rails::Application lives HERE, inside the gem.
+# frozen_string_literal: true
+
+# = Standalone mode
+#
+# An agent shouldn't need a whole Rails app of its own. `xeno new my-agent` scaffolds a directory
+# with a handful of visible files — agent/, a Gemfile, config.ru, .gitignore — and the entire
+# Rails::Application lives here, inside the gem:
 #
 #   # config.ru
 #   require "xeno/standalone"
 #   run Xeno.rails_app
 #
-# SQLite + Solid Queue inside Puma (`xeno server`) make it one process with
-# zero external services; migrations run at boot.
+# `xeno server` boots it as one process with zero external services: SQLite for storage, Solid
+# Queue inside Puma for jobs, migrations applied at boot. When the agent outgrows this, mount the
+# engine in a full Rails app and bring the agent/ directory along unchanged.
 require "rails"
 require "active_model/railtie"
 require "active_record/railtie"
@@ -15,8 +20,8 @@ require "active_job/railtie"
 require "action_controller/railtie"
 require "action_view/railtie"
 
-# A config.ru-only app has no Bundler.require(*Rails.groups); pull in what
-# the scaffolded Gemfile provides.
+# A config.ru-only app has no Bundler.require(*Rails.groups); pull in what the scaffolded Gemfile
+# provides.
 require "solid_queue"
 require "sqlite3"
 
@@ -51,9 +56,8 @@ module Xeno
             "adapter" => "sqlite3",
             "database" => ENV.fetch("XENO_DATABASE", "storage/xeno_#{Rails.env}.sqlite3"),
             "pool" => ENV.fetch("RAILS_MAX_THREADS", 10).to_i,
-            # Busy handler: web + Solid Queue's forked dispatcher/worker share this
-            # one file; without a timeout the sqlite3 adapter does NOT wait for
-            # locks ("default: no wait") and every collision raises
+            # Web and Solid Queue's forked processes share this one file; without a busy timeout the
+            # sqlite3 adapter does not wait for locks and every collision raises
             # SQLite3::BusyException. Same 5s default rails new generates.
             "timeout" => ENV.fetch("XENO_DATABASE_TIMEOUT", 5000).to_i
           }
@@ -64,12 +68,11 @@ module Xeno
     config.secret_key_base = ENV["SECRET_KEY_BASE"] || Xeno::Standalone.local_secret(APP_ROOT)
   end
 
-  module Standalone
+  module Standalone # :nodoc:
     module_function
 
-    # Boot: initialize the app, then bring the database up to date — the
-    # engine's migrations plus Solid Queue's tables (loaded straight from
-    # the solid_queue gem's install template).
+    # Boot: initialize the app, then bring the database up to date — the engine's migrations plus
+    # Solid Queue's tables (loaded straight from the solid_queue gem's install template).
     def boot!
       ENV["RAILS_ENV"] ||= "development"
       FileUtils.mkdir_p(StandaloneApplication::APP_ROOT.join("storage"))
@@ -89,11 +92,9 @@ module Xeno
       Rails.application
     end
 
-    # Solid Queue's recurring machinery is how the reaper (always) and the
-    # compiled schedules (outside development) fire in standalone mode. The
-    # file lives under storage/ (gitignored) so the scaffold stays four
-    # visible files; the env var — read by Solid Queue's supervisor, which
-    # starts after config.ru has loaded — points the scheduler at it.
+    # Solid Queue's recurring machinery fires the reaper (always) and the compiled schedules
+    # (outside development) in standalone mode. The file lives under storage/ so the scaffold stays
+    # four visible files; the env var points Solid Queue's supervisor at it.
     def write_recurring_config!
       section = { Xeno::Schedules::REAPER_KEY => Xeno::Schedules.reaper_entry }
       unless Rails.env.development?
@@ -123,8 +124,8 @@ module Xeno
       File.join(spec.gem_dir, "lib", "generators", "solid_queue", "install", "templates", "db", "queue_schema.rb")
     end
 
-    # The gem-owned puma config used by `xeno server` — Solid Queue runs
-    # inside Puma (SOLID_QUEUE_IN_PUMA), one process total.
+    # The gem-owned puma config used by `xeno server` — Solid Queue runs inside Puma
+    # (SOLID_QUEUE_IN_PUMA), one process total.
     def puma_config_path
       File.expand_path("standalone/puma.rb", __dir__)
     end