specbandit 0.13.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95622117125136b9368557368697eb0b9663983289dc7a5c53692a230ac4d7ef
-  data.tar.gz: 5d74e976511d86b4c8da066cc782fc358af1c69e89ae02edcc3935b077ad473e
+  metadata.gz: 89e101cef42f9c643d1c651261efff4a5d28c640761dc3f025ce133c78b1446d
+  data.tar.gz: 5e93530207fb1fb476fca6c2b373581cc22ba070efd3cd7f30b6a637fc1804c2
 SHA512:
-  metadata.gz: 19a2cff1aab50ad0412e515a2081b85dcd8f94addf96232bfb2be3694b02980410df1a8788d3451907a985b26fc6cfecb1dd7d45750ba108b63f84975ea36996
-  data.tar.gz: 9af9ad631d684be5485a43620b76dcda02e7e223e50b6ecab47def52ee24fa4ab296dff43e5eea11c03acaea5146178da9cced4740ebb1036b41edef38ba0852
+  metadata.gz: 164896ab49dd19b6309e4edc567b87fe31aa9bfe81a6837e5e945a46c2e38694aac1ae68ee99469160d02cea79d6e64d3ce5a4ea4edb88ef48b61977cd0142a9
+  data.tar.gz: 01047ed0fc228b16c70c93f49644379a8bddff86be657a1599cbc83196e54fd7e0722fccf3bb64529911297834464ee107a7c5f875e645c0c42d49597c1f09d6

data/README.md

@@ -136,7 +136,7 @@ specbandit push [options] [files...]
   --key KEY              Redis queue key (required)
   --pattern PATTERN      Glob pattern for file discovery
   --redis-url URL        Redis URL (default: redis://localhost:6379)
-  --key-ttl SECONDS      TTL for the Redis key (default: 21600 / 6 hours)
+  --key-ttl SECONDS      TTL for all Redis keys (default: 604800 / 1 week)
 
 specbandit work [options] [-- extra-opts...]
   --key KEY              Redis queue key (required)
@@ -147,8 +147,8 @@ specbandit work [options] [-- extra-opts...]
   --batch-size N         Files per batch (default: 5)
   --redis-url URL        Redis URL (default: redis://localhost:6379)
   --key-rerun KEY        Per-runner rerun key for re-run support (see below)
-  --key-rerun-ttl SECS   TTL for rerun key (default: 604800 / 1 week)
-  --rerun                Signal this is a re-run (fail if rerun key is empty)
+  --key-failed KEY       Redis key to record failed test files
+  --key-ttl SECONDS      TTL for all Redis keys (default: 604800 / 1 week)
   --verbose              Show per-batch file list and full command output
 
 Arguments after -- are forwarded to the adapter. They are merged with
@@ -167,11 +167,10 @@ All CLI options can be set via environment variables:
 | `SPECBANDIT_COMMAND` | Command to run (cli adapter) | _(none)_ |
 | `SPECBANDIT_COMMAND_OPTS` | Space-separated command options | _(none)_ |
 | `SPECBANDIT_BATCH_SIZE` | Files per steal | `5` |
-| `SPECBANDIT_KEY_TTL` | Key expiry in seconds | `21600` (6 hours) |
+| `SPECBANDIT_KEY_TTL` | Expiry (seconds) for **all** Redis keys | `604800` (1 week) |
 | `SPECBANDIT_RSPEC_OPTS` | Space-separated RSpec options (rspec adapter) | _(none)_ |
 | `SPECBANDIT_KEY_RERUN` | Per-runner rerun key | _(none)_ |
-| `SPECBANDIT_KEY_RERUN_TTL` | Rerun key expiry in seconds | `604800` (1 week) |
-| `SPECBANDIT_RERUN` | Signal re-run mode (`1`/`true`/`yes`) | _(false)_ |
+| `SPECBANDIT_KEY_FAILED` | Redis key for failed test files | _(none)_ |
 | `SPECBANDIT_VERBOSE` | Enable verbose output (`1`/`true`/`yes`) | _(false)_ |
 
 CLI flags take precedence over environment variables.
@@ -185,9 +184,8 @@ Specbandit.configure do |c|
   c.redis_url      = "redis://my-redis:6379"
   c.key            = "pr-123-run-456"
   c.batch_size     = 10
-  c.key_ttl        = 7200 # 2 hours (default: 21600 / 6 hours)
+  c.key_ttl        = 604_800 # 1 week (default) -- applies to every key specbandit writes
   c.key_rerun      = "pr-123-run-456-runner-3"
-  c.key_rerun_ttl  = 604_800 # 1 week (default)
 end
 
 # Push
@@ -289,7 +287,7 @@ When you use specbandit to distribute tests across multiple CI runners (e.g. a G
 This creates a subtle but serious problem with CI re-runs:
 
 1. **First run**: Runner #3 steals and executes files X, Y, Z. File Y fails. The shared queue is now empty (all files were consumed across all runners).
-2. **Re-run of runner #3**: GitHub Actions re-runs only the failed runner. It starts `specbandit work` again with the same `--key`, but the shared queue is already empty. Runner #3 sees nothing to do and **exits 0 -- the failing test silently passes**.
+2. **Re-run of runner #3**: GitHub Actions re-runs only the failed runner. It starts `specbandit work` again with the same `--key`, but the shared queue is already empty. Without a per-runner memory the runner would see nothing to do and exit 0 -- silently passing the failing test.
 
 This happens because GitHub Actions re-runs **reuse the same `run_id`**, so the key resolves to the same (now empty) Redis list.
 
@@ -306,31 +304,26 @@ specbandit work \
   --batch-size 10
 ```
 
-### How it works: three operating modes
+### How it works: the mode is derived from Redis, never from a flag
 
-Specbandit detects the mode automatically based on the state of `--key-rerun`:
+Specbandit decides what to do purely from the **state of Redis** -- there is no `--rerun` flag or environment variable to get wrong. Two signals drive the decision:
 
-| `--key-rerun` provided? | Rerun key in Redis | `--rerun` flag? | Mode | Behavior |
-|---|---|---|---|---|
-| No | -- | No | **Steal** | Original behavior. Steal from shared queue, run, done. |
-| Yes | Empty | No | **Record** | Steal from shared queue + record each batch to the rerun key. |
-| Yes | Has data | No/Yes | **Replay** | Ignore shared queue entirely. Re-run exactly the recorded files. |
-| Yes | Empty | Yes | **Fail** | Exit 1 with error. Prevents silent false pass on stale re-runs. |
-| No | -- | Yes | **Error** | Validation error: `--rerun` requires `--key-rerun`. |
+- **Published marker.** `specbandit push` writes a durable companion key (`<key>:published`) alongside the queue. Because Redis auto-deletes empty lists, a drained queue is indistinguishable from one that was never created -- the marker is the only reliable proof that work was ever enqueued.
+- **Rerun key.** The per-runner `--key-rerun` that records what this runner executed.
 
-#### The `--rerun` safety flag
+The full decision table:
 
-Without `--rerun`, specbandit cannot distinguish a first run from a re-run when the rerun key is empty (e.g., TTL expired or Redis was flushed). In that case it silently falls back to Record mode, which may find an empty shared queue and exit 0 with zero tests -- a **silent false pass**.
+| Published | Shared queue (`--key`) | Rerun key (`--key-rerun`) | Behavior |
+|---|---|---|---|
+| **No** | -- | -- | **Crash** (exit 1). Nothing was ever pushed for this key (or it expired). Refuses to run rather than silently pass. |
+| Yes | Drained / empty | Empty | **OK, exit 0.** Worker arriving late -- everything was already taken by peers and this runner has no re-run memory. |
+| Yes | Has data | Empty | **Steal.** Classic run: pop batches from the shared queue (and record them to the rerun key if one is configured). |
+| Yes | Drained / empty | Has data | **Replay.** Classic re-run: ignore the shared queue and re-run exactly the recorded files. |
+| Yes | Has data | Has data | **Crash** (exit 1). Inconsistent state -- refuses to run to avoid double-executing. |
 
-The `--rerun` flag tells specbandit "this is definitely a re-run". If the rerun key is empty, it fails hard with exit code 1 and a clear error message instead of silently passing.
+> **Empty key names count as "not provided".** A `--key-rerun` whose value is an empty string -- e.g. `--key-rerun "$VAR"` where `$VAR` is unset in CI -- is treated exactly like `--key-rerun` being absent. The same applies to `--key-failed`: an empty/unset name is treated as "not configured" and no failed files are recorded.
 
-Set it on re-run attempts using your CI's run attempt counter:
-
-```yaml
-# GitHub Actions: github.run_attempt is "1" on first run, "2"+ on re-runs
-env:
-  SPECBANDIT_RERUN: ${{ github.run_attempt != '1' && '1' || '' }}
-```
+> **The published marker replaces the old `--rerun` flag.** Earlier versions used a `--rerun` / `SPECBANDIT_RERUN` flag (driven by `github.run_attempt`) to decide whether to fail on an empty rerun key. That flag is gone: the marker lets specbandit tell "never pushed" (crash) apart from "drained, arriving late" (exit 0) without any CI-provided hint. Drop `--rerun` / `SPECBANDIT_RERUN` from your config.
 
 **On first run**, the rerun key doesn't exist yet (empty), so specbandit enters **record mode**:
 
@@ -392,11 +385,10 @@ jobs:
             --key-rerun "pr-${{ github.event.number }}-${{ github.run_id }}-runner-${{ matrix.runner }}" \
             --redis-url "${{ secrets.REDIS_URL }}" \
             --adapter rspec \
-            --batch-size 10 \
-            ${{ github.run_attempt != '1' && '--rerun' || '' }}
+            --batch-size 10
 ```
 
-The only difference from the basic example is the addition of `--key-rerun` and `--rerun`. The key structure:
+The only difference from the basic example is the addition of `--key-rerun` (no re-run flag needed -- the mode is derived from Redis). The key structure:
 
 - `--key` = `pr-42-run-100` -- **shared** across all 4 runners, same on re-run (because `run_id` is reused)
 - `--key-rerun` = `pr-42-run-100-runner-3` -- **unique per runner**, same on re-run
@@ -420,27 +412,24 @@ The only difference from the basic example is the addition of `--key-rerun` and
 
 Runners 1, 2, 4 are not started at all.
 
-### Rerun key TTL
+### Key TTL
 
-The rerun key defaults to a **1 week TTL** (`604800` seconds). This is intentionally longer than the shared queue TTL (6 hours) because re-runs can happen hours or even days after the original CI run.
+A **single** TTL governs every key specbandit writes -- the shared queue, its published marker, the per-runner rerun key, and the failed key. It defaults to **1 week** (`604800` seconds), long enough that re-runs happening hours or even days after the original CI run still find their rerun key and published marker alive.
 
-Override via `--key-rerun-ttl` or `SPECBANDIT_KEY_RERUN_TTL`:
+Override via `--key-ttl` or `SPECBANDIT_KEY_TTL` (set it on `push`, which is where the queue and its marker are created):
 
 ```bash
-# Set rerun key to expire after 3 days
-specbandit work \
-  --key "pr-42-run-100" \
-  --key-rerun "pr-42-run-100-runner-3" \
-  --key-rerun-ttl 259200
+# Everything expires after 3 days
+specbandit push --key "pr-42-run-100" --key-ttl 259200 --pattern 'spec/**/*_spec.rb'
 ```
 
 ## How it works
 
-- **Push** uses `RPUSH` to append all file paths to a Redis list in a single command, then sets `EXPIRE` on the key (default: 6 hours) to ensure stale queues are automatically cleaned up.
+- **Push** uses `RPUSH` to append all file paths to a Redis list in a single command, sets `EXPIRE` on the key, and writes a durable `<key>:published` marker (with the same TTL). Empty Redis lists are auto-deleted, so this marker is what lets `work` tell "never pushed" (crash) apart from "drained, arriving late" (exit 0).
 - **Steal** uses `LPOP key count` (Redis 6.2+), which atomically pops up to N elements. No Lua scripts, no locks, no race conditions.
-- **Record** (when `--key-rerun` is set): after each steal, the batch is also `RPUSH`ed to the per-runner rerun key with its own TTL (default: 1 week).
-- **Replay** (when `--key-rerun` has data): reads all files from the rerun key via `LRANGE` (non-destructive), splits into batches, and runs them locally. The shared queue is never touched.
-- **Rerun safety** (when `--rerun` is set): if the rerun key is empty, specbandit exits 1 immediately instead of falling through to record mode. This prevents silent false passes when the rerun key TTL has expired or Redis was flushed.
+- **Record** (when `--key-rerun` is set): after each steal, the batch is also `RPUSH`ed to the per-runner rerun key.
+- **Replay** (when the rerun key has data and the shared queue is drained): reads all files from the rerun key via `LRANGE` (non-destructive), splits into batches, and runs them locally. The shared queue is never touched.
+- **Mode selection** is derived entirely from Redis (published marker + queue/rerun state) -- see the decision table above. There is no re-run flag or environment variable.
 - **Run** delegates to the configured adapter:
   - **CLI adapter**: spawns a shell command per batch via `Open3`, appending file paths as arguments. Works with any test runner.
   - **RSpec adapter**: uses `RSpec::Core::Runner.run` in-process with `RSpec.clear_examples` between batches to reset example state while preserving configuration. No subprocess forking overhead.

data/lib/specbandit/cli.rb

@@ -63,7 +63,7 @@ module Specbandit
           Specbandit.configuration.redis_url = v
         end
 
-        opts.on('--key-ttl SECONDS', Integer, 'TTL for the Redis key in seconds (default: 21600 / 6 hours)') do |v|
+        opts.on('--key-ttl SECONDS', Integer, 'TTL for all Redis keys in seconds (default: 604800 / 1 week)') do |v|
           Specbandit.configuration.key_ttl = v
         end
 
@@ -119,20 +119,12 @@ module Specbandit
           Specbandit.configuration.key_rerun = v
         end
 
-        opts.on('--key-rerun-ttl SECONDS', Integer, 'TTL for rerun key in seconds (default: 604800 / 1 week)') do |v|
-          Specbandit.configuration.key_rerun_ttl = v
-        end
-
         opts.on('--key-failed KEY', 'Redis key to record failed test files for later review') do |v|
           Specbandit.configuration.key_failed = v
         end
 
-        opts.on('--key-failed-ttl SECONDS', Integer, 'TTL for failed key in seconds (default: 604800 / 1 week)') do |v|
-          Specbandit.configuration.key_failed_ttl = v
-        end
-
-        opts.on('--rerun', 'Signal this is a re-run (fail hard if rerun key is empty)') do
-          Specbandit.configuration.rerun = true
+        opts.on('--key-ttl SECONDS', Integer, 'TTL for all Redis keys in seconds (default: 604800 / 1 week)') do |v|
+          Specbandit.configuration.key_ttl = v
         end
 
         opts.on('--report FILE', 'Write JSON report with run statistics to FILE') do |v|
@@ -209,7 +201,7 @@ module Specbandit
           --key KEY              Redis queue key (required, or set SPECBANDIT_KEY)
           --pattern PATTERN      Glob pattern for file discovery (e.g. 'spec/**/*_spec.rb')
           --redis-url URL        Redis URL (default: redis://localhost:6379)
-          --key-ttl SECONDS      TTL for the Redis key (default: 21600 / 6 hours)
+          --key-ttl SECONDS      TTL for all Redis keys (default: 604800 / 1 week)
 
         Work options:
           --key KEY              Redis queue key (required, or set SPECBANDIT_KEY)
@@ -219,11 +211,9 @@ module Specbandit
           --rspec-opts OPTS      Extra options forwarded to RSpec (for rspec adapter)
           --batch-size N         Files per batch (default: 5, or set SPECBANDIT_BATCH_SIZE)
           --redis-url URL        Redis URL (default: redis://localhost:6379)
-           --key-rerun KEY        Per-runner rerun key for re-run support
-           --key-rerun-ttl N      TTL for rerun key (default: 604800 / 1 week)
-           --key-failed KEY       Redis key to record failed test files
-           --key-failed-ttl N     TTL for failed key (default: 604800 / 1 week)
-           --rerun                Signal this is a re-run (fail hard if rerun key is empty)
+          --key-rerun KEY        Per-runner rerun key for re-run support
+          --key-failed KEY       Redis key to record failed test files
+          --key-ttl SECONDS      TTL for all Redis keys (default: 604800 / 1 week)
           --report FILE          Write JSON report to FILE after run
           --verbose              Show per-batch file list and full command output
 
@@ -237,13 +227,10 @@ module Specbandit
           SPECBANDIT_COMMAND          Command to run (cli adapter)
           SPECBANDIT_COMMAND_OPTS     Command options (space-separated)
           SPECBANDIT_BATCH_SIZE       Batch size
-          SPECBANDIT_KEY_TTL          Key TTL in seconds (default: 21600)
+          SPECBANDIT_KEY_TTL          TTL for all Redis keys in seconds (default: 604800)
           SPECBANDIT_RSPEC_OPTS       RSpec options (rspec adapter)
           SPECBANDIT_KEY_RERUN        Per-runner rerun key
-          SPECBANDIT_KEY_RERUN_TTL    Rerun key TTL in seconds (default: 604800)
           SPECBANDIT_KEY_FAILED       Redis key for failed test files
-          SPECBANDIT_KEY_FAILED_TTL   Failed key TTL in seconds (default: 604800)
-          SPECBANDIT_RERUN            Signal re-run mode (1/true/yes)
           SPECBANDIT_VERBOSE          Enable verbose output (1/true/yes)
           SPECBANDIT_REPORT           Path to write JSON report file
 

data/lib/specbandit/configuration.rb

@@ -3,15 +3,17 @@
 module Specbandit
   class Configuration
     attr_accessor :redis_url, :batch_size, :key, :rspec_opts, :key_ttl,
-                  :key_rerun, :key_rerun_ttl, :rerun, :verbose,
+                  :key_rerun, :verbose,
                   :adapter, :command, :command_opts,
-                  :key_failed, :key_failed_ttl, :report
+                  :key_failed, :report
 
     DEFAULT_REDIS_URL = 'redis://localhost:6379'
     DEFAULT_BATCH_SIZE = 5
-    DEFAULT_KEY_TTL = 21_600 # 6 hours in seconds
-    DEFAULT_KEY_RERUN_TTL = 604_800 # 1 week in seconds
-    DEFAULT_KEY_FAILED_TTL = 604_800 # 1 week in seconds
+    # A single TTL governs every key specbandit writes: the shared queue, its
+    # published marker, the per-runner rerun key and the failed key. It defaults
+    # to 1 week because re-runs can happen hours or days after the original run,
+    # and the rerun key + published marker must still be alive when they do.
+    DEFAULT_KEY_TTL = 604_800 # 1 week in seconds
     DEFAULT_ADAPTER = 'cli'
 
     def initialize
@@ -21,14 +23,11 @@ module Specbandit
       @rspec_opts = parse_rspec_opts(ENV.fetch('SPECBANDIT_RSPEC_OPTS', nil))
       @key_ttl = Integer(ENV.fetch('SPECBANDIT_KEY_TTL', DEFAULT_KEY_TTL))
       @key_rerun = ENV.fetch('SPECBANDIT_KEY_RERUN', nil)
-      @key_rerun_ttl = Integer(ENV.fetch('SPECBANDIT_KEY_RERUN_TTL', DEFAULT_KEY_RERUN_TTL))
-      @rerun = env_truthy?('SPECBANDIT_RERUN')
       @verbose = env_truthy?('SPECBANDIT_VERBOSE')
       @adapter = ENV.fetch('SPECBANDIT_ADAPTER', DEFAULT_ADAPTER)
       @command = ENV.fetch('SPECBANDIT_COMMAND', nil)
       @command_opts = parse_space_separated(ENV.fetch('SPECBANDIT_COMMAND_OPTS', nil))
       @key_failed = ENV.fetch('SPECBANDIT_KEY_FAILED', nil)
-      @key_failed_ttl = Integer(ENV.fetch('SPECBANDIT_KEY_FAILED_TTL', DEFAULT_KEY_FAILED_TTL))
       @report = ENV.fetch('SPECBANDIT_REPORT', nil)
     end
 
@@ -36,9 +35,6 @@ module Specbandit
       raise Error, 'key is required (set via --key or SPECBANDIT_KEY)' if key.nil? || key.empty?
       raise Error, 'batch_size must be a positive integer' unless batch_size.positive?
       raise Error, 'key_ttl must be a positive integer' unless key_ttl.positive?
-      raise Error, 'key_rerun_ttl must be a positive integer' unless key_rerun_ttl.positive?
-      raise Error, 'key_failed_ttl must be a positive integer' unless key_failed_ttl.positive?
-      raise Error, '--rerun requires --key-rerun to be set' if rerun && (key_rerun.nil? || key_rerun.empty?)
     end
 
     private

data/lib/specbandit/publisher.rb

@@ -26,13 +26,28 @@ module Specbandit
         return 0
       end
 
-      queue.push(key, resolved, ttl: key_ttl)
+      push_ms = measure { queue.push(key, resolved, ttl: key_ttl) }
+      # Record a durable "published" marker so workers can tell a drained
+      # queue ("worker arriving late", OK) apart from one that was never
+      # pushed ("you didn't push work", crash). Redis auto-deletes empty
+      # lists, so the list itself cannot carry this signal.
+      mark_ms = measure { queue.mark_published(key, ttl: key_ttl) }
+
       output.puts "[specbandit] Enqueued #{resolved.size} files onto key '#{key}' (TTL: #{key_ttl}s)."
+      output.puts format('[specbandit] Redis latency: push %.1fms, mark published %.1fms.', push_ms, mark_ms)
       resolved.size
     end
 
     private
 
+    # Run the block and return the wall-clock time it took, in milliseconds.
+    # Used to surface how long the Redis round-trips took in the push log.
+    def measure
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+    end
+
     def resolve_files(files:, pattern:)
       # Priority 1: stdin (only when data is actually piped in)
       if !$stdin.tty? && $stdin.ready?

data/lib/specbandit/redis_queue.rb

@@ -45,6 +45,27 @@ module Specbandit
       with_retries { redis.llen(key) }
     end
 
+    # Mark a queue key as "published" by setting a companion marker key.
+    #
+    # The marker is a separate string key (`<key>:published`) that survives
+    # the queue list being fully drained. It is the source of truth for
+    # "was work ever pushed for this key?" -- Redis auto-deletes empty lists,
+    # so the list alone cannot distinguish "never pushed" from "drained".
+    def mark_published(key, ttl: nil)
+      with_retries do
+        if ttl
+          redis.set(published_marker(key), '1', ex: ttl)
+        else
+          redis.set(published_marker(key), '1')
+        end
+      end
+    end
+
+    # Whether a queue key has been published (its marker exists).
+    def published?(key)
+      with_retries { redis.exists?(published_marker(key)) }
+    end
+
     # Read all file paths from the list non-destructively.
     # Returns an array of file paths (empty array when key doesn't exist).
     def read_all(key)
@@ -57,6 +78,11 @@ module Specbandit
 
     private
 
+    # Companion marker key name for a given queue key.
+    def published_marker(key)
+      "#{key}:published"
+    end
+
     def with_retries(attempts: MAX_ATTEMPTS)
       retries = 0
       begin

data/lib/specbandit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Specbandit
-  VERSION = '0.13.0'
+  VERSION = '1.0.0'
 end

data/lib/specbandit/worker.rb

@@ -4,7 +4,7 @@ require 'json'
 
 module Specbandit
   class Worker
-    attr_reader :queue, :key, :batch_size, :adapter, :key_rerun, :key_rerun_ttl, :key_failed, :key_failed_ttl, :rerun,
+    attr_reader :queue, :key, :batch_size, :adapter, :key_rerun, :key_ttl, :key_failed,
                 :output, :verbose, :report
 
     def initialize(
@@ -12,10 +12,8 @@ module Specbandit
       batch_size: Specbandit.configuration.batch_size,
       adapter: nil,
       key_rerun: Specbandit.configuration.key_rerun,
-      key_rerun_ttl: Specbandit.configuration.key_rerun_ttl,
+      key_ttl: Specbandit.configuration.key_ttl,
       key_failed: Specbandit.configuration.key_failed,
-      key_failed_ttl: Specbandit.configuration.key_failed_ttl,
-      rerun: Specbandit.configuration.rerun,
       verbose: Specbandit.configuration.verbose,
       report: Specbandit.configuration.report,
       queue: nil,
@@ -27,10 +25,8 @@ module Specbandit
       @key = key
       @batch_size = batch_size
       @key_rerun = key_rerun
-      @key_rerun_ttl = key_rerun_ttl
+      @key_ttl = key_ttl
       @key_failed = key_failed
-      @key_failed_ttl = key_failed_ttl
-      @rerun = rerun
       @verbose = verbose
       @report = report
       @queue = queue || RedisQueue.new
@@ -57,21 +53,7 @@ module Specbandit
       @run_start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       adapter.setup
 
-      exit_code = if key_rerun
-                    rerun_files = queue.read_all(key_rerun)
-                    if rerun_files.any?
-                      run_replay(rerun_files)
-                    elsif rerun
-                      output.puts "[specbandit] ERROR: --rerun flag is set but rerun key '#{key_rerun}' is empty."
-                      output.puts '[specbandit] The rerun key may have expired (TTL) or Redis was flushed.'
-                      output.puts '[specbandit] Cannot replay — failing to prevent silent false pass.'
-                      1
-                    else
-                      run_steal(record: true)
-                    end
-                  else
-                    run_steal(record: false)
-                  end
+      exit_code = determine_exit_code
 
       print_summary if @batch_results.any?
       merge_json_results
@@ -83,6 +65,70 @@ module Specbandit
 
     private
 
+    # Decide the operating mode from the state of Redis and execute it.
+    #
+    # The mode is derived entirely from Redis -- never from an environment
+    # variable or flag -- following this table:
+    #
+    #   Published | Key (queue)    | Rerun key   | Behavior
+    #   ----------|----------------|-------------|-------------------------------
+    #   No        | --             | --          | Crash: nothing was ever pushed
+    #   Yes       | empty/drained  | empty       | OK: worker arriving late (0)
+    #   Yes       | has data       | empty       | Steal (record if rerun key set)
+    #   Yes       | empty/drained  | has data    | Replay recorded files
+    #   Yes       | has data       | has data    | Crash: inconsistent (weird case)
+    #
+    # "Published" is a durable marker written by `specbandit push`; it is the
+    # only reliable signal that work was ever enqueued, because Redis
+    # auto-deletes empty lists (so a drained queue is indistinguishable from a
+    # never-created one by the list alone).
+    def determine_exit_code
+      return fail_not_published unless queue.published?(key)
+
+      key_has_data = queue.length(key).positive?
+      rerun_files = key_present?(key_rerun) ? queue.read_all(key_rerun) : []
+
+      if key_has_data && rerun_files.any?
+        fail_inconsistent_state
+      elsif rerun_files.any?
+        run_replay(rerun_files)
+      elsif key_has_data
+        run_steal(record: key_present?(key_rerun))
+      else
+        # Published, but the queue is drained and this runner has no rerun
+        # memory: it simply arrived after everything was already taken.
+        output.puts "[specbandit] Queue '#{key}' already drained and no rerun files to replay. " \
+                    'Nothing to do (worker arriving late).' if verbose
+        0
+      end
+    end
+
+    # A Redis key name is usable only when it is a non-nil, non-empty string.
+    # Guards the Ruby gotcha where "" is truthy (e.g. --key-rerun "$UNSET_VAR"),
+    # which would otherwise read/write against an empty key name.
+    def key_present?(value)
+      !value.nil? && !value.empty?
+    end
+
+    # No published marker for this key: `specbandit push` was never run for it,
+    # or the key expired. Crash rather than silently pass with zero tests.
+    def fail_not_published
+      output.puts "[specbandit] ERROR: queue '#{key}' was never published."
+      output.puts '[specbandit] Run `specbandit push` before `specbandit work`, or the key/TTL may have expired.'
+      output.puts '[specbandit] Refusing to run to prevent a silent false pass.'
+      1
+    end
+
+    # Both the shared queue and this runner's rerun key hold files at once.
+    # That should never happen: a fresh run has no rerun memory yet, and a
+    # re-run reads from a drained queue. Crash instead of double-executing.
+    def fail_inconsistent_state
+      output.puts "[specbandit] ERROR: inconsistent state — shared queue '#{key}' still has files " \
+                  "while rerun key '#{key_rerun}' also has recorded files."
+      output.puts '[specbandit] Refusing to run to avoid double-execution / undefined behavior.'
+      1
+    end
+
     # Replay mode: run a known list of files in local batches.
     # Used when re-running a failed CI job -- the rerun key already
     # contains the exact files this runner executed previously.
@@ -136,7 +182,7 @@ module Specbandit
         end
 
         # Record the stolen batch so this runner can replay on re-run
-        queue.push(key_rerun, files, ttl: key_rerun_ttl) if record
+        queue.push(key_rerun, files, ttl: key_ttl) if record
 
         batch_num += 1
         output.puts "[specbandit] Batch ##{batch_num}: running #{files.size} files" if verbose
@@ -171,13 +217,13 @@ module Specbandit
     # paths are recorded (not the entire batch). For CLI adapter batches
     # (no per-file granularity), the whole batch is recorded as fallback.
     def record_failed_files(files, result)
-      return unless key_failed
+      return unless key_present?(key_failed)
       return if result.exit_code.zero?
 
       failed_files = extract_failed_files(result) || files
       return if failed_files.empty?
 
-      queue.push(key_failed, failed_files, ttl: key_failed_ttl)
+      queue.push(key_failed, failed_files, ttl: key_ttl)
     end
 
     # Extract individual failed file paths from an RspecBatchResult's JSON output.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: specbandit
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Ferran Basora
@@ -109,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Distributed test runner using Redis as a work queue
 test_files: []