pinesandbox 0.3.18 → 0.3.20

data/lib/pinesandbox/control_plane.rb

@@ -4,7 +4,7 @@ require "time"
 require_relative "errors"
 require_relative "clock"
 require_relative "operations"
-require_relative "runtime_details"
+require_relative "sandbox_details"
 require_relative "spec_version_middleware"
 
 module PineSandbox
@@ -14,7 +14,7 @@ module PineSandbox
   # specs/computer-api.yaml lifecycle routes (root, no /v1).
   # @api private
   class ControlPlane
-    Runtime = Struct.new(:id, :image, :status, :metadata, :entrypoint,
+    SandboxInfo = Struct.new(:id, :image, :status, :metadata, :entrypoint,
                          :expires_at, :created_at, :operation_id,
                          :retryable, :reason, :message, :etag, :lifecycle, :runtime_revision, keyword_init: true)
 
@@ -49,7 +49,7 @@ module PineSandbox
     # Internal adapter for the public Computer contract. No generic sandbox
     # create, image selection or task dispatch is available through this client.
     def create_computer(body:, request_timeout: nil)
-      # A create ID permits identical retries without extending runtime expiry.
+      # A create ID permits identical retries without extending the Computer's expiry.
       keyed = !!body[:create_id]
       deadline = monotonic_now + request_timeout if request_timeout
       busy_repeats = 0
@@ -135,7 +135,7 @@ module PineSandbox
       true
     end
 
-    # These methods report acceptance. RuntimeHandle waits for completion.
+    # These methods report acceptance. SandboxHandle waits for completion.
     # Keep the boolean result for integrations using older Docker servers.
     # Neither is replay-safe, so a transport fault raises instead of resending.
     def pause(sandbox_id, request_timeout: nil)
@@ -224,10 +224,10 @@ module PineSandbox
     def to_sandbox!(resp, ok:)
       raise_for_status!(resp) unless ok.include?(resp.status)
       payload = parse_json(resp)
-      Runtime.new(id: payload["id"], image: payload["image"], metadata: payload["metadata"] || {},
-                  entrypoint: payload["entrypoint"], status: runtime_state(payload.dig("status", "state")),
-                  expires_at: runtime_time(payload["expiresAt"]), created_at: runtime_time(payload["createdAt"]),
-                  lifecycle: RuntimeLifetime.from_payload(payload["lifecycle"]),
+      SandboxInfo.new(id: payload["id"], image: payload["image"], metadata: payload["metadata"] || {},
+                  entrypoint: payload["entrypoint"], status: sandbox_state(payload.dig("status", "state")),
+                  expires_at: parse_time(payload["expiresAt"]), created_at: parse_time(payload["createdAt"]),
+                  lifecycle: SandboxLifetime.from_payload(payload["lifecycle"]),
                   runtime_revision: payload["runtime_revision"],
                   operation_id: payload.dig("status", "operation_id"),
                   retryable: payload.dig("status", "retryable"),
@@ -235,11 +235,11 @@ module PineSandbox
     end
 
     # "Running" → :running, "PendingResume" → :pending_resume.
-    def runtime_state(state)
+    def sandbox_state(state)
       state&.to_s&.gsub(/([a-z\d])([A-Z])/, '\1_\2')&.downcase&.to_sym
     end
 
-    def runtime_time(value) = value.nil? || value.is_a?(Time) ? value : Time.iso8601(value)
+    def parse_time(value) = value.nil? || value.is_a?(Time) ? value : Time.iso8601(value)
 
     def raise_for_status!(resp)
       body = parse_json(resp)

data/lib/pinesandbox/error_taxonomy.rb

@@ -9,6 +9,7 @@ module PineSandbox
       "/errors/sandbox-not-ready" => true,
       "/errors/unauthorized" => false,
       "/errors/forbidden" => false,
+      "/errors/feature-disabled" => false,
       "/errors/precondition-required" => false,
       "/errors/precondition-failed" => true,
       "/errors/malformed-json" => false,
@@ -37,6 +38,8 @@ module PineSandbox
       "/errors/no-desktop-stream" => false,
       "/errors/desktop-unavailable" => false,
       "/errors/skills-unavailable" => false,
+      "/errors/artifacts-unavailable" => true,
+      "/errors/artifacts-not-configured" => false,
       "/errors/secret-in-skill" => false,
       "/errors/skill-author-failed" => true,
       "/errors/author-in-flight" => true,

data/lib/pinesandbox/errors.rb

@@ -55,7 +55,7 @@ module PineSandbox
   # An HTTP error response from the Computer API. #status is the HTTP status;
   # #problem_type and #problem_extensions carry an RFC 9457 problem detail
   # (#field, #reason, #handoff_id, #request_id and #retryable? read its common
-  # members). The message is resource-first: the runtime (#runtime_id) and the
+  # members). The message is resource-first: the Computer sandbox (#sandbox_id) and the
   # operation (#op, "<METHOD> <path>") come before #request_id, so a handler
   # that logs only the message can still route a report.
   class ApiError < Error
@@ -73,14 +73,8 @@ module PineSandbox
       super(@built_message)
     end
 
-    # The runtime that answered, when the request reached one.
-    def runtime_id = problem_extensions["sandbox_id"]
-
-    # Deprecated: use #runtime_id.
-    def sandbox_id
-      PineSandbox.deprecated_name("ApiError#sandbox_id", "#runtime_id")
-      runtime_id
-    end
+    # The id of the Computer sandbox that answered, when the request reached a Computer.
+    def sandbox_id = problem_extensions["sandbox_id"]
 
     # The response's machine `code` ({code, message} bodies), when present.
     def code = error_code
@@ -105,12 +99,11 @@ module PineSandbox
     # The response's Retry-After in seconds, when it set one.
     attr_accessor :retry_after
 
-    # Folds the runtime and operation onto an error raised before they were
+    # Folds the sandbox id and operation onto an error raised before they were
     # known, filling only what the server didn't send, and rebuilds the message.
     # Returns self, for re-raising.
-    def attach_context!(runtime_id: nil, op: nil, sandbox_id: nil)
-      runtime_id ||= sandbox_id
-      problem_extensions["sandbox_id"] ||= runtime_id if runtime_id && !runtime_id.to_s.empty?
+    def attach_context!(sandbox_id: nil, op: nil)
+      problem_extensions["sandbox_id"] ||= sandbox_id if sandbox_id && !sandbox_id.to_s.empty?
       problem_extensions["op"] ||= op if op && !op.to_s.empty?
       @built_message = build_message
       self
@@ -131,7 +124,7 @@ module PineSandbox
           "API request failed with status #{status}"
         end
       parts = []
-      parts << "runtime=#{runtime_id}" if runtime_id && !runtime_id.to_s.empty?
+      parts << "sandbox=#{sandbox_id}" if sandbox_id && !sandbox_id.to_s.empty?
       parts << "op=#{op}" if op && !op.to_s.empty?
       parts << "request_id=#{request_id}" if request_id && !request_id.to_s.empty?
       parts.empty? ? base : "#{base} (#{parts.join(', ')})"
@@ -177,6 +170,10 @@ module PineSandbox
   # suspended or out of credits): control is cut, reads stay open. Re-attach,
   # or report the suspension.
   class LeaseExpired < ForbiddenError; end
+  # The project, or this Computer's binding, doesn't have a feature the call
+  # needs, such as the shell grant for Session#exec or the artifacts feature for
+  # the artifact methods. Retrying won't help.
+  class FeatureDisabled < ForbiddenError; end
   # The access lapsed and renewing it failed for now. Retry; don't re-attach.
   class LeaseRefreshUnavailable < ServiceUnavailableError; end
   class AnotherSessionHuman < ConflictError; end
@@ -194,10 +191,23 @@ module PineSandbox
   class HandoffExpired < GoneError; end
   class HandoffPersistenceFailed < ServerError; end
 
+  # A Computer's artifacts have no file at #path (the path you passed,
+  # relative to the Computer's artifacts). A NotFoundError, so tier rescues
+  # keep catching it.
+  class ArtifactNotFoundError < NotFoundError
+    attr_reader :path
+
+    def initialize(path:, **fields)
+      @path = path
+      super(**fields)
+    end
+  end
+
   # Problem `type` → its typed error; anything else falls back to the status tier.
   PROBLEM_TYPE_CLASSES = {
     "/errors/control-not-held" => ControlNotHeld,
     "/errors/lease-expired" => LeaseExpired,
+    "/errors/feature-disabled" => FeatureDisabled,
     "/errors/lease-refresh-unavailable" => LeaseRefreshUnavailable,
     "/errors/another-session-human" => AnotherSessionHuman,
     "/errors/concurrent-transition" => ConcurrentTransition,
@@ -230,20 +240,32 @@ module PineSandbox
   class ConnectionError < Error; end
   class ReadyTimeoutError < Error; end
 
-  # The runtime reported failed, terminated or unavailable before the
+  # The Computer reported failed, terminated or unavailable before the
   # lifecycle operation finished.
-  class RuntimeFailedError < Error
-    attr_reader :runtime_id, :state
+  class SandboxFailedError < Error
+    attr_reader :sandbox_id, :state
 
-    def initialize(message = nil, runtime_id: nil, state: nil)
-      @runtime_id = runtime_id
+    def initialize(message = nil, sandbox_id: nil, state: nil)
+      @sandbox_id = sandbox_id
       @state = state
-      super(message || "Computer runtime #{runtime_id} reported #{state.inspect} before completing the lifecycle operation")
+      super(message || "Computer sandbox #{sandbox_id} reported #{state.inspect} before completing the lifecycle operation")
+    end
+  end
+
+  # The Computer's artifacts take up more than its storage limit, so an
+  # upload or a copy into them is refused before anything is sent. Delete
+  # files to make room. #used_bytes and #limit_bytes are as Pine counted
+  # them when it issued the storage token.
+  class ArtifactStorageFullError < Error
+    attr_reader :used_bytes, :limit_bytes
+
+    def initialize(used_bytes:, limit_bytes:)
+      @used_bytes = used_bytes
+      @limit_bytes = limit_bytes
+      super("the Computer's artifacts use #{used_bytes} bytes, more than their limit of #{limit_bytes}; " \
+            "delete files before writing more")
     end
   end
-  # Deprecated: use RuntimeFailedError.
-  SandboxFailedError = RuntimeFailedError
-  deprecate_constant :SandboxFailedError
 
   class StreamError < Error; end
   class StreamingUnsupportedError < Error; end
@@ -295,14 +317,14 @@ module PineSandbox
     end
   end
 
-  # Start found an existing runtime. No replacement was allocated. Preserve the
-  # BindError superclass for integrations already rescuing Start conflicts.
-  class RuntimeRetainedError < BindError
-    attr_reader :runtime_id, :state
+  # Start found the Computer still running or paused, and started nothing.
+  # Preserve the BindError superclass for integrations already rescuing Start conflicts.
+  class SandboxRetainedError < BindError
+    attr_reader :sandbox_id, :state
 
-    def initialize(runtime_id:, state:)
-      @runtime_id, @state = runtime_id, state
-      super("Computer still has runtime #{runtime_id} (#{state}); Stop it or Resume retained memory before Start")
+    def initialize(sandbox_id:, state:)
+      @sandbox_id, @state = sandbox_id, state
+      super("Computer hasn't stopped (Computer sandbox #{sandbox_id}, state #{state}); Stop it or Resume retained memory before Start")
     end
   end
 
@@ -380,46 +402,34 @@ module PineSandbox
   class ProjectAccessDenied < AttachCredentialsError; end
 
   # 412 — another attach advanced the authorization revision. Terminal:
-  # reload/adopt the winning integrator database binding; do not allocate a runtime.
+  # reload/adopt the winning integrator database binding; do not start the Computer again.
   class BindingRevisionConflictError < AttachCredentialsError
-    attr_reader :current_binding_revision, :current_runtime_id
+    attr_reader :current_binding_revision, :current_sandbox_id
 
-    def initialize(message, current_binding_revision: nil, current_runtime_id: nil, current_sandbox_id: nil, **kwargs)
+    def initialize(message, current_binding_revision: nil, current_sandbox_id: nil, **kwargs)
       @current_binding_revision = current_binding_revision
-      @current_runtime_id = current_runtime_id || current_sandbox_id
+      @current_sandbox_id = current_sandbox_id
       super(message, **kwargs)
     end
 
     # The winning binding's revision (also #current_binding_revision).
     def current_revision = current_binding_revision
-
-    # Deprecated: use #current_runtime_id.
-    def current_sandbox_id
-      PineSandbox.deprecated_name("BindingRevisionConflictError#current_sandbox_id", "#current_runtime_id")
-      current_runtime_id
-    end
   end
 
   # Portal committed a new authorization revision, but the later bind
-  # failed. The SDK has cleaned up the fresh runtime best-effort. Persist the
+  # failed. The SDK has shut the Computer down best-effort. Persist the
   # revision before retrying so the next attach can supersede this attempt.
   # #credentials is present for create_computer, whose generated identity and
   # capture keypair would otherwise be lost because the method has no result.
   class AttachAuthorizationCommittedError < BindError
-    attr_reader :binding_revision, :runtime_id, :credentials
+    attr_reader :binding_revision, :sandbox_id, :credentials
 
-    def initialize(message, binding_revision:, runtime_id: nil, sandbox_id: nil, credentials: nil, **kwargs)
+    def initialize(message, binding_revision:, sandbox_id: nil, credentials: nil, **kwargs)
       @binding_revision = binding_revision
-      @runtime_id = runtime_id || sandbox_id
+      @sandbox_id = sandbox_id
       @credentials = credentials
       super(message, **kwargs)
     end
-
-    # Deprecated: use #runtime_id.
-    def sandbox_id
-      PineSandbox.deprecated_name("AttachAuthorizationCommittedError#sandbox_id", "#runtime_id")
-      runtime_id
-    end
   end
 
   # The Computer answered with an `X-Computer-Spec-Version` major this SDK
@@ -435,44 +445,44 @@ module PineSandbox
   end
 
   # The Computer rejected the portal-issued bind_token: bad signature, unknown
-  # kid, iss/aud mismatch, expired, replayed jti, or issued for another runtime.
+  # kid, iss/aud mismatch, expired, replayed jti, or issued for another start.
   # Terminal — retrying with the same token cannot succeed.
   class BindAuthError < BindError; end
 
-  # Another runtime holds the epoch lease for this Computer (a live attach
-  # exists elsewhere, or you are attaching from two places at once).
+  # This Computer is already attached elsewhere: another attach holds its epoch
+  # lease, or you are attaching from two places at once.
   class ComputerAlreadyAttachedError < BindError; end
 
-  # The allocated runtime can't be bound (it was already bound, or a prior
-  # bind failed on it). The SDK deletes it before raising; retry attach for a
-  # fresh runtime.
-  class RuntimeUnusableError < BindError; end
-  # Deprecated: use RuntimeUnusableError.
-  PodPoisonedError = RuntimeUnusableError
+  # This Computer sandbox can't be attached (it was already attached, or a prior attach
+  # failed on it). The SDK shuts it down before raising; retry attach to start
+  # the Computer again.
+  class SandboxUnusableError < BindError; end
+  # Deprecated: use SandboxUnusableError.
+  PodPoisonedError = SandboxUnusableError
   deprecate_constant :PodPoisonedError
 
-  # Saved state was unreachable during the bind; the runtime has been
-  # cleaned up. Retry attach later (transient).
+  # Saved state was unreachable during the bind; the SDK has shut the Computer
+  # down. Retry attach later (transient).
   class SavedStateUnavailableError < BindError; end
   # Deprecated: use SavedStateUnavailableError.
   BrokerUnreachableError = SavedStateUnavailableError
   deprecate_constant :BrokerUnreachableError
 
   # The bind handshake exhausted its retries without a terminal
-  # classification. Usually a runtime-allocation or network issue.
+  # classification. Usually a slow start or a network issue.
   class BindTimeoutError < BindError; end
 
   # The Computer returned 401 for its Computer token (ct_) — a REPORT that
   # it did not recognize the binding's token, NOT an instruction to
-  # re-attach. ct_ is binding-lifetime (no idle expiry), so on a live,
-  # current runtime this state is binding_auth_lost: surface it and
-  # reconcile; only confirmed runtime-gone evidence justifies an attach
-  # (a fresh runtime invalidates every ps_ and fences the old runtime's state).
+  # re-attach. ct_ is binding-lifetime (no idle expiry), so on a running
+  # Computer this state is binding_auth_lost: surface it and reconcile; only
+  # a Computer confirmed stopped justifies an attach (a new start invalidates
+  # every ps_ and fences the previous start's state).
   # A 401 for a session token (ps_) is an ordinary UnauthorizedError.
   class TokenRejectedError < BindError
-    MESSAGE = "the Computer rejected the computer token (401). ct_ is binding-lifetime, so on a live " \
-              "current runtime this is binding_auth_lost — reconcile; re-attach ONLY on confirmed " \
-              "runtime-gone evidence (a fresh runtime invalidates every ps_)".freeze
+    MESSAGE = "the Computer rejected the computer token (401). ct_ is binding-lifetime, so on a " \
+              "running Computer this is binding_auth_lost — reconcile; re-attach ONLY once the " \
+              "Computer is confirmed stopped (a new start invalidates every ps_)".freeze
 
     # The rejection of `api_error` (a 401 answer to a Computer token), with
     # its operation and request id folded into the message.
@@ -482,14 +492,14 @@ module PineSandbox
     end
   end
 
-  # The gateway can no longer route this Computer's attached runtime. This is
-  # distinct from an /errors/session-not-found response on a live
+  # The gateway can no longer route to this Computer's host, which is also
+  # true while it's paused or recovering. This is distinct from an /errors/session-not-found response on a live
   # Computer. Inherit the legacy 404 tier so existing NotFoundError rescues
   # remain valid; the original typed ApiError is retained as Exception#cause.
-  class RuntimeGoneError < NotFoundError
+  class SandboxGoneError < NotFoundError
     def initialize(api_error)
       detail = api_error.error_message.to_s
-      message = "the attached runtime is gone"
+      message = "the Computer can't be reached at its host"
       message = "#{message}: #{detail}" unless detail.empty?
       super(
         status: api_error.status,
@@ -502,9 +512,6 @@ module PineSandbox
       self.retry_after = api_error.retry_after
     end
   end
-  # Deprecated: use RuntimeGoneError.
-  SandboxGoneError = RuntimeGoneError
-  deprecate_constant :SandboxGoneError
 
   # 429 COMPUTER_CAPACITY_EXCEEDED on create/attach: the project is at its
   # concurrent Computer limit, so nothing was provisioned. Not retried by the

data/lib/pinesandbox/models/artifact.rb

@@ -3,7 +3,7 @@ require "time"
 module PineSandbox
   module Models
     # A session artifact's metadata — a managed session output (a client upload,
-    # a claimed browser download, or an agent task output) with a download
+    # a browser download, or an agent task output) with a download
     # endpoint. Returned by {PineSandbox::Session#list_artifacts} and
     # {PineSandbox::Session#upload_artifact}. Mirrors the spec `Artifact` schema.
     Artifact = Struct.new(

data/lib/pinesandbox/models/artifact_file.rb

@@ -0,0 +1,40 @@
+require "time"
+
+module PineSandbox
+  module Models
+    # One file in a Computer's artifacts. Returned by
+    # {PineSandbox::Artifacts#list}, #upload and #copy. `path` is relative to
+    # the Computer's artifacts ("research/q3.csv"); `note` is the note the file
+    # was uploaded with, if any.
+    ArtifactFile = Struct.new(
+      :path,
+      :size,
+      :updated_at,
+      :content_type,
+      :note,
+      keyword_init: true
+    ) do
+      # From a storage object, whose name is `prefix` followed by the path.
+      def self.from_object(object, prefix:)
+        new(
+          path: object["name"].to_s.delete_prefix(prefix),
+          # Storage sends the size as a decimal string.
+          size: object["size"].nil? ? nil : Integer(object["size"].to_s, 10),
+          updated_at: object["updated"] && Time.parse(object["updated"]),
+          content_type: object["contentType"],
+          note: object.dig("metadata", "pine-note")
+        )
+      end
+    end
+
+    # One page of {PineSandbox::Artifacts#list}: the files, the folders
+    # directly below the listed prefix (each ending in "/"; none when listing
+    # recursively), and the token for the next page (nil on the last one).
+    ArtifactPage = Struct.new(
+      :files,
+      :folders,
+      :next_page_token,
+      keyword_init: true
+    )
+  end
+end

data/lib/pinesandbox/models/computer_session.rb

@@ -12,12 +12,15 @@ module PineSandbox
       :token,
       :session_dir,
       :browser,
-      :blind,
+      :artifact_access,
       :created_at,
       :last_active_at,
       keyword_init: true
     ) do
-      def self.from_payload(payload)
+      # `artifact_access_known` is false for a session whose artifact access
+      # only the Computer knows (Computer#adopt_session): #artifact_access is
+      # then nil.
+      def self.from_payload(payload, artifact_access_known: true)
         return nil unless payload
         browser_payload = payload["browser"]
         new(
@@ -26,7 +29,8 @@ module PineSandbox
           token: payload["token"],
           session_dir: payload["session_dir"],
           browser: browser_payload && Browser.from_payload(browser_payload),
-          blind: payload.fetch("blind", false),
+          # An older Computer doesn't report it; its sessions have no access.
+          artifact_access: artifact_access_known ? payload.fetch("artifact_access", "none") : nil,
           created_at: payload["created_at"] && Time.parse(payload["created_at"]),
           last_active_at: payload["last_active_at"] && Time.parse(payload["last_active_at"])
         )

data/lib/pinesandbox/operations.rb

@@ -34,9 +34,10 @@ module PineSandbox
       ["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],
+      ["createArtifactLink", "POST", "/v1/artifacts/links", :computer, false, false],
       ["createComputer", "POST", "/computer-sandboxes", :control, true, false],
+      ["createComputerArtifactToken", "POST", "/v1/computers/{computer_id}/artifacts/token", :control, false, false],
       ["createDiagnostic", "POST", "/v1/diagnostics", :control, true, true],
       ["createSession", "POST", "/sessions", :computer, false, false],
       ["deactivateSkill", "POST", "/v1/skills/{name}/deactivate", :computer, false, false],
@@ -49,7 +50,6 @@ module PineSandbox
       ["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],
@@ -74,7 +74,6 @@ module PineSandbox
       ["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],

data/lib/pinesandbox/{runtime_details.rb → sandbox_details.rb}

@@ -1,6 +1,6 @@
 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,
+  # An observation of the started Computer, not its identity or a cached health verdict.
+  SandboxLifetime = 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)
@@ -14,9 +14,9 @@ module PineSandbox
     end
   end
 
-  RuntimeDetails = Data.define(:id, :state, :reason, :message, :retryable,
+  SandboxDetails = Data.define(:id, :state, :reason, :message, :retryable,
                               :operation_id, :created_at, :expires_at, :lifecycle, :runtime_revision) do
-    def self.from_runtime(info)
+    def self.from_info(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)

data/lib/pinesandbox/{runtime_handle.rb → sandbox_handle.rb}

@@ -3,26 +3,25 @@ require_relative "errors"
 require_relative "clock"
 
 module PineSandbox
-  # Lifecycle handle for a Computer's runtime, backed by the project-scoped
+  # Lifecycle handle for a Computer sandbox, 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
+  class SandboxHandle
     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
+    alias_method :sandbox_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?
+    # the control plane's clock.
+    def initialize(control_plane:, sandbox_id: nil, status: nil, clock: nil, sleeper: nil)
+      id = sandbox_id
+      raise ArgumentError, "sandbox_id required" if id.to_s.empty?
 
       source = control_plane.respond_to?(:clock) ? control_plane.clock : PineSandbox::SYSTEM_CLOCK
       @control_plane = control_plane
@@ -53,13 +52,13 @@ module PineSandbox
     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
+      observed = sandbox_details
+      raise BindError, "Computer was started without a lifetime policy; choose the idle timeout on the next Start" unless observed.lifecycle
 
       @control_plane.set_idle_timeout(@id, seconds: seconds, etag: observed.etag)
     end
 
-    def runtime_details
+    def sandbox_details
       @control_plane.get(@id)
     end
 
@@ -101,11 +100,12 @@ module PineSandbox
 
     # 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)
+    def release_failed_sandbox(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")
+        # Accepts CAPTURE_TIMEOUT as well as CaptureTimeout to unify on SNAKE_CASE while staying backward compatible.
+        unless %i[save_failed unavailable failed terminated].include?(info.status) && !%w[CAPTURE_TIMEOUT CaptureTimeout].include?(info.reason)
+          raise PineSandbox::ConflictError.new(status: 409, error_message: "The Computer 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))
@@ -229,8 +229,8 @@ module PineSandbox
         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
+          raise PineSandbox::SandboxFailedError.new(
+            "Computer sandbox #{@id} reported #{state.inspect} before reaching #{target}", sandbox_id: @id, state: state
           )
         end
       end
@@ -245,8 +245,4 @@ module PineSandbox
     end
 
   end
-
-  # Deprecated: use RuntimeHandle.
-  SandboxHandle = RuntimeHandle
-  deprecate_constant :SandboxHandle
 end