roundhouse_ui 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 913330ea311e66bcb5eb717852a73c0c4eb51a281acbd5899fac33f623b609a2
-  data.tar.gz: 8fdaff5a284e27d7df7a63ade47294f9d5f156a14e9133f7a40a24ca194ad828
+  metadata.gz: 709f9a555e5768ad93fbacf4c18ba986bf853f0ccaf877181b8f2ad5336c45d7
+  data.tar.gz: f8c74c04bf68a45260fb0a65811b3f33ba010afbe38bb380892c651552ef544f
 SHA512:
-  metadata.gz: ae78d8ec53e92eaac58308a7701abfc11f71ad2d89f1ffe05b40611df458a6121a97f831d16770dfb0f9d37a3bdffe50905498bba41e7c86c7b74fe4bbc211d3
-  data.tar.gz: 446a6fa76c6f2cf70f2b3ec5e83d5eb06dbe6e6a393bebfab7414f3bd1e87d8fa96c6bf9ae180c284e2ae50e63ee1e1f3516a827591ab58d686fccdd8ebaf195
+  metadata.gz: cf31556bd89ae68aef4c795e9f5d681884b4ace00ab9b4fa70944d4fb9527cd5a065afa80c125ddfd21721e267918654188d727248e242e0e86d2a6ad3954382
+  data.tar.gz: 3721a96a24483cd9def146b5ae10600320ffac4890a662d722bef8bc9ffa9f1e265b6039081ae47e7a8d35d6a0abf4bda3b49c0faade22783deb8766b169794b

data/README.md

@@ -107,32 +107,59 @@ RoundhouseUi.configure do |c|
   # No-op unless the sidekiq-failures gem is loaded. Default: off.
   c.show_sidekiq_failures = true
 
-  # Set false to hide queue pause/resume controls and the "not enforced" warning,
-  # e.g. when you run reliable fetch (super_fetch) instead of RoundhouseUi::Fetch.
-  # Default: true.
+  # Set false to hide queue pause/resume controls entirely. Rarely needed — on
+  # Sidekiq Pro and Solid Queue pause is enforced natively, and on OSS Sidekiq
+  # installing RoundhouseUi::Fetch enforces it. Default: true.
   # c.pause_enabled = false
 
+  # Surface your own labels (owning team, tenant, …) on job rows, the job page,
+  # and grouped errors — and filter by them. See "Job tags" below.
+  # c.job_tags = RoundhouseUi::Tags.from_constant(:OWNER, as: :squad)
+
   # Seconds between dashboard stat polls (default 5). Raise it if polling shows
   # up in your traces — each poll re-runs the host's auth/routing on the mount.
   # c.poll_interval = 10
 
-  # Show the "slowest job classes" table on the Metrics page. Requires the
-  # DurationCollector middleware (see below). Default: false.
+  # Show the "slowest job classes" table on the Metrics page. The flag alone shows
+  # nothing — it also needs the DurationCollector middleware (see below).
+  # Default: false.
   # c.collect_durations = true
 end
 ```
 
-Every option is independent and has a safe default — set only what you need.
-`read_only`, `allow_job_editing`, and `show_sidekiq_failures` default to `false`;
-`redact_args` to `[]`; `observability` to a no-op adapter; `snapshot_store` to Redis.
+Every option is independent and has a safe default — **set only what you need**. Nothing
+here is required to mount Roundhouse.
+
+### When to turn each one on
+
+| Option | Default | Turn it on when | Leave it alone when |
+|---|---|---|---|
+| `read_only` | `false` | **Production, almost always.** Blocks purge/retry/delete/edit *server-side*, not just in the UI — so it holds even if someone hand-crafts a request. The usual shape is `!Rails.env.development?`. | You need operators to actually fix things from the UI, and you trust everyone behind the mount. |
+| `redact_args` | `[]` | **Any app whose job args carry secrets or PII** — args render in full on the job page. Matches keys case-insensitively as substrings, and walks nested hashes/arrays. | Args are all IDs and enum values. |
+| `actor_resolver` | `"anonymous"` | You want the audit log to name *who* did something. One line: `->(c) { c.current_user&.email }`. | Single-operator app, or you already audit at another layer. |
+| `allow_job_editing` | `false` | Development and debugging. **Sharp tool** — a bad edit creates an unrunnable job, and it lets the UI enqueue arbitrary classes. | Production, unless you specifically want that power and have `read_only` off anyway. |
+| `observability` | no-op | You run an APM and want per-job deep links out to it. Ships a Datadog adapter; duck-type `job_url`/`queue_url`/`error_url` for anything else. | No APM, or you'd rather not add links that only some people can open. |
+| `snapshot_store` | Redis | Your snapshots are large or need to outlive Redis (S3/disk). Duck-type `write`/`read`/`delete`/`ids`. | Redis is fine — which it usually is for occasional queue snapshots. |
+| `show_sidekiq_failures` | `false` | You use the `sidekiq-failures` gem **and** run jobs with `retry: false` — those never enter Sidekiq's retry/dead sets, so this is the only way to see them. | You don't have the gem (it's a no-op then anyway). |
+| `poll_interval` | `5` | **Raise it** if dashboard polling shows up in your traces — every poll re-runs your app's auth and routing on the mount, so a busy console adds real load. Lower it only for a livelier demo. | Default is fine for most apps. |
+| `collect_durations` | `false` | You want "slowest job classes" on Metrics, which Sidekiq doesn't track. **Also requires installing the `DurationCollector` middleware** — the flag alone shows nothing. Costs one pipelined Redis round-trip per job. | You already get per-job timing from your APM. |
+| `job_tags` | `nil` | You already know which team, tenant or product area owns a job — usually as a constant on the class — and want that visible and filterable in the UI. See [Job tags](#job-tags). | Every job belongs to the same team. |
+| `job_tags_per_job` | `false` | **Only** when `job_tags` reads the payload (tagging by tenant, account, …). Costs one resolver call per row rather than one per class. | Tags derive from the job class, which is the common case. |
+| `tag_filters` | `nil` | You want stable filter dropdowns instead of ones that only list what happens to be on screen — and want filtering on an unknown key to match nothing. | The `?tag=` URL is enough. |
+| `pause_enabled` | `true` | Leave it on. | **Rarely set this to `false`.** Pause is enforced natively on Sidekiq Pro and Solid Queue, and on OSS Sidekiq by installing `RoundhouseUi::Fetch` — so turning it off usually just hides a working feature. Only useful if you want the controls gone entirely. |
+
+Two that pair with a middleware rather than working alone: `collect_durations`
+(`DurationCollector`) and job cancellation (`CancelMiddleware`) — see
+[Cancelling jobs](#cancelling-jobs) and [Slowest job classes](#slowest-job-classes).
 
 ## Pausing queues
 
-> On **Solid Queue**, pause is **native** — it's enforced by the backend, so there's
-> nothing to install and no warning. The rest of this section is Sidekiq-only.
+> Pause is **native** — enforced with nothing to install and no warning — on both
+> **Solid Queue** and **Sidekiq Pro/Enterprise** (see below). The fetch strategy
+> below is only needed on **OSS Sidekiq**.
 
-On Sidekiq, pause/resume is pure OSS. To make a pause actually stop a queue from being
-worked, install Roundhouse's fetch strategy in your Sidekiq **server** config:
+On OSS Sidekiq, pause/resume is pure OSS. To make a pause actually stop a queue from
+being worked, install Roundhouse's fetch strategy in your Sidekiq **server** config:
 
 ```ruby
 # config/initializers/sidekiq.rb
@@ -146,11 +173,80 @@ all of Sidekiq's weighting/ordering. Until it's installed, the Queues page recor
 but **warns that they aren't enforced** (worker and web are separate processes, so
 Roundhouse detects whether a fetcher has reported in).
 
-> ⚠️ **Sidekiq Pro/Enterprise users:** super_fetch / reliable fetch sets its own
-> `fetch_class`, and Sidekiq allows only one. Installing `RoundhouseUi::Fetch` would
-> **replace reliable fetch and lose its crash-recovery guarantees** — don't. On those
-> tiers, leave the fetch strategy out and set `RoundhouseUi.pause_enabled = false` to
-> hide the pause controls and the (otherwise permanent) "not enforced" warning.
+### Sidekiq Pro / Enterprise — nothing to install
+
+Pro ships its own enforced pause, and Roundhouse uses it automatically. Pro reopens
+`Sidekiq::Queue` with `pause!`/`unpause!` and *prepends* pause support onto
+`Sidekiq::BasicFetch` (`super_fetch` honors it too), so **any Pro worker enforces
+pauses** whether or not a fetch strategy is configured.
+
+When Roundhouse detects Pro it delegates pause/resume to `Sidekiq::Queue#pause!`,
+reads paused state from Pro's registry, advertises `native_pause`, and drops the
+"not enforced" warning. So on Pro:
+
+- **Don't** install `RoundhouseUi::Fetch` — it isn't needed, and on `super_fetch`
+  installs it would displace reliable fetch and lose its crash-recovery guarantees.
+- **Don't** set `pause_enabled = false` — pause genuinely works; disabling it only
+  hides a feature you already have.
+
+Roundhouse always goes through `Sidekiq::Queue#pause!` rather than writing Pro's
+Redis key directly: Pro's fetchers read that set once at startup and afterwards
+only update on the `pro:config` pubsub message `pause!` publishes, so a raw write
+would leave running workers pulling the queue until they restarted.
+
+## Job tags
+
+Most apps already know who owns a job — commonly a constant on the class. Point
+Roundhouse at it and that label shows up as a badge on Retries, Dead, Scheduled, the
+job detail page and grouped Errors, and becomes a filter.
+
+```ruby
+# config/initializers/roundhouse.rb
+RoundhouseUi.job_tags = RoundhouseUi::Tags.from_constant(:OWNER, as: :squad)
+```
+
+That's the whole setup for the `OWNER = :growth` convention — every class defining the
+constant (including by inheritance) is tagged. Any callable works if your labels come
+from somewhere else:
+
+```ruby
+RoundhouseUi.job_tags = ->(klass:, item:) {
+  { squad: OwnershipMap.for(klass), tier: klass.end_with?("CriticalJob") ? "p1" : "p3" }
+}
+```
+
+Tags are resolved **when a page renders** — no middleware, no enqueue changes, nothing
+stored. They apply retroactively to jobs already sitting in the sets, and work the same
+on Sidekiq and Solid Queue. `klass` is always the real job class: the ActiveJob adapter's
+wrapper is unwrapped before your resolver sees it. See
+[ADR 0002](docs/adr/0002-job-tagging.md).
+
+### Filtering
+
+`?tag=key:value` filters Retries, Dead and Scheduled — for example
+`/roundhouse/retries?tag=squad:growth`. It combines with the search box, survives
+pagination, and **applies to bulk actions too**, so "delete all matching" acts on exactly
+the rows shown and never more.
+
+Declare a vocabulary to get stable dropdowns instead of relying on the URL:
+
+```ruby
+RoundhouseUi.tag_filters = { squad: %w[core training growth platform ops ai] }
+```
+
+Values may be a callable if the list is dynamic. Once declared, filtering on a key you
+didn't declare matches nothing rather than everything.
+
+### Cost and safety
+
+- By default the resolver is treated as a **pure function of the job class** and is called
+  once per class per request — a 1,000-row page costs a handful of calls, not 1,000. If
+  your resolver reads the payload, set `RoundhouseUi.job_tags_per_job = true`; it will
+  then be called once per row, so keep it cheap.
+- Tag values pass through `redact_args`, so a tag keyed `tenant_token` masks itself. This
+  is key-based only — a tag *named* `squad` whose *value* is sensitive is not masked.
+- A resolver that raises is caught and logged; the page renders without tags rather than
+  failing.
 
 ## Surfacing sidekiq-failures
 
@@ -184,6 +280,15 @@ The **Busy** page's Cancel button flags a job's JID. A queued/scheduled/retrying
 is then skipped when it would next run; a *currently running* job stops only if it
 checks in — e.g. a long loop can `break if RoundhouseUi.cancelled?(jid)`.
 
+**Timing and cost.** The middleware is close to free when nothing is cancelled: rather
+than checking each job's JID against Redis, it asks "is *anything* cancelled?" from a
+process-local gate refreshed at most every 2s, and only does the exact per-job lookup
+while cancellations are pending. The tradeoff is that a cancellation takes **up to ~2s
+to reach a worker process** — the UI and your workers are separate processes, so expect
+a brief lag after clicking Cancel. Jobs already in flight are unaffected either way
+(cancellation is cooperative), and `RoundhouseUi.cancelled?(jid)` — what a long-running
+job polls — is never gated, so it always reads current state.
+
 ## Slowest job classes
 
 Sidekiq doesn't track per-class durations, so Roundhouse can record them itself.
@@ -197,8 +302,8 @@ Sidekiq.configure_server do |config|
 end
 ```
 
-It's two cheap Redis writes per job (a counter + a summed-ms float) into a single
-hash, and a job failure never propagates from the collector.
+It's two cheap Redis writes per job (a counter + a summed-ms float) into a single hash,
+pipelined into **one round-trip**, and a job failure never propagates from the collector.
 
 ## Bulk actions on a filter
 

data/app/controllers/concerns/roundhouse_ui/job_set_browsing.rb

@@ -10,14 +10,26 @@ module RoundhouseUi
     # Returns [entries_for_page, has_next?]. Scans only far enough to fill the
     # requested page plus one (to know if a next page exists) — never loads the
     # whole set, so a 50k dead set stays cheap to page through.
-    def browse(set, query, page, per = PER_PAGE)
+    # `?tag=key:value` — an exact match against a host-defined tag (ADR 0002),
+    # parsed once per request. Deliberately structured rather than folded into
+    # the free-text query: substring search feeding bulk_apply would silently
+    # widen destructive bulk actions.
+    def tag_filter
+      key, value = params[:tag].to_s.split(":", 2)
+      return nil if key.blank? || value.blank?
+
+      [ key, value ]
+    end
+
+    def browse(set, query, page, per = PER_PAGE, tag: nil)
       start = (page - 1) * per
       jobs = []
       has_next = false
       matched = 0
+      cache = tag_cache_for(tag)
 
       set.each do |entry|
-        next if query.present? && !entry_matches?(entry, query)
+        next unless entry_selected?(entry, query, tag, cache)
 
         if matched < start
           matched += 1
@@ -36,11 +48,12 @@ module RoundhouseUi
     # Apply an op ("retry"/"delete") to every entry matching the query, capped at
     # BULK_CAP. Entries are collected first, then acted on — mutating a Sidekiq set
     # mid-iteration skips entries. Returns [count_acted_on, capped?].
-    def bulk_apply(set, query, op, cap = BULK_CAP)
+    def bulk_apply(set, query, op, cap = BULK_CAP, tag: nil)
       matches = []
       capped = false
+      cache = tag_cache_for(tag)
       set.each do |entry|
-        next if query.present? && !entry_matches?(entry, query)
+        next unless entry_selected?(entry, query, tag, cache)
 
         matches << entry
         if matches.size >= cap
@@ -52,9 +65,63 @@ module RoundhouseUi
       [ matches.size, capped ]
     end
 
-    def entry_matches?(entry, query)
+    # Both the browse and bulk paths run every candidate through this, so the
+    # rows an operator sees are exactly the rows a bulk action will touch —
+    # including when a tag value is what matched the free-text search.
+    def entry_selected?(entry, query, tag, cache)
+      return false if @queue_filter.present? && entry.queue.to_s != @queue_filter
+
+      tags = entry_tags(entry, cache)
+      return false if query.present? && !entry_matches?(entry, query, tags)
+      return true if tag.nil?
+
+      entry_tagged?(tags, tag)
+    end
+
+    # `?queue=name` — exact match, so clicking a queue pill or picking one from
+    # the palette narrows to that queue. Exact rather than substring because
+    # this feeds bulk_apply too, and "default" must never also select
+    # "default_low".
+    def queue_filter
+      params[:queue].to_s.strip.presence
+    end
+
+    def entry_tagged?(tags, (key, value))
+      # A declared vocabulary is authoritative: filtering on a key the host
+      # never declared matches nothing rather than everything.
+      declared = Tags.filters
+      return false if declared && !declared.key?(key)
+
+      Tags.match?(tags, key, value)
+    end
+
+    def entry_tags(entry, cache)
+      return Tags::EMPTY unless RoundhouseUi.job_tags
+
+      Tags.for(klass: entry.klass, item: entry.item, cache: cache)
+    end
+
+    # Shares the request memo with TagsHelper — controller ivars carry into the
+    # view, so an entry resolved while scanning is not resolved again when its
+    # badge renders. Tags.for picks the key: class name normally, jid in per-job
+    # mode.
+    def tag_cache_for(_tag)
+      @rh_tag_cache ||= {}
+    end
+
+    # Tag values are part of the haystack, so typing a squad name finds its jobs
+    # without reaching for the structured filter. Safe to widen here only because
+    # browse and bulk_apply share this predicate — if they diverged, a search
+    # would show one set of rows and "delete all matching" would act on another.
+    def entry_matches?(entry, query, tags = Tags::EMPTY)
       needle = query.downcase
-      [ entry.klass, entry.jid, entry.item["error_class"], entry.item["error_message"], entry.args.to_s ]
+      # Queue matches on equality, not substring: typing a queue name should
+      # find its jobs, but this predicate also drives bulk_apply, so "default"
+      # must never additionally select "default_low".
+      return true if entry.queue.to_s.downcase == needle
+
+      [ entry.klass, entry.jid, entry.item["error_class"], entry.item["error_message"], entry.args.to_s,
+        *tags.values ]
         .any? { |hay| hay.to_s.downcase.include?(needle) }
     end
   end

data/app/controllers/roundhouse_ui/application_controller.rb

@@ -5,6 +5,7 @@ module RoundhouseUi
     # Isolated engines don't auto-include the host's helpers; include ours.
     helper ObservabilityHelper
     helper NavHelper
+    helper TagsHelper
     helper_method :content_nonce
 
     # Self-contained CSP, set per-request on our own responses so Roundhouse is

data/app/controllers/roundhouse_ui/dashboard_controller.rb

@@ -16,6 +16,10 @@ module RoundhouseUi
     # cheap JSON, no WebSocket/build step required).
     def stats
       s = backend.stats
+      # queues was already loaded here for the count, so the names ride along
+      # free — the command palette uses them to tell a queue name from a plain
+      # search term without adding a Redis call to every page render.
+      qs = backend.queues
       render json: {
         processed: s.processed,
         failed:    s.failed,
@@ -24,7 +28,8 @@ module RoundhouseUi
         scheduled: s.scheduled_size,
         retries:   s.retry_size,
         dead:      s.dead_size,
-        queues:    backend.queues.size
+        queues:      qs.size,
+        queue_names: qs.map(&:name).sort
       }
     end
   end

data/app/controllers/roundhouse_ui/dead_controller.rb

@@ -8,7 +8,9 @@ module RoundhouseUi
       @query = params[:q].to_s.strip
       @page  = [ params[:page].to_i, 1 ].max
       @total = backend.dead_set.size
-      @jobs, @has_next = browse(backend.dead_set, @query, @page)
+      @tag = tag_filter
+      @queue_filter = queue_filter
+      @jobs, @has_next = browse(backend.dead_set, @query, @page, PER_PAGE, tag: @tag)
     end
 
     def requeue
@@ -40,7 +42,8 @@ module RoundhouseUi
     # selected/visible ones), capped for safety. Only offered when a filter is
     # active, so it can't become "retry the entire dead set" by accident.
     def bulk_all
-      count, capped = bulk_apply(backend.dead_set, params[:q].to_s.strip, params[:op])
+      @queue_filter = queue_filter
+      count, capped = bulk_apply(backend.dead_set, params[:q].to_s.strip, params[:op], BULK_CAP, tag: tag_filter)
       verb = params[:op] == "delete" ? "Deleted" : "Re-enqueued"
       note = "#{verb} #{count} matching job(s)."
       note += " Stopped at the #{JobSetBrowsing::BULK_CAP} cap — run again for more." if capped

data/app/controllers/roundhouse_ui/errors_controller.rb

@@ -8,6 +8,43 @@ module RoundhouseUi
       @scan_limit = ErrorGroups::DEFAULT_SCAN_LIMIT
       result = ErrorGroups.new(query: @query).call
       @groups, @scanned, @truncated = result.groups, result.scanned, result.truncated
+
+      # Tags resolve per group rather than per entry: every row in a
+      # klass|error group shares a class, so a class-derived tag is constant
+      # for the group. Counted before filtering, so the quick-filter strip
+      # keeps showing every squad's total while one of them is selected.
+      @group_tags = @groups.to_h { |g| [ g[:klass], Tags.for(klass: g[:klass], item: {}, cache: tag_cache) ] }
+      @tag_counts = tag_counts(@groups)
+      @tag = tag_filter
+      @groups = @groups.select { |g| Tags.match?(@group_tags[g[:klass]], *@tag) } if @tag
+    end
+
+    private
+
+    # `?tag=key:value`, shared shape with the job sets.
+    def tag_filter
+      key, value = params[:tag].to_s.split(":", 2)
+      return nil if key.blank? || value.blank?
+
+      declared = Tags.filters
+      return nil if declared && !declared.key?(key)
+
+      [ key, value ]
+    end
+
+    # { "squad" => { "core" => 4, "training" => 5 } } — the counts behind the
+    # quick-filter strip, from groups already scanned, so this costs no extra
+    # Redis work.
+    def tag_counts(groups)
+      counts = Hash.new { |h, k| h[k] = Hash.new(0) }
+      groups.each do |g|
+        @group_tags[g[:klass]].each { |key, value| counts[key][value] += g[:count] }
+      end
+      counts
+    end
+
+    def tag_cache
+      @rh_tag_cache ||= {}
     end
   end
 end

data/app/controllers/roundhouse_ui/queues_controller.rb

@@ -3,7 +3,9 @@ module RoundhouseUi
     before_action :require_writable!, only: %i[purge pause resume]
 
     def index
+      @query = params[:q].to_s.strip
       @queues = backend.queues
+      @queues = @queues.select { |q| q.name.to_s.downcase.include?(@query.downcase) } if @query.present?
       @paused = backend.paused_queues
       # Native-pause backends (Solid Queue) enforce pauses without a fetcher, so
       # they never trigger the "not enforced" warning.

data/app/controllers/roundhouse_ui/retries_controller.rb

@@ -8,7 +8,9 @@ module RoundhouseUi
       @query = params[:q].to_s.strip
       @page  = [ params[:page].to_i, 1 ].max
       @total = backend.retry_set.size
-      @jobs, @has_next = browse(backend.retry_set, @query, @page)
+      @tag = tag_filter
+      @queue_filter = queue_filter
+      @jobs, @has_next = browse(backend.retry_set, @query, @page, PER_PAGE, tag: @tag)
     end
 
     # Retry now — moves the job back to its queue immediately.
@@ -27,7 +29,8 @@ module RoundhouseUi
     # Smart bulk: retry/delete EVERY job matching the current filter, capped for
     # safety. Offered only when a filter is active.
     def bulk_all
-      count, capped = bulk_apply(backend.retry_set, params[:q].to_s.strip, params[:op])
+      @queue_filter = queue_filter
+      count, capped = bulk_apply(backend.retry_set, params[:q].to_s.strip, params[:op], BULK_CAP, tag: tag_filter)
       verb = params[:op] == "delete" ? "Deleted" : "Re-enqueued"
       note = "#{verb} #{count} matching job(s)."
       note += " Stopped at the #{JobSetBrowsing::BULK_CAP} cap — run again for more." if capped

data/app/controllers/roundhouse_ui/scheduled_controller.rb

@@ -8,7 +8,9 @@ module RoundhouseUi
       @query = params[:q].to_s.strip
       @page  = [ params[:page].to_i, 1 ].max
       @total = backend.scheduled_set.size
-      @jobs, @has_next = browse(backend.scheduled_set, @query, @page)
+      @tag = tag_filter
+      @queue_filter = queue_filter
+      @jobs, @has_next = browse(backend.scheduled_set, @query, @page, PER_PAGE, tag: @tag)
     end
 
     # Enqueue now — pulls the job out of the schedule and onto its queue.

data/app/helpers/roundhouse_ui/application_helper.rb

@@ -1,4 +1,54 @@
 module RoundhouseUi
   module ApplicationHelper
+    # A job row's identity cell. Class on the first line where the eye lands,
+    # jid on a second, dimmer line — one long line of class + hex + link is
+    # unreadable once the row also carries squad, queue and error.
+    def job_identity(klass, jid, path)
+      safe_join([
+        link_to(klass, path, class: "rh-joblink"),
+        content_tag(:div, jid, class: "rh-sub rh-mono rh-jid", title: jid)
+      ])
+    end
+
+    # Relative time answers "is this soon?", the clock time answers "does that
+    # land inside the maintenance window?". Operators need both, so show both
+    # rather than making them hover or do the arithmetic.
+    def job_time(at, overdue: "now (overdue)")
+      return content_tag(:span, "—", class: "rh-sub") if at.nil?
+
+      relative = at > Time.now ? "in #{distance_of_time_in_words(Time.now, at)}" : overdue
+      safe_join([
+        content_tag(:span, relative),
+        content_tag(:span, at.strftime("%b %-d, %H:%M"), class: "rh-sub rh-mono")
+      ], " · ")
+    end
+
+    # Set heading that tells the truth under a filter. It used to always print
+    # the whole-set size, so "Dead set · 19 jobs" sat above four filtered rows.
+    def set_heading(label, showing:, total:, query: nil, tag: nil)
+      filtered = any_filter?(query, tag)
+      count = filtered ? "#{number_with_delimiter showing} of #{number_with_delimiter total}" : number_with_delimiter(total)
+      content_tag(:h2, class: "rh-h2") do
+        safe_join([
+          "#{label} · #{count} jobs",
+          (filtered ? content_tag(:span, filter_description(query, tag), class: "hint") : nil)
+        ].compact, " ")
+      end
+    end
+
+    # Queues carry meaning at a glance (critical vs low), so render them as a
+    # pill rather than grey text lost between two columns. On the job sets the
+    # pill filters to that queue; `link:` is off where there's nothing to filter
+    # (the Queues index itself, grouped Errors rows).
+    def queue_pill(name, link: false)
+      return content_tag(:span, name, class: "rh-pill rh-mono") unless link
+
+      active = @queue_filter == name.to_s
+      link_to name, url_for(only_path: true, page: nil, q: @query.presence,
+                            tag: params[:tag].presence,
+                            queue: (active ? nil : name)),
+        class: "rh-pill rh-mono rh-pill-link#{' is-on' if active}",
+        title: active ? "Clear queue filter" : "Show only #{name}"
+    end
   end
 end

data/app/helpers/roundhouse_ui/observability_helper.rb

@@ -10,6 +10,29 @@ module RoundhouseUi
       link_to "↗ #{adapter.label}", url, target: "_blank", rel: "noopener", class: "rh-trace"
     end
 
+    # Icon-only variant for table rows. The adapter's name is worth reading once
+    # in a header or a detail page, not once per row — there it is width spent
+    # repeating a word the operator already knows.
+    def trace_icon(klass:, jid:, queue: nil)
+      adapter = RoundhouseUi.observability
+      url = adapter.job_url(klass: klass, jid: jid, queue: queue)
+      return unless url
+
+      link_to "↗", url, target: "_blank", rel: "noopener", class: "rh-trace rh-trace-ico",
+        title: "Open in #{adapter.label}", "aria-label": "Open in #{adapter.label}"
+    end
+
+    def error_trace_icon(klass:, error: nil)
+      adapter = RoundhouseUi.observability
+      return unless adapter.respond_to?(:error_url)
+
+      url = adapter.error_url(klass: klass, error: error)
+      return unless url
+
+      link_to "↗", url, target: "_blank", rel: "noopener", class: "rh-trace rh-trace-ico",
+        title: "Open in #{adapter.label}", "aria-label": "Open in #{adapter.label}"
+    end
+
     # Deep-link for a grouped error row (no single JID) — a class-wide search.
     # respond_to? keeps older/custom adapters that lack error_url working.
     def error_trace_link(klass:, error: nil)

data/app/helpers/roundhouse_ui/tags_helper.rb

@@ -0,0 +1,101 @@
+module RoundhouseUi
+  # Renders host-defined job tags (see ADR 0002). Resolution is memoized for the
+  # life of the request: a page can render hundreds of rows, and ErrorGroups
+  # scans up to DEFAULT_SCAN_LIMIT entries, so the host's resolver must not be
+  # called once per row when it only varies by class.
+  module TagsHelper
+    # The per-request memo handed to Tags.for, shared with JobSetBrowsing so a
+    # class (or job) resolved while scanning is not resolved again when its
+    # badge renders. Tags.for chooses the key: class name normally, jid in
+    # per-job mode.
+    def tag_cache
+      @rh_tag_cache ||= {}
+    end
+
+    # Tags for one job entry, as a { "key" => "value" } Hash.
+    def tags_for(entry)
+      return Tags::EMPTY unless RoundhouseUi.job_tags
+
+      Tags.for(klass: entry.klass, item: entry.item, cache: tag_cache)
+    end
+
+    # Tags for a class name alone — used by grouped Errors, where every entry in
+    # a group shares a class, so a class-derived tag is constant for the group.
+    # Passes no payload, so a per-job resolver correctly declines rather than
+    # attributing one job's tags to the whole group.
+    def tags_for_class(klass)
+      return Tags::EMPTY unless RoundhouseUi.job_tags
+
+      Tags.for(klass: klass, item: {}, cache: tag_cache)
+    end
+
+    # Pills for a resolved tag Hash. Renders nothing when there are no tags, so
+    # every call site can be unconditional.
+    def tag_badges(tags)
+      return if tags.blank?
+
+      safe_join(tags.map { |key, value| tag_badge(key, value) }, " ")
+    end
+
+    # Tags get their own table column rather than an inline badge: class names
+    # vary wildly in length, so inline badges land at ragged x-positions and
+    # can't be scanned down. Only worth a column when a host configured tags.
+    def tag_column?
+      RoundhouseUi.job_tags.present?
+    end
+
+    # Header for that column. With the usual single dimension this is the tag's
+    # own name ("squad"); with several there's no one right label.
+    def tag_column_label
+      keys = Tags.filters&.keys
+      keys&.one? ? keys.first.titleize : "Tags"
+    end
+
+    # Cell contents. Stacks when a host defines more than one dimension.
+    def tag_cell(tags)
+      return content_tag(:span, "—", class: "rh-sub") if tags.blank?
+
+      tag_badges(tags)
+    end
+
+    # Values offered as filter chips where no counts are available. Prefers the
+    # host's declared vocabulary, so the chips stay put as you filter; falls back
+    # to whatever the visible rows happen to carry, which at least beats nothing
+    # but shifts as you page.
+    def tag_vocabulary
+      declared = Tags.filters
+      return declared if declared.present?
+
+      seen = Hash.new { |h, k| h[k] = [] }
+      Array(@jobs).each do |job|
+        tags_for(job).each { |key, value| seen[key] << value unless seen[key].include?(value) }
+      end
+      seen.transform_values(&:sort)
+    end
+
+    # Human description of the active filter set, so a bulk confirm names every
+    # constraint that will be applied — not just the text query.
+    # Every active constraint must appear here. A confirm that names only the
+    # text query while a queue or tag also narrows the set understates what is
+    # about to be destroyed.
+    def filter_description(query, tag, queue = @queue_filter)
+      parts = []
+      parts << "matching “#{query}”" if query.present?
+      parts << "tagged #{tag[0]}: #{tag[1]}" if tag
+      parts << "in queue #{queue}" if queue.present?
+      parts.join(" and ")
+    end
+
+    # Any filter active? Bulk-on-match is filter-gated, so this decides whether
+    # the bulk bar renders at all — and which empty-state copy is honest.
+    def any_filter?(query, tag, queue = @queue_filter)
+      query.present? || !tag.nil? || queue.present?
+    end
+
+    # Value only — the key is near-constant down a column, so repeating it is
+    # noise. It stays in the tooltip for hosts with more than one dimension.
+    def tag_badge(key, value)
+      content_tag(:span, value, class: "rh-pill rh-pill-tag", title: "#{key}: #{value}")
+    end
+  end
+end