riffer-rig 0.16.0 → 0.17.0

data/lib/riffer/rig/credentials.rb

@@ -5,7 +5,7 @@ require 'open3'
 module Riffer::Rig::Credentials
   extend self
 
-  PATH = File.expand_path('~/.riffer/auth.json') #: String
+  PATH = Riffer::Rig::Directories.riffer(Dir.home, 'auth.json') #: String
 
   ENTRY_TYPE = 'api_key'
 
@@ -39,6 +39,36 @@ module Riffer::Rig::Credentials
     Resolution.new(values: resolution.values, missing: missing)
   end
 
+  # @rbs identifier: String | Symbol
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs env: Riffer::Rig::Env
+  # @rbs auth_path: String
+  # @rbs label: String
+  # @rbs setup: Riffer::Rig::ProviderSetup
+  # @rbs config: Riffer::Config?
+  # @rbs settings_path: String
+  # @rbs known: Hash[Symbol, String]
+  # @rbs return: (Hash[Symbol, String] | String)
+  def install_values(
+    identifier,
+    host:,
+    env:,
+    auth_path:,
+    label: identifier.to_s,
+    setup: Riffer::Rig::ProviderSetup.for(identifier),
+    config: Riffer.config,
+    settings_path: Riffer::Rig::Settings::File::PATH,
+    known: {}
+  )
+    resolution = install(identifier, host:, setup:, env:, config:, auth_path:, settings_path:, known:)
+    return resolution if resolution.is_a?(String)
+    return resolution.values if resolution.missing.empty?
+
+    "#{label} has no #{setup.missing_fields(resolution.missing)}; " \
+      'set it in the environment or run riffer interactively to paste it' \
+      "#{" (create one at #{setup.url})" if setup.url}"
+  end
+
   # A registered extension provider has no Riffer::Config member, so the
   # assignment stays built-ins-only.
   # @rbs identifier: String | Symbol
@@ -107,7 +137,7 @@ module Riffer::Rig::Credentials
     return stored if stored.is_a?(String)
     return :stored if secret_fields.any? { |field| stored.key?(field.name.to_s) }
 
-    setup.chain ? :chain : :missing
+    setup.chain? ? :chain : :missing
   end
 
   private
@@ -119,14 +149,7 @@ module Riffer::Rig::Credentials
   # @rbs auth_path: String
   # @rbs settings_path: String
   # @rbs return: (Resolution | String)
-  def resolve(
-    identifier,
-    host:,
-    setup: Riffer::Rig::ProviderSetup.for(identifier),
-    env: Riffer::Rig::Env.new,
-    auth_path: PATH,
-    settings_path: Riffer::Rig::Settings::File::PATH
-  )
+  def resolve(identifier, host:, setup:, env:, auth_path:, settings_path:)
     secrets = stored_secrets(identifier, auth_path)
     return secrets if secrets.is_a?(String)
 
@@ -136,13 +159,22 @@ module Riffer::Rig::Credentials
     found = setup.fields.to_h do |field|
       [field.name, env.value_for(field) || stored_value(field, secrets, plain, env) || field.fallback&.call]
     end.compact
-    required = setup.fields.select(&:required)
-    answers = ask_for(required.reject { |field| found.key?(field.name) }, identifier, host)
+    unresolved = setup.fields.select(&:required).reject { |field| found.key?(field.name) }
+    pending = outside_chain(unresolved, setup)
+    answers = ask_for(pending, identifier, host)
     refusal = store(identifier, answers, setup:, auth_path:, settings_path:)
     return refusal if refusal
 
-    values = found.merge(answers)
-    Resolution.new(values:, missing: required.map(&:name) - values.keys)
+    Resolution.new(values: found.merge(answers), missing: pending.map(&:name) - answers.keys)
+  end
+
+  # @rbs fields: Array[Riffer::Rig::ProviderSetup::Field]
+  # @rbs setup: Riffer::Rig::ProviderSetup
+  # @rbs return: Array[Riffer::Rig::ProviderSetup::Field]
+  def outside_chain(fields, setup)
+    return fields unless fields.any?(&:secret) && setup.chain?
+
+    fields.reject(&:secret)
   end
 
   # @rbs fields: Array[Riffer::Rig::ProviderSetup::Field]

data/lib/riffer/rig/directories.rb

@@ -17,4 +17,11 @@ module Riffer::Rig::Directories
     root = dirs.index { |dir| File.exist?(File.join(dir, '.git')) } || 0
     dirs.take(root + 1)
   end
+
+  # @rbs root: String
+  # @rbs *names: String
+  # @rbs return: String
+  def riffer(root, *names)
+    File.join(root, '.riffer', *names)
+  end
 end

data/lib/riffer/rig/extension.rb

@@ -22,6 +22,7 @@ class Riffer::Rig::Extension
     @requires = requires && Gem::Requirement.new(requires)
     @mismatch = check(@requires)
     @block = block
+    freeze
   end
 
   # @rbs registrar: Riffer::Rig::Registrar

data/lib/riffer/rig/headless.rb

@@ -76,6 +76,7 @@ class Riffer::Rig::Headless
     @json = json
     @job_idle_timeout = job_idle_timeout
     @stdin_timeout = stdin_timeout
+    @streamed_text = false
     @wrote_text = false
     @break_before_text = false
   end
@@ -245,8 +246,8 @@ class Riffer::Rig::Headless
     return 0 if stop_reason == :completed
 
     @error.puts("turn ended: #{stop_reason}") if stop_reason
-    return 130 if stop_reason == Riffer::Rig::Runtime::INTERRUPT_CANCELLED
-    return 3 if stop_reason && Riffer::Rig::Runtime::STOPPED_WITHOUT_COMPLETING.include?(stop_reason)
+    return 130 if stop_reason == Riffer::Rig::Runtime::StopReason::INTERRUPT_CANCELLED
+    return 3 if stop_reason && Riffer::Rig::Runtime::StopReason::STOPPED_WITHOUT_COMPLETING.include?(stop_reason)
 
     1
   end

data/lib/riffer/rig/loader/extension_source.rb

@@ -80,12 +80,12 @@ class Riffer::Rig::Loader::ExtensionSource
 
   # @rbs return: String
   def home_rig_path
-    File.expand_path(File.join(@home, '.riffer', 'rig.rb'))
+    File.expand_path(Riffer::Rig::Directories.riffer(@home, 'rig.rb'))
   end
 
   # @rbs return: String
   def project_rig_path
-    File.expand_path(File.join(@cwd, '.riffer', 'rig.rb'))
+    File.expand_path(Riffer::Rig::Directories.riffer(@cwd, 'rig.rb'))
   end
 
   # @rbs autoload: bool
@@ -135,7 +135,7 @@ class Riffer::Rig::Loader::ExtensionSource
 
   # @rbs return: String
   def trust_path
-    File.join(@home, '.riffer', 'trust.json')
+    Riffer::Rig::Directories.riffer(@home, 'trust.json')
   end
 
   # @rbs path: String
@@ -171,7 +171,7 @@ class Riffer::Rig::Loader::ExtensionSource
   # @rbs feature: String
   # @rbs return: bool
   def local?(feature)
-    roots = [File.expand_path(File.join(@home, '.riffer')), File.expand_path(@cwd)] #: Array[String]
+    roots = [File.expand_path(Riffer::Rig::Directories.riffer(@home)), File.expand_path(@cwd)] #: Array[String]
     roots.any? { |root| feature.start_with?("#{root}#{File::SEPARATOR}") }
   end
 end

data/lib/riffer/rig/loader/reasoning.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Loader::Reasoning
+  extend self
+
+  # @rbs flag: String?
+  # @rbs env: String?
+  # @rbs return: String?
+  def forced(flag, env)
+    flag || env
+  end
+
+  # @rbs flag: String?
+  # @rbs env: String?
+  # @rbs return: String?
+  def rejection(flag, env)
+    level = forced(flag, env)
+    return unless level
+
+    rejection = Riffer::Rig::Settings::ModelOptions.reasoning_rejection(level)
+    return unless rejection
+
+    flag ? rejection : "RIFFER_REASONING: #{rejection}"
+  end
+end

data/lib/riffer/rig/loader/reloader.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Loader::Reloader
+  # @rbs @source: Riffer::Rig::Loader::ExtensionSource
+  # @rbs @host: Riffer::Rig::Hosts::_Host
+  # @rbs @settings: ^() -> (Hash[Symbol, untyped] | String)
+  # @rbs @credentials: ^(String) -> (Hash[Symbol, String] | String)
+  # @rbs @extensions: ^(Riffer::Rig::Settings::Document, Array[Riffer::Rig::Extension]) -> Array[Riffer::Rig::Extension]
+  # @rbs @rediscovers: bool
+  # @rbs @mode: (:auto | :manual | nil)
+  # @rbs @file_state: Hash[String, Time?]
+
+  # @rbs source: Riffer::Rig::Loader::ExtensionSource
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs settings: ^() -> (Hash[Symbol, untyped] | String)
+  # @rbs credentials: ^(String) -> (Hash[Symbol, String] | String)
+  # @rbs extensions: ^(Riffer::Rig::Settings::Document, Array[Riffer::Rig::Extension]) -> Array[Riffer::Rig::Extension]
+  # @rbs rediscovers: bool
+  # @rbs mode: (:auto | :manual | nil)
+  # @rbs return: void
+  def initialize(source:, host:, settings:, credentials:, extensions:, rediscovers:, mode:)
+    @source = source
+    @host = host
+    @settings = settings
+    @credentials = credentials
+    @extensions = extensions
+    @rediscovers = rediscovers
+    @mode = mode
+    @file_state = file_state
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs force: bool
+  # @rbs return: (Riffer::Rig::Runtime | String)
+  def reload(runtime, force: false)
+    return runtime if !force && file_state == @file_state
+    return runtime if !force && manual?
+
+    outcome = perform(runtime)
+    # Every attempt advances the state, failed ones included, so a failure is
+    # not retried at every request.
+    @file_state = file_state
+    outcome
+  end
+
+  private
+
+  # @rbs return: bool
+  def manual?
+    return @mode == :manual if @mode
+
+    settings = @settings.call
+    settings.is_a?(Hash) && Riffer::Rig::Settings::Document.new(settings).reload == :manual
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs return: (Riffer::Rig::Runtime | String)
+  def perform(runtime)
+    settings = @settings.call
+    return notify_failure(settings) if settings.is_a?(String)
+
+    rediscovered = @rediscovers ? @source.rediscover : [] #: Array[Riffer::Rig::Extension] | String
+    return notify_failure(rediscovered) if rediscovered.is_a?(String)
+
+    candidates = @extensions.call(Riffer::Rig::Settings::Document.new(settings), rediscovered)
+    extensions = @source.validated(candidates, settings)
+    provider = runtime.model.partition('/').first
+    credentials = @credentials.call(provider)
+    return notify_failure(credentials) if credentials.is_a?(String)
+
+    runtime.merge_credentials(provider.to_sym, credentials)
+    runtime.rebuild(extensions: extensions, settings: settings)
+    runtime
+  rescue StandardError => e
+    # The automatic check runs mid-turn with nothing else to catch a raise,
+    # and a raised attempt must still advance the file state.
+    notify_failure(e.message)
+  end
+
+  # @rbs message: String
+  # @rbs return: String
+  def notify_failure(message)
+    @host.notify(message, level: :error)
+    message
+  end
+
+  # @rbs return: Hash[String, Time?]
+  def file_state
+    @rediscovers ? @source.file_state : {}
+  end
+end

data/lib/riffer/rig/loader.rb

@@ -10,12 +10,8 @@ class Riffer::Rig::Loader
   # @rbs @riffer_config: Riffer::Config
   # @rbs @store: Riffer::Rig::Stores::_Store | nil
   # @rbs @source: Riffer::Rig::Loader::ExtensionSource
-  # @rbs @stripped: Array[Symbol]
-  # @rbs @extensions_enabled: bool
-  # @rbs @extra_extensions: Array[Riffer::Rig::Extension]
-  # @rbs @recorder_extensions: Array[Riffer::Rig::Extension]
-  # @rbs @file_state: Hash[String, Time?]?
-  # @rbs @reload_mode: (:auto | :manual | nil)
+  # @rbs @reloaders: ObjectSpace::WeakKeyMap[Riffer::Rig::Runtime, Riffer::Rig::Loader::Reloader]
+  # @rbs @sdk: singleton(Riffer::Rig::SDK)
 
   # @rbs cwd: String
   # @rbs host: Riffer::Rig::Hosts::_Host
@@ -26,7 +22,7 @@ class Riffer::Rig::Loader
   # @rbs options: Riffer::Rig::Loader::Options
   # @rbs reload: (:auto | :manual | nil)
   # @rbs extra_extensions: Array[Riffer::Rig::Extension]
-  # @rbs snapshot: Hash[Symbol, untyped]?
+  # @rbs snapshot: (Riffer::Rig::Runtime::Snapshot | Hash[Symbol, untyped])?
   # @rbs return: Riffer::Rig::Runtime
   def self.runtime(
     cwd:,
@@ -49,6 +45,7 @@ class Riffer::Rig::Loader
   # @rbs home: String
   # @rbs riffer_config: Riffer::Config
   # @rbs store: Riffer::Rig::Stores::_Store | nil
+  # @rbs sdk: singleton(Riffer::Rig::SDK)
   # @rbs return: void
   def initialize(
     cwd:,
@@ -56,7 +53,8 @@ class Riffer::Rig::Loader
     env: Riffer::Rig::Env.load,
     home: Dir.home,
     riffer_config: Riffer.config,
-    store: Riffer::Rig::Stores::JSONL.new(home: home)
+    store: Riffer::Rig::Stores::JSONL.new(home: home),
+    sdk: Riffer::Rig::SDK
   )
     raise ConfigurationError, env.message if env.is_a?(Riffer::Rig::Env::Invalid)
 
@@ -66,18 +64,15 @@ class Riffer::Rig::Loader
     @home = home
     @riffer_config = riffer_config
     @store = store
+    @sdk = sdk
     @source = Riffer::Rig::Loader::ExtensionSource.new(cwd: cwd, home: home, host: host)
-    @stripped = []
-    @extensions_enabled = true
-    @recorder_extensions = []
-    @file_state = nil
-    @reload_mode = nil
+    @reloaders = ObjectSpace::WeakKeyMap.new
   end
 
   # @rbs options: Riffer::Rig::Loader::Options
   # @rbs reload: (:auto | :manual | nil)
   # @rbs extra_extensions: Array[Riffer::Rig::Extension]
-  # @rbs snapshot: Hash[Symbol, untyped]?
+  # @rbs snapshot: (Riffer::Rig::Runtime::Snapshot | Hash[Symbol, untyped])?
   # @rbs return: Riffer::Rig::Runtime
   def runtime(options = Options.new, reload: nil, extra_extensions: [], snapshot: nil)
     settings = merged_settings
@@ -85,31 +80,27 @@ class Riffer::Rig::Loader
 
     document = Riffer::Rig::Settings::Document.new(settings)
     selected = select_model(options.model || @env.model || document.model)
-    check_reasoning(options)
+    rejection = Riffer::Rig::Loader::Reasoning.rejection(options.reasoning, @env.reasoning)
+    raise ConfigurationError, rejection if rejection
+
     provider = Riffer::Rig::Settings::ModelOptions.provider_for(selected).to_s
     ensure_sdk(provider)
     credentials = install_credentials(provider)
     raise ConfigurationError, credentials if credentials.is_a?(String)
 
     @riffer_config.catalog_files = document.catalog_files
-    @extensions_enabled = options.extensions
-    @extra_extensions = extra_extensions
-    @reload_mode = reload
-    @stripped = { skills: options.skills, agents_md: options.agents_md }.reject { |_name, kept| kept }.keys
-    loaded = bundled(document)
-    loaded += @source.discover(autoload: document.autoload) if options.extensions
-    loaded += @extra_extensions
+    stripped = { skills: options.skills, agents_md: options.agents_md }.reject { |_name, kept| kept }.keys
+    discovered = options.extensions ? @source.discover(autoload: document.autoload) : [] #: Array[Riffer::Rig::Extension]
 
-    recorder = recorder_for(document, resumed: !snapshot.nil?)
-    @recorder_extensions = recorder ? [Riffer::Rig::Stores::Recorder.extension(recorder)] : []
-    loaded += @recorder_extensions
+    saved = snapshot && Riffer::Rig::Runtime::Snapshot.of(snapshot)
+    recorder = recorder_for(document, resumed: !saved.nil?)
+    recording = recorder ? [Riffer::Rig::Stores::Recorder.extension(recorder)] : [] #: Array[Riffer::Rig::Extension]
 
-    snapshot = snapshot_without_forced(snapshot, options)
-    reasoning = forced_reasoning(options, snapshot)
+    saved = snapshot_without_forced(saved, options)
 
     built = Riffer::Rig::Runtime.new(
       selected,
-      extensions: loaded,
+      extensions: bundled(document, stripped) + discovered + extra_extensions + recording,
       tools: options.tools,
       settings: settings,
       host: @host,
@@ -118,17 +109,29 @@ class Riffer::Rig::Loader
       credentials: { provider.to_sym => credentials },
       env: @env,
       auth_path: home_auth_path,
-      reasoning: reasoning || settings_reasoning(document),
+      settings_path: home_settings_path,
+      reasoning: Riffer::Rig::Loader::Reasoning.forced(options.reasoning, @env.reasoning),
       riffer_config: @riffer_config,
       model_options: Riffer::Rig::Settings::ModelOptions.model_options(selected),
       native_tools: document.native_tools,
-      snapshot: snapshot
+      snapshot: saved
     )
-    built.install_command(Riffer::Rig::Commands::Reload.command(self))
+    reloader = Riffer::Rig::Loader::Reloader.new(
+      source: @source,
+      host: @host,
+      settings: -> { merged_settings },
+      credentials: ->(name) { install_credentials(name) },
+      extensions: ->(current, found) { bundled(current, stripped) + extra_extensions + found + recording },
+      rediscovers: options.extensions,
+      mode: reload
+    )
+    @reloaders[built] = reloader
+    built.install_command(Riffer::Rig::Commands::Reload.command(reloader))
     store = @store
     built.install_command(Riffer::Rig::Commands::Trace.command(store)) if store && recorder
-    built.install_reload_check(->(runtime) { automatic_reload(runtime) }) unless reload_mode(document) == :manual
-    @file_state = file_state
+    unless (reload || document.reload) == :manual
+      built.install_reload_check(->(runtime) { _ = reloader.reload(runtime) })
+    end
     recorder&.attach(built)
     built
   end
@@ -145,8 +148,6 @@ class Riffer::Rig::Loader
     resume(latest.id, options)
   end
 
-  # A resume carries the history over and nothing else: the settings,
-  # credentials, extensions and tools are today's.
   # @rbs id: String
   # @rbs options: Riffer::Rig::Loader::Options
   # @rbs extra_extensions: Array[Riffer::Rig::Extension]
@@ -190,56 +191,22 @@ class Riffer::Rig::Loader
     store.delete(id)
   end
 
-  # Without force, a no-op while the tracked file set and the two rig.rb paths
-  # look as the last discovery left them and the reload mode is not manual —
-  # the entry point the automatic trigger (#133) calls. The snapshot advances
-  # on every attempt, failed ones included, so a failure does not retry every
-  # request. Failures are notified once and reported as the message, the way
-  # Settings::ModelOptions.rejection reports a rejection; the Runtime is the success value.
   # @rbs runtime: Riffer::Rig::Runtime
   # @rbs force: bool
   # @rbs return: (Riffer::Rig::Runtime | String)
   def reload(runtime, force: false)
-    return runtime if !force && file_state == @file_state
-    return runtime if !force && manual_reload?
-
-    outcome = perform_reload(runtime)
-    @file_state = file_state
-    outcome
+    reloader = @reloaders[runtime]
+    reloader ? reloader.reload(runtime, force: force) : runtime
   end
 
   private
 
-  # The reload mode a build runs under: the keyword wins over the setting,
-  # the setting over the default.
-  # @rbs document: Riffer::Rig::Settings::Document
-  # @rbs return: (:auto | :manual)
-  def reload_mode(document)
-    @reload_mode || document.reload
-  end
-
-  # @rbs return: bool
-  def manual_reload?
-    return true if @reload_mode == :manual
-
-    settings = merged_settings
-    settings.is_a?(Hash) && reload_mode(Riffer::Rig::Settings::Document.new(settings)) == :manual
-  end
-
-  # The automatic trigger: runs at every before_request boundary, so the
-  # change check decides and a no-op costs the stat alone.
-  # @rbs runtime: Riffer::Rig::Runtime
-  # @rbs return: void
-  def automatic_reload(runtime)
-    _ = reload(runtime)
-  end
-
   # @rbs return: (Hash[Symbol, untyped] | String)
   def merged_settings
     home = read_settings(home_settings_path)
     return home if home.is_a?(String)
 
-    project = read_settings(File.join(@cwd, '.riffer', 'settings.json'))
+    project = read_settings(Riffer::Rig::Directories.riffer(@cwd, 'settings.json'))
     return project if project.is_a?(String)
 
     Riffer::Rig::Settings.merge(home, project)
@@ -254,57 +221,11 @@ class Riffer::Rig::Loader
     "#{path} sets \"model\" to a value that is not a string"
   end
 
-  # Notifies every failure once and reports its message, unexpected raises
-  # included — the automatic check runs mid-turn with no other isolation, and a
-  # raised attempt must still advance the snapshot in reload. A rebuilt Runtime
-  # is the success value.
-  # @rbs runtime: Riffer::Rig::Runtime
-  # @rbs return: (Riffer::Rig::Runtime | String)
-  def perform_reload(runtime)
-    settings = merged_settings
-    return notify_failure(settings) if settings.is_a?(String)
-
-    candidates = reload_candidates(Riffer::Rig::Settings::Document.new(settings))
-    return notify_failure(candidates) if candidates.is_a?(String)
-
-    extensions = @source.validated(candidates + @recorder_extensions, settings)
-    provider = runtime.model.partition('/').first
-    credentials = install_credentials(provider)
-    return notify_failure(credentials) if credentials.is_a?(String)
-
-    runtime.merge_credentials(provider.to_sym, credentials)
-    runtime.rebuild(extensions: extensions, settings: settings)
-    runtime
-  rescue StandardError => e
-    notify_failure(e.message)
-  end
-
-  # @rbs message: String
-  # @rbs return: String
-  def notify_failure(message)
-    @host.notify(message, level: :error)
-    message
-  end
-
-  # @rbs document: Riffer::Rig::Settings::Document
-  # @rbs return: (Array[Riffer::Rig::Extension] | String)
-  def reload_candidates(document)
-    candidates = bundled(document) + @extra_extensions
-    return candidates unless @extensions_enabled
-
-    rediscovered = @source.rediscover
-    rediscovered.is_a?(String) ? rediscovered : candidates + rediscovered
-  end
-
   # @rbs document: Riffer::Rig::Settings::Document
+  # @rbs stripped: Array[Symbol]
   # @rbs return: Array[Riffer::Rig::Extension]
-  def bundled(document)
-    Riffer::Rig::Bundled::BY_NAME.except(*document.disabled.map(&:to_sym), *@stripped).values
-  end
-
-  # @rbs return: Hash[String, Time?]
-  def file_state
-    @extensions_enabled ? @source.file_state : {}
+  def bundled(document, stripped)
+    Riffer::Rig::Bundled::BY_NAME.except(*document.disabled.map(&:to_sym), *stripped).values
   end
 
   # @rbs configured: String?
@@ -348,14 +269,14 @@ class Riffer::Rig::Loader
     return unless sdk
 
     gem, requirement = sdk
-    message = Riffer::Rig::SDK.ensure(gem, requirement, host: @host)
+    message = @sdk.ensure(gem, requirement, host: @host)
     raise ConfigurationError, message if message
   end
 
   # @rbs provider: String
   # @rbs return: (Hash[Symbol, String] | String)
   def install_credentials(provider)
-    Riffer::Rig::Loader::Credentials.install(
+    Riffer::Rig::Credentials.install_values(
       provider,
       host: @host,
       env: @env,
@@ -367,65 +288,25 @@ class Riffer::Rig::Loader
 
   # @rbs return: String
   def home_settings_path
-    File.join(@home, '.riffer', 'settings.json')
+    Riffer::Rig::Directories.riffer(@home, 'settings.json')
   end
 
   # @rbs return: String
   def home_auth_path
-    File.join(@home, '.riffer', 'auth.json')
-  end
-
-  # A reasoning level from the flag or the environment is refused, the way a
-  # bad model string is; one from the settings document or a session's recorded
-  # switch falls back to the model's default instead.
-  # @rbs options: Riffer::Rig::Loader::Options
-  # @rbs return: void
-  def check_reasoning(options)
-    forced = options.reasoning || @env.reasoning
-    return unless forced
-
-    rejection = Riffer::Rig::Settings::ModelOptions.reasoning_rejection(forced)
-    return unless rejection
-
-    raise ConfigurationError, options.reasoning ? rejection : "RIFFER_REASONING: #{rejection}"
-  end
-
-  # The reasoning in effect for the build, over the settings document: the flag,
-  # then the session's recorded switch, then RIFFER_REASONING.
-  # @rbs options: Riffer::Rig::Loader::Options
-  # @rbs snapshot: Hash[Symbol, untyped]?
-  # @rbs return: String?
-  def forced_reasoning(options, snapshot)
-    options.reasoning || recorded_reasoning(snapshot) || @env.reasoning
-  end
-
-  # @rbs snapshot: Hash[Symbol, untyped]?
-  # @rbs return: String?
-  def recorded_reasoning(snapshot)
-    saved = snapshot && snapshot[:reasoning]
-    Riffer::Rig::Settings::ModelOptions.reasoning_level(saved) if saved.is_a?(String)
-  end
-
-  # A settings level riffer does not accept silently keeps the model's default.
-  # @rbs document: Riffer::Rig::Settings::Document
-  # @rbs return: String?
-  def settings_reasoning(document)
-    Riffer::Rig::Settings::ModelOptions.reasoning_level(document.reasoning)
+    Riffer::Rig::Directories.riffer(@home, 'auth.json')
   end
 
-  # A model or reasoning level chosen for the run wins for that run only: it is
-  # not recorded, so a later resume restores the session's own switches.
-  # @rbs snapshot: Hash[Symbol, untyped]?
+  # @rbs snapshot: Riffer::Rig::Runtime::Snapshot?
   # @rbs options: Riffer::Rig::Loader::Options
-  # @rbs return: Hash[Symbol, untyped]?
+  # @rbs return: Riffer::Rig::Runtime::Snapshot?
   def snapshot_without_forced(snapshot, options)
-    snapshot = snapshot&.merge(model: nil) if options.model
-    snapshot = snapshot&.merge(reasoning: nil) if options.reasoning
+    # The flags beat the session's recorded switches, which the Runtime would
+    # otherwise restore over them.
+    snapshot = snapshot&.without_model if options.model
+    snapshot = snapshot&.without_reasoning if options.reasoning
     snapshot
   end
 
-  # The store records unless it was declined with store: nil or globally with
-  # "sessions": {"save": false}.
   # @rbs document: Riffer::Rig::Settings::Document
   # @rbs resumed: bool
   # @rbs return: Riffer::Rig::Stores::Recorder?