specguard-ruby 0.3.23 → 0.3.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9fac934e9b12828579be8d52a3b9022d327e0011a02a8d509203c4b41ae64ab
-  data.tar.gz: 8e91e21c7a1667c7f0d3139e8ea41143e1e527684a37a3bb07c61bbd88518784
+  metadata.gz: dd1e42b8014d4627c1126b81fd4e419e000316e788f0115a24dbbf9041ad52b1
+  data.tar.gz: d74ca48cff5263d913f727a94d59b6bb6ffd477ff4a31bddcf7d83599b96f9c3
 SHA512:
-  metadata.gz: 1e90253128008f3e5461b76ef9a6b92edcd9c55fcb21933805d1f492c26a53e64efb924b1caa45a1dc109c69469aada4fafdc26277527d74b61fe477a1b8cf92
-  data.tar.gz: 5586aca98c5894cf121fd1380f9af56f5feab57119c599e3e5cd33f5900c6be5df63dc41c4fb35eba3512ef50568dfbd36cfaca6f7a9351fbadfd3e654d8c9c9
+  metadata.gz: 79519698cb6c136909f09bd425548bdac0e3ab936145449e983937d2f9f97e9f1e30e7f3bcd9936e1c200b2c49358157d9b97469804f3b11a200538557dc78f3
+  data.tar.gz: c034dc9514a7cb085909a1bcdfb7c51e84dd67af457bbd73c26c4a4d31f21afae6c6893a7f42d2475dd350b80d0112879698ab5a912cf2dee5c83dfa7abc7c25

data/README.md

@@ -31,7 +31,9 @@ SPECGUARD_ENDPOINT=https://specguard.example SPECGUARD_API_KEY=sgk_… bundle ex
 
 The plugin rides alongside Minitest's own reporters (the suite's output is unchanged), posts one
 envelope per process with the same field names the RSpec formatter sends, and never fails the run:
-a refused or unreachable delivery costs one line on stderr and a line in the local sink. Without
+a refused or unreachable delivery costs one line on stderr and a line in the replay queue — and
+when that queue cannot be written either, the same one line reports the loss rather than promising
+a file that is not there (see [Shipping the run to SpecGuard](#shipping-the-run-to-specguard)). Without
 `SPECGUARD_API_KEY` nothing is sent — the run is appended to the local development record, exactly
 as the RSpec formatter behaves. Parameterized tests — the `define_method("test_x_#{param}")` loop
 idiom — ship one row per instance, not one row per definition site, so each instance's outcome and
@@ -468,14 +470,28 @@ is written to `log/test_results.local.jsonl` — the local development record,
 kept apart from the replay queue — so local development needs no opt-out, and a
 fork with no secret configured behaves like a laptop rather than like a broken
 build. The local file's name is configurable via `SPECGUARD_LOCAL_OUTPUT_PATH`
-(or `SpecGuard::RSpec.configure { |c| c.local_output_path = ... }`).
-
-**A failed delivery is never silent, and never lost.** If the endpoint refuses
-the run (a `401` from a rotated key, a `400`, a `500`) or cannot be reached at
-all (connection refused, DNS failure, timeout), the formatter prints **one**
-line to stderr naming the status or the error, and writes the payload to
-`log/test_results.jsonl` — the **replay queue**: runs offered to the endpoint
-and not accepted — so the run can be replayed later with
+(or `SpecGuard::RSpec.configure { |c| c.local_output_path = ... }`). The write
+itself is silent when it succeeds — the ordinary case on any machine that can
+create `log/` — and it usually does.
+
+**When the local file cannot be written, the run says so instead.** A read-only
+mount, a full disk, a regular file sitting where the directory should be: both
+Ruby clients print **one** line to stderr naming the **configured** path and the
+underlying error, whatever it is, and the test run is unaffected. The path in
+the line is the client's own — the one your configuration set — and it has to
+be, because a failure like a closed stream carries no path of its own:
+
+```
+SpecGuard: could not write telemetry to log/test_results.local.jsonl
+(IOError: closed stream). The test run is unaffected.
+```
+
+**A failed delivery is never silent, and the run is kept whenever it can be.**
+If the endpoint refuses the run (a `401` from a rotated key, a `400`, a `500`)
+or cannot be reached at all (connection refused, DNS failure, timeout), the
+formatter prints **one** line to stderr naming the status or the error, and
+writes the payload to `log/test_results.jsonl` — the **replay queue**: runs
+offered to the endpoint and not accepted — so the run can be replayed later with
 [`specguard-ingest`](#replaying-a-saved-run--specguard-ingest):
 
 ```
@@ -503,6 +519,23 @@ a reason it can read — an empty body, or the HTML a proxy answers a `413` with
 — prints the bare status line above and is still reported as a refusal, not as
 an error.
 
+**And when the queue cannot be written either, that same line says so.** A
+refused delivery whose `log/` is unwritable — a read-only mount, a full disk, a
+regular file sitting where the directory should be — really does lose the run,
+and the second half of the line reports the queue rather than promising it:
+
+```
+SpecGuard: could not deliver test telemetry (HTTP 401 — the API key was not
+accepted). The replay queue log/test_results.jsonl could not be written either
+(Errno::EACCES: Permission denied @ rb_sysopen - log/test_results.jsonl), so
+this run's telemetry was lost.
+```
+
+Still one line, still the status first — and still no effect on your suite's
+exit code, which is the only promise SpecGuard makes about a run of yours. Both
+Ruby clients behave this way; the Minitest reporter's sentence is the same
+beyond the wording of the fallback clause.
+
 There are **no retries**, and the whole delivery is bounded by `timeout`
 (10 seconds by default, against `Net::HTTP`'s own 60): telemetry is explicitly
 allowed to be lost, and a retry would only double what a hung endpoint can cost
@@ -654,7 +687,11 @@ named, rather than blindly re-sent:
 bundle exec specguard-ingest --from-line 7 log/test_results.jsonl
 ```
 
-The numbering never shifts: line 7 is line 7 of the file you gave it, both times.
+The numbering never shifts between invocations that do not drain: line 7 is
+line 7 of the file you gave it, both times. (`--drain` is the one exception —
+removing the accepted lines renumbers what is left, so a drain report's numbers
+describe the file as it was read, not as the next run finds it; see
+[Draining the queue as it is accepted](#draining-the-queue-as-it-is-accepted---drain).)
 Re-sending a line that already landed is harmless *only* when it carries a
 `ci_run_id` — that is the identity SpecGuard folds a redelivery onto. A line
 **without** one has nothing to fold onto and becomes a second run, and a keyless
@@ -806,6 +843,85 @@ were ingested, so a replayed run becomes the repository's latest. For the case
 this exists to serve — replay the run that just failed, right after fixing the
 credential — that is correct.
 
+#### Draining the queue as it is accepted — `--drain`
+
+The replay queue is *runs offered to the endpoint and not accepted* — and until
+the run is drained, a line the endpoint **did** accept stays in it. The next
+incident's failures append behind it, and "re-running the command is the retry"
+then re-sends every one of those already-accepted runs: harmless when the line
+carries a `ci_run_id` (it folds onto the run it already made), a duplicate row
+when it does not. `--drain` is the opt-in follow-through:
+
+```bash
+bundle exec specguard-ingest --drain log/test_results.jsonl
+```
+
+```
+line 1: accepted — HTTP 202, test_run_id 41f2c9b8, ci_run_id 17442
+line 2: not delivered — HTTP 503 — upstream is down
+specguard-ingest: delivered 1 of 2 runs from log/test_results.jsonl; 1 could not be delivered; 1 accepted line removed from log/test_results.jsonl
+```
+
+Only the lines answered `202` **in this invocation** are removed — there is no
+heuristic and nothing is guessed at, which is the same line the rest of this
+command draws. Everything else stays **byte for byte, in the file's order**:
+
+- **refused** lines — a `400` is refused every time it is offered, and the
+  payload still needs fixing;
+- **undelivered** lines — the endpoint never stored them, so they were never
+  accepted;
+- **unparseable** lines — never a run, so never accepted;
+- **blank** lines — never anything;
+- every line **`--from-line` or `--lines` held back** — it was not sent, so it
+  was not accepted, whatever the endpoint would have said.
+
+The rewrite is **atomic**: a temporary file in the same directory, renamed over
+the original, so a failure mid-drain leaves the file exactly as it was — and
+nothing is written at all unless something was actually accepted.
+
+**The removal renumbers what it leaves.** The rewrite keeps the surviving lines
+byte for byte and in order, and packing them up from the top gives them new
+numbers: a queue of `[accepted, not delivered, accepted]` becomes a two-line
+file whose former lines 2 and 3 are now lines 1 and 2 — while the report above
+still says `line 2`, because that number describes the file **as it was read**.
+That is deliberate: the report is a receipt about the file this invocation
+opened, and emitting post-drain numbers would make it disagree with the file it
+read. So do **not** feed a drain report's numbers to the next command's
+`--from-line` or `--lines` — when lines remain, the summary's drain clause says
+so in as many words. The resume is simply: re-run `--list` to see the
+renumbered file, or run `--drain` again. The "the numbering never shifts"
+guarantee holds between invocations that do not drain.
+
+**A concurrent append is carried.** The formatter appends to the queue with no
+lock, so a run can land while the deliveries are still going. Bytes appended
+after the file was read and before the rewrite are carried into it verbatim.
+One window remains — the instant between the final read and the rename — and
+it is disclosed in the code rather than claimed closed; closing it would take a
+lock in the formatter, which is deliberately not this flag's business.
+
+**Only the replay queue is drained.** Another path is refused with a `2` — the
+local record `log/test_results.local.jsonl` is a development record, not a
+queue, and removing accepted lines from it would delete ordinary laptop runs
+that were never failures. The comparison is exact: the file must be spelled as
+`SPECGUARD_OUTPUT_PATH` (or the default) configures the queue. `--drain` with
+`--list` is refused with a `2` as well — a listing delivers nothing, so there
+is nothing for it to drain.
+
+The removal is **stated, never silent**: the summary gains the clause above,
+and the `--json` document's `summary` carries a `drained` count (absent without
+the flag). When lines remain after the rewrite, the clause carries its second
+half and says so: the surviving lines are renumbered, and the report's numbers
+above — which describe the file as it was read — no longer address it. A drain
+that cannot complete is a `2` — the delivery report still
+prints in full, a warning on stderr names the file, and the file is left as it
+was, because a `0` would read as "drained" about a queue that was not.
+
+When the whole queue was accepted, the file is left **empty**, and the next
+`specguard-ingest` run — with or without `--drain` — sends nothing, warns, and
+exits `0`, exactly as it does over any empty file. Draining by default is
+deliberately not the behaviour: a tool that deletes your queue unless told not
+to has made the product decision for you.
+
 #### Machine-readable output — `--json`
 
 An HTTP `400` is the one **permanent** verdict in the table above: a refused line
@@ -863,6 +979,7 @@ bundle exec specguard-ingest --json log/test_results.jsonl
 | `summary.blank` / `skipped` | the two ways a line of the file is not a row here, counted rather than dropped |
 | `summary.absent` | the `--lines` numbers the file does not have, in the shorthand you typed them — a number or an `N-M` range per entry — or `null` when the selector was fully satisfied; never `[]`, on `selector`'s terms |
 | `summary.selector` | `"--lines"`, `"--from-line"`, or `null` when nothing was held back |
+| `summary.drained` | with `--drain`: how many accepted lines were removed from the file — `0` where the flag asked and nothing was accepted. Absent without the flag, and never present under `--list`, which cannot drain. When `drained` is greater than `0`, each `lines[].number` refers to the file **before** the drain: the rewrite renumbers the lines it leaves, so those numbers describe the file as it was read and no longer address the rewritten file |
 | `lines[]` | one entry per row, in the file's order |
 | `foldings[]` | folding, **observed**: the lines that went out with one `ci_run_id` and came back with one `test_run_id`. The same statement the text report makes as a sentence |
 

data/lib/specguard/minitest/reporter.rb

@@ -61,24 +61,54 @@ module SpecGuard
       # and would surface as noise. The RSpec formatter's `capture` makes the
       # equivalent call about a metadata-less example.
       class << self
-        # `Dir.pwd` at load time, not per row: a reporter constructed inside a
-        # test that changes the working directory would otherwise relativize
-        # one suite's rows against two different roots.
+        # `Dir.pwd` bound once — by the first `Reporter.new` (whose
+        # `#initialize` reads it, SPGD-1421) or the first direct read — never
+        # per row: a reporter constructed inside a test that changes the
+        # working directory would otherwise relativize one suite's rows
+        # against two different roots. The memo is what binds it — an
+        # unmemoized `Dir.pwd` here re-reads the cwd on every row and is
+        # exactly the two-root split this comment names, with both spellings
+        # individually well-formed so nothing downstream can detect the
+        # drift. The memo is also the ONE value the annotation lookup reads
+        # against: `#initialize` hands it over, so the relativization root
+        # and the lookup's read root cannot drift apart the way they did when
+        # each bound `Dir.pwd` at its own moment.
         def repo_root
-          Dir.pwd
+          @repo_root ||= Dir.pwd
         end
       end
 
       def initialize(configuration: SpecGuard::RSpec.configuration,
                      transport: nil, output: $stderr,
-                     annotations: SpecGuard::RSpec::AnnotationLookup.new,
+                     annotations: nil,
                      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
         @configuration = configuration
         # Injected for the specs; the real thing is built the same way the
         # RSpec formatter builds it, from the same configuration object.
         @transport = transport
         @output = output
-        @annotations = annotations
+        # ONE binding, ONE moment (SPGD-1421). The relativization root and the
+        # annotation lookup's read root used to be bound separately: the memo
+        # below lazily, on the FIRST row; the lookup's `Dir.pwd` at
+        # construction. A run whose cwd moved to an ANCESTOR of the
+        # construction directory in between relativized its rows against the
+        # moved-to directory and resolved them against the construction one —
+        # `<root>/work/sample_test.rb` under construction root `<root>/work`
+        # reads as `work/sample_test.rb`, which the lookup expanded into the
+        # doubled `<root>/work/work/...` no file answers — so every readable,
+        # correctly annotated spec in the run shipped `unannotated`, with
+        # nothing downstream able to tell. Both halves now read one value,
+        # bound at construction — the earlier of the two moments, and the one
+        # SPGD-1417 already gave the lookup. Reading the memo here is
+        # load-bearing even when a lookup is injected (the specs do): it pins
+        # the relativization root at construction, so no row can ever bind it
+        # somewhere the lookup is not. The default lookup is handed that same
+        # value; `#relative_path` reads the same memo. (SPGD-1429 extends the
+        # same one-binding hand-over to the RSpec formatter: its constructor
+        # binds one root, hands it to the default lookup, and pins rspec-core's
+        # lazily memoized relativization regex to the same moment.)
+        root = self.class.repo_root
+        @annotations = annotations || SpecGuard::RSpec::AnnotationLookup.new(root: root)
         @clock = clock
         @rows = []
         @started_at = nil
@@ -198,7 +228,7 @@ module SpecGuard
       # to the transport, whose own contract is that nothing escapes it — a
       # non-success `Result` costs one stderr line and a queued run.
       def deliver(data)
-        return append(data, @configuration.local_output_path) if @configuration.api_key.to_s.strip.empty?
+        return append_local(data) if @configuration.api_key.to_s.strip.empty?
 
         if @configuration.commit_sha.to_s.strip.empty?
           return fall_back(data, "no commit sha could be resolved (set SPECGUARD_COMMIT_SHA)")
@@ -317,17 +347,69 @@ module SpecGuard
 
       # One JSON run per line, to whichever file this delivery's outcome
       # warrants (see `#deliver` for which and why).
+      #
+      # Returns the exception the write died of, or `nil` when it landed,
+      # rather than warning itself. Both call sites need the outcome *in* their
+      # own sentence — the keyless branch has no preceding line and says so
+      # directly, the fall-back folds it into the delivery line it is already
+      # spending the run's one warning on — and a warning here would reach
+      # `warn_once` first on the fall-back path and spend that budget on the
+      # generic write message, losing the HTTP status the operator needs
+      # (SPGD-1413). `Interrupt` stays outside the clause, as everywhere else
+      # in this class.
       def append(data, path)
         FileUtils.mkdir_p(File.dirname(path))
         File.open(path, "a") { |f| f.puts(JSON.generate(data)) }
+        nil
       rescue ScriptError, StandardError => e
-        warn_once("could not write telemetry to #{path} (#{e.class}: #{e.message}). The test run is unaffected.")
+        e
+      end
+
+      # The keyless branch's write, and its own warning. Nothing preceded it on
+      # this path, so the budget is free and the failure gets the whole line —
+      # naming the configured sink path, which is the one fact `#report`'s
+      # outer handler could not supply if this were left to raise.
+      def append_local(data)
+        path = @configuration.local_output_path
+        error = append(data, path)
+        return if error.nil?
+
+        warn_once("could not write telemetry to #{path} " \
+                  "(#{error.class}: #{error.message}). The test run is unaffected.")
       end
 
+      # The refused-delivery sink, and the one line the run is allowed to
+      # report it on.
+      #
+      # == The order, which SPGD-1400 fenced and SPGD-1413 kept
+      #
+      # `reason` is still what the one allotted line is spent on — the status
+      # and the platform's own words, the fact that tells an operator what to
+      # DO. That was the argument for warning before the write and it has not
+      # moved: nothing else may take this budget, which is why `#append` no
+      # longer warns for itself.
+      #
+      # What moved is the *sink clause*. It used to promise the replay queue
+      # before the write that fills it had been attempted, and was never
+      # corrected when that write failed: `warn_once` returns on `@warned`, so
+      # `#append`'s rescue fired into a no-op and a lost run printed "The test
+      # run is unaffected." The clause is now composed after the write, from
+      # `#append`'s answer, so it reports the queue rather than promising it.
+      # One line, same order of reasoning, and the promise is only made when it
+      # is true.
       def fall_back(data, reason)
-        warn_once("could not deliver test telemetry (#{reason}). Falling back to the replay queue. " \
-                  "The test run is unaffected.")
-        append(data, @configuration.output_path)
+        path = @configuration.output_path
+        error = append(data, path)
+        warn_once("could not deliver test telemetry (#{reason}). #{sink_clause(path, error)}")
+      end
+
+      # Report, not promise — see `#fall_back` for why that is the whole of
+      # this slice, and why the order above it did not move.
+      def sink_clause(path, error)
+        return "Falling back to the replay queue. The test run is unaffected." if error.nil?
+
+        "The replay queue #{path} could not be written either " \
+          "(#{error.class}: #{error.message}), so this run's telemetry was lost."
       end
 
       # Once per process, like the formatter's `warn_once`: fifty failing

data/lib/specguard/rspec/annotation_lookup.rb

@@ -87,7 +87,12 @@ module SpecGuard
     #     nobody;
     #   * an `@intent:` whose payload could not be captured or parsed
     #     ({Finding#problem?} — `KIND_EXTRACTION` / `KIND_PARSE`);
-    #   * a file that could not be read at all (`KIND_READ`);
+    #   * a file that could not be read at all (`KIND_READ`) — read against
+    #     the root bound at construction, never against wherever the cwd has
+    #     since moved, so a readable, correctly annotated spec no longer turns
+    #     unreadable just because the suite changed directory. What still
+    #     lands here is a path that names nothing under that root: genuinely
+    #     absent, or relative to some other root this run never bound;
     #   * a syntactically fine annotation the schema rejects;
     #   * the schema itself failing to load.
     #
@@ -148,11 +153,38 @@ module SpecGuard
       # path cannot drift apart.
       EMPTY_INDEX = Index.new({}.freeze, {}.freeze).freeze
 
+      # The read root, bound here at construction rather than per read. Both
+      # clients build one lookup at suite start ({Formatter}'s and
+      # {Reporter}'s constructors default it in) and then hand it
+      # repo-relative paths, and a suite is free to change the working
+      # directory between those two moments. Resolving per read would open
+      # every relative spelling against wherever the cwd had since moved —
+      # a readable, correctly annotated spec file that no longer resolves
+      # from the new cwd answers {EMPTY_INDEX}, which is byte-for-byte what a
+      # genuinely unannotated example reports, so nothing downstream could
+      # detect the loss. Binding here keeps one run on one root — the same
+      # one-binding-per-run rule the reporter already applies to its own
+      # relativization, applied to the lookup's half of the pipeline. When
+      # the cwd never moves, resolution is the identity on every path the
+      # suite hands over.
+      #
+      # SPGD-1421 added the `root` parameter for the same one-binding rule one
+      # level up: the client binds its own relativization root at construction
+      # and hands that value here, so both halves of one run resolve against
+      # ONE root instead of each reading `Dir.pwd` at its own moment. Both
+      # Ruby clients hand that value over now — the Minitest reporter since
+      # SPGD-1421, the RSpec formatter since SPGD-1429. The default keeps
+      # this constructor's own SPGD-1417 binding — the caller's cwd, read at
+      # construction, never re-read per read.
+      #
       # @param env [Hash, ENV] where `SPECGUARD_VALIDATE_INTENT` is read from.
       #   Injected for testing, and read LAZILY — see {#backend}.
-      def initialize(env: ENV)
+      # @param root [String] the directory relative spellings resolve against;
+      #   bound here, no later than construction, whatever its source.
+      def initialize(env: ENV, root: Dir.pwd)
         @env = env
         @indexes = {}
+        @root = root
       end
 
       # The intent to attach to one example, or nil when it is unannotated.
@@ -165,7 +197,9 @@ module SpecGuard
       # what keeps "warns once" from becoming "warns once but rescans the file
       # for every one of the remaining examples".
       #
-      # @param file [String, nil] the example's file, as the payload records it
+      # @param file [String, nil] the example's file, as the payload records it.
+      #   A relative spelling is resolved against the root bound at
+      #   construction — see {#initialize} — and never against the live cwd.
       # @param line [Integer, nil] `example.metadata[:line_number]`
       # @return [Hash, nil] the parsed, schema-valid annotation
       def intent_for(file:, line:)
@@ -245,16 +279,43 @@ module SpecGuard
 
       # @return [Index]
       def build_index(file)
+        # One resolution for both legs: the local read below and the validator
+        # subprocess (#verdicts_for -> Runner#check) must answer about the SAME
+        # file, and the child inherits this process's working directory rather
+        # than being told one — so an unresolved relative spelling used to fail
+        # on both legs at once, which is why the degradation was total.
+        # Resolving before either leg runs gives both one path. The memo
+        # stays keyed by the caller's spelling; the resolution is
+        # deterministic per construction, so the two can never disagree.
+        resolved = resolve_path(file)
+
         # The read happens on BOTH paths and first on both. The backend does not
         # need it to find annotations — it reads the file itself — but the
         # comment-form rule below is a property of the LINE an annotation sits
         # on, which no report carries, so the text is required either way. Doing
         # it first also keeps the two paths agreeing about an unreadable file
         # without a subprocess being started to rediscover it.
-        text = read(file)
+        text = read(resolved)
         return EMPTY_INDEX if text.nil?
 
-        index_from(verdicts_for(file, text), text)
+        index_from(verdicts_for(resolved, text), text)
+      end
+
+      # A caller-named path, made absolute against the root {#initialize} bound.
+      #
+      # Absolute spellings pass through untouched — they are what every existing
+      # caller hands over, and expanding them could only normalize a string the
+      # caller meant literally. A leading `~` passes through too:
+      # {File.expand_path} would resolve it against `$HOME` even with a root
+      # given, and a path that could not be read before resolution existed must
+      # keep reading as unreadable, not start reading somewhere new.
+      #
+      # @param file [String] a non-empty path, as the caller named it
+      # @return [String]
+      def resolve_path(file)
+        return file if file.start_with?(File::SEPARATOR, "~")
+
+        File.expand_path(file, @root)
       end
 
       # One shell-out per FILE, which is the cost model this class already
@@ -337,6 +398,10 @@ module SpecGuard
       # class filters out, and nil here becomes {EMPTY_INDEX}. Either way, every
       # example in a file that could not be read is unannotated.
       #
+      # {#build_index} hands the path over already resolved — once for both
+      # this leg and the validator subprocess — so `file` here opens the same
+      # file whichever leg asks, wherever the cwd has since moved.
+      #
       # @return [String, nil]
       def read(file)
         File.read(file, encoding: "UTF-8")

data/lib/specguard/rspec/formatter.rb

@@ -255,6 +255,24 @@ module SpecGuard
       example_started example_passed example_failed example_pending dump_summary
     ].freeze
 
+    class << self
+      # `Dir.pwd` bound once — by the first formatter construction (whose
+      # `#initialize` reads it, SPGD-1429) or the first direct read — never
+      # per row: a suite that changes the working directory after the
+      # formatter was built would otherwise relativize one run's rows
+      # against two different roots. The memo is what binds it — an
+      # unmemoized `Dir.pwd` here re-reads the cwd on every read and is
+      # exactly the two-root split the constructor's comment names, with
+      # both spellings individually well-formed so nothing downstream can
+      # detect the drift. The memo is also the ONE value the default
+      # annotation lookup reads against: `#initialize` hands it over, so
+      # the relativization root and the lookup's read root cannot drift
+      # apart the way they did when each bound `Dir.pwd` at its own moment.
+      def repo_root
+        @repo_root ||= Dir.pwd
+      end
+    end
+
     # @param output [IO] the stream RSpec hands every formatter. This class's
     #   product is a file, so nothing in the capture path writes here — but the
     #   stream is *not* unused, and a reader who is here because stdout went
@@ -287,11 +305,40 @@ module SpecGuard
     #   `SpecGuard::AnnotationLookup`, neither of which exists — a NameError
     #   raised from a formatter's constructor, which RSpec reports as
     #   "No examples found".
-    def initialize(output = nil, error_stream: $stderr,
-                   annotations: SpecGuard::RSpec::AnnotationLookup.new)
+    #
+    #   Omitted or nil, the constructor builds the default lookup itself and
+    #   hands it the one root bound below — the only construction production
+    #   ever runs, and the arm that makes the hand-over observable.
+    def initialize(output = nil, error_stream: $stderr, annotations: nil)
       super(output)
+      # ONE binding, ONE moment (SPGD-1429). This constructor used to bind two
+      # roots at two moments and nothing made them agree: the lookup's read
+      # root here, at construction, and rspec-core's relativization root —
+      # `Metadata.relative_path_regex` memoizes `Dir.pwd` on its first READ —
+      # on the first captured row, after the spec files have loaded. A suite
+      # whose cwd moves to a SHALLOWER ancestor in between relativized its
+      # rows against the moved-to directory and resolved those spellings
+      # against the construction one — `<root>/work/sample_spec.rb` read as
+      # `work/sample_spec.rb` under construction root `<root>/work` resolves
+      # into the doubled `<root>/work/work/...`, which no file answers — so
+      # every readable, correctly annotated spec in the run shipped
+      # `unannotated` with nothing downstream able to tell. The same
+      # two-root split `SPGD-1421` closed on the Minitest reporter, whose
+      # `reporter.rb` comment is the reference for this repair. Both halves
+      # now read one value, bound at construction — the earlier of the two
+      # moments, and the one `SPGD-1417` already gave the lookup.
+      #
+      # Reading the memo is load-bearing even when a lookup is injected (the
+      # specs do): `#relative_path` delegates to rspec-core either way, so
+      # pinning the regex here is what stops any row from binding it somewhere
+      # the lookup is not. The reader binds only when unbound — when something
+      # has already bound it, the read is a no-op and rspec-core's own value
+      # is left alone: its memoization is correct for what it does, and
+      # overwriting a bound value would second-guess it.
+      root = self.class.repo_root
+      ::RSpec::Core::Metadata.relative_path_regex
       @error_stream = error_stream
-      @annotations = annotations
+      @annotations = annotations || SpecGuard::RSpec::AnnotationLookup.new(root: root)
       @specs = []
       @warned = false
       # Stamped here rather than from a `start` hook on purpose. `:start` is not
@@ -666,9 +713,15 @@ module SpecGuard
     # Sink selection, and the fallback that keeps a failed delivery from being
     # a silent one.
     #
-    # Called from inside {#never_fail_the_run}, so nothing below has to guard
-    # itself against raising — including the fallback `append`, whose own
-    # failure modes (unwritable `log/`, full disk) are already covered there.
+    # Called from inside {#never_fail_the_run}, so a raise below it cannot
+    # fail the run — but neither arm leaves its failure to that generic
+    # envelope, because each spends the run's one warning on a line that has
+    # to say what actually happened. {#append} catches the sink's failure
+    # modes itself and hands the outcome back, so the one line {#fall_back} is
+    # spending can report whether the queue took the run rather than promise
+    # it (SPGD-1413); the keyless {#append_local} does the same and names the
+    # configured sink path in the line it emits, the way the Minitest twin
+    # does (SPGD-1400). Nothing raises out of either way.
     #
     # == Why a failure writes the file rather than shrugging
     #
@@ -954,12 +1007,27 @@ module SpecGuard
       count == 1 ? noun : "#{noun}s"
     end
 
+    # The delivery failed; this is the second sink and the one line the run is
+    # allowed to say so on.
+    #
+    # == The order, which SPGD-1400 fenced and SPGD-1413 kept
+    #
+    # `reason` is still the first thing settled and still the fact the one
+    # allotted line is spent on: a 401 and a 400 call for entirely different
+    # actions, and no amount of detail about a file substitutes for the status.
+    # That was the argument for warning before the write, and it is unchanged.
+    #
+    # What moved is only the *sink clause*. It used to be a promise — "falling
+    # back to <path>; the test run is unaffected" — emitted before the write it
+    # described, and never corrected when that write failed: `emit_warning`
+    # returns on `@warned`, so the second failure had no budget left to report
+    # itself and a lost run printed a line saying it was safe. The clause is now
+    # composed *after* the write, from {#append}'s own answer, so it reports the
+    # queue rather than promising it. One line, same order of reasoning, and the
+    # promise is only made when it is true.
     def fall_back(data, reason)
-      # Warned before the write, not after: if the fallback write *also* fails,
-      # the outer guard's one allotted warning has already been spent on the
-      # more specific message, which is the one naming the status code.
-      warn_delivery_failure(reason)
-      append(data)
+      path = SpecGuard::RSpec.configuration.output_path
+      warn_delivery_failure(reason, path: path, error: append(data, path))
     end
 
     def transport_for(configuration)
@@ -1033,20 +1101,49 @@ module SpecGuard
       (::RSpec::Core::Metadata.relative_path(string) || string).sub(%r{\A\./}, "")
     end
 
-    # Appends one line. Opened in append mode and written with a single call so
-    # that two suites sharing an output path (parallel CI shards, say) interleave
-    # whole runs rather than halves of one.
-    def append(data)
-      path = SpecGuard::RSpec.configuration.output_path
+    # Appends one line to the replay queue. Opened in append mode and written
+    # with a single call so that two suites sharing an output path (parallel CI
+    # shards, say) interleave whole runs rather than halves of one.
+    #
+    # `path` is passed in rather than read here, so the line {#fall_back}
+    # composes and the file it describes are provably the same string — a
+    # second read of a process-wide singleton could answer differently and name
+    # a path nothing was written to.
+    #
+    # Returns the exception the write died of, or `nil` when it landed — the
+    # fall-back's one line is composed from that answer (see {#fall_back}), and
+    # a raise here could not be, because `close`'s {#never_fail_the_run} would
+    # only reach a warning budget the delivery message has already spent.
+    # `Interrupt` is deliberately outside the clause, as everywhere else in this
+    # file: Ctrl-C must stay Ctrl-C.
+    def append(data, path)
       append_to(data, path)
+      nil
+    rescue ScriptError, StandardError => e
+      e
     end
 
     # The keyless branch's sink: `local_output_path`, a local development
     # record deliberately kept apart from {#append}'s replay queue so that
     # `specguard-ingest log/test_results.jsonl` re-delivers only genuine
     # failed deliveries. See {Configuration#local_output_path}.
+    #
+    # Its failure is its own line rather than {#never_fail_the_run}'s generic
+    # substitute: the path is knowable here — read once into a local, for the
+    # same reason {#append} takes one — and the Minitest twin names it on the
+    # same input (SPGD-1400), as does this file's delivery arm through
+    # {#sink_clause} (SPGD-1413). The write goes through {#append} so the
+    # exception comes back as a value to compose the line from; left to raise,
+    # it would fall through to {#never_fail_the_run} and spend the run's one
+    # warning on the one sentence this exists to replace. `Interrupt` stays
+    # outside, as everywhere else in this file.
     def append_local(data)
-      append_to(data, SpecGuard::RSpec.configuration.local_output_path)
+      path = SpecGuard::RSpec.configuration.local_output_path
+      error = append(data, path)
+      return if error.nil?
+
+      emit_warning("SpecGuard: could not write telemetry to #{path} " \
+                   "(#{error.class}: #{error.message}). The test run is unaffected.")
     end
 
     def append_to(data, path)
@@ -1079,11 +1176,30 @@ module SpecGuard
     # status when there was one — a 400 and a 401 call for entirely different
     # actions, and a warning that only said "delivery failed" would leave the
     # reader unable to tell which.
-    def warn_delivery_failure(reason)
-      path = SpecGuard::RSpec.configuration.output_path
+    #
+    # `error` is {#append}'s answer, and it decides the line's second clause
+    # only. `nil` means the queue took the run, and the sentence is exactly the
+    # one this formatter has always printed. Anything else means both sinks are
+    # gone: the run really is lost, and the line says so rather than promising a
+    # file that is not there (SPGD-1413). The status clause is identical either
+    # way, because which of the two happened does not change what refused the
+    # delivery.
+    #
+    # Both are required rather than defaulted. There is one call site, and a
+    # default would be a branch no input could reach — the same objection
+    # {#annotated_percentage} states about an unreachable zero-guard.
+    def warn_delivery_failure(reason, path:, error:)
+      emit_warning("#{DELIVERY_WARNING_PREFIX} (#{reason}). #{sink_clause(path, error)}")
+    end
+
+    # Report, not promise. Composed after the write so it can tell the operator
+    # which of the two things actually happened — see {#fall_back} for why that
+    # is the whole of this slice, and why the order above it did not move.
+    def sink_clause(path, error)
+      return "Falling back to #{path}; the test run is unaffected." if error.nil?
 
-      emit_warning("#{DELIVERY_WARNING_PREFIX} (#{reason}). " \
-                   "Falling back to #{path}; the test run is unaffected.")
+      "The replay queue #{path} could not be written either " \
+        "(#{error.class}: #{error.message}), so this run's telemetry was lost."
     end
 
     def emit_warning(line)

data/lib/specguard/rspec/ingest_cli.rb

@@ -162,6 +162,43 @@ module SpecGuard
     # convention and the shell's; this file adopts it on purpose and pins it in
     # the spec, so it is a decision rather than a default nobody looked at.
     #
+    # == `--drain`, the follow-through, and why it removes only what it saw
+    #
+    # A successful replay used to leave the queue byte-identical: this file had
+    # no write, rename or truncate path, so the next incident's failures
+    # appended behind runs that had already landed, and the README's retry
+    # gesture — re-running the command — re-sent every one of them. A line with
+    # a `ci_run_id` folds onto the run it already made, so re-sending it is
+    # harmless; a line without one has nothing to fold onto and becomes a
+    # second row on the platform. `--drain` is the opt-in answer: after the
+    # deliveries, exactly the lines answered 202 **in this invocation** are
+    # removed from the file.
+    #
+    # Only those. The removal is keyed to what was *observed*, never to what
+    # was inferred — the same line this file draws against guessing which lines
+    # were failures. A refused line is refused every time it is offered, an
+    # undelivered one never arrived, an unparseable one was never a run, a
+    # blank one was never anything, and a line a selector held back was never
+    # sent — so all of them stay, byte for byte, in the file's order. The queue
+    # is failure-only by construction, which is what makes removing accepted
+    # lines coherent here in a way it would not be on the mixed local record:
+    # draining a file of ordinary laptop runs would delete runs that were
+    # never failures. That is the second guard — the drain refuses any path
+    # that is not the configured replay queue, compared exactly as
+    # {#no_such_file_message} compares, and it refuses `--list` too, since a
+    # listing delivers nothing for it to drain.
+    #
+    # The rewrite is atomic: a temporary file in the same directory, renamed
+    # over the original, so a failure mid-drain leaves the file as it was —
+    # and the file is not touched at all unless something was accepted. Bytes
+    # appended while the deliveries ran (the formatter appends to the queue
+    # with no lock) are carried into the rewrite; the window that remains
+    # between the final read and the rename is disclosed at {#drain_source},
+    # not claimed closed. A drain that cannot complete is stated, never
+    # silent: the deliveries are still reported in full, the warning names the
+    # file, and the run exits 2, because a 0 would read as "drained" about a
+    # queue that was not.
+    #
     # == `--list`, which is what makes "check the file first" an instruction
     #
     # Having refused to guess *for* the user, this command owes them what they
@@ -218,20 +255,26 @@ module SpecGuard
       BANNER = "Usage: specguard-ingest [options] <file>"
 
       # Shown by `--help`. The second paragraph is the one that has to be there:
-      # the sink mixes failed deliveries with ordinary keyless local runs and
-      # nothing on the line tells them apart, so a developer must not be able to
+      # the local record — and any replay-queue file from before the sink split
+      # — mixes failed deliveries with ordinary keyless local runs and nothing
+      # on the line tells them apart, so a developer must not be able to
       # discover only afterwards that they pushed their laptop's history.
       DESCRIPTION = <<~TEXT.freeze
-        Re-delivers a saved run to SpecGuard's ingest endpoint. <file> is a
-        log/test_results.jsonl written by the RSpec formatter — one whole run per
-        line, byte-for-byte the body the endpoint was offered.
+        Re-delivers a saved run to SpecGuard's ingest endpoint. <file> is a file
+        the RSpec formatter wrote — one whole run per line, byte-for-byte the
+        body the endpoint was offered. The formatter writes failed deliveries
+        to the replay queue, log/test_results.jsonl, and — when no API key is
+        configured — ordinary local runs to the local development record,
+        log/test_results.local.jsonl.
 
         EVERY line in <file> is delivered — or, when you narrow it, every line
-        --from-line or --lines names. The formatter writes to this file both
-        when a delivery failed and when no API key was configured at all, and
-        the two are indistinguishable on the line, so a laptop's file is a file
-        of ordinary local runs and all of them will be sent. Nothing is
-        filtered and nothing is guessed at.
+        --from-line or --lines names. The two files were split precisely so a
+        log/test_results.jsonl written entirely by this version or later could
+        hold only genuine failed deliveries — by construction. But the local
+        record, and any file written before the split, carries no marker: a
+        laptop's file is a file of ordinary local runs mixed with genuine
+        failures, indistinguishable on the line, and all of them will be sent.
+        Nothing is filtered and nothing is guessed at.
 
         So check the file first: --list prints one row per line — branch, commit,
         ci_run_id or its absence, how many examples, how long — and delivers
@@ -246,6 +289,22 @@ module SpecGuard
         that same numbering, instead of re-sending all of it. Both narrow the
         same file, so give one or the other and never both.
 
+        --drain is the follow-through, and it is opt-in: after the deliveries,
+        the lines this invocation got a 202 for are removed from <file>, so the
+        next incident's failures do not land behind runs that already landed.
+        Everything else stays byte for byte and in order — refused, undelivered,
+        unparseable and blank lines, and every line --from-line or --lines held
+        back. Removing lines renumbers what is left: the report's line numbers
+        describe <file> as it was read, not as the next run finds it, so resume
+        by re-running --list (or --drain) rather than reusing those numbers.
+        The rewrite is atomic: a temporary file in the same directory,
+        renamed over the original, so a failure mid-drain leaves the file as it
+        was, and bytes appended while the deliveries ran are carried into the
+        rewrite. Only the replay queue is drained — another path is refused,
+        because the local record is a development record, not a queue — and
+        --drain with --list is refused too, since a listing delivers nothing
+        for it to drain.
+
         Reads SPECGUARD_ENDPOINT, SPECGUARD_API_KEY and SPECGUARD_TIMEOUT.
 
         --json replaces the human report with one JSON document on stdout, in
@@ -264,10 +323,11 @@ module SpecGuard
              an unreadable file, an unparseable line, a delivery that never
              reached the endpoint, or one the endpoint answered without ever
              reading it (401, 404, 429, 5xx — nothing was stored, so none of
-             them is a verdict about your run). With --list the only reachable
-             2s are a bad flag and a file that cannot be read: listing needs no
-             credentials, and an unparseable line becomes a row in the listing
-             rather than an exit code
+             them is a verdict about your run). With --drain, a rewrite that
+             could not complete is a 2 as well — the file is left as it was.
+             With --list the only reachable 2s are a bad flag and a file that
+             cannot be read: listing needs no credentials, and an unparseable
+             line becomes a row in the listing rather than an exit code
       TEXT
 
       # Every line in the file was accepted by the endpoint — including the
@@ -360,8 +420,36 @@ module SpecGuard
       # selector was fully satisfied, and empty under `--from-line`, whose
       # past-the-end case is already a suffix that selected nothing.
       #
+      # `raw` and `read_bytes` are the drain's inputs, captured by
+      # {#read_source} and by nothing else: the file's exact bytes as of the
+      # read, and that read's length in bytes. The rebuild keeps `raw`'s lines
+      # minus the accepted numbers — which is what makes "byte for byte" a
+      # property of the rewrite rather than a hope — and `read_bytes` is where
+      # the tail starts: anything appended past it while the deliveries ran is
+      # carried into the rewrite verbatim. They are members of {Source} rather
+      # than a second read inside {#drain_source} because the length that
+      # matters is the one the numbered lines were counted against; a fresh
+      # read at drain time would answer a different read.
+      #
       # @return [Array<String>] `absent`, each entry a number or an `N-M` range
-      Source = Struct.new(:path, :lines, :blank, :skipped, :absent, :selector, keyword_init: true)
+      Source = Struct.new(:path, :lines, :blank, :skipped, :absent, :selector,
+                          :raw, :read_bytes, keyword_init: true)
+
+      # What `--drain` did, decided once in {#drain_source} and rendered by
+      # both renderers — the same one-fact-two-renderings discipline the status
+      # counts and the folding groups are held to. `removed` is the count of
+      # lines taken out of the file (0 when nothing was accepted, so no rewrite
+      # happened at all), `remaining` is the count of lines the rewrite LEFT in
+      # the file — `kept + appended`, counted as lines (blank lines and the
+      # carried tail included), so a renderer can tell a queue that still holds
+      # work from one the drain emptied. `remaining` is meaningful only where a
+      # rewrite actually happened: on the no-accept and failed paths the file
+      # did not move, so it stays `nil`. `failed` is a rewrite that could not
+      # complete: the file was left as it was, the warning is already on
+      # stderr, and the exit code is a 2, because a 0 would read as "drained"
+      # about a queue that was not. `nil` — no {Drain} at all — is the flag's
+      # absence, and both renderers render nothing for it.
+      Drain = Struct.new(:removed, :remaining, :failed, keyword_init: true)
 
       # What the command line asked for. A struct rather than a bare path,
       # because `--from-line` is the second half of the same question — which
@@ -371,12 +459,15 @@ module SpecGuard
       # starting point, and the two are mutually exclusive (see the class
       # comment). `list` is the third half: whether those lines are to be
       # *shown* or *sent*. `json` is orthogonal to all three — it chooses the
-      # renderer, never the set and never the verdict.
+      # renderer, never the set and never the verdict. `drain` is the one
+      # member about what happens *after* the sending: whether the lines this
+      # invocation got a 202 for are to be removed from <file> once the
+      # deliveries are done.
       #
       # `line_set` is an Array of Ranges rather than an expanded Array of
       # Integers, so `--lines 1-90000000` costs nothing to hold. `nil` means the
       # flag was not given and `from_line` is the selector.
-      Options = Struct.new(:path, :from_line, :list, :line_set, :json, keyword_init: true)
+      Options = Struct.new(:path, :from_line, :list, :line_set, :json, :drain, keyword_init: true)
 
       # One entry of a `--lines` spec: `12` or `12-15`, and nothing else. No
       # sign, no open end, no whitespace inside — {#parse_line_set} strips each
@@ -425,9 +516,14 @@ module SpecGuard
 
         source = read_source(options)
         results = source.lines.map { |number, text| deliver_line(number, text, transport) }
-
-        report(source, results, json: options.json)
-        exit_code(results)
+        # After the deliveries, before the report — the only position where the
+        # summary can state what the drain removed. `drained` is nil without
+        # the flag, and both renderers render nothing for it, which is the
+        # whole of the flag being opt-in.
+        drained = options.drain ? drain_source(source, results) : nil
+
+        report(source, results, json: options.json, drained: drained)
+        exit_code(results, drained: drained)
       rescue Errno::EPIPE
         # The report's reader stopped listening — `| head`, a quitting pager,
         # a CI log tailer. The deliveries happened and the per-line verdicts
@@ -436,7 +532,7 @@ module SpecGuard
         # nil on the `--list` path, which builds none, and when the pipe
         # closed before any delivery was made; then {EXIT_OK} stands. See
         # the class comment.
-        results ? exit_code(results) : EXIT_OK
+        results ? exit_code(results, drained: drained) : EXIT_OK
       rescue UsageError => e
         @stderr.puts "specguard-ingest: error: #{e.message}"
         EXIT_MISUSE
@@ -455,7 +551,14 @@ module SpecGuard
       # reached the endpoint leaves the job unfinished, and reporting that as
       # "your content was refused" is the exact confusion the contract exists to
       # prevent.
-      def exit_code(results)
+      #
+      # `drained` joins the dominance list ahead of the content verdicts, on
+      # the same grounds: a drain that could not complete left the queue
+      # holding everything it held before, accepted lines included, and
+      # reporting that as "your content was refused" (or as a clean 0) would
+      # both be the wrong shout.
+      def exit_code(results, drained: nil)
+        return EXIT_MISUSE if drained&.failed
         return EXIT_MISUSE if results.any? { |result| %i[undelivered unparseable].include?(result.status) }
         return EXIT_REFUSED if results.any? { |result| result.status == :refused }
 
@@ -662,7 +765,7 @@ module SpecGuard
       #   from, which is not a verdict about anybody's run.
       def read_source(options)
         path = options.path
-        raise UsageError, "no such file: #{path}" unless File.exist?(path)
+        raise UsageError, no_such_file_message(path) unless File.exist?(path)
         raise UsageError, "not a file: #{path}" unless File.file?(path)
 
         lines = []
@@ -700,13 +803,50 @@ module SpecGuard
           end
         end
 
+        # The drain's capture, taken AFTER the line walk and for that reason:
+        # read first, length second means `read_bytes` covers everything the
+        # numbered lines were counted against, even where an append landed
+        # between the two reads — such bytes are in `raw` (as extra tail lines
+        # numbered past the delivered set, kept by any rewrite) and past
+        # `read_bytes` is genuinely only what arrived after this method
+        # returned. Reading the bytes first would invert that: a line appended
+        # in the gap could then be delivered AND carried back by the tail.
+        #
+        # Binary on purpose — this is the file's bytes, not its characters.
+        # The default path never looks at either member; the whole capture is
+        # the drain's, and its cost on the default path is one read.
+        raw = File.binread(path)
+
         Source.new(path: path, lines: lines, blank: blank, skipped: skipped,
                    absent: absent_entries(options, length),
-                   selector: options.line_set ? :line_set : :from_line)
+                   selector: options.line_set ? :line_set : :from_line,
+                   raw: raw, read_bytes: raw.bytesize)
       rescue SystemCallError, IOError => e
         raise UsageError, "could not read #{path}: #{e.message}"
       end
 
+      # The `no such file` refusal, with one conditional clause: when the
+      # missing path IS the configured replay queue and the configured local
+      # record exists, name the record. A keyless developer is pointed at
+      # `log/test_results.jsonl` by the help while their run wrote the other
+      # file, and this is the one moment the tool can say so. The guard is the
+      # conjunction — equality, not "the path looks like a queue", and an
+      # existence check, not "the record is merely configured" — so an ordinary
+      # typo keeps the plain message byte-for-byte, and the clause cannot fire
+      # on a relative default that happens to resolve against the working
+      # directory.
+      def no_such_file_message(path)
+        configuration = Configuration.new(env: @env)
+        local = configuration.local_output_path
+        if path == configuration.output_path && File.exist?(local)
+          "no such file: #{path} — the replay queue was never written, but the " \
+            "local record #{local} does exist (what the formatter writes when " \
+            "no API key is configured)"
+        else
+          "no such file: #{path}"
+        end
+      end
+
       # The whole of the selection, and the only place it is decided. `--lines`
       # is an explicit set, so a line it does not name is held back wherever in
       # the file it sits; `--from-line` is a suffix, so only the lines before it
@@ -765,7 +905,7 @@ module SpecGuard
       # renderers can disagree about how much of a file it delivered is worse
       # than one that only prints prose: the disagreement is unfalsifiable from
       # outside the process.
-      def report(source, results, json:)
+      def report(source, results, json:, drained: nil)
         if results.empty?
           @stderr.puts "specguard-ingest: warning: #{source.path} holds no runs to deliver#{empty_detail(source)}"
           return unless json
@@ -776,12 +916,12 @@ module SpecGuard
 
         if json
           @stdout.puts IngestReporter.render_delivery(source: source, results: results, counts: counts,
-                                                      foldings: foldings)
+                                                      foldings: foldings, drained: drained)
           return
         end
 
         results.each { |result| @stdout.puts line_report(result) }
-        @stdout.puts summary_line(source, results, counts)
+        @stdout.puts summary_line(source, results, counts, drained)
         foldings.each { |folding| @stdout.puts folding_observation(folding) }
       end
 
@@ -866,7 +1006,7 @@ module SpecGuard
       # accepted count is over the total rather than on its own, and every other
       # outcome gets a clause of its own instead of being folded into a
       # remainder the reader has to compute.
-      def summary_line(source, results, counts)
+      def summary_line(source, results, counts, drained)
         parts = ["specguard-ingest: delivered #{counts.fetch(:accepted, 0)} of " \
                  "#{results.length} run#{'s' unless results.length == 1} from #{source.path}"]
 
@@ -876,10 +1016,36 @@ module SpecGuard
         parts << blank_clause(source) if source.blank.positive?
         parts << skipped_clause(source) if source.skipped.positive?
         parts << absent_clause(source) if source.absent.any?
+        parts << drain_clause(source, drained) if drained&.removed&.positive?
 
         parts.join("; ")
       end
 
+      # The drain's clause, present exactly when lines were removed and never
+      # otherwise — the summary's established shape, where a clause names a
+      # fact that is positive rather than padding the line with zeroes. The
+      # `removed: 0` of a rewrite that did not happen (nothing was accepted)
+      # needs no clause: the accepted count in the first clause already says
+      # so. The `removed: 0` of a rewrite that FAILED is carried by the stderr
+      # warning and by the exit code, both louder than a clause would be.
+      #
+      # The clause's second half states the consequence the removal has for
+      # the numbers this very report just printed: a rewrite that leaves any
+      # line in the file renumbers them, because the survivors are packed up
+      # from the top — so the numbers above describe the file as it was READ,
+      # not as the next invocation will find it, and must not be reused to
+      # address it. A drain that emptied the file says nothing extra: there is
+      # no number left for the sentence to be about.
+      def drain_clause(source, drained)
+        clause = +"#{drained.removed} accepted line#{'s' unless drained.removed == 1} removed from #{source.path}"
+        return clause unless drained.remaining&.positive?
+
+        left = drained.remaining
+        clause << " — the #{left} line#{'s' unless left == 1} left " \
+                  "#{left == 1 ? 'is' : 'are'} now numbered from 1, so the numbers above " \
+                  "no longer address #{left == 1 ? 'it' : 'them'}"
+      end
+
       # Folding, stated only where it was *seen*.
       #
       # The proposal for this tool asked it to say whether a replayed line
@@ -911,6 +1077,96 @@ module SpecGuard
           "came back with test_run_id #{folding.test_run_id} — the endpoint folded them onto one run"
       end
 
+      # --drain: remove from <file> exactly the lines this invocation got a 202
+      # for, atomically, carrying anything appended while the deliveries ran.
+      #
+      # == What is removed, and what is not
+      #
+      # Only `:accepted` results, by their own file-line numbers — the removal
+      # is keyed to what the endpoint answered this run, never to a guess about
+      # which lines were failures. Everything else {Source#raw} holds is kept:
+      # refused, undelivered and unparseable lines, the blank ones, and every
+      # line a selector held back — each byte for byte, in the file's order.
+      #
+      # == The tail, carried
+      #
+      # The formatter appends to the queue with no lock, so bytes can land
+      # after {#read_source} and before this rewrite. Those bytes are the
+      # tail: everything in the file NOW past the length read then, carried
+      # into the rewrite verbatim. They were never delivered, so the accepted
+      # set can never name them — carrying them is what keeps a concurrent
+      # append from being destroyed by the very run that emptied the queue.
+      #
+      # == The residual race, disclosed rather than closed
+      #
+      # The tail read below is as late as the design can put it, which narrows
+      # the race to read → rename: bytes a formatter appends AFTER that read
+      # but BEFORE {File.rename} lands go to the old inode and are lost when
+      # the rename swaps the directory entry. The window is two syscalls wide
+      # and is NOT closed — closing it would take a lock in the formatter, and
+      # that is deliberately out of scope here. What this code claims is
+      # narrower: everything appended before the final read survives, and a
+      # failure at any point before the rename leaves the original
+      # byte-identical.
+      #
+      # Nothing is written unless something was accepted: a drain over a file
+      # whose every line was refused, or whose selector held everything back,
+      # leaves the file — and its mtime — exactly as it was.
+      #
+      # @return [Drain] what was removed; `failed`, with the warning already
+      #   on stderr, when the rewrite could not complete
+      def drain_source(source, results)
+        accepted = results.select { |result| result.status == :accepted }.map(&:number)
+        return Drain.new(removed: 0, failed: false) if accepted.empty?
+
+        # Binary throughout: `raw` is the file's bytes, and the rebuild is a
+        # byte operation, not a character one. `each_line` splits on the same
+        # `"\n"` the numbering was counted with, so `number` here is the
+        # number the reports printed.
+        kept = String.new(encoding: Encoding::BINARY)
+        source.raw.each_line.with_index(1) do |text, number|
+          kept << text unless accepted.include?(number)
+        end
+
+        current = File.binread(source.path)
+        appended =
+          if current.bytesize > source.read_bytes
+            current.byteslice(source.read_bytes, current.bytesize - source.read_bytes)
+          else
+            String.new(encoding: Encoding::BINARY)
+          end
+
+        rewritten = kept + appended
+        drain_write(source.path, rewritten)
+        # Counted as LINES, on `each_line`'s terms — the same split the
+        # numbering itself was built on — never as bytes: a blank line counts,
+        # and a queue the drain emptied reads 0 rather than 1.
+        Drain.new(removed: accepted.length, remaining: rewritten.each_line.count, failed: false)
+      rescue SystemCallError, IOError => e
+        # Stated, never silent — and reported without costing the delivery
+        # report: stdout below is still the full per-line report, this warning
+        # names the file, and {#exit_code} turns the run into a 2, because a
+        # 0 would read as "drained" about a queue that was not.
+        @stderr.puts "specguard-ingest: warning: could not remove the accepted lines from #{source.path}: " \
+                     "#{e.message} — the file is left as it was"
+        Drain.new(removed: 0, failed: true)
+      end
+
+      # The atomic swap: a temporary file in the SAME directory — `rename` is
+      # only atomic within one filesystem — renamed over the original. A
+      # failure at any point before the rename leaves the original untouched,
+      # and the `ensure` takes the temporary with it.
+      def drain_write(path, content)
+        tmp = File.join(File.dirname(path),
+                        ".#{File.basename(path)}.drain-#{Process.pid}-#{rand(1 << 32).to_s(36)}.tmp")
+        begin
+          File.binwrite(tmp, content)
+          File.rename(tmp, path)
+        ensure
+          File.unlink(tmp) if File.exist?(tmp)
+        end
+      end
+
       # @return [Options, nil] `nil` when `--help` or `--version` has already
       #   said everything the invocation was asking for.
       def parse_options(argv)
@@ -918,6 +1174,7 @@ module SpecGuard
         line_set = nil
         list = false
         json = false
+        drain = false
 
         parser = OptionParser.new do |o|
           o.banner = BANNER
@@ -957,6 +1214,13 @@ module SpecGuard
           o.on("--json", "Emit one JSON document on stdout instead of the human report") do
             json = true
           end
+          # Delivery-shaped and opt-in: it changes nothing about what is sent,
+          # only what happens to <file> afterwards, and the guards below hold
+          # it to the queue and refuse it a listing.
+          o.on("--drain", "After delivering, remove from <file> exactly the lines this run accepted —",
+               "atomically, keeping every other line byte for byte") do
+            drain = true
+          end
           o.on("-v", "--version", "Print the version and exit") do
             @stdout.puts "specguard-ruby #{VERSION}"
             return nil
@@ -978,7 +1242,35 @@ module SpecGuard
           raise UsageError, "--from-line and --lines both choose which lines to send; give one or the other"
         end
 
-        Options.new(path: files.first, from_line: from_line || 1, list: list, line_set: line_set, json: json)
+        # `--drain` follows the delivery; `--list` is the refusal to deliver.
+        # They are not an intersection to resolve but two answers to "does this
+        # run send anything", and a listing that also drained would either
+        # drain nothing silently or drain without the deliveries the removal
+        # is keyed to — both are the quiet-failure shape this file refuses.
+        if drain && list
+          raise UsageError, "--drain delivers and removes the lines that were accepted; " \
+                            "--list delivers nothing, so there is nothing for it to drain"
+        end
+
+        # The drain may empty the replay queue and nothing else. A path that
+        # is not {Configuration#output_path} is either the local record — a
+        # development record of ordinary keyless runs, not a queue, where
+        # removing accepted lines would delete runs that were never failures —
+        # or a file this invocation was pointed at by mistake. The comparison
+        # is exact string equality, the one {#no_such_file_message} makes: a
+        # path spelled differently from the configuration is refused rather
+        # than resolved, and SPECGUARD_OUTPUT_PATH relocates the drain with
+        # the queue.
+        if drain
+          queue = Configuration.new(env: @env).output_path
+          if files.first != queue
+            raise UsageError, "--drain empties the replay queue, and #{files.first} is not it " \
+                              "(configured as #{queue}) — the local record is a development record, not a queue"
+          end
+        end
+
+        Options.new(path: files.first, from_line: from_line || 1, list: list, line_set: line_set, json: json,
+                    drain: drain)
       rescue OptionParser::ParseError => e
         # Uncaught, this is the likeliest way a user sees a false "the endpoint
         # refused your run": OptionParser raises and Ruby exits 1. Retyping it

data/lib/specguard/rspec/ingest_reporter.rb

@@ -113,13 +113,17 @@ module SpecGuard
       #   {IngestCLI} for both renderers
       # @param foldings [Array<IngestCLI::Folding>] the folding observations,
       #   grouped once for both renderers
+      # @param drained [IngestCLI::Drain, nil] what `--drain` removed, or nil
+      #   when the flag was absent — the key is then absent from `summary`,
+      #   which is the whole of the flag being opt-in
       # @return [String] one JSON document, without a trailing newline
-      def self.render_delivery(source:, results:, counts:, foldings:)
+      def self.render_delivery(source:, results:, counts:, foldings:, drained: nil)
         document(
           mode: MODE_DELIVER,
           source: source,
           lines: results.map { |result| delivered(result) },
-          summary: summary(source, lines: results.length, counts: counts, attempted: attempted(counts)),
+          summary: summary(source, lines: results.length, counts: counts, attempted: attempted(counts),
+                           drained: drained),
           foldings: foldings.map { |folding| folded(folding) }
         )
       end
@@ -177,8 +181,15 @@ module SpecGuard
       # render the identical document. It is `null` rather than `[]` where the
       # selector was fully satisfied, on {#selector}'s terms: a fact that does
       # not apply is absent, never a fabricated empty.
-      def self.summary(source, lines:, counts:, attempted:)
-        {
+      #
+      # `drained` is the `--drain` count, and it is present exactly when the
+      # flag was given — `0` where the flag asked and nothing was accepted, so
+      # a consumer that asked for the drain can always read its outcome here,
+      # and a document without the key is a run that never asked. The listing
+      # never carries it: `--drain --list` is refused before either renderer
+      # runs.
+      def self.summary(source, lines:, counts:, attempted:, drained: nil)
+        summary = {
           "lines" => lines,
           "attempted" => attempted,
           "accepted" => counts.fetch(:accepted, 0),
@@ -190,6 +201,8 @@ module SpecGuard
           "absent" => absent(source),
           "selector" => selector(source)
         }
+        summary["drained"] = drained.removed if drained
+        summary
       end
 
       # The typed line numbers the file does not have, in the shorthand they

data/lib/specguard/version.rb

@@ -7,5 +7,5 @@
 # framework-scoped version constant a lie, so the number moved here and the
 # rspec module now points at it for back-compat.
 module SpecGuard
-  VERSION = "0.3.23"
+  VERSION = "0.3.24"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: specguard-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.23
+  version: 0.3.24
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json