silas 0.6.2 → 0.6.3

data/docs/traces.md

@@ -0,0 +1,131 @@
+# The trace schema
+
+Every step your agent takes is rows in **your** database — transactional,
+priced, and joinable to the business rows the agent touched. Most frameworks
+treat their execution record as internal bookkeeping in a store beside your
+app. Silas treats it as **a documented, versioned interface**: your analytics,
+your dashboards, and your own tooling are meant to query these tables
+directly.
+
+That is the whole point of the trace living where it does. An external
+observability platform can show you what the agent said; it cannot join the
+tool call to the `refunds` row it created, in one query, with no export:
+
+```sql
+SELECT ti.tool_name, ti.arguments, ti.approved_by, r.amount_pence
+FROM silas_tool_invocations ti
+JOIN refunds r ON r.id = json_extract(ti.result, '$.refund_id')
+WHERE ti.approval_state = 'approved';
+```
+
+## The contract
+
+Columns documented here are **stable within a major version**: they may gain
+siblings in any release, but renames and semantic changes only happen at a
+major, and appear in the CHANGELOG under an upgrade note. Columns *not* listed
+here are internal — query them if you like, but they can move without notice.
+
+## `silas_sessions` — a conversation
+
+| Column | Meaning |
+|---|---|
+| `agent_name` | Which agent owns the session (`"agent"` = the root agent). |
+| `status` | `active` \| `archived`. **Note:** parked work is a *turn* state, not a session state. |
+| `parent_session_id` | Set when this session was created by a handoff or delegation — the lineage the inbox renders. |
+| `channel` | The transport that started it (`"slack"`, `"email"`, …), `NULL` for direct/API. |
+| `metadata` | JSON. Channel-specific context (e.g. the inbound email's sender). Plain `json`, not `jsonb` — the schema works identically on SQLite and Postgres. |
+
+## `silas_turns` — one request, run durably
+
+| Column | Meaning |
+|---|---|
+| `index` | Position within the session; `(session_id, index)` is unique. |
+| `status` | `queued` \| `running` \| `waiting` (parked for a human) \| `in_doubt` \| `completed` \| `failed` \| `canceled`. At most one non-final turn per session — enforced by `index_silas_turns_single_active`. |
+| `input` | What the user (or channel, or schedule) asked. |
+| `instructions_snapshot` | The system prompt as rendered **once** at turn start; immutable after. What the model actually saw, forever. |
+| `definitions_digest` | Hash of tool schemas + skill descriptions at turn start — the nondeterminism guard that refuses to resume a turn against a changed agent. |
+| `failure_reason` | Why a `failed` turn failed (`max_steps`, `definitions_changed`, `job_failed`, budget reasons, …). |
+| `input_tokens` / `output_tokens` / `cost_microcents` | Accumulated across the turn's steps. 1,000,000 microcents = $1. |
+| `budget_overrides` | JSON. A human's top-up on a budget-parked turn, beating `agent.yml` limits. |
+| `started_at` / `finished_at` | Wall-clock bounds. Note `started_at` resets on resume after a park — `limits.timeout` measures *active* time, not human deliberation. |
+
+## `silas_steps` — one model call
+
+| Column | Meaning |
+|---|---|
+| `index` | Position within the turn; `(turn_id, index)` is unique — at most one persisted model response per slot. |
+| `status` | `started` \| `completed`. |
+| `model` / `provider` | What actually served this step. Provider is stamped at execution so historical cost survives registry changes. |
+| `response_blocks` | The model's full response — text, tool calls — as JSON. Replay rebuilds the conversation from these rows. |
+| `stop_reason` | Why the model stopped (`tool_use`, `end_turn`, …). |
+| `terminal` | Write-once after completion; **the** loop-control column. A resumed continuation must re-derive the identical step sequence from it. |
+| `input_tokens` / `output_tokens` | This step's usage; cost derives from these plus `(model, provider)` pricing at read time. |
+
+## `silas_tool_invocations` — one tool call, exactly once
+
+The heart of the ledger.
+
+| Column | Meaning |
+|---|---|
+| `tool_call_id` | The model's id for the call. `(step_id, tool_call_id)` is unique — **this index is the exactly-once key**. |
+| `tool_name` / `arguments` | What was called, with what. Arguments are model-authored — render escaped. |
+| `status` | `pending` \| `started` \| `completed` \| `failed` \| `in_doubt`. |
+| `effect_mode` | `transactional` \| `at_most_once` \| `idempotent` — **snapshotted from the tool class at creation**, so editing a tool mid-park cannot change the semantics of an existing invocation. |
+| `result` | The tool's return value (or the question's answer, or `{"denied": reason}`). |
+| `approval_state` | `NULL` (no gate) \| `required` \| `approved` \| `declined` \| `expired`. `NULL` on a completed invocation means *policy cleared it*; a value means *a decision was made* — that distinction is load-bearing for audit. |
+| `approved_by` | Who decided. `NULL` on an auto-cleared gate, an identity string on a human verdict. |
+| `approval_expires_at` / `decline_reason` | The TTL, and the human's stated reason. |
+
+**The free labeled dataset.** `approval_state` + `approved_by` +
+`decline_reason` record a human's verdict on a specific agent action, with
+full context, in production, at zero annotation cost. If you ever train or
+evaluate against your own traffic, this is where the labels already are.
+
+## `silas_compactions` — summaries that survive replay
+
+One row per compacted span: `session_id`, `up_to_turn_index` (unique
+together — exactly one summary per span no matter how many replays race),
+`status`, `summary`, and what the summarisation itself cost (`tokens_before`,
+`input_tokens`, `output_tokens`, `model`). Deterministic by construction: the
+message builder reads the row, never recomputes.
+
+## `silas_memories` — what the agent knows across sessions
+
+`agent_name`, `scope` (`agent` private \| `app` shared), `subject`,
+`attribute_name`, `content`, `status` (`active` \| `superseded`),
+`superseded_by_id`, and provenance (`session_id`, `turn_id`). Approval-gated
+on write by default. **Single-tenant per deployment** — see
+[guarantees](guarantees.md) for the boundary.
+
+## Queries you already own
+
+Cost per agent per day:
+
+```sql
+SELECT s.agent_name, date(t.created_at) AS day, SUM(t.cost_microcents)/1e6 AS dollars
+FROM silas_turns t JOIN silas_sessions s ON s.id = t.session_id
+GROUP BY 1, 2 ORDER BY 2 DESC;
+```
+
+Every action a specific person approved, with what it did:
+
+```sql
+SELECT ti.created_at, ti.tool_name, ti.arguments, ti.result
+FROM silas_tool_invocations ti
+WHERE ti.approved_by = 'dana@example.com' ORDER BY ti.created_at DESC;
+```
+
+What parked, and for how long, before a human answered:
+
+```sql
+SELECT ti.tool_name, ti.approval_state,
+       (julianday(ti.updated_at) - julianday(ti.created_at)) * 24 AS hours_parked
+FROM silas_tool_invocations ti
+WHERE ti.approval_state IN ('approved','declined','expired');
+```
+
+The replay principle behind all of this: `Silas::MessageBuilder` reconstructs
+the exact prompt at any step from these rows alone, deterministically. Nothing
+in the trace reads the clock or mutable state — which is why a crashed turn
+resumes byte-identically, and why the trace you query is the trace that
+actually ran.

data/docs/tutorial.md

@@ -220,10 +220,12 @@ app/agents/escalations/
 ```
 
 Restart, and the desk can delegate durably: the built-in `handoff` tool files
-a **self-contained brief** that starts a linked session for the named agent —
-exactly-once-guarded and cycle-checked — instead of two models chatting
-freely (a cost and audit hazard, deliberately unblessed). Talk to a
-specialist directly with `Silas.agent("escalations").start(input: "…")` or
+a **self-contained brief** that starts a linked session for the named agent,
+rather than letting two models chat freely (a cost and audit hazard,
+deliberately unblessed). A handoff is cycle-checked and at-most-once: a crash
+mid-handoff parks it in doubt for a person instead of starting the colleague
+twice. Talk to a specialist directly with
+`Silas.agent("escalations").start(input: "…")` or
 `bin/rails silas:chat AGENT=escalations`; the inbox filters by agent.
 
 ## 10 · Fit the governors: budgets and compaction

data/docs/vs-eve.md

@@ -1,7 +1,7 @@
 # Silas vs eve
 
-> Written **2026-07-26** against **eve 0.27.6** and Silas 0.5.x, from eve's
-> published docs and source. Both projects move fast — if you're reading this
+> Written **2026-07-29** against **eve 0.27.8** (source and shipped docs, not
+> marketing) and Silas 0.6.x. Both projects move fast — if you're reading this
 > much later, re-verify before deciding.
 
 Silas and eve share the same organising idea: **an agent is a directory of
@@ -16,22 +16,31 @@ So the honest first cut is simply your stack: **a TypeScript team should use
 eve; a Rails team should use Silas.** The rest of this page is for people near
 the boundary — and for the differences that go deeper than language.
 
+One framing note, because it keeps this page honest: eve is a platform
+company's product, shipping weekly at roughly twenty-five times Silas's source
+volume. A surface-area comparison is a race Silas isn't running. What follows
+compares the **guarantees and the shape**, which is where the projects
+genuinely differ.
+
 ---
 
 ## The comparison
 
-| | Silas | eve (0.27.6) |
+| | Silas | eve (0.27.8) |
 |---|---|---|
 | **Shape** | A gem in your Rails app — your database, your job queue, your auth, one deploy. | A TypeScript service beside your app, with its own workflow store and deploy. |
 | **Authoring** | A directory of plain files. | A directory of plain files — genuinely the same idea. |
-| **Durable loop** | Survives `kill -9`, resumes from the last completed step. Chaos-gated every release: zero duplicate effects, byte-identical replay, SQLite + Postgres. | Workflow-engine replay; interrupted steps re-run. |
+| **Durable loop** | Survives `kill -9`, resumes from the last completed step. A `kill -9` harness (275-run matrix, SQLite + Postgres) is run before each release, results committed to the repo. | Workflow-engine replay; its own docs: "A step interrupted mid-execution re-runs." |
 | **Tool-effect semantics** | **Exactly-once** for DB-recorded effects (`transactional!` — effect + ledger in one transaction). Default at-most-once: an ambiguous crash **parks for a human**. | **At-least-once, documented as such** — "make non-idempotent side effects like charges or emails idempotent, or gate them with approval." Dedup is the tool author's job. |
-| **Human-in-the-loop** | Parks at zero compute; cleared from inbox, Slack, signed email, or API; parks expire; `ask_question` for the reverse direction. | `needsApproval` on tools. |
-| **Operator surface** | A production inbox mounted in your app: live traces, approval cards, audit trail, cost accounting, web chat. | A dev TUI ("not a production chat UI or customer-facing dashboard"); production UIs are assembled from templates. |
-| **Memory** | Shipped: approval-gated triples with provenance and supersession. | Deliberately out of scope. |
+| **Human-in-the-loop** | Parks at zero compute for days; cleared from inbox, Slack, signed email, or API; **approvals expire** (`approval_ttl`); verdicts are compare-and-swap (one card can't be spent twice); `ask_question` for the reverse direction. | `needsApproval` on tools, with typed input requests (options, freeform, display hints — a nicer request shape than Silas's). Approvals have **no expiry**: an unanswered one waits forever. |
+| **A message arriving mid-approval** | **Dropped today** — the sender is told delivery succeeded. An honest gap, fix scheduled. | **Held and replayed** after the approval settles — eve is ahead here. |
+| **A deploy while work is parked** | The turn **refuses to resume against a changed agent** (`NondeterminismError`, loud). Snapshot-resume is planned. | The next turn silently uses the new deployment's instructions, model, and tools — a parked approval can resume into a different agent than the one that asked. |
+| **Operator surface** | A production inbox mounted in your app: activity feed, approval cards, audit trail, cost accounting, handoff lineage, web chat — behind your auth. | A capable dev TUI (drives remote deployments: `--url`, `/deploy`, `/connect`) plus frontend SDKs and templates; the production operator surface is assembled by you. |
+| **Memory** | Cross-session memory ships: approval-gated triples with provenance and supersession. | `defineState` ships typed **session-scoped** durable state; anything cross-session "belongs in an external store" (its own docs) — integrations and patterns, not a shipped subsystem. |
+| **Evals** | Scenario DSL with scripted model decisions running the **real ledger and real tools against real rows**, keyless, as a deploy gate. | A broader harness: `defineEval`, dataset fan-out, gate-vs-soft severity, LLM-as-judge, reporters. eve is ahead on breadth; the difference in kind is that Silas evals exercise the real transactional machinery. |
+| **Channels** | Slack + email built in, **routable to named agents**; a generator scaffolds any transport. | More first-party surfaces (Slack, Discord, Teams, Telegram, Twilio, GitHub, Linear, chat SDK), growing quickly. |
 | **Ecosystem** | Ruby/Rails. | TypeScript + the AI SDK — a much larger ecosystem, with Vercel's distribution behind it. |
-| **Channels & integrations** | Slack + email built in; a generator scaffolds any transport. | More first-party surfaces, growing quickly. |
-| **Maturity** | Early (0.5.x); the durability contract is chaos-verified on every release. | Weeks old publicly; backed by a platform company, shipping at platform speed. |
+| **Maturity** | Early (0.6.x); pre-1.0, evolving deliberately. | Pre-1.0 and explicit about it: "prefer breaking changes… no legacy fallback logic." Backed by a platform company. |
 
 ---
 
@@ -50,22 +59,37 @@ framework where you don't have to.
 
 **Ambiguity parks.** At-least-once means a crash can re-fire a side effect.
 Silas's default is at-most-once with **in-doubt → human**: it never
-double-fires, and an ambiguous call waits for a person.
+double-fires, and an ambiguous call waits for a person. Everyone has
+approved/denied; Silas also has *we don't know, so someone decides*.
+
+**A park is a contract.** Approvals expire rather than ghosting forever, a
+verdict can't be spent twice, and a resumed turn is guaranteed to be the same
+agent that parked — or it fails loudly rather than continuing as something
+else. eve makes the opposite trade on that last point, deliberately: deploys
+apply to live sessions. For exploratory agents that's convenient; for an agent
+whose parked action a human already approved, Silas treats silently redefining
+it as an audit failure.
 
 **The operator surface ships.** `mount Silas::Engine` and the inbox exists —
-held/working/filed rail, live traces, approval cards, audit trail, cost, web
-chat — behind your app's own auth.
+the feed, approval cards, audit trail, cost, lineage — behind your app's own
+auth.
 
-**Memory ships.** Approval-gated, with provenance and supersession. eve
-reasonably says "bring your own"; Silas ships the batteries.
+**The trace lives in your database.** Every step, tool call, argument, result,
+approval and cost is rows in *your* schema, joinable to the business rows the
+agent actually touched. See [traces](traces.md) — the schema is a documented,
+versioned interface, not internal bookkeeping.
 
 ## Where eve goes further
 
 - **The ecosystem.** TypeScript and the AI SDK are where most of the agent
   world lives — more examples, more integrations, a bigger hiring pool, and
   Vercel's reach.
-- **Surface breadth and velocity.** More first-party channels and
-  integrations today, with a platform company's release cadence.
+- **Surface breadth and velocity.** More first-party channels, a fuller evals
+  harness, frontend SDKs, session workspaces with file tools, and a platform
+  company's release cadence.
+- **Deferred input while parked.** A message arriving during an approval is
+  held and replayed. Silas currently drops it — the most honest single row on
+  this page, and scheduled work.
 - **Sandboxing posture.** Container sandboxes are integral to eve's design.
   Silas ships an interim Docker seam and reaches microVM-class isolation via
   the [hermetic](https://github.com/danielstpaul/hermetic) gem.
@@ -88,6 +112,6 @@ app's database, that's where the agent belongs.
 
 ---
 
-*Claims about eve come from its docs and source at 0.27.6, quoted or
+*Claims about eve come from its source and docs at 0.27.8, quoted or
 paraphrased in good faith; corrections welcome. Silas's numbers are
 reproducible from `chaos_host/results/`.*

data/docs/why-silas.md

@@ -28,8 +28,8 @@ beside your app — it's a gem inside the Rails app you already deploy:
 
 Every serious framework makes the loop durable. Silas draws the line a step
 past that, and verifies it with a chaos harness that `kill -9`s live agents
-hundreds of times per release (zero duplicate effects, byte-identical replay
-— [guarantees](guarantees.md)):
+mid-turn — a 275-run matrix before each release, zero duplicate effects,
+byte-identical replay ([guarantees](guarantees.md)):
 
 - **Exactly-once tool effects.** A `transactional!` tool's database write and
   the ledger's record of it commit in **one transaction**. A crash mid-refund
@@ -62,10 +62,10 @@ rails new desk -m https://raw.githubusercontent.com/danielstpaul/silas/main/temp
 
 ## The honest notes
 
-- **Silas is early** — 0.5.x, and the guarantees are proven by a reproducible
-  chaos harness rather than years of production traffic. The contract is
-  measured on every release, and it's stated precisely so you know exactly
-  what's promised.
+- **Silas is early** — 0.6.x, and the guarantees are proven by a reproducible
+  chaos harness rather than years of production traffic. The maintainer runs
+  the matrix before each release and commits the results, and the contract is
+  stated precisely so you know exactly what's promised.
 - **Rails-only, on purpose.** If your team lives in TypeScript, eve is
   excellent and closer to home — the [comparison](vs-eve.md) is honest about
   that in both directions.

data/lib/generators/silas/install/install_generator.rb

@@ -1,4 +1,5 @@
 require "rails/generators"
+require "silas/doctor" # ASYNC_QUEUE_REMEDY — one remedy text, two surfaces
 
 module Silas
   module Generators
@@ -125,6 +126,26 @@ module Silas
             9. Restart your server if it was running (app/agent/ registers at boot).
         MSG
       end
+
+      # Rails defaults development to the in-process :async adapter, which the
+      # doctor step above FAILS — without this the documented happy path ends
+      # on a red X. Detected, printed, never written: a gsub against the host's
+      # database.yml no-ops silently the moment they've edited it, and a
+      # force-written cable.yml clobbers whatever Redis config they run.
+      def show_queue_adapter_remedy
+        return unless defined?(::ActiveJob::Base)
+        return unless ::ActiveJob::Base.queue_adapter.class.name.to_s.include?("AsyncAdapter")
+
+        say <<~MSG, :yellow
+
+          Queue adapter: this app is on ActiveJob's in-process :async adapter, and
+          `bin/rails silas:doctor` fails it — :async runs a re-enqueued continuation
+          concurrently with the original, which double-executes steps and breaks
+          exactly-once tool effects.
+
+          #{Silas::Doctor::ASYNC_QUEUE_REMEDY}
+        MSG
+      end
     end
   end
 end

data/lib/generators/silas/install/templates/initializer.rb

@@ -39,6 +39,11 @@ Silas.configure do |config|
   # installed registry (units per 1k tokens; 1e6 units = $1):
   # config.model_prices["your-fine-tune"] = { in: 3000, out: 15_000 }
 
+  # Which agent an inbound Slack thread or email wakes. Unmatched threads wake
+  # the root agent; a name that isn't in app/agents/ fails boot, not a webhook.
+  # config.channel_routes = { "slack" => { "C0BILLING" => "bookkeeper" },
+  #                           "email" => { "billing@example.com" => "bookkeeper" } }
+
   # Where eval scenarios live (bin/rails silas:eval).
   # config.eval_dir = "test/agent_evals"
 end

data/lib/silas/channel.rb

@@ -4,36 +4,110 @@ module Silas
   #
   # Inbound is pure trigger reuse: dispatch maps an external thread to a Session
   # via silas_sessions.channel + continuation_token, then calls the UNCHANGED
-  # public API (new thread -> Silas.agent.start; reply -> session.continue).
+  # public API (new thread -> the routed agent's .start; reply -> continue).
   # Outbound (deliver the agent's answer / an approval request) is a subclass
   # responsibility, invoked off the loop by ChannelDeliveryJob — so the loop's
   # determinism and the ledger's exactly-once are never touched.
   class Channel
     TOKEN_PURPOSE = "silas/channel".freeze
+    # silas_sessions.agent_name for the root app/agent — the column's default,
+    # and the name the loop reads as "no named scope".
+    ROOT_AGENT = "agent".freeze
 
     def self.channel_name = name.demodulize.underscore
 
-    # Stable external-thread key, namespaced by channel so two channels can't collide.
-    def self.namespaced(thread_key) = "#{channel_name}:#{thread_key}"
+    # Stable external-thread key, namespaced by channel AND agent: two channels
+    # can't collide, and two staff members sharing one transport can't either.
+    def self.namespaced(thread_key, agent_name = nil)
+      "#{channel_name}:#{agent_name.presence || ROOT_AGENT}:#{thread_key}"
+    end
+
+    # Tokens minted before routing existed have no agent segment. Every one of
+    # them belongs to the root agent — dispatch could start nothing else — so a
+    # miss on the new form falls back to this one and a live thread upgrades
+    # without losing its session.
+    def self.legacy_namespaced(thread_key) = "#{channel_name}:#{thread_key}"
 
-    # The single inbound entry point for every transport.
-    def self.dispatch(thread_key:, input:, metadata: {})
-      token = namespaced(thread_key)
-      if (session = Silas::Session.find_by(continuation_token: token))
+    def self.find_session(thread_key, agent_name)
+      Silas::Session.find_by(continuation_token: namespaced(thread_key, agent_name)) ||
+        Silas::Session.find_by(continuation_token: legacy_namespaced(thread_key))
+    end
+
+    # The single inbound entry point for every transport. `agent` is the NAME of
+    # the staff member this thread belongs to (nil or "agent" = the root agent);
+    # callers read it off configuration with .route_for.
+    def self.dispatch(thread_key:, input:, metadata: {}, agent: nil)
+      name = resolve_agent(agent)
+      if (session = find_session(thread_key, name))
         session.continue(input: input)
         session
       else
-        Silas.agent.start(input: input, metadata: metadata,
-                          channel: channel_name, continuation_token: token)
+        owner = name ? Silas.agent(name) : Silas.agent
+        owner.start(input: input, metadata: metadata,
+                    channel: channel_name, continuation_token: namespaced(thread_key, name))
       end
     rescue ActiveRecord::RecordNotUnique
       # Concurrent first-inbound race: the other request created the session;
-      # treat this message as a continue.
-      session = Silas::Session.find_by!(continuation_token: namespaced(thread_key))
+      # treat this message as a continue. Nothing to continue means the conflict
+      # was something else, so let it out.
+      session = find_session(thread_key, name) or raise
       session.continue(input: input)
       session
     end
 
+    # ---- routing: which agent an inbound thread wakes -----------------------
+
+    # config.channel_routes, normalised to { transport => { key => agent_name } }.
+    # Keys are matched downcased because email recipients are case-insensitive;
+    # Slack channel ids are unaffected by folding both sides the same way.
+    def self.routes
+      (Silas.config.channel_routes || {}).to_h do |transport, table|
+        [ transport.to_s, table.to_h { |key, agent| [ key.to_s.downcase, agent.to_s ] } ]
+      end
+    end
+
+    # The agent name a thread on `transport` belongs to, or nil for the root
+    # agent. Candidate keys are tried in order and the first match wins, so a
+    # caller holding several (an email's recipients) passes them all.
+    def self.route_for(transport, *keys)
+      table = routes[transport.to_s] or return nil
+
+      keys.flatten.filter_map { |key| table[key.to_s.downcase] }.first
+    end
+
+    # Checked at boot by Registry.install! against the app/agents/ roster. A
+    # route naming an agent that doesn't exist is a deploy failure, not a
+    # runtime one: Silas.agent raises on an unknown name, and discovering that
+    # at dispatch time would strand every future message on the thread.
+    def self.validate_routes!(staff)
+      staff = staff.map(&:to_s)
+      routes.each do |transport, table|
+        table.each do |key, agent|
+          next if agent == ROOT_AGENT || staff.include?(agent)
+
+          raise Error, "config.channel_routes[#{transport.inspect}][#{key.inspect}] routes to " \
+                       "agent #{agent.inspect}, which does not exist" \
+                       "#{staff.any? ? " (known: #{staff.sort.join(', ')})" : " — no app/agents/ directories found"}"
+        end
+      end
+    end
+
+    # nil means the root agent. An unknown name resolves to nil instead of
+    # raising: dispatch runs inside a webhook handler, and a 500 there is a
+    # message Slack retries into its own retry guard and then loses. Boot
+    # already refused a bad route, so this only fires when routes were assigned
+    # after boot — the thread lands on the root agent, exactly where it landed
+    # before routing existed, and the log says so.
+    def self.resolve_agent(name)
+      name = name.to_s
+      return nil if name.empty? || name == ROOT_AGENT
+      return name if Silas.named_agent?(name)
+
+      Rails.logger&.error("[Silas] channel route names unknown agent #{name.inspect}; " \
+                          "starting the root agent instead. Fix config.channel_routes.")
+      nil
+    end
+
     # Resolve the channel instance that owns a session (for outbound delivery).
     def self.for_session(session)
       return nil if session.channel.blank?

data/lib/silas/configuration.rb

@@ -50,9 +50,23 @@ module Silas
     # Channels: name -> Channel subclass (wired by the Registry). Slack creds
     # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
     attr_accessor :channel_resolver
+    # Inbound routing: which named agent an external thread wakes. Data only —
+    # { transport => { key => agent_name } }, where transport is the channel's
+    # filename identity and key is whatever that transport calls a destination:
+    #
+    #   config.channel_routes = {
+    #     "slack" => { "C0BILLING" => "bookkeeper" },
+    #     "email" => { "billing@shop.test" => "bookkeeper" }
+    #   }
+    #
+    # Unmatched threads wake the root agent. Names are checked at boot against
+    # app/agents/ (Registry.install!) — a typo fails the deploy, never a
+    # webhook.
+    attr_accessor :channel_routes
     attr_writer :slack_signing_secret, :slack_bot_token
     # Bind host for the in-process MCP server (Mcp::Server — the "mount your
-    # tools as MCP" seam).
+    # tools as MCP" seam). Inert: nothing outside Mcp::Server's own specs calls
+    # .start, so this setting has no effect until a mounted endpoint ships.
     attr_accessor :mcp_server_host
 
     # Renamed in 0.4, removed in 2.0. "engine" meant two unrelated things —
@@ -134,6 +148,7 @@ module Silas
       @agent_override = nil
       @instructions_dir = nil
       @channel_resolver = nil
+      @channel_routes = {}
       @slack_signing_secret = nil
       @slack_bot_token = nil
       @mcp_server_host = "127.0.0.1"

data/lib/silas/doctor.rb

@@ -10,6 +10,35 @@ module Silas
   class Doctor
     Check = Struct.new(:status, :label, :detail) # status: :pass | :warn | :fail
 
+    # Rails defaults development to :async, which the queue_adapter check below
+    # FAILS — so a stock app fails the doctor the installer told it to run. The
+    # remedy travels with the failure, and the install generator prints this
+    # same constant when it detects :async, so the two surfaces can't drift.
+    # Printed, never written: database.yml and cable.yml belong to the host app.
+    ASYNC_QUEUE_REMEDY = <<~MSG.freeze
+      Add to config/environments/development.rb:
+
+          config.active_job.queue_adapter = :solid_queue
+          config.solid_queue.connects_to = { database: { writing: :queue } }
+
+      and a queue database to config/database.yml (SQLite shown — drop the
+      connects_to line above if Solid Queue shares your primary database):
+
+          development:
+            primary:
+              <<: *default
+              database: storage/development.sqlite3
+            queue:
+              <<: *default
+              database: storage/development_queue.sqlite3
+              migrations_paths: db/queue_migrate
+
+      Then `bin/rails db:prepare`, and run the worker next to the server:
+      `bin/jobs`. On an app that predates Rails 8, `bundle add solid_queue &&
+      bin/rails solid_queue:install` first. For scripts and demos `:inline` is
+      also safe — synchronous, no durability.
+    MSG
+
     def self.run(root: Rails.root) = new(root: root).run
 
     def initialize(root:)
@@ -49,11 +78,15 @@ module Silas
       when /AsyncAdapter/
         Check.new(:fail, "queue adapter",
                   "in-process :async double-executes continuation steps and voids the durability " \
-                  "contract — use :solid_queue (see DEPLOY.md)")
+                  "contract — use :solid_queue (see DEPLOY.md)\n\n#{ASYNC_QUEUE_REMEDY.indent(3).chomp}")
       when /InlineAdapter/
         Check.new(:warn, "queue adapter", "inline — fine for scripts and demos, no durability")
       else
-        Check.new(:warn, "queue adapter", "#{name.demodulize} — durability requires a serializing, DB-backed adapter")
+        Check.new(:warn, "queue adapter",
+                  "#{name.demodulize} — no dead-job rescue path: DeadJobRescuerJob sweeps expired approvals " \
+                  "but returns early unless SolidQueue is defined, so a job killed with its worker is never " \
+                  "retried and a turn stranded mid-tool stays running with its in-doubt invocation unswept. " \
+                  "Durability requires a serializing, DB-backed adapter.")
       end
     end
 

data/lib/silas/registry.rb

@@ -20,6 +20,10 @@ module Silas
       Silas.config.agent_override = nil
       Silas.config.instructions_dir = nil
       Silas.reset_agent_memo!
+      # Boot is the last place a bad channel route can fail safely. Directory
+      # names, not built scopes: validation must not force every named agent's
+      # tools to constantize before anything needs them.
+      Silas::Channel.validate_routes!(registry.named_agent_dirs.map { |dir| File.basename(dir) })
       registry
     end
 
@@ -182,6 +186,13 @@ module Silas
     # identity under const_base, skills, the load_skill builtin when skills
     # exist, run_code when asked, and the scope's own digest (the same
     # NondeterminismError guard root turns get).
+    #
+    # A named agent is a full member of staff: it gets ask_question (parking to
+    # ask a person is the premise, not a root-agent privilege) and the shared
+    # remote connections. Connections live in the root app/agent/connections/ —
+    # one set of credentials for the app, reachable by everyone. Subagents get
+    # neither: they run inside a parent's turn, which is where the human contact
+    # and the remote surface belong.
     def build_agent_scope(dir, name, const_base:, agent: nil, run_code: false, named: false)
       tools = Dir[dir.join("tools/*.rb")].sort.to_h do |file|
         tname = File.basename(file, ".rb")
@@ -193,6 +204,7 @@ module Silas
       end
       skills = Dir[dir.join("skills/*.md")].sort.map { |f| Skill.parse(f) }
       builtins = {}
+      builtins["ask_question"] = Silas::Tools::AskQuestion if named && Silas.config.ask_question
       builtins["load_skill"] = Silas::Tools::LoadSkill if skills.any?
       builtins["run_code"] = Silas::Tools::RunCode if run_code
       if named && Silas.memory_enabled?
@@ -200,8 +212,14 @@ module Silas
         builtins["recall"] = Silas::Tools::Recall
       end
       builtins["handoff"] = Silas::Tools::Handoff if named && named_agent_dirs.size > 1
-      resolver = ->(n) { (tools[n] || builtins.fetch(n)).new }
-      definitions = (tools.values + builtins.values).map(&:schema)
+      remote = connections if named
+      resolver = lambda do |n|
+        klass = tools[n] || builtins[n]
+        return klass.new if klass
+
+        remote&.resolve(n) or raise Error, "unknown tool #{n.inspect} for agent #{name.inspect}"
+      end
+      definitions = (tools.values + builtins.values).map(&:schema) + (remote&.definitions || [])
       loaded_agent = agent || Silas::Agent.load(dir: dir)
       payload = { tools: definitions, skills: skills.map { |s| [ s.name, s.description ] } }
       payload[:final_answer] = loaded_agent.final_answer if loaded_agent.final_answer.present?