Class: Pikuri::Subprocess

Inherits:
Object
  • Object
show all
Defined in:
lib/pikuri/subprocess.rb

Overview

Chokepoint for all subprocess spawning in pikuri. Forces a new process group for each invocation, tracks pgids so descendants of the direct child (commands backgrounded with &) can be cleaned up at process exit, and captures combined stdout+stderr through a single pipe.

Seam discipline

All subprocess spawning in lib/ goes through Subprocess.spawn. Direct Process.spawn / Open3.* / system / backticks anywhere in lib/ are bugs. The convention is grep-enforceable: grep -rnE ‘Process.spawn|Open3.|bsystem(’ lib/ should only hit this file (plus the comment in pikuri-mcp/lib/pikuri/mcp/servers.rb explaining the MCP exception).

Timeouts are the caller’s job

Subprocess.spawn does not implement a timeout — Ruby’s Timeout.timeout cannot kill subprocesses cleanly. Callers that need a timeout wrap their argv with coreutils’ timeout binary:

Pikuri::Subprocess.spawn(
  'timeout', '--signal=TERM', '--kill-after=5s', '120s',
  'bash', '-c', command,
  chdir: workspace.cwd.to_s
)

When timeout and its FD-inheriting children die, the combined output pipe closes and #wait‘s io.read returns. No Ruby-side timeout machinery; the timeout binary handles SIGTERM-then- SIGKILL race-free.

Backgrounded subprocesses

When a shell command backgrounds work with &, the resulting process stays in our pgroup. #wait returns as soon as the direct child exits, but Subprocess.active keeps the pgid in the tracked set as long as any process in the group is alive (probed with kill(0, -pgid)). On pikuri exit, Subprocess.cleanup! sends SIGTERM to every tracked group. The model can opt out via nohup cmd & or setsid cmd & — both detach from our group.

State is process-global

One @active Set for the whole process, swept once at exit via Finalizers (see the registration at the bottom of this file). A Mutex guards register/prune/cleanup; v1 is single-threaded, so this is more for the exit-sweep/register race than for current callers.

Why Pikuri::Subprocess, not top-level

First class actually under the Pikuri:: namespace. Domain classes (Tool, Agent, URLCache) are top-level as a legacy convention — they predate the namespacing decision and an eventual refactor moves them too. For now: library-level infrastructure under Pikuri::; domain objects flat. See CLAUDE.md for the convention.

Defined Under Namespace

Classes: Result

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(io:, wait_thr:) ⇒ Subprocess

Returns a new instance of Subprocess.



107
108
109
110
111
112
 
# File 'lib/pikuri/subprocess.rb', line 107

def initialize(io:, wait_thr:)
  @io       = io
  @wait_thr = wait_thr
  @pid      = wait_thr.pid
  @pgid     = wait_thr.pid # pgroup:true → pgid == pid
end

Instance Attribute Details

#io ⇒ IO (readonly)

Returns read end of the combined stdout+stderr pipe. Exposed for future live-streaming consumers; v1 callers go straight to #wait, which drains it.

Returns:

  • (IO) —

    read end of the combined stdout+stderr pipe. Exposed for future live-streaming consumers; v1 callers go straight to #wait, which drains it.



104
105
106
 
# File 'lib/pikuri/subprocess.rb', line 104

def io
  @io
end

#pgid ⇒ Integer (readonly)

Returns process group id. Equal to #pid since the child was spawned with pgroup: true (it’s the group leader).

Returns:

  • (Integer) —

    process group id. Equal to #pid since the child was spawned with pgroup: true (it’s the group leader).



99
100
101
 
# File 'lib/pikuri/subprocess.rb', line 99

def pgid
  @pgid
end

#pid ⇒ Integer (readonly)

Returns direct child’s pid.

Returns:

  • (Integer) —

    direct child’s pid



95
96
97
 
# File 'lib/pikuri/subprocess.rb', line 95

def pid
  @pid
end

Class Method Details

.active ⇒ Array<Integer>

Currently-tracked process groups, with dead ones pruned as a side effect. Useful for a future /bg REPL command or a between-turn status line.

Returns:

  • (Array<Integer>) 


151
152
153
154
155
156
 
# File 'lib/pikuri/subprocess.rb', line 151

def active
  @mutex.synchronize do
    @active.delete_if { |g| !alive?(g) }
    @active.to_a
  end
end

.cleanup! ⇒ void

This method returns an undefined value.

SIGTERM every tracked process group. Run at process exit via Finalizers (production) and from after blocks (specs). Best-effort — ignores errors from already-dead groups.



163
164
165
166
167
168
 
# File 'lib/pikuri/subprocess.rb', line 163

def cleanup!
  @mutex.synchronize do
    @active.each { |g| Process.kill('-TERM', g) rescue nil }
    @active.clear
  end
end

.spawn(*argv, chdir:, env: {}) ⇒ Subprocess

Spawn argv in a new process group, redirecting stderr onto stdout. Tracked for cleanup.

Parameters:

  • argv (Array<String>) —

    command and arguments. Caller does any shell wrapping (e.g. ‘bash’, ‘-c’, cmd) when shell interpretation is wanted; argv is passed to exec directly, so no implicit shell expansion happens here.

  • chdir (String, Pathname) —

    working directory

  • env (Hash{String=>String}) (defaults to: {}) —

    extra environment variables to set in the child process. The child otherwise inherits the parent’s full environment; entries in env override or add to it. Default {} (pure inheritance). Used by Code::Bash to thread Workspace::Filesystem#env (host git identity, etc.) into a bash subprocess whose sandbox would otherwise strip the host’s config files.

Returns:

  • (Subprocess) —

    handle — call #wait to block for the direct child to exit and read the captured output



87
88
89
90
91
92
 
# File 'lib/pikuri/subprocess.rb', line 87

def self.spawn(*argv, chdir:, env: {})
  stdin, io, wait_thr = Open3.popen2e(env, *argv, chdir: chdir.to_s, pgroup: true)
  stdin.close
  register(wait_thr.pid)
  new(io: io, wait_thr: wait_thr)
end

Instance Method Details

#terminate ⇒ void

This method returns an undefined value.

SIGTERM the whole process group without blocking for output —the stop button for a daemon child (one the caller never #waits on, e.g. Memory::Mem0Server‘s socat relay). Best-effort and idempotent: an already-dead group is a no-op. The group stays in the exit-sweep set until it actually dies, so a child that ignores SIGTERM is still re-signalled by cleanup! at process exit.



137
138
139
140
141
142
143
 
# File 'lib/pikuri/subprocess.rb', line 137

def terminate
  Process.kill('-TERM', @pgid)
rescue Errno::ESRCH
  # already gone
ensure
  self.class.send(:prune, @pgid)
end

#wait ⇒ Result

Block until the direct child exits, read whatever remains on the combined-output pipe, return a Result. The pgid stays tracked if the group still has live members (backgrounded children); pruned if everything’s gone.

Returns:



120
121
122
123
124
125
126
 
# File 'lib/pikuri/subprocess.rb', line 120

def wait
  output = @io.read
  @io.close
  Result.new(output: output, status: @wait_thr.value)
ensure
  self.class.send(:prune, @pgid)
end