pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/models/computer_session.rb

@@ -0,0 +1,57 @@
+module PineSandbox
+  module Models
+    # Computer session — the per-window slice of a Pine CUA computer.
+    #
+    # Returned by {PineSandbox::Computer#create_session}. Holds the
+    # session token (ps_*) used to drive that session's tabs and exec surface.
+    # The computer-level token (ct_*) is intentionally NOT held here —
+    # ct_ scope is the {ComputerSandbox}'s, not the session's.
+    Session = Struct.new(
+      :name,
+      :label,
+      :token,
+      :session_dir,
+      :browser,
+      :blind,
+      :created_at,
+      :last_active_at,
+      keyword_init: true
+    ) do
+      def self.from_payload(payload)
+        return nil unless payload
+        browser_payload = payload["browser"]
+        new(
+          name: payload["name"],
+          label: payload["label"],
+          token: payload["token"],
+          session_dir: payload["session_dir"],
+          browser: browser_payload && Browser.from_payload(browser_payload),
+          blind: payload.fetch("blind", false),
+          created_at: payload["created_at"] && Time.parse(payload["created_at"]),
+          last_active_at: payload["last_active_at"] && Time.parse(payload["last_active_at"])
+        )
+      end
+
+      def browser?
+        !browser.nil?
+      end
+    end
+
+    Browser = Struct.new(
+      :primary_tab_id,
+      :owned_tab_ids,
+      :window_id,
+      :started_at,
+      keyword_init: true
+    ) do
+      def self.from_payload(payload)
+        new(
+          primary_tab_id: payload["primary_tab_id"],
+          owned_tab_ids: payload.fetch("owned_tab_ids", []),
+          window_id: payload["window_id"],
+          started_at: payload["started_at"] && Time.parse(payload["started_at"])
+        )
+      end
+    end
+  end
+end

data/lib/pinesandbox/models/computer_tab.rb

@@ -0,0 +1,30 @@
+module PineSandbox
+  module Models
+    # Tab inside a computer session. Returned by {PineSandbox::Session#tabs} and
+    # the result of {PineSandbox::Session#create_tab}.
+    Tab = Struct.new(
+      :target_id,
+      :url,
+      :title,
+      :label,
+      :active,
+      :window_id,
+      keyword_init: true
+    ) do
+      def self.from_payload(payload)
+        new(
+          target_id: payload["target_id"],
+          url: payload["url"],
+          title: payload["title"],
+          label: payload["label"],
+          active: payload.fetch("active", false),
+          window_id: payload["window_id"]
+        )
+      end
+
+      def active?
+        active
+      end
+    end
+  end
+end

data/lib/pinesandbox/models/file_entry.rb

@@ -0,0 +1,38 @@
+require "time"
+
+module PineSandbox
+  module Models
+    # File or directory entry in a session workdir listing.
+    #
+    # Returned by {PineSandbox::Session#list_files}. Paths are relative to the
+    # session workdir root; absolute container paths are never exposed.
+    FileEntry = Struct.new(
+      :relative_path,
+      :name,
+      :is_dir,
+      :size,
+      :mode,
+      :modified_at,
+      keyword_init: true
+    ) do
+      def self.from_payload(payload)
+        new(
+          relative_path: payload["relative_path"],
+          name: payload["name"],
+          is_dir: !!payload["is_dir"],
+          size: payload["size"],
+          mode: payload["mode"],
+          modified_at: payload["modified_at"] && Time.parse(payload["modified_at"])
+        )
+      end
+
+      def dir?
+        is_dir
+      end
+
+      def is_dir?
+        is_dir
+      end
+    end
+  end
+end

data/lib/pinesandbox/operations.rb

@@ -0,0 +1,134 @@
+module PineSandbox
+  # @api private — the public operations this SDK sends: operationId, method,
+  # path template, host role, whether a request may be sent again after a
+  # transport fault, and whether that rests on an Idempotency-Key. A copy of the server-SDK slice of
+  # sdks/pine-computer/contract/operations.json, which the test suite checks
+  # this table against; the gem ships without the contract files.
+  module Operations
+    # `keyed`: the operation's replay safety rests on an Idempotency-Key
+    # header, so a request without one is sent once.
+    Operation = Struct.new(:id, :method, :path, :host, :replay_safe, :keyed, :pattern, :specificity, keyword_init: true) do
+      def replay_safe? = replay_safe
+
+      # Whether this request may be sent again after a transport fault.
+      def resendable?(idempotency_key)
+        replay_safe && (!keyed || !idempotency_key.to_s.empty?)
+      end
+    end
+
+    def self.build(id, method, path, host, replay_safe, keyed)
+      pattern = Regexp.new("\\A#{path.split(/(\{[^}]+\})/).map { |part| part.start_with?("{") ? "[^/]+" : Regexp.escape(part) }.join}\\z")
+      # Literal path segments outweigh parameters, so /v1/skills/drafts wins
+      # over /v1/skills/{name}.
+      specificity = path.split("/").count { |segment| !segment.start_with?("{") }
+      Operation.new(id: id, method: method, path: path, host: host, replay_safe: replay_safe, keyed: keyed,
+                    pattern: pattern, specificity: specificity).freeze
+    end
+    private_class_method :build
+
+    TABLE = [
+      ["activateSkill", "POST", "/v1/skills/{name}/activate", :computer, false, false],
+      ["answerAgentV2", "POST", "/v2/sessions/{name}/agent/answer", :computer, true, false],
+      ["authorSkillDraft", "POST", "/v1/sessions/{name}/skills", :computer, false, false],
+      ["bindComputer", "POST", "/v1/coord/bind", :computer, false, false],
+      ["cancelAgentV2", "POST", "/v2/sessions/{name}/agent/cancel", :computer, true, false],
+      ["cancelAuthorRun", "POST", "/v2/sessions/{name}/skills/author/{author_id}/cancel", :computer, false, false],
+      ["captureCheckpoint", "POST", "/v1/coord/capture", :computer, false, false],
+      ["claimDownloadOrphan", "POST", "/downloads/orphans/{guid}/claim", :computer, false, false],
+      ["computerUse", "POST", "/v1/sessions/{name}/computer-use", :computer, false, false],
+      ["createComputer", "POST", "/computer-sandboxes", :control, true, false],
+      ["createDiagnostic", "POST", "/v1/diagnostics", :control, true, true],
+      ["createSession", "POST", "/sessions", :computer, false, false],
+      ["deactivateSkill", "POST", "/v1/skills/{name}/deactivate", :computer, false, false],
+      ["decidePasskeyCeremony", "POST", "/v1/passkeys/ceremonies/{ceremony_id}", :computer, false, false],
+      ["decideSessionPasskeyCeremony", "POST", "/v1/sessions/{name}/passkeys/ceremonies/{ceremony_id}", :computer, false, false],
+      ["declareSessionPasskeyIntent", "POST", "/v1/sessions/{name}/passkeys/intents", :computer, false, false],
+      ["deleteComputer", "DELETE", "/v1/computers/{computer_id}", :control, true, false],
+      ["deleteOrphan", "DELETE", "/orphans/{target_id}", :computer, true, false],
+      ["deletePasskey", "DELETE", "/v1/passkeys/{credential_id}", :computer, true, false],
+      ["deleteSession", "DELETE", "/sessions/{name}", :computer, true, false],
+      ["deleteSkillVersion", "DELETE", "/v1/skills/{name}/versions/{version}", :computer, true, false],
+      ["destroyComputer", "DELETE", "/sandboxes/{sandboxId}", :control, true, false],
+      ["discardDownloadOrphan", "DELETE", "/downloads/orphans/{guid}", :computer, true, false],
+      ["getAgentEventsPageV2", "GET", "/v2/sessions/{name}/agent/events/page", :computer, true, false],
+      ["getAgentEventsV2", "GET", "/v2/sessions/{name}/agent/events", :computer, true, false],
+      ["getAgentTurnV2", "GET", "/v2/sessions/{name}/agent/turns/{turn_id}", :computer, true, false],
+      ["getAgentTurnsV2", "GET", "/v2/sessions/{name}/agent/turns", :computer, true, false],
+      ["getAgentV2", "GET", "/v2/sessions/{name}/agent", :computer, true, false],
+      ["getArtifact", "GET", "/v1/sessions/{name}/artifacts/{artifact_id}", :computer, true, false],
+      ["getBindPubkey", "GET", "/v1/coord/bind-pubkey", :computer, true, false],
+      ["getCapabilities", "GET", "/v1/capabilities", :computer, true, false],
+      ["getComputer", "GET", "/sandboxes/{sandboxId}", :control, true, false],
+      ["getComputerBinding", "GET", "/v1/computers/{computer_id}", :control, true, false],
+      ["getControl", "GET", "/v1/sessions/{name}/control", :computer, true, false],
+      ["getControlEvents", "GET", "/v1/sessions/{name}/control/events", :computer, true, false],
+      ["getDiagnostic", "GET", "/v1/diagnostics/{id}", :control, true, false],
+      ["getHandoff", "GET", "/v1/sessions/{name}/handoffs/{handoff_id}", :computer, true, false],
+      ["getProjectPolicy", "GET", "/v1/project-policy", :control, true, false],
+      ["getSession", "GET", "/sessions/{name}", :computer, true, false],
+      ["getSessionFile", "GET", "/v1/sessions/{name}/files", :computer, true, false],
+      ["getSkill", "GET", "/v1/skills/{name}", :computer, true, false],
+      ["getSkillVersion", "GET", "/v1/skills/{name}/versions/{version}", :computer, true, false],
+      ["getState", "GET", "/state", :computer, true, false],
+      ["learnSkill", "POST", "/v2/sessions/{name}/learn", :computer, false, false],
+      ["listAllSkillVersions", "GET", "/v1/skills/versions", :computer, true, false],
+      ["listArtifacts", "GET", "/v1/sessions/{name}/artifacts", :computer, true, false],
+      ["listAvailableLocations", "GET", "/v1/locations", :control, true, false],
+      ["listDownloadOrphans", "GET", "/downloads/orphans", :computer, true, false],
+      ["listHandoffs", "GET", "/v1/sessions/{name}/handoffs", :computer, true, false],
+      ["listOrphans", "GET", "/orphans", :computer, true, false],
+      ["listPasskeyCeremonies", "GET", "/v1/passkeys/ceremonies", :computer, true, false],
+      ["listPasskeys", "GET", "/v1/passkeys", :computer, true, false],
+      ["listSessionFiles", "GET", "/v1/sessions/{name}/files/list", :computer, true, false],
+      ["listSessionPasskeyCeremonies", "GET", "/v1/sessions/{name}/passkeys/ceremonies", :computer, true, false],
+      ["listSessions", "GET", "/sessions", :computer, true, false],
+      ["listSkillDrafts", "GET", "/v1/skills/drafts", :computer, true, false],
+      ["listSkillVersions", "GET", "/v1/skills/{name}/versions", :computer, true, false],
+      ["listSkills", "GET", "/v1/skills", :computer, true, false],
+      ["mintAttachCredentials", "POST", "/v1/computers/{computer_id}/attach-credentials", :control, true, true],
+      ["mintControlToken", "POST", "/v1/control-token", :control, true, false],
+      ["mintDesktopToken", "POST", "/v1/sessions/{name}/desktop-token", :computer, false, false],
+      ["observeSession", "POST", "/v1/sessions/{name}/observe", :computer, false, false],
+      ["patchControl", "PATCH", "/v1/sessions/{name}/control", :computer, false, true],
+      ["pauseComputer", "POST", "/sandboxes/{sandboxId}/pause", :control, false, false],
+      ["postControlNotify", "POST", "/v1/sessions/{name}/control/notify", :computer, false, false],
+      ["putSessionAttachment", "PUT", "/v1/sessions/{name}/files", :computer, false, false],
+      ["refineSkill", "POST", "/v2/sessions/{name}/refine", :computer, false, false],
+      ["registerComputer", "POST", "/v1/computers", :control, true, false],
+      ["resetAgentThreadV2", "POST", "/v2/sessions/{name}/agent/reset", :computer, false, false],
+      ["resumeComputer", "POST", "/sandboxes/{sandboxId}/resume", :control, false, false],
+      ["runAgentV2", "POST", "/v2/sessions/{name}/agent/run", :computer, true, true],
+      ["sessionEpoch", "GET", "/sessions/{name}/epoch", :computer, true, false],
+      ["sessionExec", "POST", "/sessions/{name}/exec", :computer, false, false],
+      ["sessionFocus", "POST", "/sessions/{name}/focus", :computer, false, false],
+      ["sessionTerminalRecreate", "POST", "/sessions/{name}/terminal/recreate", :computer, false, false],
+      ["setComputerIdleTimeout", "PUT", "/sandboxes/{sandboxId}/idle-timeout", :control, false, false],
+      ["setSkillEnabled", "PUT", "/v1/skills/{name}/enabled", :computer, false, false],
+      ["steerAgentV2", "POST", "/v2/sessions/{name}/agent/steer", :computer, false, false],
+      ["stopComputerRuntime", "POST", "/sandboxes/{sandboxId}/stop", :control, true, false],
+      ["streamAuthorEventsV2", "GET", "/v2/sessions/{name}/skills/author/{author_id}/events", :computer, true, false],
+      ["tabsCreate", "POST", "/sessions/{name}/tabs", :computer, false, false],
+      ["tabsDelete", "DELETE", "/sessions/{name}/tabs/{target_id}", :computer, true, false],
+      ["tabsList", "GET", "/sessions/{name}/tabs", :computer, true, false],
+      ["tabsPatch", "PATCH", "/sessions/{name}/tabs/{target_id}", :computer, false, false],
+      ["teachSkill", "POST", "/v2/sessions/{name}/teach", :computer, false, false],
+      ["uploadArtifact", "POST", "/v1/sessions/{name}/artifacts", :computer, false, false],
+      ["uploadFile", "POST", "/v1/sessions/{name}/upload_file", :computer, false, false],
+      ["zipArtifacts", "GET", "/v1/sessions/{name}/artifacts/zip", :computer, true, false],
+    ].map { |row| build(*row) }.freeze
+
+    BY_ID = TABLE.to_h { |operation| [operation.id, operation] }.freeze
+
+    module_function
+
+    def fetch(id) = BY_ID.fetch(id)
+
+    # The operation a request to `path` (no query) on a `host` role matches, or
+    # nil for a route outside the table.
+    def match(host, method, path)
+      method = method.to_s.upcase
+      TABLE.select { |op| op.host == host && op.method == method && op.pattern.match?(path) }
+           .max_by(&:specificity)
+    end
+  end
+end

data/lib/pinesandbox/response_handler.rb

@@ -0,0 +1,88 @@
+module PineSandbox
+  # Turns an HTTP error response into the matching typed error: the problem
+  # type's class when the body is an RFC 9457 problem detail Pine knows,
+  # otherwise the status tier.
+  module ResponseHandler
+    # Standard RFC 9457 problem-detail fields. Anything outside this
+    # set is treated as a "problem extension" and surfaced via
+    # ApiError#problem_extensions so callers can read e.g.
+    # `err.handoff_id` or `err.field`.
+    PROBLEM_DETAIL_STANDARD_KEYS = %w[type title status detail instance].freeze
+
+    private
+
+    def raise_for_status!(response_or_status, body = nil)
+      if response_or_status.respond_to?(:status)
+        status = response_or_status.status
+        parsed_body = parse_error_body(response_or_status.body)
+        raw_body = response_or_status.body.to_s
+      else
+        status = response_or_status
+        parsed_body = parse_error_body(body)
+        raw_body = body.is_a?(String) ? body : JSON.generate(body)
+      end
+
+      # Prefer the typed problem-detail class when the response body
+      # carries an RFC 9457 `type` slug we know about; fall back to
+      # the status-tier class otherwise. Existing rescues against the
+      # status-tier classes keep working — typed classes inherit from
+      # them (see PineSandbox::ApiError).
+      problem_type = parsed_body["type"] if parsed_body.is_a?(Hash)
+      error_class = PineSandbox.problem_class_for(problem_type) || status_tier_class_for(status)
+
+      problem_ext =
+        if parsed_body.is_a?(Hash) && problem_type
+          parsed_body.reject { |k, _| PROBLEM_DETAIL_STANDARD_KEYS.include?(k.to_s) }
+        else
+          {}
+        end
+
+      # X-Request-Id is set on EVERY response by the server's outermost
+      # middleware (0C error contract). A conformant ProblemDetail body echoes
+      # it as `request_id`, but raw / non-typed error bodies carry it only in
+      # the header — capture it so ApiError#request_id is populated for any
+      # error, not just typed problem details. The body value (if present)
+      # wins; both are the same id by contract.
+      if response_or_status.respond_to?(:headers)
+        rid = response_or_status.headers["x-request-id"] || response_or_status.headers["X-Request-Id"]
+        problem_ext["request_id"] ||= rid if rid && !rid.to_s.empty?
+      end
+
+      raise error_class.new(
+        status: status,
+        error_code: parsed_body["code"] || parsed_body["errorCode"] || parsed_body["error"],
+        error_message: parsed_body["message"] || parsed_body["errorMessage"] ||
+                       (problem_type ? parsed_body["detail"] : nil),
+        response_body: raw_body,
+        problem_type: problem_type,
+        problem_extensions: problem_ext
+      )
+    end
+
+    def status_tier_class_for(status)
+      case status
+      when 400 then BadRequestError
+      when 401 then UnauthorizedError
+      when 403 then ForbiddenError
+      when 404 then NotFoundError
+      when 409 then ConflictError
+      when 410 then GoneError
+      when 412 then PreconditionFailedError
+      when 422 then UnprocessableEntityError
+      when 428 then PreconditionRequiredError
+      when 503 then ServiceUnavailableError
+      when 500..599 then ServerError
+      else ApiError
+      end
+    end
+
+    def parse_error_body(body)
+      return body if body.is_a?(Hash)
+      return {} if body.nil? || body == ""
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "message" => body.to_s }
+    end
+  end
+end

data/lib/pinesandbox/runtime_details.rb

@@ -0,0 +1,25 @@
+module PineSandbox
+  # An observation of one runtime, not the identity or a cached health verdict.
+  RuntimeLifetime = Data.define(:idle_timeout_seconds, :min_idle_timeout_seconds,
+                                :max_idle_timeout_seconds, :max_runtime_age_seconds,
+                                :stop_at, :deadline) do
+    def self.from_payload(value)
+      return unless value
+
+      new(idle_timeout_seconds: value.fetch("idle_timeout_seconds"),
+          min_idle_timeout_seconds: value.fetch("min_idle_timeout_seconds"),
+          max_idle_timeout_seconds: value.fetch("max_idle_timeout_seconds"),
+          max_runtime_age_seconds: value.fetch("max_runtime_age_seconds"),
+          stop_at: Time.iso8601(value.fetch("stop_at")), deadline: Time.iso8601(value.fetch("deadline")))
+    end
+  end
+
+  RuntimeDetails = Data.define(:id, :state, :reason, :message, :retryable,
+                              :operation_id, :created_at, :expires_at, :lifecycle, :runtime_revision) do
+    def self.from_runtime(info)
+      new(id: info.id, state: info.status, reason: info.reason, message: info.message,
+          retryable: info.retryable, operation_id: info.operation_id,
+          created_at: info.created_at, expires_at: info.expires_at, lifecycle: info.lifecycle, runtime_revision: info.runtime_revision)
+    end
+  end
+end

data/lib/pinesandbox/runtime_handle.rb

@@ -0,0 +1,252 @@
+require "securerandom"
+require_relative "errors"
+require_relative "clock"
+
+module PineSandbox
+  # Lifecycle handle for a Computer's runtime, backed by the project-scoped
+  # ControlPlane. A powered-on Computer holds one of these;
+  # Computer#stop/#kill/#alive? delegate here. It carries NO data-plane knowledge —
+  # the coordinator host is derived separately from the Zone.
+  # @api private
+  class RuntimeHandle
+    READY = :running
+    WAIT_FAILURE_STATES = %i[failed terminated unavailable].freeze
+    LIVE = %i[running pending stopping].freeze
+    DEFAULT_POLL_INTERVAL = 2
+
+    attr_reader :id
+    alias_method :runtime_id, :id
+
+    # `clock` returns monotonic seconds and `sleeper` waits; both default to
+    # the control plane's clock. `sandbox_id:` is the deprecated spelling of
+    # `runtime_id:`.
+    def initialize(control_plane:, runtime_id: nil, sandbox_id: nil, status: nil, clock: nil, sleeper: nil)
+      id = runtime_id || sandbox_id
+      raise ArgumentError, "runtime_id required" if id.to_s.empty?
+
+      source = control_plane.respond_to?(:clock) ? control_plane.clock : PineSandbox::SYSTEM_CLOCK
+      @control_plane = control_plane
+      @id = id.to_s
+      @status = status
+      @clock = clock || -> { source.monotonic }
+      @sleeper = sleeper || ->(seconds) { source.sleep(seconds) }
+    end
+
+    # Allocation may reuse Running from its create response. Memory resume must
+    # discard that observation and wait for the controller's new completion.
+    def wait_until_running(timeout:, interval: DEFAULT_POLL_INTERVAL)
+      return self if @status == READY
+
+      wait_until_state(:running, timeout: timeout, interval: interval)
+    end
+
+    def pause(timeout: 360, interval: DEFAULT_POLL_INTERVAL)
+      transition_memory(:pause, :paused, timeout: timeout, interval: interval)
+    end
+
+    def resume(timeout: 360, interval: DEFAULT_POLL_INTERVAL)
+      transition_memory(:resume, :running, timeout: timeout, interval: interval)
+    end
+
+    def status
+      refresh_status
+    end
+
+    def set_idle_timeout(seconds:)
+      observed = runtime_details
+      raise BindError, "Runtime has no admitted lifetime policy; choose idle timeout on the next Start" unless observed.lifecycle
+
+      @control_plane.set_idle_timeout(@id, seconds: seconds, etag: observed.etag)
+    end
+
+    def runtime_details
+      @control_plane.get(@id)
+    end
+
+    # Observe existing intent before admitting a new operation. No SDK memory
+    # or saved operation cursor is needed to continue Stop from another backend.
+    def stop(wait_timeout: 390, interval: DEFAULT_POLL_INTERVAL)
+      return false if wait_timeout <= 0
+
+      deadline = @clock.call + wait_timeout
+      info = @control_plane.get(@id, request_timeout: wait_timeout)
+      return true if released?(info)
+      if info.status == :save_failed && !info.retryable
+        raise StopSaveError.new(Error.new(info.message), retryable: false)
+      end
+      unless %i[saving stopping].include?(info.status)
+        begin
+          @control_plane.stop(@id, operation_id: SecureRandom.uuid, request_timeout: remaining(deadline))
+        rescue PineSandbox::ConflictError
+          # A concurrent caller may have admitted Stop first. Join only that
+          # actual operation; a memory-transition conflict is still an error.
+          info = @control_plane.get(@id, request_timeout: remaining(deadline))
+          raise unless %i[saving stopping].include?(info.status)
+        end
+      end
+      loop do
+        info = next_observation(info, deadline, interval)
+        return true if released?(info)
+        if info.status == :save_failed
+          raise StopSaveError.new(Error.new(info.message), retryable: info.retryable == true)
+        end
+      end
+    rescue PineSandbox::NotFoundError
+      true
+    rescue PineSandbox::TimeoutError
+      raise if @clock.call < deadline
+
+      false
+    end
+
+    # Explicit saved-state recovery discards retained memory. It is allowed
+    # only after a recorded failure and is fenced by the observed HTTP ETag.
+    def release_failed_runtime(info, wait_timeout: 90, interval: DEFAULT_POLL_INTERVAL)
+      deadline = @clock.call + wait_timeout
+      unless info.status == :stopping
+        unless %i[save_failed unavailable failed terminated].include?(info.status) && info.reason != "CaptureTimeout"
+          raise PineSandbox::ConflictError.new(status: 409, error_message: "Runtime has no recorded failure; use Stop or Resume")
+        end
+        raise PineSandbox::Error, "Server did not supply a conditional release version" if info.etag.to_s.empty?
+        @control_plane.destroy(@id, if_match: info.etag, request_timeout: remaining(deadline))
+      end
+      wait_until_released(info, deadline, interval)
+    rescue PineSandbox::TimeoutError
+      raise if @clock.call < deadline
+      false
+    end
+
+    # Delete, then wait for the sandbox record to disappear. This confirms
+    # compute release only. Computer#stop uses the controller's graceful Stop.
+    # false retains the caller's handle when deletion remains unconfirmed.
+    def terminate(wait_timeout: 90, interval: DEFAULT_POLL_INTERVAL)
+      deadline = @clock.call + wait_timeout
+      return false if wait_timeout <= 0
+
+      @control_plane.destroy(@id, request_timeout: wait_timeout)
+      wait_until_released(nil, deadline, interval)
+    rescue PineSandbox::TimeoutError
+      raise if @clock.call < deadline
+
+      false
+    end
+
+    # Ungraceful force-recover: best-effort DELETE, no wait. Never raises.
+    def kill
+      @control_plane.destroy(@id)
+      true
+    rescue StandardError
+      false
+    end
+
+    def alive?
+      LIVE.include?(refresh_status)
+    rescue StandardError
+      false
+    end
+
+    # Absence or explicit controller compute release permits dropping the handle.
+    # Generic terminal state, timeout, and errors are insufficient.
+    def gone?(request_timeout: 5)
+      released?(@control_plane.get(@id, request_timeout: request_timeout))
+    rescue PineSandbox::NotFoundError
+      true
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def wait_until_released(info, deadline, interval)
+      loop do
+        return false if @clock.call >= deadline
+        begin
+          info = next_observation(info, deadline, interval)
+          return true if released?(info)
+        rescue PineSandbox::NotFoundError
+          return true
+        rescue StandardError
+          # A failed observation is not proof of deletion. Preserve the
+          # existing bounded retry without spinning after a transport error.
+          @sleeper.call([interval, remaining(deadline)].min)
+        end
+      end
+    rescue PineSandbox::TimeoutError
+      false
+    end
+
+    def next_observation(previous, deadline, interval)
+      timeout = remaining(deadline)
+      if previous
+        @control_plane.wait_for_change(@id, previous: previous, request_timeout: timeout, interval: interval)
+      else
+        @control_plane.get(@id, request_timeout: timeout)
+      end
+    end
+
+    def remaining(deadline)
+      timeout = deadline - @clock.call
+      raise PineSandbox::TimeoutError, "Computer #{@id} Stop wait ended; the server continues cleanup" if timeout <= 0
+      timeout
+    end
+
+    def released?(info)
+      info.status == :terminated && info.reason == "COMPUTE_RELEASED"
+    end
+
+    def transition_memory(operation, target, timeout:, interval:)
+      raise ArgumentError, "timeout must be positive" unless timeout.positive?
+
+      deadline = @clock.call + timeout
+      accepted = @control_plane.public_send(operation, @id, request_timeout: timeout)
+      @status = nil
+      unless accepted
+        # Older Docker servers answer 409 for an already completed transition.
+        remaining = deadline - @clock.call
+        raise PineSandbox::ReadyTimeoutError, "Computer #{@id} #{operation} exceeded its deadline" if remaining <= 0
+        return self if refresh_status(request_timeout: remaining) == target
+
+        raise PineSandbox::ConflictError.new(status: 409, error_message: "Computer #{@id} cannot #{operation} in its current state")
+      end
+      wait_until_state(target, timeout: deadline - @clock.call, interval: interval)
+    end
+
+    def wait_until_state(target, timeout:, interval:)
+      deadline = @clock.call + timeout
+      info = nil
+      loop do
+        remaining = deadline - @clock.call
+        if remaining <= 0
+          raise PineSandbox::ReadyTimeoutError, "Computer #{@id} did not reach #{target} before the deadline (last state #{@status.inspect})"
+        end
+        begin
+          info = next_observation(info, deadline, interval)
+          state = @status = info.status
+        rescue PineSandbox::TimeoutError => error
+          raise error if @clock.call < deadline
+
+          raise PineSandbox::ReadyTimeoutError, "Computer #{@id} did not reach #{target} before the deadline"
+        end
+        return self if state == target
+        if WAIT_FAILURE_STATES.include?(state)
+          raise PineSandbox::RuntimeFailedError.new(
+            "Computer runtime #{@id} reported #{state.inspect} before reaching #{target}", runtime_id: @id, state: state
+          )
+        end
+      end
+    end
+
+    def refresh_status(request_timeout: nil)
+      @status = if request_timeout
+        @control_plane.get(@id, request_timeout: request_timeout).status
+      else
+        @control_plane.get(@id).status
+      end
+    end
+
+  end
+
+  # Deprecated: use RuntimeHandle.
+  SandboxHandle = RuntimeHandle
+  deprecate_constant :SandboxHandle
+end