silas 0.6.2 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a34eec0f8444f42ef91b1db155bc2786c28ce0de5ed345d9e63b39af9b29756
-  data.tar.gz: 94c9b0464629b6f23eab8f4811e5dd63cdec63d480388cf01c8b0b9111a43376
+  metadata.gz: 8544d250988c08dfa8766c6ccfd512391f91977d301c976b9a11bbdf2120a64d
+  data.tar.gz: 15ff50ad44a2c1357d8b950c7d6bda8a326f6b1b54e4f4cbb1b02c3d2a8f4a1b
 SHA512:
-  metadata.gz: 62c5e530ccc6cfbc3cbfa7b1388b72e53545172acc054b7565930eef56541f8e839846435435585db3fcc3161d40994345b0da5e24fcdc0de1710988efc7ab35
-  data.tar.gz: e8c83c1733efd76810fe2d0cd5e5e57c8b1d929d1a5556d685e376c704108c550494f07e6eb332d6968e458f1bfbb85b5fc024016d1f951dfb1d6a351b6b4683
+  metadata.gz: b14467a4ebbc1001a6e627b2c06d2ee95f1ecb7fdd086fbd39f36061e02325c7910295158d5cfa775f10e1f0f84a09aa0c43167ec5fe4cb0600ecb7dfba8f707
+  data.tar.gz: 32ad0ff55610960130a8427271645a4fe30e264cd9832f14c049d5ee7909165785c62921a235ca80fd81e2746e222ed12534e1a7174bfeec88f2f047b571c473

data/CHANGELOG.md

@@ -1,5 +1,214 @@
 # Changelog
 
+## 0.6.3 (2026-07-29)
+
+Two safety declarations were failing open, and one approval card could be
+spent twice. The rest of the release is the console, the channel layer and the
+docs catching up with what the framework already does.
+
+### Fixed
+
+- **Tool declarations now inherit — a base class silently disarmed both
+  gates.** Ruby does not inherit class-level instance variables, and
+  `Silas::Tool` stored all four of its declarations in them. So the ordinary
+  Rails move of factoring shared declarations into a base class — a `MoneyTool`
+  declaring `transactional!` and `approval :always`, with
+  `class IssueRefund < MoneyTool; end` under it — left `IssueRefund` running at
+  `effect_mode :at_most_once` and `approval :never`: no database transaction
+  around the write, no human gate, no error and no warning. The two
+  declarations the Ledger acts on both failed **open**, into their least safe
+  defaults, and the transcript looked entirely normal. `param` refinements had
+  the same defect, which compounds the string-default trap: a subclass lost its
+  base's `param :amount_pence, :integer`, so the model was told to send a
+  string and any numeric comparison in an approval lambda raised outside the
+  ledger's rescue. Settings now resolve up the ancestry with the nearest
+  explicit declaration winning; param refinements merge down, so a subclass can
+  override one param without dropping the rest. Direct subclasses that declare
+  nothing keep the documented defaults. **If your app has a tool base class,
+  read `YourTool.effect_mode` and `YourTool.approval_policy` in a console
+  before you deploy — that is what those tools have been running as.**
+- **`approve!`, `answer!` and `decline!` are compare-and-swap — one approval
+  could be spent twice.** The guard read in-memory state and the settle paths
+  then wrote with a bare `update!`, so two holders of the same rendered
+  approval card — two people, a double-click, a retried POST — both passed it,
+  both wrote, and both reached `resume_turn!`. Each then found no invocation
+  still `required` and enqueued a fresh `AgentLoopJob`: **one turn ran twice**,
+  two paid model calls, the second minting `tool_call` ids the ledger has never
+  seen and therefore cannot dedup. That is the double-execution the
+  unsafe-queue-adapter boot guard exists to prevent, arriving instead through
+  the approval path — the one path whose entire purpose is to be the safe place
+  a human intervenes. A verdict now settles through an `update_all` scoped to
+  `approval_state "required"` and raises naming the approver who won, rather
+  than silently overwriting a decline with an approval; `resume_turn!` moves
+  the turn out of `waiting`/`in_doubt` with a second compare-and-swap and
+  enqueues only if it won that one, which covers the case a per-invocation
+  claim cannot — two gated invocations on one step, settled concurrently, each
+  legitimately winning its own row and both then seeing no remaining gate.
+  Chaos on the fixed path: worker 25/25 and parked 15/15, all completed, all
+  transcripts byte-identical, zero duplicate side effects.
+- **The installer sent you to a doctor it had already failed.** Rails defaults
+  development to the in-process `:async` queue adapter, and the doctor fails
+  `:async` — correctly, because a re-enqueued continuation runs concurrently
+  with the original there and double-executes steps. The install generator's
+  last words were "then `bin/rails silas:doctor` to verify the whole setup", so
+  the first thing the framework told a new developer was a red X for a
+  condition it knew about before it printed the instruction. The generator now
+  detects the adapter and prints the exact config to paste — printed, never
+  written — and the doctor prints the same text beside the failure, from the
+  same constant, so the two cannot drift. The doctor's unrecognised-adapter
+  branch also stops reading as a style preference: a Sidekiq or GoodJob app is
+  now told what it actually loses, which is `DeadJobRescuerJob` (it returns
+  early unless Solid Queue 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. It stays a warning, and the boot guard stays scoped to
+  `:async`.
+- **Six published claims about the guarantees were false** — all of them in the
+  material a reader uses to decide whether the durability contract can be
+  trusted. Chaos does not run "hundreds of times per release": `ci.yml` has no
+  chaos job and `release.yml` runs only rspec, so the harness is real and
+  reproducible and a human runs it. The matrix is **275 runs**, not 295 —
+  `bin/full_gate` is 100 + 100 + 10 + 10 + 5 + 25 + 25, and `RESULTS.md`'s own
+  table summed to 275 under the inflated total. Handoffs are **at-most-once**,
+  not "exactly-once-guarded"; a crash mid-handoff parks in doubt for a person.
+  `Silas::Mcp::Server` was documented as a shipped seam when nothing outside
+  its specs calls `.start`, so an app cannot turn it on at all — the code stays
+  because a mounted endpoint is the planned shape, and both pages now say it is
+  not wired up. Two pages still read 0.5.x. `guarantees.md` also told readers
+  the gate figures were the last batch in each results file: `results/*.jsonl`
+  is append-only and every per-change run appends to it, so the last batch is
+  whatever ran most recently. The page now says what is true — batches start
+  where `run` restarts at 1, no field marks which one was a gate, and
+  `chaos_host/RESULTS.md` is the record — and the rows stay unedited, including
+  the inconvenient ones. `CONTRIBUTING.md` promised the chaos gate only "where
+  the loop changed" against four published pages promising the full gate before
+  every release; it now matches the public promise.
+- **The README's `IssueRefund` example never declared its integer param.** Param
+  types default to string, so the model was told to send `"6400"` and the
+  example's own `input[:amount_pence] > 2_500` raised `ArgumentError` — inside
+  `approval_verdict`, outside `run_tool!`'s rescue, which kills the loop job
+  and (in development, where no rescuer is scheduled) strands the turn in
+  `running` with no diagnostic. `docs/tools.md`, the skill and
+  `templates/desk.rb` all had it right; the one place it was missing was the
+  most-copied snippet in the project.
+- **`docs/headless.md` named a scope helper that does not exist** (`with_scope`
+  for `Silas.with_agent_scope`) and suggested `Session.where(status: "waiting")`
+  — `waiting` is a turn status, and a session query for it validates fine and
+  silently returns nothing. Corrected to the approval queue and parked turns,
+  with both vocabularies named so the trap is visible rather than inferred.
+- **A named agent asking for a tool it doesn't have raised a bare `KeyError`.**
+  It now raises `Silas::Error` naming both the tool and the agent, which is
+  what the operator needs to see in the log.
+
+### Upgrading
+
+- **Settle parked turns for your named agents before deploying this.** Named
+  agents gain `ask_question` and the connection tools (below), and adding tools
+  to a scope changes that scope's definitions digest — the nondeterminism guard
+  refuses to resume a turn against a different agent than the one that started
+  it. A turn parked under a named agent — waiting on an approval, a question,
+  or an in-doubt call — is failed with `definitions_changed` when it wakes after
+  the upgrade, not resumed. Clear the inbox for each named agent and let those
+  turns finish first. Root-agent and subagent digests are unchanged, so their
+  parked turns are unaffected.
+
+### Added
+
+- **Channels route to named staff.** `Silas::Channel.dispatch` hardcoded
+  `Silas.agent.start` and neither first-party caller could say otherwise, so
+  every Slack thread and every email woke the root agent: an app could employ
+  staff with their own tools, instructions and cron and still had no way to
+  send `#billing` or `billing@` to the bookkeeper. `config.channel_routes` maps
+  a transport-specific key to an agent name
+  (`{"slack" => {"C0BILLING" => "bookkeeper"}}`); unmatched threads wake the
+  root agent, so nothing changes for an app that sets nothing. Routes are
+  checked at boot against the `app/agents/` roster — a typo fails the deploy
+  and names the staff that do exist, rather than raising inside a webhook,
+  where Slack retries, the retry guard drops the retry, and the message is
+  gone. The continuation token now carries the agent as well as the channel
+  (`slack:bookkeeper:C1:ts`), and a lookup that misses the new form falls back
+  to the old one, so a live thread keeps the session — and the agent — it
+  already had. Only new threads route.
+- **Named agents get `ask_question` and the remote connections.** A named
+  agent (`app/agents/<name>/`) is staff, not a lesser agent: it can park to
+  ask a person, and it can reach the MCP tools declared in
+  `app/agent/connections/` — one set of credentials for the whole app,
+  resolved the same way the root agent resolves them. Its scope was built by
+  the same builder subagents use, which grants only `load_skill`, `run_code`,
+  `remember`, `recall` and `handoff` — so the member of staff woken by its own
+  Slack channel or email address was structurally the one that could not stop
+  and ask, in a framework whose premise is that a turn parks for days waiting
+  on a human. And the remote credentials are the app's, not the root agent's,
+  yet only the root agent could spend them. `config.ask_question` governs the
+  builtin exactly as it governs the root agent. `delegate` stays root-only:
+  subagents belong to the root agent's turn.
+- **`docs/headless.md` — Silas without the inbox.** The inbox is a mountable
+  engine, not a requirement, and nothing said so. The page names the pattern —
+  drive `approve!`/`decline!`/`answer!` from your own controllers, since the
+  inbox, the JSON API, the Slack controller and the signed email links are four
+  callers of the same three `ToolInvocation` methods — and what you take on
+  instead of pretending it is free: rendering model-authored arguments, your
+  own authorization, live updates (the engine's broadcast targets are internal,
+  not a contract), and the real coupling, which is that
+  `Channel.approval_url` mints links against `Engine.routes`. It also covers
+  `Silas.with_agent_scope` for apps whose capabilities vary per user or tenant,
+  with the two constraints that bite: connection credentials are paths into the
+  app's own credentials rather than per-end-user OAuth tokens, and changing an
+  agent's capabilities fails its parked turns loudly on resume — while teaching
+  it facts does not, because memory is not in the definitions digest.
+- **The console accounts for a handoff.** `Session` has carried
+  `parent_session` and `child_sessions` since 0.5 and the JSON API serializes
+  both, but no view read either — so the one relationship a multi-agent
+  framework exists to express appeared in the inbox as a new row with a
+  different agent's name, no explanation and no route back to the session that
+  started it. Three places state it now: a child session names the agent that
+  handed over and links to its session, the call that made a child renders that
+  child in the feed at the point it happened (with its agent and its turn's
+  state), and the index marks child rows with the parent's agent, so a row that
+  read as a stray reads as the second half of a handoff. The pairing is
+  recovered from `session_id` in the handoff's own result and accepted only
+  when that session's parent is the calling session — `session_id` is a
+  plausible key for any tool to return, and a lineage line that is merely
+  probably true is worse than none. `handoff` is at-most-once, so a crash
+  between `Session.create!` and the result leaves a colleague started with
+  nothing in the trace naming it; those children are listed under the feed
+  rather than dropped.
+- **A render-side test for every live-update target.** Turbo addresses an
+  element that must already be on the page: broadcast to an id no view renders
+  and nothing raises, nothing logs, nothing updates — the trace stops moving
+  while every spec stays green. That is exactly how 0.6.1's held-pill bug
+  shipped, and seven of the ten targets had never been checked against a real
+  render. Each is now pinned to the partial that must render it, the five
+  `replace` targets additionally to that partial's root element (the only shape
+  that survives a swap), and the contract runs backwards too — every
+  broadcasting transition is driven with the seam captured and the emitted set
+  held to the nine covered — so a target added with no view to receive it fails
+  as well.
+
+### Changed
+
+- **The session page shows what the agent did, not the trace.** Every tool call
+  rendered identically — name, status pill, a key/value table of arguments, a
+  disclosure around the result — so a read that returned a row and a
+  transactional write that moved money carried the same weight, and the
+  sentence an operator came for had to be reassembled from the parts on every
+  row. Each invocation is now one line: `issue_refund · order #4821 · GBP 64.00
+  → approved by Dana · refunded`, with arguments and result behind the
+  disclosure. Salience comes from effect mode, the property that says whether a
+  row mattered: an idempotent call that worked is furniture, `at_most_once` is
+  loud, and `transactional` earns the heaviest rule on the page, because its
+  write and its ledger row commit together. A failure is loud whatever it
+  touched, and so is anything still owing a person a verdict. Both readings
+  ship in the DOM with a checkbox choosing between them in CSS — a broadcast
+  render has no params and no reader to ask, so a choice baked into the render
+  would snap back on the first replace. A settled turn also states its own
+  audit: when it was asked, where it stands, how many tools ran and how many of
+  them wrote. Three absences now say so out loud instead of showing as gaps — a
+  turn that called no tools, a completed step that produced neither text nor a
+  call, and a tool that returned nothing — because an unexplained hole in a
+  feed reads as a rendering bug. `running` reads **WORKING** in the pill, the
+  same word the index rail's Working group uses for the same turn; the database
+  strings and the JSON API are untouched.
+
 ## 0.6.2 (2026-07-26)
 
 The providers guide and the remaining community files.

data/README.md

@@ -75,6 +75,7 @@ Create a tool at `app/agent/tools/issue_refund.rb` — the keyword signature
 ```ruby
 class Agent::Tools::IssueRefund < Silas::Tool
   description "Refund part or all of an order."
+  param :amount_pence, :integer, desc: "Amount in pence (1800 = £18.00)"
   approval ->(session:, input:) { input[:amount_pence] > 2_500 ? :user_approval : :approved }
   transactional!   # DB effect + ledger commit atomically -> exactly-once
 
@@ -95,8 +96,9 @@ bin/rails silas:chat
 Refunds over £25 hold for a person — in the operator inbox the gem mounts at
 `/silas/inbox`, in Slack, or over the JSON API — and approving resumes the
 turn exactly where it stopped, with exactly one refund row in your database.
-How that's guaranteed (and verified with a `kill -9` chaos harness on every
-release): [guarantees](https://danielstpaul.github.io/silas/guarantees).
+How that's guaranteed — and verified by a `kill -9` chaos harness run before
+each release, results committed under `chaos_host/results/`:
+[guarantees](https://danielstpaul.github.io/silas/guarantees).
 
 ## Status
 

data/app/controllers/silas/channels/slack_controller.rb

@@ -17,6 +17,8 @@ module Silas
           thread_key = "#{params[:team_id]}:#{event[:channel]}:#{event[:thread_ts] || event[:ts]}"
           channel_class.dispatch(
             thread_key: thread_key, input: event[:text].to_s,
+            # Which staff member owns this Slack channel (nil -> the root agent).
+            agent: Silas::Channel.route_for("slack", event[:channel]),
             metadata: { "slack" => { "channel" => event[:channel],
                                      "thread_ts" => event[:thread_ts] || event[:ts],
                                      "user" => event[:user] } }

data/app/controllers/silas/inbox/sessions_controller.rb

@@ -22,7 +22,9 @@ module Silas
 
         # One query for the rows + turns, one for the pending counts — the
         # per-row active_turn/turns.last/counts pattern was ~4 queries a card.
-        @sessions = scope.limit(PER_PAGE).includes(:turns).to_a
+        # parent_session rides along for the lineage line: every child row
+        # names the agent that handed to it, and that must not cost a query.
+        @sessions = scope.limit(PER_PAGE).includes(:turns, :parent_session).to_a
         @next_before = @sessions.last&.id if @sessions.size == PER_PAGE
         @pending_counts = Silas::ToolInvocation.joins(:turn)
                                                .where(approval_state: "required",

data/app/helpers/silas/inbox/trace_helper.rb

@@ -18,8 +18,10 @@ module Silas
       # UI-only relabels — the database strings and the JSON API are untouched
       # (an operator who reads "held" here and greps the API will find
       # `waiting`; docs name both). Safety-system vocabulary: a turn is held
-      # at the signal until a person clears it.
-      UI_LABEL = { "waiting" => "held", "completed" => "clear" }.freeze
+      # at the signal until a person clears it. `running` reads WORKING so the
+      # pill and the rail's Working group say the same word about the same
+      # turn; the disclosure on every tool row prints the raw enum.
+      UI_LABEL = { "waiting" => "held", "running" => "working", "completed" => "clear" }.freeze
 
       def status_label(status)
         UI_LABEL[status.to_s] || status.to_s.tr("_", " ")
@@ -52,6 +54,226 @@ module Silas
         end
       end
 
+      # ---- the feed ----------------------------------------------------
+      #
+      # One invocation, one sentence: what ran, on what, how it ended.
+      #
+      #   issue_refund · order #4821 · GBP 64.00 → held for approval
+      #   issue_refund · order #4821 · GBP 64.00 → approved by Dana · refunded
+      #
+      # Everything these return is PLAIN TEXT. Arguments and results are
+      # model-authored, so they reach the page only through ERB's escape —
+      # nothing here may be marked html_safe.
+
+      # A verdict outranks the status it wrote: `decline!` sets status=failed,
+      # but a person refusing is not a crash and must not read like one.
+      INVOCATION_STATE = {
+        "pending" => "working", "started" => "working", "completed" => "clear",
+        "failed" => "failed", "in_doubt" => "in_doubt"
+      }.freeze
+
+      STATE_ASPECT = {
+        "held" => "amber", "working" => "blue", "clear" => "green", "failed" => "red",
+        "declined" => "red", "expired" => "quiet", "in_doubt" => "violet"
+      }.freeze
+
+      # The states are settled quietly ONLY here; every other state either
+      # needs a person or lost one.
+      SETTLED_QUIETLY = %w[clear working].freeze
+
+      MONEY_KEYS = %w[amount total price subtotal].freeze
+      CURRENCY_KEYS = %w[currency currency_code].freeze
+
+      def invocation_state(invocation)
+        return "held" if invocation.awaiting_approval?
+        return invocation.approval_state if %w[declined expired].include?(invocation.approval_state)
+
+        INVOCATION_STATE.fetch(invocation.status, invocation.status)
+      end
+
+      def invocation_state_class(invocation)
+        "deed-#{STATE_ASPECT.fetch(invocation_state(invocation), 'quiet')}"
+      end
+
+      # Salience. A read that worked is furniture; a tool that moved money or
+      # sent a message is not, and neither is anything a person still owes a
+      # verdict on. A FAILED read is loud too — having no effect doesn't make
+      # a failure quiet. `idempotent` is the mode a tool declares when it only
+      # reads; `transactional` is the one whose write and ledger row commit
+      # together, and it gets the heaviest rule on the page.
+      def invocation_weight(invocation)
+        return "deed-exact" if invocation.effect_mode == "transactional"
+        return "deed-loud" unless SETTLED_QUIETLY.include?(invocation_state(invocation))
+
+        invocation.effect_mode == "idempotent" ? "deed-quiet" : "deed-loud"
+      end
+
+      def invocation_outcome(invocation)
+        state = invocation_state(invocation)
+        case state
+        when "held"     then invocation.question? ? "held for an answer" : "held for approval"
+        when "working"  then "working"
+        when "in_doubt" then "in doubt — nobody knows whether it ran"
+        when "declined" then declined_phrase(invocation)
+        when "expired"  then invocation.question? ? "expired — nobody answered" : "expired — nobody cleared it"
+        else [ verdict_phrase(invocation), result_or_failure_phrase(invocation, state) ].compact.join(" · ")
+        end
+      end
+
+      # The middle of the sentence: enough of the call to recognise the job
+      # without opening anything. Non-scalars are left out — a nested hash
+      # flattened onto one line is noise — and wait in the disclosure.
+      def invocation_arg_phrases(invocation, limit: 3)
+        args = invocation.arguments
+        return [] unless args.is_a?(Hash) && args.any?
+
+        merged, phrases = money_phrase(args)
+        args.each do |key, value|
+          break if phrases.size >= limit
+          next if merged.include?(key.to_s) || !scalar_arg?(value)
+
+          phrases << arg_phrase(key.to_s, value)
+        end
+        phrases
+      end
+
+      # "GBP 64.00" is what an operator scans a refund line for; as two
+      # separate phrases the currency and the number sit apart and neither
+      # reads as money. Returns [keys consumed, phrases].
+      def money_phrase(args)
+        currency = args.find { |k, v| CURRENCY_KEYS.include?(k.to_s) && v.to_s.match?(/\A[A-Za-z]{3}\z/) }
+        amount = args.find { |k, v| MONEY_KEYS.include?(k.to_s) && v.is_a?(Numeric) }
+        return [ [], [] ] unless currency && amount
+
+        [ [ currency[0].to_s, amount[0].to_s ], [ format("%s %.2f", currency[1].to_s.upcase, amount[1]) ] ]
+      end
+
+      # `order_id: 4821` reads as "order #4821". A bare flag reads as itself:
+      # "dry run" beats "dry run true", and "no dry run" beats "dry run false".
+      def arg_phrase(key, value)
+        return "#{key.delete_suffix("_id").tr("_", " ")} ##{value}" if key.end_with?("_id")
+
+        label = key.tr("_", " ")
+        return label if value == true
+        return "no #{label}" if value == false
+
+        "#{label} #{value.to_s.truncate(48)}"
+      end
+
+      # What came back. A tool that returned nothing SAYS so — the absence is
+      # a fact about the run, not a gap in the sentence.
+      def invocation_result_phrase(invocation)
+        result = invocation.result
+        return "returned nothing" if result.nil? || result == {} || result == ""
+        return result.to_s.truncate(48) unless result.is_a?(Hash)
+
+        key, value = result.find { |_k, v| scalar_arg?(v) }
+        key ? arg_phrase(key.to_s, value) : "#{result.size} #{"field".pluralize(result.size)} returned"
+      end
+
+      # Where the turn stands, in the words the pill has no room for. Never
+      # says "waiting": the enum is `waiting`, the operator's word is HELD.
+      def turn_progress(turn)
+        case turn.status
+        when "queued"    then "queued for a worker"
+        when "running"   then "working now"
+        when "waiting"   then "held — a person is needed"
+        when "in_doubt"  then "in doubt — a tool crashed mid-call"
+        when "canceled"  then "stopped before it finished"
+        when "failed"    then turn.failure_reason.present? ? "failed — #{turn.failure_reason}" : "failed"
+        when "completed" then turn.finished_at ? "answered #{silas_relative_time(turn.finished_at)}" : "answered"
+        else status_label(turn.status)
+        end
+      end
+
+      # A settled turn's one-line audit: how much ran, and how much of it
+      # wrote. Reads off the loaded steps so the session page adds no queries.
+      def turn_effects_summary(turn)
+        invocations = turn.steps.flat_map(&:tool_invocations)
+        return "no tools ran — answered directly" if invocations.empty?
+
+        wrote = invocations.count { |i| i.effect_mode != "idempotent" && i.status == "completed" }
+        "#{pluralize(invocations.size, "tool")} · #{wrote.zero? ? "nothing written" : "#{wrote} wrote"}"
+      end
+
+      # ---- lineage -----------------------------------------------------
+      #
+      # A handoff or a delegation starts a SECOND session. Nothing on the child
+      # points back at the call that made it — the only link is the invocation
+      # result — so the feed recovers the pair from there, and the child's
+      # metadata says which of the two it was.
+
+      LINEAGE_FROM = { "handoff" => "handed over by", "delegation" => "delegated by" }.freeze
+      LINEAGE_TO   = { "handoff" => "handed to", "delegation" => "delegated to" }.freeze
+
+      def lineage_relation(child)
+        meta = child.metadata
+        return nil unless meta.is_a?(Hash)
+        return "handoff" if meta.key?("handoff_from")
+
+        "delegation" if meta.key?("delegated_from")
+      end
+
+      def lineage_from_phrase(child) = LINEAGE_FROM.fetch(lineage_relation(child), "started by")
+      def lineage_to_phrase(child)   = LINEAGE_TO.fetch(lineage_relation(child), "started")
+
+      def invocation_child_session(invocation)
+        result = invocation.result
+        return nil unless result.is_a?(Hash) && result["session_id"].present?
+
+        child = Silas::Session.find_by(id: result["session_id"])
+        # Any tool may return a key called `session_id` meaning something of its
+        # own. Only a session whose parent IS this call's session was started
+        # by this call.
+        child if child && child.parent_session_id == invocation.turn.session_id
+      end
+
+      # Children the feed has no place for. An at_most_once handoff that
+      # crashes after Session.create! records no result, so the call that made
+      # the child names nothing — without this the child is visible only from
+      # the index, which is the orphan the lineage work exists to end.
+      def stranded_child_sessions(session, turns)
+        placed = turns.flat_map(&:steps).flat_map(&:tool_invocations).filter_map do |i|
+          i.result["session_id"].to_i if i.result.is_a?(Hash) && i.result["session_id"].present?
+        end
+        session.child_sessions.reject { |child| placed.include?(child.id) }
+      end
+
+      # The turn a session is judged by: the one in flight, else the last one
+      # to settle. Reads off the loaded association — the index depends on that.
+      def session_state_turn(session)
+        session.turns.detect(&:active?) || session.turns.last
+      end
+
+      def scalar_arg?(value)
+        case value
+        when String then value.present?
+        when Numeric, true, false then true
+        else false
+        end
+      end
+
+      def verdict_phrase(invocation)
+        case invocation.approval_state
+        when "approved"
+          invocation.approved_by.present? ? "approved by #{invocation.approved_by}" : "auto-approved by policy"
+        when "answered"
+          invocation.approved_by.present? ? "answered by #{invocation.approved_by}" : "answered"
+        end
+      end
+
+      def declined_phrase(invocation)
+        who = invocation.approved_by.present? ? "declined by #{invocation.approved_by}" : "declined"
+        invocation.decline_reason.present? ? "#{who} — “#{invocation.decline_reason}”" : who
+      end
+
+      def result_or_failure_phrase(invocation, state)
+        return "failed — #{invocation.error.to_s.lines.first.to_s.strip.truncate(72).presence || "no reason recorded"}" if state == "failed"
+        return nil if invocation.approval_state == "answered" # the answer IS the result
+
+        invocation_result_phrase(invocation)
+      end
+
       # Prefixed: this helper is registered host-wide (broadcast renders need
       # it), and "relative_time" is exactly the name a host app would define.
       def silas_relative_time(time)

data/app/mailboxes/silas/agent_mailbox.rb

@@ -9,6 +9,10 @@ module Silas
       channel_class.dispatch(
         thread_key: self.class.thread_key(mail),
         input: body_text,
+        # Which staff member was written to (nil -> the root agent). Every
+        # recipient is a candidate — To, Cc, and the forwarding headers Action
+        # Mailbox's own routing matches on — first route wins.
+        agent: Silas::Channel.route_for("email", mail.recipients),
         metadata: { "email" => { "from" => mail.from&.first, "subject" => mail.subject } }
       )
     rescue Silas::TurnInProgressError

data/app/models/silas/tool_invocation.rb

@@ -44,7 +44,7 @@ module Silas
       end
       assert_parked!
       assert_turn_resumable!
-      update!(status: "pending", approval_state: "approved", approved_by: by)
+      claim_verdict!(status: "pending", approval_state: "approved", approved_by: by)
       Silas.instrument(:approval, action: "approved", tool: tool_name, by: by,
                                   invocation_id: id, turn_id: turn_id)
       resume_turn!
@@ -60,8 +60,8 @@ module Silas
 
       assert_parked!
       assert_turn_resumable!
-      update!(status: "completed", approval_state: "answered", approved_by: by,
-              result: { "answer" => text })
+      claim_verdict!(status: "completed", approval_state: "answered", approved_by: by,
+                     result: { "answer" => text })
       Silas.instrument(:approval, action: "answered", tool: tool_name, by: by,
                                   invocation_id: id, turn_id: turn_id)
       resume_turn!
@@ -74,8 +74,8 @@ module Silas
     def decline!(reason:, by: nil)
       assert_parked!
       assert_turn_resumable!
-      update!(status: "failed", approval_state: "declined", approved_by: by,
-              decline_reason: reason, result: { "denied" => reason })
+      claim_verdict!(status: "failed", approval_state: "declined", approved_by: by,
+                     decline_reason: reason, result: { "denied" => reason })
       Silas.instrument(:approval, action: "declined", tool: tool_name, by: by,
                                   invocation_id: id, turn_id: turn_id)
       resume_turn!
@@ -102,6 +102,27 @@ module Silas
       raise Error, "invocation #{id} is not awaiting approval (state: #{approval_state.inspect})"
     end
 
+    # A verdict is a state TRANSITION, not a write. `assert_parked!` reads
+    # in-memory state, so without a compare-and-swap two holders of the same
+    # rendered approval card — two people, a double-click, a retried POST —
+    # both pass it, both write, and both reach `resume_turn!`. Two fresh
+    # AgentLoopJobs then run one turn concurrently: two paid model calls, and
+    # the second mints tool_call ids the ledger has never seen and therefore
+    # cannot dedup. That is precisely the double-execution `warn_unsafe_queue_
+    # adapter!` refuses to allow the Async adapter to cause, arriving instead
+    # through the approval path — the one path whose entire purpose is to be
+    # the safe place a human intervenes. Claim the row, or lose loudly.
+    def claim_verdict!(attrs)
+      claimed = self.class.where(id: id, approval_state: "required")
+                    .update_all(attrs.merge(updated_at: Time.current))
+      if claimed.zero?
+        reload
+        raise Error, "invocation #{id} was already settled (state: #{approval_state.inspect}, " \
+                     "by: #{approved_by.inspect}) — another verdict won the race"
+      end
+      reload
+    end
+
     # A failed turn must never be zombie-resumed by a stale approval card:
     # force-fail paths expire approvals first, but a card already rendered in
     # someone's browser can still POST — the verdict must land on a live turn.
@@ -123,7 +144,17 @@ module Silas
       # point is waiting for a person. Cost/token budgets stay cumulative;
       # they measure real spend.
       parked_for = turn.updated_at ? (Time.current - turn.updated_at).to_f : nil
-      turn.update!(status: "queued", started_at: Time.current)
+      # Second CAS, for the case a per-invocation claim cannot cover: two gated
+      # invocations on one step, settled concurrently. Both verdicts legitimately
+      # win their own row, both then see no remaining gate above, and both would
+      # enqueue. Only the verdict that actually moves the turn out of a parked
+      # status resumes it.
+      claimed = Silas::Turn.where(id: turn.id, status: %w[waiting in_doubt])
+                           .update_all(status: "queued", started_at: Time.current,
+                                       updated_at: Time.current)
+      return if claimed.zero?
+
+      turn.reload
       Silas.instrument(:resume, turn_id: turn.id, parked_for: parked_for)
       AgentLoopJob.perform_later(turn.id)
     end