holder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c71f17499d6b8c123a250db4d8d4a76e3c6e6aadbd5d0bb76469a62f815d6211
+  data.tar.gz: 0301ea4c0f61ae3c70e26c6fd55b3688d6799697c3bf57ec1e4facfd05852c74
+SHA512:
+  metadata.gz: df00fbb37ca6d2ec85f599d0c38bb50280711ef849801704023c6032f4b70b06adb63223fb1b4362e98295a5b6525496f6466a5796d50132f14ae4f6f7e1a5a1
+  data.tar.gz: 5133ecde07e6be99b797821a55bdf26f8d2ca128b7a127a0afbafc85860190569f66509d73df2c916a9fbe96b2940bd3ca699f9930a8ca6caba0fc39f6d0192f

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,170 @@
+# ===========================================================================
+# RuboCop Configuration
+#
+# Base: Stock RuboCop defaults
+# AI guardrails: rubocop-claude plugin (all Claude/ cops + stricter metrics)
+# Performance: rubocop-performance (with chain-hostile cops disabled)
+#
+# Philosophy: idiomatic Ruby, pipeline-style chaining, strict for AI agents,
+# readable for humans.
+# ===========================================================================
+
+plugins:
+  - rubocop-claude
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 4.0
+  Exclude:
+    - bin/*
+    - vendor/**/*
+    - lib/core_ext/**/*
+    - rakelib/project.rb
+    - rakelib/project_version.rb
+    - rakelib/version_tag.rb
+    - rakelib/github_release.rb
+    - rakelib/strict_shell.rb
+
+# ===========================================================================
+# Overrides from stock — personal style preferences
+# ===========================================================================
+
+# Double quotes everywhere. One less decision to make.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Frozen string literal is transitional cruft. Ruby 3.4 has chilled strings,
+# full default freeze is coming in a future Ruby.
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+# Pipeline style. Chaining multi-line blocks is the whole point.
+Style/MultilineBlockChain:
+  Enabled: false
+
+# Block delimiters are a taste call. Pipeline code uses braces for chaining,
+# do/end for side effects. No cop captures this nuance.
+Style/BlockDelimiters:
+  Enabled: false
+
+# Write arrays like arrays.
+Style/WordArray:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+# Argument indentation: consistent 2-space indent, not aligned to first arg.
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
+# Dot-aligned chaining. Dots form a visual column.
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: aligned
+
+# ===========================================================================
+# Overrides from rubocop-claude — loosen where pipeline style conflicts
+# ===========================================================================
+
+Claude/NoOverlyDefensiveCode:
+  MaxSafeNavigationChain: 2
+
+Style/SafeNavigation:
+  MaxChainLength: 2
+
+# Allow `return a, b` for tuple-style returns.
+Style/RedundantReturn:
+  AllowMultipleReturnValues: true
+
+# ===========================================================================
+# Overrides from rubocop-performance — disable chain-hostile cops
+# ===========================================================================
+
+Performance/ChainArrayAllocation:
+  Enabled: false
+
+Performance/MapMethodChain:
+  Enabled: false
+
+# ===========================================================================
+# Additional tightening — not set by stock or rubocop-claude
+# ===========================================================================
+
+# Short blocks push toward small chained steps instead of fat lambdas.
+Metrics/BlockLength:
+  Max: 8
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
+  AllowedMethods:
+    - command
+    - test
+  Exclude:
+    - "holder.gemspec"
+    - "rakelib/**/*"
+    - "spec/**/*"
+
+# An integration example's subject is a behaviour, not a class -- "tearing down
+# a group whose leader has already exited" -- and several of them legitimately
+# drive the same class from different angles. So those files describe in prose.
+# Unit specs still describe their class, and their paths still have to match it.
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/integration/**/*"
+
+# Gemspec and rake files use patterns that trigger Claude cops legitimately.
+Claude/NoFancyUnicode:
+  Exclude:
+    - "holder.gemspec"
+
+Claude/MysteryRegex:
+  Exclude:
+    - "rakelib/**/*"
+
+# Zeitwerk loaders are mutable by design — only flag literal mutable values.
+Style/MutableConstant:
+  EnforcedStyle: literals
+
+# Anonymous forwarding (*, **, &) breaks TruffleRuby, JRuby, and
+# Ruby < 3.2. Named args are explicit and portable.
+Style/ArgumentsForwarding:
+  Enabled: false
+
+# Explicit begin/rescue/end is clearer than implicit method-body rescue.
+Style/RedundantBegin:
+  Enabled: false
+
+# Compact class names are fine for small files and tests.
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Classes get rdoc.
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - "spec/**/*"
+
+# Trailing commas in multiline literals and arguments.
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+# Permit targeted inline `# rubocop:disable` directives. The HolderTest case class
+# carries a few by-design exemptions (a large test class, churn helper metrics)
+# that are clearer as local directives than as blanket per-file config excludes.
+Style/DisableCopsWithinSourceCodeDirective:
+  Enabled: false
+

data/.ruby-version

@@ -0,0 +1 @@
+4.0.1

data/CLAUDE.md

@@ -0,0 +1,89 @@
+# HOLDER
+
+## Description
+Holder is a robust, yet ergonomic process supervisor written in ruby.
+Its goal is to allow ruby to have more control in orchestrating continuous, external shellouts, like a short lived nginx server.
+
+It leans on ruby's own open3 library, whilst handling the parts that open3 doesn't. 
+
+## Rules
+
+1. **Commit often, and always forward**. Commit work frequently, and never rewrite history unless explicitly told to do so. "Rewriting history" is defined as any non-append only operation, such as amending, destructive rebasing (e.g. squashing), force pushing, and the like.
+
+2. **Idiomatic, current-generation code only.** Always write idiomatic Ruby, and idiomatic usage of whatever gems/frameworks this project depends on. This is a greenfield project on the latest version of every tool — use the newest APIs and patterns, never deprecated or legacy-compatibility ones.
+
+3. **Cross-reference the bundled framework docs before writing framework code.** Any line in a framework-related file (Rails, Sinatra, Hanami, etc., whichever this project uses) must first be checked against the bundled reference docs to confirm it follows the latest idiomatic pattern. Never write framework code from memory alone. Also use ruby-lsp to assist with writing.
+
+5. **Self-documenting code over comments.** Communicate intent primarily through naming:
+   - Well-named local variables (noun) and methods (verb) can often articulate the same thing a one line comment can.
+   - Proper abstractions and entities with good names usually tell a story better than comments. Distill:
+     - the _behaviors_ you need (methods/modules)
+     - the _performer_ of those behaviors (classes/objects)
+     - the _requirements_ of those behaviors (arguments/parameters)
+     - the _recipient_ (if any) of those behaviors (return value)
+   - If you have truly exhausted the above, then a comment is recommended.
+
+6. **Avoid vague "-or"/"-er" names** (e.g. `LineProcessor`, `DataManager`). Only use one when Ruby or its frameworks spec it out as a defined architectural role — like Rails does with `Controller` or `Serializer` — with its own responsibilities and conventions, not just a common-sounding name you've assigned yourself. Despite this gem being called "holder", it does not have a class with the same name - it leans on a properly named domain model.
+
+7. **"Done" means done**, as defined in the next section.
+
+8. **Specs are tiered by cost, and the tier decides everything else**, as defined in the Testing section.
+
+## Testing
+
+RSpec only. Two tiers, and which one a spec belongs to is decided by what it
+costs to run, never by what it is about.
+
+**`spec/unit`** — pure logic. Spawns no child, sleeps for nothing, asserts no
+duration. Held to a hard one-second budget that an example may lower and may
+never raise: an example that wants longer is an integration example in the wrong
+directory. These describe a **class**, and the file path has to match it
+(`describe Holder::Tenant` lives at `spec/unit/holder/tenant_*_spec.rb`).
+
+**`spec/integration`** — real children, real signals, host-dependent fixtures.
+These describe a **behaviour in prose** (`RSpec.describe "tearing down a process
+group"`), because the subject is a behaviour and several files legitimately
+drive the same class from different angles.
+
+Rules that follow from the split:
+
+- **The watchdog is a backstop, not an assertion.** Its job is to stop a wedged
+  example, and its default is deliberately tight enough to also bound teardown
+  itself — most teardown examples assert liveness only *after* `terminate`
+  returns, so the budget is the only thing bounding how long `terminate` may
+  take. Do not loosen it to make something pass. An example whose own scripted
+  work approaches the budget states a bigger one with `it "...", timeout: 8`,
+  **and** asserts explicitly whatever the budget had been bounding implicitly.
+- **A timing contract is an expectation, never a budget.** "Teardown returns
+  within `PUMP_GRACE + 2`" is `expect(elapsed { ... }).to be < ...`.
+- **Never loosen a cop to make a spec pass.** A `RSpec/ExampleLength`,
+  `MultipleExpectations` or `SpecFilePathFormat` offence means the spec is not
+  fine-grained enough: split the example per contract, lift staging into a named
+  helper, or split the file. `:aggregate_failures` is for facets of one
+  genuinely expensive staged scenario, not for dodging a split.
+- **Nothing survives an example.** Every child, pipe, tmpfile and path is
+  registered with `cleanup` so it is undone even when the example fails.
+- Support classes and helper modules live in `spec/support` and are
+  Zeitwerk-autoloaded, exactly as the gem's own constants are.
+
+**A ported or refactored spec has never been seen to fail, so it has not been
+tested.** Before trusting one, re-introduce the regression it exists to catch
+and watch it go red.
+
+## Definition of "done"
+
+A task is not done until every loose end is taken care of. Do not stop with outstanding follow-ups, deferred fixes, or "still pending" items — finish them as part of the task.
+
+State completion without caveats. A task is either **done and production ready** or it is **not done** — there is no third state. Do not hedge, do not attach "known limitations" or "runner-ups" to something you call complete. If something remains, the task is not done.
+
+**Blocked is a specific claim, not a synonym for difficult.** You are genuinely blocked only when completing the task requires a decision, credential, permission, or resource outside your access — not because the problem is hard, ambiguous, or would take a long time to work through. If you can make progress by reasoning further, researching, or trying an alternative approach, you are not blocked.
+
+If you are genuinely blocked, you are to do the following before stopping "not done" work:
+
+1. Record the reason in `_claude/blocklog.md`.
+2. Spin up 3 subagents, each given the same problem statement independently, without seeing each other's reasoning until after they've each proposed a path forward.
+3. Communicate the issue at hand, and what you think the paths forward are.
+4. Record each subagent's proposed path and reasoning in `_claude/blocklog.md`.
+5. If at least 2/3 subagents independently agree on the same path forward, take that path. If the agreement is because they were fed the same framing or assumptions rather than reaching it independently, treat that as no consensus. Otherwise:
+   - Stop working.
+   - Report to user that you are stopping because the work is **not done** and you are **blocked**.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Gillis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+# Holder
+
+A process supervisor that ensures no child is left behind.
+
+Spawning a child process in Ruby is easy; tearing it down cleanly is not. A child
+that ignores `SIGTERM`, a shell that backgrounds grandchildren into the same
+process group, a redirect pump blocked on an IO that never reaches EOF — any of
+these can leave you with orphaned processes, leaked file descriptors, or dangling
+threads.
+
+Holder wraps `Open3` and gives you a single `Handle` that owns the whole lifecycle:
+it launches the child in its own process group, lets you talk to its streams, and
+on teardown signals the **entire group**, escalates to `SIGKILL` if the grace
+period lapses, reaps the child, joins the redirect pumps, and closes every pipe it
+owns. Teardown is idempotent, thread-safe, and callable from any thread.
+
+## Requirements
+
+- Ruby >= 4.0.1
+- A Unix-like OS (teardown relies on POSIX process groups and signals)
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```
+$ bundle add holder
+```
+
+Or install it directly:
+
+```
+$ gem install holder
+```
+
+## Usage
+
+A `Holder::Tenant` describes a command to run; `#run` launches it and returns a
+`Holder::Handle`. `#run` has two forms.
+
+### Block form — scoped, self-cleaning
+
+The handle is yielded to the block and torn down automatically when the block
+exits, **even if it raises**. `#run` returns the block's value. This is ideal for
+a process whose lifetime should be tied to a scope — a server you need up only
+while a test runs, say:
+
+```ruby
+require "holder"
+
+# Bring nginx up only while your integration suite runs. nginx forks a master
+# plus worker processes; signalling just the master would orphan the workers, so
+# Holder tears down the whole process group. On block exit — or if the block
+# raises — everything is reaped and the port is freed.
+Holder::Tenant.new("nginx", "-g", "daemon off;", "-c", "/etc/nginx/test.conf").run do |nginx|
+  sleep 0.5                                    # wait for nginx to bind the port
+  MyApp::IntegrationSuite.run(base_url: "http://localhost:8080")
+end
+```
+
+### No-block form — you own teardown
+
+`#run` returns the handle; call `#wait` to block until it exits on its own, or
+`#terminate`/`#interrupt` to stop it whenever you like. Good for a long-running
+process you read from until you've seen enough:
+
+```ruby
+# Follow a growing log file in the background, then stop it when you're done.
+handle = Holder::Tenant.new("tail", "-F", "/var/log/app.log").run
+
+handle.stdout.each_line do |line|
+  break if line.include?("migration complete")
+end
+
+handle.terminate   # SIGTERM the group, escalate to SIGKILL after the grace period, reap
+```
+
+### Redirecting streams
+
+Pass an **IO object** (not a path or fd number) as `in:`, `out:`, or `err:`:
+
+```ruby
+# Feed an IO as the child's stdin (drained to EOF, then closed for you)
+sorted = File.open("names.txt") do |input|
+  Holder::Tenant.new("sort", in: input).run { |handle| handle.stdout.read }
+end
+
+# Send the child's stdout/stderr to your own IOs
+File.open("build.log", "w") do |log|
+  Holder::Tenant.new("make", "build", out: log, err: log).run.wait
+end
+```
+
+A stream you redirect is talked to through *your* IO, so the matching accessor on
+the handle is `nil`; a stream you leave alone is exposed as a pipe
+(`handle.stdin` / `handle.stdout` / `handle.stderr`).
+
+Anything other than an IO or `nil` is rejected by `#run`, before anything is
+spawned:
+
+```ruby
+Holder::Tenant.new("cat", in: 0).run             # => ArgumentError
+Holder::Tenant.new("cat", out: "log.txt").run    # => ArgumentError
+Holder::Tenant.new("cat", err: StringIO.new).run # => ArgumentError
+```
+
+### Group teardown
+
+The child always runs in its own process group (this is not overridable), so
+teardown reaches backgrounded grandchildren too. Signalling only the wrapper
+process would orphan anything it spawned; Holder signals the whole group:
+
+```ruby
+# A dev script that boots a server and a file watcher alongside it. Both — and
+# the shell that launched them — are reaped when the block exits.
+Holder::Tenant.new("sh", "-c", "npm run watch & npm start").run do |handle|
+  # ... run against the server ...
+end
+```
+
+### Forwarding spawn options
+
+Any keyword other than `in:`/`out:`/`err:` is forwarded to the underlying spawn
+(`chdir`, `umask`, `unsetenv_others`, ...):
+
+```ruby
+Holder::Tenant.new("git", "log", "--oneline", "-5", out: $stdout, chdir: "/path/to/repo").run.wait
+```
+
+## API
+
+### `Holder::Tenant`
+
+- `Tenant.new(*command, in: nil, out: nil, err: nil, **spawn_opts)` — describe a
+  command. `in:`/`out:`/`err:` take an IO or `nil`; `spawn_opts` are forwarded to
+  the spawn.
+- `#run` — launch, return a `Handle` (caller owns teardown).
+- `#run { |handle| ... }` — launch, yield the handle, tear it down on block exit,
+  and return the block's value.
+
+### `Holder::Handle`
+
+| Member | Description |
+| --- | --- |
+| `#pid` | the child's process id |
+| `#stdin` / `#stdout` / `#stderr` | the pipe for a stream you did **not** redirect, otherwise `nil` |
+| `#wait(drain_grace: 2)` | block until the child exits on its own, reap group leftovers, give a redirected `out:` up to `drain_grace` seconds to finish draining, and return the child's `Process::Status` |
+| `#terminate(grace: 5)` | `SIGTERM` the group, wait `grace` seconds, then `SIGKILL`; reap and close pipes. Returns the `Process::Status` |
+| `#interrupt(grace: 5)` | same as `#terminate` but the first signal is `SIGINT` |
+| `#pump_error` | the unexpected error a redirect pump hit (e.g. `ENOSPC`) — or a `StalledSinkError` when `#wait` gave up on an `out:` sink that would not drain — else `nil`; available after teardown. When both pumps fail, the output-losing (drain) error wins |
+
+`#terminate`, `#interrupt`, and `#wait` are idempotent, thread-safe, and may be
+called from any thread; calling `#terminate` twice returns the same status.
+Concurrent teardowns share one escalation clock — the earliest deadline any
+caller asked for wins, so a `terminate(grace: 0)` is never stuck behind another
+caller's longer grace.
+
+### `Holder::Error`
+
+Base error class for the gem. Its one subclass, `Holder::StalledSinkError`, is
+what `#pump_error` reports when `#wait` gave up on an `out:` sink that would
+not drain.
+
+## How teardown works
+
+1. Signal the whole process group with the first signal (`TERM` or `INT`) — always,
+   even if the leader has already exited, since orphaned grandchildren keep the
+   group's pgid alive.
+2. Wait up to `grace` seconds for the group to die; if it doesn't, send `SIGKILL`
+   and wait again.
+3. Reap the child.
+4. Join the redirect pumps, giving a healthy one `Handle::PUMP_GRACE` seconds to
+   finish draining; a pump still blocked on a misbehaving IO is interrupted so it
+   can never wedge teardown.
+5. Close every pipe the handle owns. Caller-provided `in:`/`out:`/`err:` IOs are
+   **not** closed — you opened them, so you close them.
+
+`#wait` differs in two ways: it sends no first signal (group leftovers found
+after the leader's own exit are killed outright), and it is far more patient
+with the `out:` drain — a child that exited on its own gets `drain_grace`
+seconds (default 2, versus teardown's 1-second `PUMP_GRACE`) for its redirected
+output to finish draining, and a healthy-but-slower sink can be granted more.
+A sink that still hasn't drained by then cannot wedge `#wait`: the drain is cut
+off and the discarded output surfaces as a `StalledSinkError` in `#pump_error`
+— never a silent truncation.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then:
+
+- `rake spec` — run the whole suite
+- `rake spec:unit` — the fast tier only (`spec/unit`): pure logic, no child
+  processes, and a hard 1-second per-example budget. This is the edit-run loop.
+- `rake spec:integration` — the slow tier only (`spec/integration`): real
+  children, real signals, timing budgets
+- `rake rubocop` — run the linter
+- `rake` — spec then rubocop (the default task)
+- `rake zeitwerk:validate` — verify the gem follows Zeitwerk naming conventions
+
+Specs are tiered by cost, not by subject. A `spec/unit` example must stay
+sub-second and spawn nothing; an example that needs a real child belongs in
+`spec/integration`, where the watchdog is a hang catcher rather than an
+assertion — anything a budget would have bounded implicitly is stated as an
+explicit expectation instead.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,32 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :spec do
+  desc "Run the fast tier only -- pure logic, no child processes"
+  RSpec::Core::RakeTask.new(:unit) { |task| task.pattern = "spec/unit/**/*_spec.rb" }
+
+  desc "Run the integration tier only -- real children, timing budgets"
+  RSpec::Core::RakeTask.new(:integration) { |task| task.pattern = "spec/integration/**/*_spec.rb" }
+end
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "gempilot/version_task"
+Gempilot::VersionTask.new
+
+namespace :zeitwerk do
+  desc "Verify all files follow Zeitwerk naming conventions"
+  task :validate do
+    ruby "-e", <<~RUBY
+      require 'holder'
+      Holder::LOADER.eager_load(force: true)
+      puts 'Zeitwerk: All files loaded successfully.'
+    RUBY
+  end
+end
+
+task default: [:spec, :rubocop]

data/lib/holder/error.rb

@@ -0,0 +1,5 @@
+module Holder
+  ##
+  # Base error class for holder.
+  class Error < StandardError; end
+end

data/lib/holder/handle.rb

@@ -0,0 +1,233 @@
+module Holder
+  # A live process handle.
+  #
+  # A regular class, not a Data: a handle is stateful (it gets torn down) and
+  # has internals to hide. Data.define exposes every field as a public reader,
+  # which is the leak we're closing -- so the wait_thread, pump threads, owned
+  # pipes, and mutex live in ivars with no readers.
+  #
+  # Public surface: stdin/stdout/stderr (only the streams you did NOT redirect;
+  # a redirected stream is talked to via your own IO, so its accessor is nil),
+  # pid, and terminate/interrupt/wait.
+  #
+  # Teardown is plain method calls guarded by a mutex, so it's idempotent,
+  # thread-safe, and callable from any thread. terminate and interrupt are the
+  # same robust teardown differing only in the first signal: send it, wait
+  # GRACE for the group to die, then guarantee death with SIGKILL, reap the
+  # child, join the pumps, and close the pipes we own. Concurrent teardowns
+  # share one escalation clock -- the earliest deadline any caller asked for
+  # wins -- so a terminate(grace: 0) is never wedged behind another caller's
+  # longer grace. wait is the passive counterpart: no first signal, leftovers
+  # killed outright, and a redirected out: sink drained for a caller-tunable
+  # drain_grace (defaulting well past a teardown's PUMP_GRACE) -- bounded so a
+  # sink that never drains can't wedge wait, with a cut-short drain surfaced
+  # as a StalledSinkError in pump_error rather than a silent truncation.
+  class Handle
+    # seconds to wait after the first signal before escalating to SIGKILL
+    GRACE = 5
+
+    # seconds to wait for a pump to drain after the process exits
+    # before interrupting it (see reap_pumps)
+    PUMP_GRACE = 1
+
+    # interval between process-group liveness polls while awaiting the grace window
+    POLL = 0.02
+
+    # default for wait's drain_grace: seconds wait keeps delivering a redirected
+    # out: sink's buffered output -- patient well past a teardown's PUMP_GRACE --
+    # before giving up on a sink that never drains, so a wedged sink cannot block
+    # wait forever
+    WAIT_DRAIN_GRACE = 2
+
+    # Whether an EPERM from a group signal means the group is gone. macOS/BSD
+    # report a zombie-only group (its last survivor a defunct process) as EPERM,
+    # so there it means gone. Linux never reports EPERM for a group we own -- there
+    # EPERM means the group is alive but unsignalable (e.g. a child that dropped
+    # privilege), which must surface rather than be mistaken for an empty group.
+    EPERM_MEANS_GONE = !RUBY_PLATFORM.include?("linux")
+
+    attr_reader :stdin, :stdout, :stderr, :pid, :pump_error
+
+    def initialize(stdin:, stdout:, stderr:, wait_thread:, pump_threads:, owned_ios:, drain_pump: nil) # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @wait_thread = wait_thread
+      @pump_threads = pump_threads
+      @drain_pump = drain_pump
+      @owned_ios = owned_ios
+      @pid = wait_thread.pid
+      @pump_error = nil
+      @mutex = Mutex.new
+      @escalation_tick = ConditionVariable.new
+      @kill_deadline = nil
+    end
+
+    def terminate(grace: GRACE) = teardown("TERM", grace)
+
+    def interrupt(grace: GRACE) = teardown("INT", grace)
+
+    # Wait for the process to exit on its own, then reap its group and finalize.
+    # A redirected out: sink gets drain_grace seconds to finish draining (see
+    # deliver_redirected_output).
+    def wait(drain_grace: WAIT_DRAIN_GRACE)
+      # Block on the waiter OUTSIDE the mutex: Thread#value is itself
+      # thread-safe, and holding the mutex across the block would wedge a
+      # concurrent terminate -- it could not acquire the mutex to signal until
+      # the process exited on its own. finalize runs under the mutex and is
+      # idempotent, so a terminate signal that finalizes first is harmless.
+      status = @wait_thread.value
+      begin
+        @mutex.synchronize { kill_group_leftovers }
+        deliver_redirected_output(drain_grace)
+      ensure
+        # finalize even if reaping the group raised (an unsignalable group surfaces
+        # EPERM), so the owned pipes are always closed.
+        @mutex.synchronize { finalize }
+      end
+      status
+    end
+
+    private
+
+    # The child exited on its own, so bytes still buffered toward an out: sink are
+    # real output the caller asked for -- join the drain pump so it delivers them,
+    # patient well past a teardown's PUMP_GRACE by default, and a caller with a
+    # slower sink can raise drain_grace further. But a sink that never drains (a
+    # full pipe whose reader never reads) would wedge wait forever, so once the
+    # grace passes kill the pump and record the discarded output as a
+    # StalledSinkError in pump_error -- truncation surfaces, never passes as a
+    # clean delivery. Runs outside the mutex, so a concurrent terminate can still
+    # cut a wedged sink short even sooner.
+    def deliver_redirected_output(drain_grace)
+      return if @drain_pump.nil? || @drain_pump.join(drain_grace)
+
+      @drain_pump.kill
+      @drain_pump.join
+      @mutex.synchronize { @pump_error ||= StalledSinkError.new(drain_grace) }
+    end
+
+    def teardown(signal, grace)
+      @mutex.synchronize do
+        begin
+          escalate(signal, grace)
+        ensure
+          # Close our pipes and reap the pumps even when escalate raised -- a group
+          # we cannot signal surfaces EPERM, and the handle's resources must still
+          # be released rather than leaked.
+          finalize
+          @kill_deadline = nil
+        end
+        @wait_thread.value
+      end
+    end
+
+    # Send the first signal, grant the whole GROUP grace to exit, then guarantee
+    # death with SIGKILL and reap the leader.
+    def escalate(signal, grace)
+      # Always signal the group, even if the leader has already exited: an orphaned
+      # grandchild keeps the leader's pgid, so the group outlives the leader and
+      # still needs the signal. signal_group rescues the empty-group case.
+      signal_group(signal)
+      # Grace is measured against the whole GROUP, not just the leader: poll
+      # membership so a grandchild the leader backgrounded gets the same grace to
+      # shut down cleanly, then KILL whatever is left. The membership guard narrows
+      # -- but cannot close -- the window in which a recycled pgid could be
+      # signalled: probing liveness cannot prove the group is still ours, an
+      # inherent hazard of addressing processes by id.
+      await_group_exit(grace)
+      signal_group("KILL") if group_alive?
+      @wait_thread.join
+    end
+
+    def signal_group(signal)
+      begin
+        Process.kill("-#{signal}", @pid)
+      rescue Errno::ESRCH
+        # An empty group -- the leader is reaped and no members survive; nothing
+        # left to signal.
+      rescue Errno::EPERM
+        # macOS/BSD: a zombie-only group, also nothing left to signal. Linux: the
+        # group is alive but unsignalable -- surface it rather than silently
+        # treating the group as reaped.
+        raise unless EPERM_MEANS_GONE
+      end
+    end
+
+    # Block until the process group is empty or the shared kill deadline
+    # passes. Concurrent teardowns tighten one clock -- the earliest requested
+    # deadline wins -- and each tick releases the mutex, so a second caller is
+    # never wedged behind an in-flight grace window: it gets in, tightens the
+    # deadline, and every caller escalates together.
+    def await_group_exit(grace)
+      requested = monotonic + grace
+      @kill_deadline = [@kill_deadline || requested, requested].min
+      while group_alive?
+        deadline = @kill_deadline
+        break if deadline.nil? || monotonic >= deadline
+
+        @escalation_tick.wait(@mutex, POLL)
+      end
+    end
+
+    # wait sent no first signal, so group leftovers get no grace: a grandchild
+    # that outlived the leader is killed outright (no child left behind), which
+    # also releases any pipe end it held open so wait's drain can finish.
+    # Unless a terminate/interrupt is mid-grace -- then honor its window rather
+    # than cutting it short, and fire its overdue KILL ourselves only if that
+    # teardown never escalated (its thread may have died mid-flight).
+    def kill_group_leftovers
+      while group_alive?
+        deadline = @kill_deadline
+        break signal_group("KILL") if deadline.nil? || monotonic >= deadline
+
+        @escalation_tick.wait(@mutex, POLL)
+      end
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # True while the process group still has a member. getpriority with PRIO_PGRP
+    # probes the group directly by its (positive) group id and sends no signal,
+    # raising ESRCH once the group is empty. On Linux reading a group's priority
+    # needs no permission, so a live-but-unsignalable group correctly reads as
+    # alive and its EPERM surfaces where we actually signal it, in signal_group;
+    # macOS/BSD instead report a zombie-only group as EPERM, which means gone here.
+    def group_alive?
+      begin
+        Process.getpriority(Process::PRIO_PGRP, @pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      end
+    end
+
+    def finalize
+      @pump_error ||= reap_pumps
+      @owned_ios.each { |io| io.close unless io.closed? }
+    end
+
+    # Join the pumps, but never let one wedge teardown. Once the process has
+    # exited, a healthy pump finishes draining in milliseconds, so it joins
+    # within PUMP_GRACE and is never touched. A pump still blocked after that
+    # is stuck on a misbehaving user IO -- an in: source that never reaches EOF
+    # ($stdin, an open socket), or an out: sink that never drains -- and its
+    # remaining work is moot now that the child is gone. Thread#kill unblocks
+    # copy_stream's read/write and runs the pump's ensure (which closes its
+    # pipe); a killed pump's #value is nil, so it's ignored here. Of the
+    # genuine captured errors, the drain pump's outranks the feed pump's: a
+    # failed drain lost output the caller redirected, while a failed feed
+    # merely starved a child that is already gone.
+    def reap_pumps
+      errors = @pump_threads.filter_map do |pump|
+        unless pump.join(PUMP_GRACE)
+          pump.kill
+          pump.join
+        end
+        error = pump.value
+        [pump, error] if error
+      end.to_h
+      errors[@drain_pump] || errors.values.first
+    end
+  end
+end

data/lib/holder/stalled_sink_error.rb

@@ -0,0 +1,13 @@
+module Holder
+  ##
+  # Recorded in <tt>Handle#pump_error</tt> when +wait+ gave up on a redirected
+  # +out:+ sink that would not drain within its +drain_grace+: the sink's pump
+  # was interrupted and the child's still-buffered output discarded, so the
+  # redirect is incomplete. A healthy sink that is merely slower than the
+  # default can be granted more patience via <tt>wait(drain_grace:)</tt>.
+  class StalledSinkError < Error
+    def initialize(drain_grace)
+      super("out: sink still undrained after #{drain_grace}s; remaining output discarded")
+    end
+  end
+end

data/lib/holder/stream_type.rb

@@ -0,0 +1,12 @@
+module Holder
+  ##
+  # Type matcher for the +in:+/+out:+/+err:+ redirect arguments. Defined under
+  # +Holder+ -- NOT core <tt>::IO</tt> -- and matches only real IO instances
+  # (<tt>$stdin</tt>/<tt>$stdout</tt>/<tt>$stderr</tt>, File, pipe ends). Integer
+  # fds, path strings, StringIO, Tempfile and other duck types are rejected at
+  # validation, so a stray <tt>run(in: 0)</tt> raises up front instead of slipping
+  # through and detonating later inside a pump.
+  module StreamType
+    def self.===(other) = other.is_a?(::IO)
+  end
+end

data/lib/holder/tenant.rb

@@ -0,0 +1,127 @@
+require "open3"
+
+module Holder
+  ##
+  # Builds and launches a child process, returning a Handle that owns its teardown.
+  #
+  # +in:+, +out:+, and +err:+ each accept an IO (or +nil+) to redirect that stream
+  # to; any other keyword (+chdir+, +umask+, ...) is forwarded to the spawn. The
+  # child always runs in its own process group so the whole group can be torn down
+  # together -- this is not overridable.
+  class Tenant
+    attr_reader :handle, :pgroup, :kwargs
+    private attr_reader :args
+    private attr_writer :handle
+
+    def initialize(*args, in: nil, out: nil, err: nil, **kwargs)
+      @args = args
+      @io_defs = { in:, out:, err: }
+      @pgroup = true
+      @kwargs = kwargs
+    end
+
+    def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # Validate the three streams up front. The one-line pattern match checks each
+      # is an IO or nil (in: is a keyword, so it can't be named as a local); we then
+      # read the values out by key. A bad stream raises ArgumentError here rather
+      # than slipping through and detonating later inside a pump.
+      unless @io_defs in { in: StreamType | nil, out: StreamType | nil, err: StreamType | nil }
+        raise ArgumentError, "in:, out:, and err: must each be an IO object or nil"
+      end
+
+      u_sin, u_sout, u_serr = @io_defs.values_at(:in, :out, :err)
+
+      # Open3 ALWAYS pipes stdin and stdout, so in:/out: are always pumped; err is
+      # the only stream that can go direct, and only via popen2. So the entire
+      # 8-case dispatch is just this, and the only thing handed to spawn directly
+      # is a redirected err:. Any extra kwargs (chdir, umask, unsetenv_others,
+      # close_others, ...) are forwarded to spawn; they go in first so our
+      # pgroup: true and err redirect win on collision and the group-teardown
+      # invariant is never overridden.
+      meth = u_serr ? :popen2 : :popen3
+      spawn_redirects = u_serr ? { err: u_serr } : {}
+
+      # Each form uses its matching Open3 form: block -> Open3's block form (its
+      # close+reap is a backstop under our kill); no-block -> Open3's non-block
+      # form (the handle owns teardown).
+      if block_given?
+        Open3.public_send(meth, *args, **kwargs, pgroup:, **spawn_redirects) do |*streams|
+          self.handle = build_handle(streams, meth, u_sin, u_sout, u_serr)
+          begin
+            yield handle
+          ensure
+            handle.terminate
+          end
+        end
+      else
+        streams = Open3.public_send(meth, *args, **kwargs, pgroup:, **spawn_redirects)
+        self.handle = build_handle(streams, meth, u_sin, u_sout, u_serr)
+      end
+    end
+
+    private
+
+    def build_handle(streams, meth, u_sin, u_sout, u_serr)
+      block_keys = meth == :popen3 ? %i[sin sout serr wait] : %i[sin sout wait]
+      piped = block_keys.zip(streams).to_h
+      sin_pipe = piped[:sin]
+      sout_pipe = piped[:sout]
+      serr_pipe = piped[:serr] # nil for popen2 (stderr isn't piped there)
+
+      # feed a redirected in: into the stdin pipe, then close it so the child
+      # reads EOF and can exit on its own (Open3.capture3's `i.close`)
+      feed_pump = pump(u_sin, sin_pipe, close_after: true) if u_sin
+      # drain a redirected out: from the stdout pipe into the caller's IO; the
+      # handle knows it apart so wait can deliver it to the last byte
+      drain_pump = pump(sout_pipe, u_sout) if u_sout
+      # a redirected err: went direct via popen2 -- no pump
+
+      Handle.new(
+        # hide the internal pipe for any stream you redirected; you talk to your IO
+        stdin: u_sin ? nil : sin_pipe,
+        stdout: u_sout ? nil : sout_pipe,
+        stderr: u_serr ? nil : serr_pipe,
+        wait_thread: piped.fetch(:wait),
+        pump_threads: [feed_pump, drain_pump].compact,
+        drain_pump:,
+        owned_ios: [sin_pipe, sout_pipe, serr_pipe].compact,
+      )
+    end
+
+    # The pump's value is its failure report: nil for a clean copy (or one cut
+    # short by teardown races), otherwise the first error worth surfacing --
+    # copying outranks closing, since a failed copy is the earlier cause. The
+    # close lives in an ensure so a pump killed mid-copy still closes its pipe;
+    # a killed pump never reaches the trailing expression, so its value stays
+    # nil as reap_pumps expects.
+    def pump(src, destination, close_after: false)
+      Thread.new do
+        error = nil
+        begin
+          error = copy_error(src, destination)
+        ensure
+          error ||= (close_error(destination) if close_after)
+        end
+        error
+      end
+    end
+
+    def copy_error(src, destination)
+      IO.copy_stream(src, destination)
+      nil
+    rescue IOError, Errno::EPIPE, Errno::EBADF
+      nil # source/dest torn down underneath us (the EPIPE Open3.capture3 swallows)
+    rescue StandardError => e
+      e # unexpected (e.g. ENOSPC writing a redirect); capture so teardown finishes
+    end
+
+    def close_error(destination)
+      destination.close unless destination.closed?
+      nil
+    rescue IOError, Errno::EPIPE, Errno::EBADF
+      nil # already torn down underneath us, same as a copy hitting a closed pipe
+    rescue StandardError => e
+      e # a close that lost buffered writes; capture so teardown finishes
+    end
+  end
+end

data/lib/holder/version.rb

@@ -0,0 +1,3 @@
+module Holder
+  VERSION = "0.1.0".freeze
+end

data/lib/holder.rb

@@ -0,0 +1,12 @@
+require "zeitwerk"
+
+##
+# Top-level namespace for the holder gem.
+#
+# All constants under +Holder+ (Error, StalledSinkError, Tenant, Handle,
+# StreamType) live in their own files under <tt>lib/holder/</tt> and are
+# autoloaded by Zeitwerk -- there are no +require+ statements for local files.
+module Holder
+  LOADER = Zeitwerk::Loader.for_gem
+  LOADER.setup
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: holder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Gillis
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email:
+- david@flipmine.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/holder.rb
+- lib/holder/error.rb
+- lib/holder/handle.rb
+- lib/holder/stalled_sink_error.rb
+- lib/holder/stream_type.rb
+- lib/holder/tenant.rb
+- lib/holder/version.rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A process supervisor that ensures no child is left behind
+test_files: []