xeno 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '03921563a3c8f8a6ef1a2f6c8274f6851f65daeebe66b617e2fc9729673bd571'
-  data.tar.gz: 51e0a0f0646cc28974e73e8cca0e5c485fc60113c664161a0e31b74d6bfb5201
+  metadata.gz: 4925abe330e6c36702e33e5c9322ef3b23aa7a9ad1f98d2e2aedbfa0ae691593
+  data.tar.gz: 8f7beb0a6be6b1ebe57f90811f3c99384ab42db88583643311426c756ba99223
 SHA512:
-  metadata.gz: 8a5e8aa4d6ce79696fc85275c07ddb4522c2fd18b667120087841367d94a279258763ce9ab45bb7764556e8954b70f1f751f6b88549983c4622ea58eea2a3cc6
-  data.tar.gz: cdb8ceae13f48c5277d9760715021749d6ddfa40fa0a9a7045631c7cbb6323096e17aabd097b3b0b0d37c3513d7a4f9f1e7d4585b654bee683955b56a71bbf46
+  metadata.gz: 5dc647886c481b5d0f19cddcca9759a73a07d354120c1e6399d40e0c3dad4a0cae94a278d5a61a6cbd6b1b82043f483a0a742b61aae4ce38a5816805c0531a6e
+  data.tar.gz: 5eae3ba1312fcaeda570024497bbbdea16a623fc6a6aff0be73ef16f4375a8509292f61ac7da67b72b08040af66d8a44f9b7e73805f9868ef2c6d33938b1f2c9

data/CHANGELOG.md

@@ -2,12 +2,55 @@
 
 Format follows [Keep a Changelog](https://keepachangelog.com); versions follow
 [SemVer](https://semver.org). **xeno is on the `0.0.x` preview line: any release may
-change anything.** `0.1.0` will mark the first release we consider usable in anger —
+change anything.** `0.1.0` will mark the first release we consider usable in anger:
 after RubyLLM v2 GA is absorbed and the API has held still through early-adopter
 feedback.
 
 ## [Unreleased]
 
+## [0.0.2] - 2026-08-13
+
+**Upgrading from 0.0.1 requires a fresh database.** The migrations were squashed
+and the old stamps no longer exist, so there is no migration path forward: the
+`0.0.x` preview line reserves exactly this.
+
+### Added
+
+- Interop with RubyLLM's tool approvals. A tool that declares `requires_approval`
+  and no xeno `approval` policy parks for approval instead of executing ungated;
+  an explicit policy, including `:never`, still wins. Approve and deny decisions
+  also land on the standard `ruby_llm_tool_calls.approval` column, so tooling
+  built against RubyLLM's convention reads xeno sessions natively.
+- Tools that declare a `tool_call:` keyword on `execute` receive the
+  `RubyLLM::ToolCall` they were invoked by, so a tool body can read its own
+  call id for logging or correlation. Tools without the keyword are called
+  exactly as before.
+
+### Changed
+
+- The `ruby_llm` pin moved from `2aaddf96` to `be80b6f1` (145 commits of upstream
+  v2 development). No xeno API usage changed; the bundle swaps `ruby_llm-schema`
+  for `schematist`. The scaffold Gemfile and README point at the new ref.
+- The engine's eight migrations are now two: `create_ruby_llm_tables` and
+  `create_xeno_tables`. The old set replayed pre-release history, creating tables
+  only to drop them again, through a database no install has ever had. The new
+  pair produces the same final schema without the churn, and each
+  `ruby_llm_*` table is skipped when the database
+  already has it, so a host app that ran ruby_llm's own installer keeps what it
+  owns.
+- The transcript tables match upstream's current install template: tool calls
+  carry `approval`, messages carry `server_tool_calls` and `raw_content`. All
+  three are read behind column guards, so behavior is unchanged until the pinned
+  ruby_llm persists them.
+- The `Gemfile` no longer prefers a local ruby_llm checkout when one happens to
+  sit next door. Development bundles the same pinned ref as everyone else.
+
+### Fixed
+
+- Removing an agent's instructions now takes effect at the next turn, the same
+  way editing them always has: staging clears the persisted system message when
+  nothing resolves, instead of silently keeping the stale one.
+
 ## [0.0.1] - 2026-08-07
 
 The first public release of xeno, a framework for durable AI agents built on Rails:
@@ -28,7 +71,7 @@ The first public release of xeno, a framework for durable AI agents built on Rai
   post-then-edit streaming).
 - Markdown cron schedules compiled to Solid Queue recurring entries, with dedup.
 - Generators (`xeno:install`, `xeno:tool`) and standalone mode: `xeno new my-agent` /
-  `xeno server` — one process, sqlite, zero services. Scaffolds include a pinned
+  `xeno server` for one process, sqlite, zero services. Scaffolds include a pinned
   `ruby_llm` Gemfile, dotenv, and an AGENTS.md pointing coding agents at the gem docs.
 - Standalone first boot refreshes the model registry after the boot migrations, so
   current model ids resolve without a manual `RubyLLM.models.refresh!`.

data/README.md

@@ -5,7 +5,7 @@ xeno is a framework for durable AI agents. Built on Rails, it runs standalone (`
 A xeno agent is a session that survives restarts and deploys mid-turn, waits days for a human approval without holding a process, and resumes exactly where it stopped. Under the hood, xeno composes [RubyLLM](https://rubyllm.com) for model calls with ActiveJob and ActiveRecord for durability.
 
 > [!WARNING]
-> xeno currently tracks RubyLLM v2 (unreleased), pinned to git ref [`2aaddf96`](https://github.com/crmne/ruby_llm/commit/2aaddf96). The released `ruby_llm` gem (1.16.0) is not compatible. Standalone apps get the pin from the scaffold's Gemfile. If your Rails app already uses a released `ruby_llm`, xeno cannot run alongside it today. This resolves at RubyLLM v2 GA, when xeno switches to the released gem.
+> xeno currently tracks RubyLLM v2 (unreleased), pinned to git ref [`be80b6f1`](https://github.com/crmne/ruby_llm/commit/be80b6f1). The released `ruby_llm` gem (1.16.0) is not compatible. Standalone apps get the pin from the scaffold's Gemfile. If your Rails app already uses a released `ruby_llm`, xeno cannot run alongside it today. This resolves at RubyLLM v2 GA, when xeno switches to the released gem.
 
 ## The filesystem is the authoring interface
 
@@ -155,6 +155,8 @@ Xeno.configure do |config|
 end
 ```
 
+Every knob is listed in [docs/configuration.md](docs/configuration.md).
+
 Development with no lambda configured stays usable on localhost; everywhere else the absence of a checker is a 401.
 
 The principal is also the ownership boundary: a session belongs to the principal stamped at creation, and every session-scoped endpoint returns 404 for any other principal. See `docs/runtime.md` for the authorization rules.

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler/setup"
 
 APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)

data/app/controllers/xeno/api_controller.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Base for every engine endpoint. Auth fails closed: without a configured
-  # authenticate lambda, everything is 401. The lambda receives the request;
-  # a falsy return is a 401; its truthy return value is the request
-  # principal (stamped onto sessions by the HTTP channel).
-  class ApiController < ActionController::API
+  # Base for every engine endpoint. Auth fails closed: without a configured authenticate lambda,
+  # everything is 401. The lambda receives the request; a falsy return is a 401; its truthy return
+  # value is the request principal (stamped onto sessions by the HTTP channel).
+  class ApiController < ActionController::API # :nodoc:
     before_action :authenticate!
 
     rescue_from ActiveRecord::RecordNotFound do
@@ -18,9 +19,8 @@ module Xeno
       render json: { error: error.message }, status: :conflict
     end
 
-    # The development fallback principal (no auth lambda configured). It
-    # matches every session — in development only — so the dev UI and
-    # localhost curl stay usable.
+    # The development fallback principal (no auth lambda configured). It matches every session — in
+    # development only — so the dev UI and localhost curl stay usable.
     DEV_PRINCIPAL = { "user" => "dev" }.freeze
 
     private
@@ -28,8 +28,8 @@ module Xeno
     def authenticate!
       checker = Xeno.config.authenticate
 
-      # Development with no auth configured stays usable (the dev UI, curl on
-      # localhost). Everywhere else the absence of a checker is a 401.
+      # Development with no auth configured stays usable (the dev UI, curl on localhost). Everywhere
+      # else the absence of a checker is a 401.
       if checker.nil? && Rails.env.development?
         @current_principal = DEV_PRINCIPAL
         return
@@ -44,11 +44,9 @@ module Xeno
       @current_principal == true ? nil : @current_principal
     end
 
-    # Ownership rule: a session belongs to the principal stamped at create.
-    # A non-matching caller gets the same 404 as a nonexistent id (no
-    # existence leak). A lambda that returns bare `true` yields nil
-    # principals everywhere — single-tenant mode, every authenticated
-    # caller matches (documented in docs/runtime.md).
+    # A session belongs to the principal stamped at create; a non-matching caller gets the same 404
+    # as a nonexistent id (no existence leak). A lambda returning bare `true` yields nil principals
+    # everywhere — single-tenant mode, every authenticated caller matches.
     def find_owned_session!
       session = Session.find(params[:id])
       raise ActiveRecord::RecordNotFound unless owns?(session)
@@ -57,9 +55,8 @@ module Xeno
     end
 
     def owns?(session)
-      # Object identity on purpose: only the fallback path above grants the
-      # wildcard, never a configured lambda that happens to return the same
-      # hash.
+      # Object identity on purpose: only the fallback path above grants the wildcard, never a
+      # configured lambda that happens to return the same hash.
       return true if Rails.env.development? && @current_principal.equal?(DEV_PRINCIPAL)
 
       session.principal == current_principal.as_json

data/app/controllers/xeno/application_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   class ApplicationController < ActionController::Base
   end

data/app/controllers/xeno/dev_controller.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Development conveniences. Schedules never fire on cadence in dev; this
-  # endpoint triggers one by name. Refuses to exist outside
-  # development (XENO_DEV_ROUTES=1 lets tests exercise it).
-  class DevController < ApiController
+  # Development conveniences. Schedules never fire on cadence in dev; this endpoint triggers one by
+  # name. Refuses to exist outside development (XENO_DEV_ROUTES=1 lets tests exercise it).
+  class DevController < ApiController # :nodoc:
     before_action :ensure_development
 
     def dispatch_schedule

data/app/controllers/xeno/dev_ui_controller.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The mounted dev chat UI: chat with the
-  # agent, watch the event stream live (over xeno's own SSE endpoint), and
-  # approve/deny/answer parked work. Development only.
-  class DevUiController < ApplicationController
+  # The mounted dev chat UI: chat with the agent, watch the event stream live (over xeno's own SSE
+  # endpoint), and approve/deny/answer parked work. Development only.
+  class DevUiController < ApplicationController # :nodoc:
     before_action :ensure_development
 
     def index

data/app/controllers/xeno/health_controller.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Xeno
   # The one unauthenticated endpoint: liveness only, leaks nothing.
-  class HealthController < ApiController
+  class HealthController < ApiController # :nodoc:
     skip_before_action :authenticate!
 
     def show

data/app/controllers/xeno/sessions_controller.rb

@@ -1,13 +1,13 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The HTTP channel: always mounted, fail-closed. The channel owns the
-  # continuation token (the resume handle): create returns one, follow-up
-  # messages must present it, terminal states release it, reset retires the
-  # session so the same token can start fresh.
-  class SessionsController < ApiController
-    # POST /v1/sessions { message:, continuation_token: (optional) }
-    # Client-supplied tokens are restricted to the reserved `http:`
-    # namespace — a crafted `slack:<channel>:<ts>` token would otherwise
-    # hijack which Slack thread the agent posts into.
+  # The HTTP channel: always mounted, fail-closed. The channel owns the continuation token (the
+  # resume handle): create returns one, follow-up messages must present it, terminal states release
+  # it, reset retires the session so the same token can start fresh.
+  class SessionsController < ApiController # :nodoc:
+    # POST /v1/sessions { message:, continuation_token: (optional) } Client-supplied tokens are
+    # restricted to the reserved `http:` namespace — a crafted `slack:<channel>:<ts>` token would
+    # otherwise hijack which Slack thread the agent posts into.
     def create
       message = params.require(:message)
       token = params[:continuation_token].presence
@@ -31,9 +31,9 @@ module Xeno
              status: :conflict
     end
 
-    # POST /v1/sessions/:id/messages { message:, continuation_token:, steer: }
-    # steer: true stops the active turn (settled safely) and makes this
-    # message the next turn instead of queueing behind the current work.
+    # POST /v1/sessions/:id/messages { message:, continuation_token:, steer: } steer: true stops the
+    # active turn (settled safely) and makes this message the next turn instead of queueing behind
+    # the current work.
     def message
       session = find_owned_session!
 
@@ -73,10 +73,9 @@ module Xeno
                      turn_status: action.turn.reload.status }
     end
 
-    # POST /v1/sessions/:id/cancel — stop the active turn, session intact.
-    # A parked/pending turn cancels immediately (no process holds it); a
-    # running turn is cancelled cooperatively via the persisted flag the
-    # runner's checker polls (takes effect within a chunk or step boundary).
+    # POST /v1/sessions/:id/cancel — stop the active turn, session intact. A parked/pending turn
+    # cancels immediately (no process holds it); a running turn is cancelled cooperatively via the
+    # persisted flag the runner's checker polls (takes effect within a chunk or step boundary).
     def cancel
       session = find_owned_session!
       turn = session.turns.where(status: %w[pending running waiting]).order(:sequence).first
@@ -87,9 +86,9 @@ module Xeno
         session.chat.cancel!
         render json: { turn_id: turn.id, cancelling: true }, status: :accepted
       else
-        # Settle BEFORE cancelling: a parked turn's assistant tool_calls are
-        # still unanswered, and leaving them dangling bricks the session
-        # (every later generate replays the malformed transcript).
+        # Settle BEFORE cancelling: a parked turn's assistant tool_calls are still unanswered, and
+        # leaving them dangling bricks the session (every later generate replays the malformed
+        # transcript).
         session.settle_unanswered_tool_calls!(turn, reason: "cancelled by user")
         turn.update!(status: "cancelled")
         session.update!(status: "running") if session.status == "waiting"
@@ -98,9 +97,8 @@ module Xeno
       end
     end
 
-    # POST /v1/sessions/:id/compact — request a manual compaction. It runs
-    # as a claimed turn, so it queues behind any active or parked turn and
-    # executes the moment the session is free. Never appends a user message.
+    # POST /v1/sessions/:id/compact — manual compaction. Runs as a claimed turn: queues behind
+    # active or parked work, never appends a user message.
     def compact
       session = find_owned_session!
 
@@ -114,8 +112,8 @@ module Xeno
       render json: { session_id: session.id, turn_id: turn.id, status: "requested" }, status: :accepted
     end
 
-    # POST /v1/sessions/:id/reset — retire the session (the /new command);
-    # releases the continuation token so the same handle can start fresh.
+    # POST /v1/sessions/:id/reset — retire the session (the /new command); releases the continuation
+    # token so the same handle can start fresh.
     def reset
       session = find_owned_session!
 

data/app/controllers/xeno/slack_controller.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The Slack Events API endpoint. The generic auth lambda is skipped —
-  # Slack's own request signature IS the authentication (verified in
-  # constant time), and it fails closed: no configured slack channel = 404,
-  # bad or stale signature = 401.
-  class SlackController < ApiController
+  # The Slack Events API endpoint. The generic auth lambda is skipped — Slack's own request
+  # signature IS the authentication (verified in constant time), and it fails closed: no configured
+  # slack channel = 404, bad or stale signature = 401.
+  class SlackController < ApiController # :nodoc:
     skip_before_action :authenticate!
 
     def events
@@ -28,11 +29,9 @@ module Xeno
 
     private
 
-    # Fast ack (Slack retries anything that misses its 3s window) + retry
-    # dedup: the event_id claim and the job enqueue commit together, so a
-    # retry storm yields exactly one processing job — and a crash before
-    # the ack leaves the claim unclaimed for the retry to win. Events
-    # without an event_id (shouldn't happen for event_callback) process
+    # Fast ack (Slack retries anything past its 3s window) with retry dedup: the event_id claim and
+    # the job enqueue commit together, so a retry storm yields one processing job, and a crash
+    # before the ack leaves the claim for the retry to win. Events without an event_id process
     # without dedup rather than being dropped.
     def enqueue_event(payload)
       event_id = payload["event_id"]

data/app/controllers/xeno/streams_controller.rb

@@ -1,14 +1,13 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The session event stream: SSE by default, NDJSON on request
-  # (`?format=ndjson` or `Accept: application/x-ndjson` — one envelope per
-  # line, friendlier to curl/jq and non-browser consumers). `?start_index=N`
-  # rewinds/resumes — events are durable rows, so reconnecting clients
-  # replay history and then follow live. The stream ends when the session
-  # reaches a terminal status (or the optional configured max duration).
+  # The session event stream: SSE by default, NDJSON on request (`?format=ndjson` or `Accept:
+  # application/x-ndjson`). `?start_index=N` rewinds — events are durable rows, so clients replay
+  # history and then follow live. The stream ends at a terminal session status or the configured max
+  # duration.
   #
-  # Known limitation (documented): ActionController::Live holds a thread
-  # per connected client.
-  class StreamsController < ApiController
+  # Known limitation: ActionController::Live holds a thread per client.
+  class StreamsController < ApiController # :nodoc:
     include ActionController::Live
 
     KEEPALIVE_INTERVAL = 5 # seconds without a write before a ping
@@ -26,8 +25,8 @@ module Xeno
       def close = @sse.close
     end
 
-    # NDJSON framing: one envelope per line (type/index live inside the
-    # envelope); a bare newline as keepalive — line parsers skip empties.
+    # NDJSON framing: one envelope per line (type/index live inside the envelope); a bare newline as
+    # keepalive — line parsers skip empties.
     class NdjsonWriter
       def initialize(stream)
         @stream = stream
@@ -58,21 +57,19 @@ module Xeno
         end
         last_write = Process.clock_gettime(Process::CLOCK_MONOTONIC) if events.any?
 
-        # A full batch means more history is waiting — keep paging through
-        # the catch-up without sleeping or ending on a terminal status.
+        # A full batch means more history is waiting — keep paging through the catch-up without
+        # sleeping or ending on a terminal status.
         next if events.size == batch_limit
 
         break unless session.reload.active?
         break if stream_expired?(started)
-        # A graceful stop must not wait out the in-flight-request window —
-        # the stream is resumable by design (events are durable rows, the
-        # client reconnects with its cursor), so close it and let the
-        # server exit. The 5s force cap in the puma config stays as the
+        # A graceful stop must not wait out the in-flight-request window. The stream is resumable by
+        # design, so close it and let the server exit; the 5s force cap in the puma config is the
         # backstop.
         break if server_shutting_down?
 
-        # A quiet stream never writes, so a dead client would never raise and
-        # this thread would poll forever — keepalives make disconnects visible.
+        # A quiet stream never writes, so a dead client would never raise and this thread would poll
+        # forever — keepalives make disconnects visible.
         if Process.clock_gettime(Process::CLOCK_MONOTONIC) - last_write > KEEPALIVE_INTERVAL
           writer.keepalive
           last_write = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -110,9 +107,8 @@ module Xeno
       false
     end
 
-    # ActionController::Live runs the action on its OWN thread, so Puma's
-    # thread-local Server.current is nil here (verified against a live
-    # server). Find the process's server instance once per connection.
+    # ActionController::Live runs the action on its own thread, so Puma's thread-local
+    # Server.current is nil here. Find the process's server instance once per connection.
     def puma_server
       return nil unless defined?(Puma::Server)
 

data/app/helpers/xeno/application_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   module ApplicationHelper
   end

data/app/jobs/xeno/application_job.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   class ApplicationJob < ActiveJob::Base
   end

data/app/jobs/xeno/reaper_job.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Periodic sweep for turns with no live owner (see Xeno::Reaper). Fired
-  # by Solid Queue's recurring machinery, a cron hitting `xeno:reap`, or
-  # any other scheduler — running it twice is harmless.
-  class ReaperJob < ApplicationJob
+  # Periodic sweep for turns with no live owner (see Xeno::Reaper). Fired by Solid Queue's recurring
+  # machinery, a cron hitting `xeno:reap`, or any other scheduler — running it twice is harmless.
+  class ReaperJob < ApplicationJob # :nodoc:
     queue_as :default
 
     def perform

data/app/jobs/xeno/schedule_job.rb

@@ -1,15 +1,13 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Fires one scheduled run: a fire-and-forget task-mode session under the
-  # app principal. Solid Queue recurring entries (rake xeno:schedules:sync)
-  # and the dev dispatch endpoint both enqueue this.
+  # Fires one scheduled run: a fire-and-forget task-mode session under the app principal, enqueued
+  # by Solid Queue recurring entries or the dev dispatch endpoint.
   #
-  # At-least-once safe: queues redeliver, and Solid Queue's recurring
-  # (task, run-at) dedup only covers the enqueue, not the execution. Each
-  # enqueue carries one ActiveJob job_id; the dedup row claims it in the
-  # SAME transaction that opens the session, so a redelivered tick can
-  # never double-open — it re-enqueues the recorded turn instead (idle
-  # no-op if the first delivery finished: the claim CAS decides).
-  class ScheduleJob < ApplicationJob
+  # At-least-once safe: queues redeliver, and recurring dedup covers only the enqueue. The dedup row
+  # claims this job_id in the same transaction that opens the session, so a redelivered tick can
+  # never double-open — it re-enqueues the recorded turn instead.
+  class ScheduleJob < ApplicationJob # :nodoc:
     queue_as :default
 
     discard_on ArgumentError
@@ -43,9 +41,8 @@ module Xeno
 
     private
 
-    # This job_id already ran (or died mid-run): pick up ITS turn instead of
-    # opening a second session. The claim CAS makes this a no-op when the
-    # first delivery actually finished.
+    # This job_id already ran (or died mid-run): pick up ITS turn instead of opening a second
+    # session. The claim CAS makes this a no-op when the first delivery actually finished.
     def redelivered_turn(claimed)
       return nil if claimed
 

data/app/jobs/xeno/slack_event_job.rb

@@ -1,11 +1,11 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Processes one verified Slack event off the webhook path. The endpoint
-  # acks inside Slack's 3-second window and hands the payload here; session
-  # work (DB writes, LLM turns via TurnJob) happens on the queue. Slack
-  # retry storms die at the event_id dedup row (claimed atomically with
-  # this enqueue); a session can never be double-opened by a retry — the
-  # thread's continuation token is unique among active sessions.
-  class SlackEventJob < ApplicationJob
+  # Processes one verified Slack event off the webhook path: the endpoint acks inside Slack's
+  # 3-second window and hands the payload here. Retry storms die at the event_id dedup row, and a
+  # session can never be double-opened — the thread's continuation token is unique among active
+  # sessions.
+  class SlackEventJob < ApplicationJob # :nodoc:
     queue_as :default
 
     discard_on ActiveJob::DeserializationError

data/app/jobs/xeno/turn_job.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 module Xeno
-  # One turn = one job. All correctness (claim, fencing, replay) lives in
-  # TurnRunner + the database; the queue only provides at-least-once
-  # delivery and retry backoff.
-  class TurnJob < ApplicationJob
+  # One turn = one job. All correctness (claim, fencing, replay) lives in TurnRunner + the database;
+  # the queue only provides at-least-once delivery and retry backoff.
+  class TurnJob < ApplicationJob # :nodoc:
     queue_as :default
 
     retry_on StandardError, wait: :polynomially_longer, attempts: 5

data/app/mailers/xeno/application_mailer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   class ApplicationMailer < ActionMailer::Base
     default from: "from@example.com"

data/app/models/xeno/action.rb

@@ -1,17 +1,15 @@
+# frozen_string_literal: true
+
 module Xeno
-  # One requested tool call: the durability checkpoint and (in M4) the
-  # approval state. A completed action means "executed AND its result is in
-  # the transcript" — the two are committed in one transaction, so replay
-  # logic can trust either signal.
+  # One requested tool call: the durability checkpoint and the approval state. A completed action
+  # means executed and its result is in the transcript — committed in one transaction, so replay can
+  # trust either signal.
   class Action < ApplicationRecord
-    STATUSES = %w[pending pending_approval approved denied completed failed].freeze
-    KINDS = %w[tool question].freeze
+    enum :status, %w[pending pending_approval approved denied completed failed].index_with(&:itself), validate: true
+    enum :kind, %w[tool question].index_with(&:itself), prefix: true, validate: true
 
     belongs_to :turn, class_name: "Xeno::Turn"
 
-    validates :status, inclusion: { in: STATUSES }
-    validates :kind, inclusion: { in: KINDS }
-
     def self.record!(turn, tool_call, kind: "tool")
       find_or_create_by!(turn: turn, tool_call_id: tool_call.id) do |action|
         action.tool_name = tool_call.name
@@ -19,8 +17,5 @@ module Xeno
         action.input = tool_call.arguments
       end
     end
-
-    def completed? = status == "completed"
-    def awaiting_input? = %w[pending_approval].include?(status)
   end
 end

data/app/models/xeno/application_record.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true

data/app/models/xeno/chat.rb

@@ -1,18 +1,16 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The persisted RubyLLM chat backing one session's transcript.
-  # Owned by xeno — host apps with their own acts_as chat classes are
-  # unaffected; the message class below pins the transcript inside the
-  # engine namespace. Models, tool calls, usage, and batches are RubyLLM
-  # library records (ruby_llm_* tables), polymorphic toward this class.
+  # The persisted RubyLLM chat backing one session's transcript, owned by xeno — host apps with
+  # their own acts_as chat classes are unaffected. Models, tool calls, usage, and batches are
+  # RubyLLM library records (ruby_llm_* tables), polymorphic toward this class.
   class Chat < ApplicationRecord
     acts_as_chat message_class: "Xeno::Message"
 
-    # assume_model_exists and protocol are runtime attributes, not columns —
-    # a freshly loaded record loses them, and the first to_llm build (which
-    # with_instructions triggers) then resolves the model strictly and with
-    # the provider's default protocol: ModelNotFoundError on the SECOND
-    # message of any session using a custom/OpenAI-compatible model
-    # (finding K). Every entry point re-applies them from the definition.
+    # assume_model_exists and protocol are runtime attributes, not columns, so a freshly loaded
+    # record loses them and the first to_llm build resolves the model strictly — ModelNotFoundError
+    # on the session's second message for a custom model. Every entry point re-applies them from the
+    # definition.
     def apply_runtime_options!(model_options)
       self.assume_model_exists = model_options[:assume_model_exists] if model_options.key?(:assume_model_exists)
       self.protocol = model_options[:protocol] if model_options.key?(:protocol)

data/app/models/xeno/dedup.rb

@@ -1,14 +1,14 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The at-least-once dedup ledger. Redelivered work (a cron tick fired
-  # twice, a Slack retry storm) claims its (scope, key) once; every other
-  # delivery loses the unique-index race and can read what the winner
-  # recorded in metadata.
+  # The at-least-once dedup ledger. Redelivered work (a cron tick fired twice, a Slack retry storm)
+  # claims its (scope, key) once; every other delivery loses the unique-index race and can read what
+  # the winner recorded in metadata.
   class Dedup < ApplicationRecord
     validates :scope, :key, presence: true
 
-    # Returns the freshly claimed row, or nil when the key was already
-    # claimed. Safe inside enclosing transactions (savepoint), safe under
-    # concurrency (the unique index decides).
+    # Returns the freshly claimed row, or nil when the key was already claimed. Safe inside
+    # enclosing transactions (savepoint), safe under concurrency (the unique index decides).
     def self.claim(scope, key, metadata: {})
       transaction(requires_new: true) do
         create!(scope: scope, key: key, metadata: metadata)