workspaces 0.1.20 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b62d0530751f975a4e8604a691dce7bc133c3d7bd57a966e08e9b9e24c7088d9
-  data.tar.gz: 3fb3b5acff924444694d1390b9edd0f4dc2eaf5885da24b938552180b52a0b0e
+  metadata.gz: 2aca45b37e744578006f9b80c3b42a8d664d3b989e9443c10505e357b739338d
+  data.tar.gz: cdfb7b28c2fb5f66ace3e778cceb9654a07271fbad73321768829a498248feb5
 SHA512:
-  metadata.gz: e860375ef8492aba63ef9340ff2ad29e22fc504353546d343b3e2c3dc31833b9df5bc77de4a8b367eeeb8e3423aef5918e0f61a51d4de26dd8ea9d916af7bec3
-  data.tar.gz: d8521f83fd632951c5ac551f52f1c4a72db8d22afd33dca483bad10e1f82456f01d8fcf4fa0d50fc00e93cb98da32eab34ae6c16454a8cb931e5654c9349ee19
+  metadata.gz: 764c88c9ebb620cace6381b7e95b1ba32e2cb6e4e80da503a28f68ec1acb783a84a99bf4eb7213cb97e2d4787ce9117bee0c09504649367517b56bb593821a1d
+  data.tar.gz: dab1db619647ee35bdcd731c6072b762e9788a42877eb684411368d1e7461230267adedbf8a875354f9d0ec50f91f3a81e4654b75f6c29e14c6b0a0f7d0b8896

data/README.md

@@ -75,6 +75,26 @@ A few things worth knowing:
   `workspaces exec <id> -- git lfs pull --include='path/**'`.
 - Workspaces created before this behavior keep their real files; nothing is converted.
 
+### Running a command in a workspace
+
+`workspaces exec <id> [--timeout SECONDS] -- COMMAND [ARGUMENTS...]` runs a command in the
+workspace's directory with the workspace's environment, and exits with the command's own status.
+
+- It holds the workspace's lock while it runs, so a restart, stop or removal is refused until it
+  finishes. That is what stops a command racing a rebuild.
+- A command is stopped after **15 minutes** by default, along with everything it started, and
+  `exec` exits 124 (what `timeout(1)` uses). Change it with `--timeout SECONDS` or
+  `WORKSPACES_EXEC_TIMEOUT_SECONDS`; `0` means no limit. An explicit `--timeout` wins.
+- Anyone refused while it runs is told what holds the lock, for example
+  `Workspace is busy: running a command (bin/rails), pid 1365484, for 28m 5s. It will be stopped
+  automatically after 15m 0s`. Only the executable is recorded, never its arguments, because
+  those can carry secrets.
+- The lock is released by the operating system when its holder exits for any reason, including
+  being killed, so a dead command cannot leave a workspace stuck.
+- The preview keeps being served while a command runs, because `exec` leaves the server alone. A
+  restart, rebuild, PR update or removal holding the lock still takes the preview offline, since
+  those replace the server or its files.
+
 ### Step timings
 
 Per-step durations are persisted in seconds in workspace step status JSON, so they

data/lib/workspaces/cli.rb

@@ -225,19 +225,75 @@ module Workspaces
       raise ArgumentError, "Could not remove: #{result['problems'].join('; ')}" unless result['problems'].empty?
     end
 
+    EXEC_USAGE = 'Usage: workspaces exec ID [--timeout SECONDS] -- COMMAND [ARGUMENTS...]'.freeze
+    # What `timeout(1)` exits with, so scripts that already handle that keep working.
+    EXEC_TIMED_OUT = 124
+
     def execute(argv)
       id = argv.shift
-      unless argv.shift == '--' && !argv.empty?
-        raise ArgumentError,
-              'Usage: workspaces exec ID -- COMMAND [ARGUMENTS...]'
+      timeout = nil
+      while argv.first && argv.first != '--'
+        flag = argv.shift
+        raise ArgumentError, EXEC_USAGE unless flag == '--timeout' && !argv.empty?
+
+        timeout = argv.shift
+      end
+      raise ArgumentError, EXEC_USAGE unless argv.shift == '--' && !argv.empty?
+
+      limit = Config.exec_timeout_seconds(timeout)
+      # Only the executable goes in the record: arguments can carry secrets, and the record is readable
+      # by anyone who can read the lock directory.
+      registry.with_lock(id, operation: 'exec', detail: File.basename(argv.first)) do |workspace, lock|
+        run_exec(workspace, argv, limit, lock)
+      end
+    end
+
+    # Runs the command in its own process group so the limit, or a cancel, can stop it and everything it
+    # started, then reports what `timeout(1)` would.
+    def run_exec(workspace, argv, limit, lock)
+      child_env = ChildEnv.for_workspace(workspace_path: workspace.path)
+      pid = Process.spawn(child_env, [argv.first, argv.first], *argv.drop(1),
+                          chdir: workspace.path.to_s, unsetenv_others: true, pgroup: true)
+      lock.update('child_pid' => pid, 'process_group' => pid, 'timeout_seconds' => limit)
+      status = wait_for_exec(pid, limit)
+      return status.exitstatus || (128 + status.termsig) if status
+
+      warn "workspaces exec: #{File.basename(argv.first)} timed out after #{DurationFormat.call(limit)} and was stopped"
+      EXEC_TIMED_OUT
+    end
+
+    # The exit status, or nil when the limit ran out first and the process group was stopped.
+    def wait_for_exec(pid, limit)
+      deadline = limit && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + limit)
+      loop do
+        reaped, status = Process.wait2(pid, Process::WNOHANG)
+        return status if reaped
+
+        if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          stop_group(pid)
+          return nil
+        end
+        sleep 0.05
       end
+    end
 
-      registry.with_lock(id) do |workspace|
-        child_env = ChildEnv.for_workspace(workspace_path: workspace.path)
-        pid = Process.spawn(child_env, [argv.first, argv.first], *argv.drop(1),
-                            chdir: workspace.path.to_s, unsetenv_others: true)
-        _, status = Process.wait2(pid)
-        status.exitstatus || (128 + status.termsig)
+    # TERM first so a command can clean up, KILL for anything still there after a few seconds.
+    def stop_group(pid)
+      Process.kill('TERM', -pid)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+      until Process.wait2(pid, Process::WNOHANG)
+        break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        sleep 0.05
+      end
+      Process.kill('KILL', -pid)
+    rescue Errno::ESRCH, Errno::ECHILD
+      nil
+    ensure
+      begin
+        Process.wait2(pid)
+      rescue Errno::ECHILD
+        nil
       end
     end
 
@@ -257,7 +313,7 @@ module Workspaces
       'Usage: bin/workspaces serve [--require FILE] | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
         'list [--pr NUMBER] [--json] | show/start/prepare/restart ID [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
         'resume ID [--from STEP | --only STEP] [--json] | stop ID | keep-awake ID [--off] | ' \
-        'exec ID -- COMMAND... | remove ID [--force] | purge-secrets [--dry-run]'
+        'exec ID [--timeout SECONDS] -- COMMAND... | remove ID [--force] | purge-secrets [--dry-run]'
     end
 
     def help(*)

data/lib/workspaces/config.rb

@@ -20,6 +20,7 @@ module Workspaces
     DEFAULT_SLEEP_AFTER_MINUTES = 30
     DEFAULT_WAKE_TIMEOUT_SECONDS = 90
     DEFAULT_SLEEP_SWEEP_SECONDS = 30
+    DEFAULT_EXEC_TIMEOUT_SECONDS = 900
 
     # Seconds a ready workspace may go without preview traffic before it is put to sleep, or nil when
     # sleeping is switched off (WORKSPACES_SLEEP_AFTER_MINUTES=0). Fractions of a minute are allowed.
@@ -28,6 +29,19 @@ module Workspaces
       minutes.zero? ? nil : minutes * 60
     end
 
+    # How long `workspaces exec` lets a command run before stopping it, or nil for no limit. An explicit
+    # value (the --timeout option) wins over WORKSPACES_EXEC_TIMEOUT_SECONDS, which wins over the default.
+    # Zero means no limit.
+    def self.exec_timeout_seconds(explicit)
+      value = explicit.nil? ? ENV.fetch('WORKSPACES_EXEC_TIMEOUT_SECONDS', DEFAULT_EXEC_TIMEOUT_SECONDS.to_s) : explicit
+      seconds = Float(value)
+      raise ArgumentError, 'The exec timeout must be a non-negative number of seconds' unless seconds.finite? && seconds >= 0
+
+      seconds.zero? ? nil : (seconds % 1).zero? ? seconds.to_i : seconds
+    rescue ArgumentError, TypeError
+      raise ArgumentError, 'The exec timeout must be a non-negative number of seconds'
+    end
+
     # How long the first request to a sleeping preview waits for the server to be ready.
     def self.wake_timeout_seconds
       positive_number('WORKSPACES_WAKE_TIMEOUT_SECONDS', DEFAULT_WAKE_TIMEOUT_SECONDS)

data/lib/workspaces/coordinator.rb

@@ -42,7 +42,7 @@ module Workspaces
     # message) when the request cannot be honoured.
     def rerun(id, mode: :retry, key: nil)
       workspace = @registry.find(id)
-      lock = acquire_lock(id)
+      lock = acquire_lock(id, 'resume')
       return false unless lock
 
       plan = rerun_plan(id, mode, key)
@@ -96,7 +96,7 @@ module Workspaces
     # the workspace is busy, is kept awake, is not running, or is already asleep.
     def sleep!(id)
       @registry.find(id)
-      lock = acquire_lock(id)
+      lock = acquire_lock(id, 'sleep')
       return false unless lock
 
       begin
@@ -122,7 +122,7 @@ module Workspaces
     # the one holding the workspace lock gets past the check.
     def wake(id)
       workspace = @registry.find(id)
-      lock = acquire_lock(id)
+      lock = acquire_lock(id, 'wake')
       return false unless lock
 
       entry = @state.get(id) || {}
@@ -142,7 +142,7 @@ module Workspaces
 
     # Stops the server by hand. A workspace stopped this way is not asleep, so traffic never wakes it.
     def stop(id)
-      @registry.with_lock(id) do
+      @registry.with_lock(id, operation: 'stop') do
         Backend.new(id).stop!
         @state.set(id, 'status' => 'stopped', 'message' => 'Server stopped', 'sleep_state' => nil, 'slept_at' => nil)
       end
@@ -249,7 +249,7 @@ module Workspaces
     end
 
     def finish_interrupted_sleep(id)
-      lock = acquire_lock(id)
+      lock = acquire_lock(id, 'sleep')
       return unless lock
 
       begin
@@ -262,6 +262,7 @@ module Workspaces
     def snapshot_fields(id, entry, busy, status, log, include_log)
       {
         'workspace_id' => id, 'status' => status, 'active' => busy,
+        'lock_operation' => busy ? WorkspaceLock.holder(id)&.fetch('operation', nil) : nil,
         'sleeping' => status == 'sleeping', 'slept_at' => entry['slept_at'],
         'keep_awake' => !!entry['keep_awake'], 'sleep_after_seconds' => Config.sleep_after_seconds,
         'message' => status == entry['status'] ? entry['message'] : status.capitalize,
@@ -290,7 +291,7 @@ module Workspaces
 
     def launch(id, restart:, force:, prelaunch: nil)
       workspace = @registry.find(id)
-      lock = acquire_lock(id)
+      lock = acquire_lock(id, restart ? 'restart' : 'prepare')
       return false unless lock
 
       if prelaunch && !restart && !force && Backend.new(id).running?
@@ -335,12 +336,8 @@ module Workspaces
                  'prepare_started_at' => now, 'completed_at' => nil, 'last_error' => nil, 'total_seconds' => nil)
     end
 
-    def acquire_lock(id)
-      Config.locks_dir.mkpath
-      # The worker owns this duplicate; closing the request's descriptor must not release its lock.
-      File.open(Config.prepare_lock_path(id), File::RDWR | File::CREAT, 0o600) do |file|
-        file.dup if file.flock(File::LOCK_EX | File::LOCK_NB)
-      end
+    def acquire_lock(id, operation)
+      WorkspaceLock.acquire(id, operation: operation)
     end
 
     def publish_starting(id, restart, extra: {})
@@ -434,10 +431,7 @@ module Workspaces
     end
 
     def locked?(id)
-      path = Config.prepare_lock_path(id)
-      return false unless path.file?
-
-      File.open(path, File::RDWR) { |lock| !lock.flock(File::LOCK_EX | File::LOCK_NB) }
+      WorkspaceLock.held?(id)
     end
 
     def log_tail(id, log)

data/lib/workspaces/front_door.rb

@@ -165,7 +165,7 @@ module Workspaces
                 else
                   @coordinator.update_environment(id, **parse_environment_changes(params))
                 end
-      return response(409, 'Workspace is busy preparing, restarting, or running a command') unless updated
+      return response(409, WorkspaceLock.busy_message(id)) unless updated
 
       redirect(Config.dashboard_url(id))
     rescue EnvironmentOverrides::Invalid => e
@@ -326,13 +326,23 @@ module Workspaces
       end
 
       snapshot = @coordinator.snapshot(id, include_log: false)
-      return unavailable(id, request) unless snapshot['status'] == 'ready' && !snapshot['active']
+      return unavailable(id, request) unless servable?(snapshot)
 
       request.env[WORKSPACE_ID_ENV] = id
       request.env[WORKSPACE_ENV] = snapshot
       @forwarder.call(request.env)
     end
 
+    # A ready workspace is served unless something is changing it. A command run with `exec` leaves the
+    # server alone, so a preview keeps working while one runs, and a command that hangs cannot take the
+    # preview down with it. Anything else holding the lock (a restart, a rebuild, a PR update, removal) may
+    # be replacing the server or its files, and so does an unknown holder: those are still refused.
+    def servable?(snapshot)
+      return false unless snapshot['status'] == 'ready'
+
+      !snapshot['active'] || snapshot['lock_operation'] == 'exec'
+    end
+
     # A lease keeps the workspace awake for as long as its request is being served. A response body
     # that is still being produced (anything but a buffered Array) keeps it until the server closes it.
     def hold_lease(result, lease)

data/lib/workspaces/registry.rb

@@ -1,4 +1,5 @@
 require_relative 'worktree'
+require_relative 'workspace_lock'
 require_relative 'state_store'
 require_relative 'backend'
 require_relative 'recipe'
@@ -28,23 +29,24 @@ module Workspaces
       workspace
     end
 
-    def with_lock(id)
+    # Runs the block holding the workspace's lock, or raises ArgumentError saying who holds it. The block
+    # gets the workspace, and the lock when it wants to add to the holder record.
+    def with_lock(id, operation: 'busy', detail: nil)
       workspace = find(id)
-      Config.locks_dir.mkpath
-      File.open(Config.prepare_lock_path(id), File::RDWR | File::CREAT, 0o600) do |lock|
-        unless lock.flock(File::LOCK_EX | File::LOCK_NB)
-          raise ArgumentError,
-                'Workspace is busy preparing, restarting, or running a command'
-        end
-
-        yield workspace
+      lock = WorkspaceLock.acquire(id, operation: operation, detail: detail)
+      raise ArgumentError, WorkspaceLock.busy_message(id) unless lock
+
+      begin
+        yield workspace, lock
+      ensure
+        lock.close
       end
     end
 
     # Removes the workspace and its saved settings and secrets. Returns the secrets that could not be
     # removed (empty when all went), so callers can say so rather than report a clean removal.
     def remove(id, force: false)
-      with_lock(id) do |workspace|
+      with_lock(id, operation: 'remove') do |workspace|
         raise ArgumentError, 'Workspace has uncommitted/untracked work' if !force && workspace.dirty?
 
         Backend.new(id).stop!
@@ -78,7 +80,7 @@ module Workspaces
     end
 
     def update_pr(id)
-      with_lock(id) do |workspace|
+      with_lock(id, operation: 'update-pr') do |workspace|
         result = workspace.update_from_pr!
         message = result['updated'] ? 'PR checkout updated. Rebuild & restart to run the new code.' : 'PR checkout is already current.'
         StateStore.new(Config.state_file).set(id, 'source_update_message' => message,

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.20'
+  VERSION = '0.1.21'
 end

data/lib/workspaces/workspace_lock.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require_relative 'config'
+require_relative 'duration_format'
+
+module Workspaces
+  # The per-workspace lock that serializes preparing, restarting, stopping, removing, updating and
+  # running commands, plus a record of who holds it.
+  #
+  # The lock is a non-blocking exclusive flock, so the kernel releases it when the holder exits for
+  # any reason, including SIGKILL. A holder that died therefore never leaves the lock stuck; only a
+  # holder that is alive and not finishing does. The record in the file is written by the holder and
+  # emptied when it lets go. It is only meaningful while the lock is held, so a record left behind by
+  # a holder that died is ignored.
+  class WorkspaceLock
+    GENERIC_BUSY = 'Workspace is busy preparing, restarting, or running a command'
+
+    OPERATIONS = {
+      'prepare' => 'preparing', 'restart' => 'restarting', 'resume' => 're-running setup steps',
+      'sleep' => 'putting the workspace to sleep', 'wake' => 'waking the workspace',
+      'stop' => 'stopping the server', 'remove' => 'removing the workspace',
+      'update-pr' => 'updating the PR checkout'
+    }.freeze
+
+    # Takes the lock, or returns nil when someone else holds it.
+    def self.acquire(id, operation:, detail: nil)
+      Config.locks_dir.mkpath
+      file = File.open(Config.prepare_lock_path(id), File::RDWR | File::CREAT, 0o600)
+      unless file.flock(File::LOCK_EX | File::LOCK_NB)
+        file.close
+        return nil
+      end
+
+      lock = new(file)
+      lock.update('operation' => operation, 'pid' => Process.pid, 'started_at' => Time.now.utc.iso8601,
+                  'detail' => detail)
+      lock
+    rescue StandardError
+      file&.close unless file&.closed?
+      raise
+    end
+
+    # True while some process holds the lock.
+    def self.held?(id)
+      path = Config.prepare_lock_path(id)
+      return false unless path.file?
+
+      File.open(path, File::RDWR) { |file| !file.flock(File::LOCK_EX | File::LOCK_NB) }
+    end
+
+    # What the current holder wrote, or nil when nothing holds the lock or the record cannot be read.
+    def self.holder(id)
+      return nil unless held?(id)
+
+      record = JSON.parse(Config.prepare_lock_path(id).read)
+      record.is_a?(Hash) ? record : nil
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def self.busy_message(id)
+      record = holder(id)
+      return GENERIC_BUSY unless record
+
+      "Workspace is busy: #{describe(record)}"
+    end
+
+    def self.describe(record)
+      operation = record['operation'].to_s
+      return describe_command(record) if operation == 'exec'
+
+      OPERATIONS.fetch(operation, operation)
+    end
+
+    def self.describe_command(record)
+      text = +'running a command'
+      text << " (#{record['detail']})" if record['detail']
+      pids = [record['child_pid'] && "pid #{record['child_pid']}"].compact
+      text << ", #{pids.join(', ')}" unless pids.empty?
+      elapsed = elapsed_text(record['started_at'])
+      text << ", for #{elapsed}" if elapsed
+      limit = DurationFormat.call(record['timeout_seconds'])
+      text << ". It will be stopped automatically after #{limit}" if limit
+      text
+    end
+    private_class_method :describe_command
+
+    def self.elapsed_text(started_at)
+      DurationFormat.call(Time.now - Time.iso8601(started_at.to_s))
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :elapsed_text
+
+    def initialize(file)
+      @file = file
+      @record = {}
+    end
+
+    # Adds to what the holder has told the world, keeping what it already said.
+    def update(fields)
+      @record = @record.merge(fields.compact)
+      @file.rewind
+      @file.truncate(0)
+      @file.write(JSON.generate(@record))
+      @file.flush
+    end
+
+    # A descriptor the background worker owns, so the request that took the lock can close its own
+    # without releasing it.
+    def dup
+      self.class.allocate.tap { |copy| copy.send(:adopt, @file.dup, @record) }
+    end
+
+    def close
+      return if @file.closed?
+
+      @file.truncate(0)
+      @file.close
+    rescue IOError, SystemCallError
+      @file.close unless @file.closed?
+    end
+
+    def closed?
+      @file.closed?
+    end
+
+    private
+
+    def adopt(file, record)
+      @file = file
+      @record = record
+    end
+  end
+end

data/lib/workspaces.rb

@@ -1,4 +1,5 @@
 require_relative 'workspaces/config'
+require_relative 'workspaces/workspace_lock'
 require_relative 'workspaces/state_store'
 require_relative 'workspaces/port_allocator'
 require_relative 'workspaces/child_env'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.20
+  version: 0.1.21
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-30 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -107,6 +107,7 @@ files:
 - lib/workspaces/vault/file_vault.rb
 - lib/workspaces/version.rb
 - lib/workspaces/workflow.rb
+- lib/workspaces/workspace_lock.rb
 - lib/workspaces/worktree.rb
 homepage:
 licenses: