pinesandbox 0.3.18 → 0.3.20

data/lib/pinesandbox/computer.rb

@@ -8,20 +8,21 @@ require_relative "bind_hpke"
 require_relative "capture_keypair"
 require_relative "adapters/coordinator_adapter"
 require_relative "adapters/snapshot_adapter"
+require_relative "artifacts"
 require_relative "session"
 
 module PineSandbox
   # A persistent Computer — the one object in this SDK. It is either
   # powered-off (just an `id` + the per-Computer `key` you hold in your DB)
-  # or powered-on (bound to a live runtime). `attach` allocates a runtime,
-  # runs the bind/restore handshake so the Computer resumes its prior state,
-  # and returns `self`; you then drive it through `create_session`. `stop`
-  # saves supported state and releases the runtime, and you can `attach`
-  # again later onto a fresh runtime with state restored.
+  # or powered-on (started and attached). `attach` starts it, runs the
+  # bind/restore handshake so the Computer resumes its prior state, and
+  # returns `self`; you then drive it through `create_session`. `stop` saves
+  # supported state and shuts the Computer down, and you can `attach` again
+  # later to start it with state restored.
   #
   #   computer = PineSandbox::Computer.new("0190…", key: secret_32_bytes)
   #   computer.attach(connection)
-  #   session  = computer.create_session(name: "main", browser: true)
+  #   session  = computer.create_session
   #   session.create_tab(url: "https://example.com")
   #   computer.stop
   #
@@ -30,25 +31,25 @@ module PineSandbox
   # attach-credentials provider) is set once on the connection. The API key
   # alone cannot read state (that needs the private key material).
   #
-  # Not thread-safe: a single Computer instance carries one binding (runtime
-  # + ct_); drive one Computer from one thread at a time.
+  # Not thread-safe: a single Computer instance carries one binding (sandbox
+  # id + ct_); drive one Computer from one thread at a time.
   class Computer
     CURRENT_KEY_VERSION = 1
     DEFAULT_MAX_BIND_ATTEMPTS = 3
-    # Allocation and runtime readiness; independent of the sandbox lifetime.
+    # How long to wait for the Computer to start; independent of its idle timeout.
     DEFAULT_READY_TIMEOUT = 300
-    # Wall-clock budget for a just-allocated runtime to become bindable. Spans
-    # the gap between allocation reporting "running" and the Computer actually
-    # serving; the bind handshake retries not-ready responses (404 / 503 /
-    # transient transport errors) within it. Generous — a healthy runtime
-    # clears it in seconds; this only bounds one that never comes up.
+    # Wall-clock budget for a just-started Computer to become bindable. Spans
+    # the gap between the lifecycle reporting "running" and the Computer
+    # actually serving; the bind handshake retries not-ready responses (404 /
+    # 503 / transient transport errors) within it. Generous — a healthy
+    # Computer clears it in seconds; this only bounds one that never comes up.
     DEFAULT_BIND_READY_TIMEOUT = 120
     # The Computer id is a lowercase UUIDv7; a non-matching id would be
     # rejected late as a BindAuthError, so reject it up front instead.
     UUID_V7 = /\A[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/.freeze
 
     # Transient transport failures worth retrying the bind handshake on, in
-    # both raw Faraday and SDK shapes. A just-allocated runtime may not be
+    # both raw Faraday and SDK shapes. A just-started Computer may not be
     # accepting connections yet (connection refused / TLS not up) — the same
     # convergence window as 404/503.
     TRANSIENT_BIND_ERRORS = [
@@ -56,16 +57,12 @@ module PineSandbox
       PineSandbox::TimeoutError, PineSandbox::ConnectionError
     ].freeze
 
-    attr_reader :id, :binding_revision, :last_authorized_runtime_id, :location
+    attr_reader :id, :binding_revision, :last_authorized_sandbox_id, :location
 
-    # Deprecated: use #last_authorized_runtime_id.
-    def last_authorized_sandbox_id
-      PineSandbox.deprecated_name("Computer#last_authorized_sandbox_id", "#last_authorized_runtime_id")
-      last_authorized_runtime_id
-    end
-
-    # The runtime this Computer is attached to, or nil when it has none.
-    def runtime_id = @sandbox&.id
+    # The id of the Computer sandbox this Computer is attached to (the API's
+    # `sandbox_id`); it changes on every start.
+    # nil when it isn't attached.
+    def sandbox_id = @sandbox&.id
 
     # @api private — internal plumbing, NOT a supported end-user surface. It is
     # public only because `Session` reaches it via `parent.coordinator` (Ruby
@@ -185,19 +182,20 @@ module PineSandbox
       self
     end
 
-    # Allocate a runtime and bind this Computer to it, restoring its state.
+    # Start this Computer and bind to it, restoring its state.
     # Returns self (now powered-on). Safe across its internal retries —
     # convergence retries re-send the SAME minted envelope, so a
-    # committed-but-lost bind replays idempotently. A runtime-identity
-    # shift is terminal because Portal has already committed the one
-    # authorization allowed for this sandbox. Raises if this Computer is already
+    # committed-but-lost bind replays idempotently. A change of pod_uid or
+    # coord_boot_id is terminal because Portal has already committed the one
+    # authorization allowed for this Computer sandbox. Raises if this Computer is already
     # attached (call #stop or #kill first — re-attaching live must not
-    # silently discard state); on any bind failure the freshly allocated runtime
-    # is deleted and the Computer is left powered-off before a typed error.
+    # silently discard state); on any bind failure the SDK shuts the
+    # just-started Computer down and leaves it powered-off before a typed error.
     #
     # @param config [PineSandbox::Connection]
-    # timeout is the sandbox lifetime. ready_timeout bounds allocation and runtime
-    # readiness; bind_ready_timeout separately bounds the bind/restore handshake.
+    # timeout is how long the Computer keeps running without use. ready_timeout
+    # bounds how long it takes to start; bind_ready_timeout separately bounds the
+    # bind/restore handshake.
     # @param pod_env [nil, Hash] Deprecated; only nil or an empty hash is accepted.
     def attach(config, timeout: 300, ready_timeout: DEFAULT_READY_TIMEOUT, pod_env: nil, metadata: nil,
                location: nil,
@@ -230,7 +228,7 @@ module PineSandbox
       # receipt, not authority to overwrite a newer country another client may
       # have committed after this instance stopped.
       requested_location = normalize_location(location) if location
-      @last_authorized_runtime_id = nil
+      @last_authorized_sandbox_id = nil
       @connection = config
       @clock = config.respond_to?(:clock) ? config.clock : PineSandbox::SYSTEM_CLOCK
 
@@ -241,7 +239,7 @@ module PineSandbox
         body: build_computer_create_body(timeout: timeout, metadata: metadata).merge(create_id: create_id),
         request_timeout: ready_timeout
       )
-      @sandbox = RuntimeHandle.new(control_plane: config.control_plane, runtime_id: info.id, status: info.status)
+      @sandbox = SandboxHandle.new(control_plane: config.control_plane, sandbox_id: info.id, status: info.status)
       # Wait for the pod to report Running (a CUA pod's readiness; the bind handshake
       # below is the functional coord-readiness check). A pod that fails or never
       # becomes Ready is destroyed before the typed error leaves #attach.
@@ -251,16 +249,16 @@ module PineSandbox
         reset_bound_state
         raise
       end
-      # Drive the Computer at its runtime's gateway host `https://<runtime_id>.computer.<zone>`
+      # Drive the Computer at its gateway host `https://<sandbox_id>.computer.<zone>`
       # — port-less, header-less, role-by-path; coord gates every route on the bearer.
-      @coordinator = Adapters::CoordinatorAdapter.new(runtime_id: info.id, zone: config.zone, clock: @clock)
+      @coordinator = Adapters::CoordinatorAdapter.new(sandbox_id: info.id, zone: config.zone, clock: @clock)
 
       # Two retry budgets converge on the bind handshake:
-      #  - readiness (DEADLINE-bounded): the runtime was just allocated, so the
+      #  - readiness (DEADLINE-bounded): the Computer sandbox was just started, so the
       #    gateway can't reach a serving Computer yet — 404 (not yet routable),
       #    503 (not yet ready), a transient transport error, or an in-flight
-      #    bind settling (409 bind-in-progress). All clear as the runtime
-      #    starts, so retry until a wall-clock DEADLINE — a cold runtime or a
+      #    bind settling (409 bind-in-progress). All clear as the Computer
+      #    starts, so retry until a wall-clock DEADLINE — a cold start or a
       #    slow restore can outlast a few tries, and attempt-counting gives up early.
       #  - restore restart (ATTEMPT-bounded): if coord's short-lived two-round
       #    challenge expires, clear only restore_secrets and restart round one
@@ -282,7 +280,7 @@ module PineSandbox
             retry
           end
           reset_bound_state
-          raise BindTimeoutError.new("Computer runtime did not become bindable within #{bind_ready_timeout}s (last: HTTP #{e.status}): #{e.message}", cause: e)
+          raise BindTimeoutError.new("Computer did not become bindable within #{bind_ready_timeout}s (last: HTTP #{e.status}): #{e.message}", cause: e)
         elsif restore_no_challenge?(e) && restore_attempts < max_bind_attempts
           # Only coord's short-lived restore challenge expired. Reuse the one
           # Portal authorization committed for this sandbox and restart round one.
@@ -324,21 +322,19 @@ module PineSandbox
       stop
     end
 
-    # Adopt an ALREADY-bound runtime by its `runtime_id` + `ct_`, WITHOUT allocating
-    # or re-binding. For a trusted backend that persisted `{id, key, runtime_id,
+    # Adopt an ALREADY-attached Computer by its `sandbox_id` + `ct_`, WITHOUT starting
+    # or re-binding. For a trusted backend that persisted `{id, key, sandbox_id,
     # ct_}` and needs to drive across processes/requests (e.g. re-mint a desktop
     # `dt_` for a reconnect). No bind handshake runs, so the state `key` is unused
-    # here — it matters only for #attach (restore onto a fresh runtime). Refuses if
-    # already attached; use Client#start_computer to restore state onto a NEW runtime.
-    # `sandbox_id:` is the deprecated spelling of `runtime_id:`.
-    def adopt(config, computer_token:, runtime_id: nil, sandbox_id: nil, status: :running,
+    # here — it matters only for #attach (restore on the next start). Refuses if
+    # already attached; use Client#start_computer to start it again with state restored.
+    def adopt(config, sandbox_id:, computer_token:, status: :running,
               binding_revision: @binding_revision)
       raise BindError.new("Computer already attached — call #stop or #kill first") if @sandbox
       unless config.respond_to?(:control_plane) && config.respond_to?(:zone)
         raise ArgumentError, "config must be a PineSandbox::Connection (control_plane + zone)"
       end
-      runtime_id ||= sandbox_id
-      raise ArgumentError, "runtime_id required" if runtime_id.to_s.empty?
+      raise ArgumentError, "sandbox_id required" if sandbox_id.to_s.empty?
       raise ArgumentError, "computer_token required" if computer_token.to_s.empty?
       unless binding_revision.is_a?(Integer) && binding_revision >= 0
         raise ArgumentError, "binding_revision must be a non-negative integer"
@@ -346,9 +342,9 @@ module PineSandbox
 
       @connection = config
       @clock = config.respond_to?(:clock) ? config.clock : PineSandbox::SYSTEM_CLOCK
-      @coordinator = Adapters::CoordinatorAdapter.new(runtime_id: runtime_id, zone: config.zone,
+      @coordinator = Adapters::CoordinatorAdapter.new(sandbox_id: sandbox_id, zone: config.zone,
                                                       discovery_token: computer_token, clock: @clock)
-      @sandbox = RuntimeHandle.new(control_plane: config.control_plane, runtime_id: runtime_id, status: status)
+      @sandbox = SandboxHandle.new(control_plane: config.control_plane, sandbox_id: sandbox_id, status: status)
       @computer_token = computer_token
       @binding_revision = binding_revision
       self
@@ -381,35 +377,54 @@ module PineSandbox
 
     # --- driving the powered-on Computer (sessions hold the `ps_*` token) ---
 
+    # Creates a session and returns it holding its session token. Save its
+    # name and token, with #binding_revision, when this returns: no other call
+    # returns the token, and #adopt_session needs both to drive the session from
+    # another request or process. The session ends when the Computer stops or
+    # is recovered; delete the record then.
+    #
     # `name` is optional: omit it (or pass nil/"") to let the Computer mint a
     # friendly adjective-noun-hex name (e.g. "brave-otter-9f3a1c") — read it back
     # off the returned {Session}. `label` is an optional human-meaningful tag,
     # distinct from the addressing name. A duplicate name raises
-    # PineSandbox::ConflictError.
-    def create_session(name: nil, label: nil, browser: false, blind: false)
+    # PineSandbox::ConflictError. Every session has its own browser window.
+    #
+    # `artifact_access` is what the session's agent may do with the Computer's
+    # artifacts (see Client#artifacts): "none" (the default: nothing, and the
+    # agent isn't told about them), "read_only" (list and read) or
+    # "read_write" (also save and delete files and make public links). A
+    # Symbol works too. Your own access with the project key is the same
+    # either way.
+    def create_session(name: nil, label: nil, artifact_access: nil)
+      unless artifact_access.nil? || ((artifact_access.is_a?(String) || artifact_access.is_a?(Symbol)) &&
+                                      Session::ARTIFACT_ACCESS.include?(artifact_access.to_s))
+        raise ArgumentError, "artifact_access must be one of #{Session::ARTIFACT_ACCESS.join(', ')}"
+      end
+
+      options = { name: name, label: label }
+      options[:artifact_access] = artifact_access.to_s unless artifact_access.nil?
       rebind_on_unauthorized do
-        payload = coordinator!.create_session(
-          token: computer_token, name: name, label: label, browser: browser, blind: blind
-        )
+        payload = coordinator!.create_session(token: computer_token, **options)
         Session.new(parent: self, payload: payload)
       end
     end
 
-    # Ergonomic one-call desktop delegation — the common playground flow is
-    #   client.create_computer(...).delegate_desktop
-    # Ensures the named (browser) desktop session exists, then returns its
+    # Desktop delegation in one call:
+    #   computer.delegate_desktop(name: session.name)
+    # Ensures the named desktop session exists, then returns its
     # browser-safe {DelegatedConnection} (host + session name + spec major +
     # a fresh short-TTL `dt_`; no `ct_`/`ps_`/JWS). `create: true` (default) creates
     # the session if absent; `create: false` requires it. To refresh the `dt_`
     # before a reconnect, call `session(name).delegate` again (server-side).
-    def delegate_desktop(name: "main", create: true, browser: true)
+    def delegate_desktop(name:, create: true)
+      require_session_name!(name)
       s =
         begin
           session(name)
         rescue PineSandbox::NotFoundError
           raise unless create
 
-          create_session(name: name, browser: browser)
+          create_session(name: name)
         end
       s.delegate
     end
@@ -420,16 +435,18 @@ module PineSandbox
       end
     end
 
-    # Reconstruct the same session from credentials saved with this binding.
+    # Rebuilds a session from the name and token saved when it was created,
+    # under this Computer's current binding.
     # No request, session creation or token refresh; authorization is checked
-    # on first use. Metadata remains available through #session(name).
+    # on first use. Metadata remains available through #session(name); the
+    # rebuilt session's #artifact_access is nil, since only the Computer knows it.
     def adopt_session(name, session_token)
       coordinator!
       unless name.is_a?(String) && !name.empty? && session_token.is_a?(String) && !session_token.empty?
         raise ArgumentError, "session name and token are required"
       end
 
-      Session.new(parent: self, payload: { "name" => name, "token" => session_token })
+      Session.new(parent: self, payload: { "name" => name, "token" => session_token }, artifact_access_known: false)
     end
 
     # computer.skills.* — the Computer's learned-skill lifecycle (Computer Skills): list/get the
@@ -439,6 +456,23 @@ module PineSandbox
       @skills ||= Skills.new(self)
     end
 
+    # A public link to one of the Computer's artifacts (see Client#artifacts),
+    # served by this running Computer: anyone with the URL can download the
+    # file as it is when they open it. The link stops working after
+    # `expires_in_seconds` (60 to 2,592,000) if given, when the file is
+    # deleted, and always when the Computer stops. Returns the response Hash,
+    # { "url" => …, "expires_at" => … }; "expires_at" only with an expiry.
+    def artifact_link(path, expires_in_seconds: nil)
+      path = ArtifactPath.check!(path)
+      unless expires_in_seconds.nil? || (expires_in_seconds.is_a?(Integer) && expires_in_seconds.between?(60, 2_592_000))
+        raise ArgumentError, "expires_in_seconds must be an integer from 60 to 2592000"
+      end
+
+      rebind_on_unauthorized do
+        coordinator!.create_artifact_link(token: computer_token, path: path, expires_in_seconds: expires_in_seconds)
+      end
+    end
+
     # capabilities — the product features this Computer can use for its binding, and the limits
     # it enforces on your calls.
     def capabilities
@@ -446,7 +480,8 @@ module PineSandbox
     end
 
     # Qualify the current public agent contract before a workflow changes
-    # control or submits work. Unsupported runtimes raise AgentProtocolUnsupported;
+    # control or submits work. A Computer started on an older release raises
+    # AgentProtocolUnsupported;
     # binding-auth and transport failures retain their ordinary SDK meaning.
     def require_agent_protocol!
       rebind_on_unauthorized { coordinator!.require_agent_protocol!(token: computer_token) }
@@ -471,16 +506,18 @@ module PineSandbox
     # with the ct_. Hides the session lookup + etag handshake + actor_type so callers
     # don't reach into Session. ct_-only, so it works on an adopted Computer.
     # Returns the new ControlState.
-    def take_control(name: "main", actor_type: "user_click")
+    def take_control(name:, actor_type: "user_click")
+      require_session_name!(name)
       rebind_on_unauthorized { session(name).take_control(actor_type: actor_type) }
     end
 
-    def release_control(name: "main", actor_type: "user_click")
+    def release_control(name:, actor_type: "user_click")
+      require_session_name!(name)
       rebind_on_unauthorized { session(name).release_control(actor_type: actor_type) }
     end
 
-    # Lazily-allocated snapshot reader (GET /state, ct_-gated). Bound to the
-    # CURRENT runtime; reset on every (re-)attach so it never points at a
+    # Lazily-built snapshot reader (GET /state, ct_-gated). Bound to the
+    # CURRENT attach; reset on every (re-)attach so it never points at a
     # stale one.
     def snapshot
       @snapshot ||= Adapters::SnapshotAdapter.new(coordinator: coordinator!, token_provider: -> { computer_token })
@@ -490,15 +527,15 @@ module PineSandbox
     # Computer's cookie jar, returned once committed. This is the EXPLICIT
     # durability primitive: call it when you want the current state guaranteed
     # restorable on the next #attach without stopping the Computer. #stop
-    # tries a final save before releasing the runtime, and releases it even
-    # when that save fails.
+    # tries a final save before shutting the Computer down, and shuts it down
+    # even when that save fails.
     # Content-hash-gated: an unchanged state returns `{"skipped" => true}` and
     # the prior snapshot stays latest. Returns the persisted snapshot
     # descriptor.
     #
     # SCOPE: a live checkpoint captures the cookie jar (the identity carrier
     # for most auth). localStorage is only captured with Chrome stopped
-    # (#stop / restart onto a fresh runtime), so a mid-session #checkpoint does not
+    # (on #stop), so a mid-session #checkpoint does not
     # refresh it — the last stopped-capture value is preserved and restored.
     def checkpoint
       rebind_on_unauthorized { coordinator!.capture(token: computer_token) }
@@ -544,31 +581,17 @@ module PineSandbox
       rebind_on_unauthorized { coordinator!.close_orphan_tab(token: computer_token, target_id: target_id) }
     end
 
-    def orphan_downloads
-      rebind_on_unauthorized { coordinator!.list_orphan_downloads(token: computer_token) }
-    end
-
-    def claim_orphan_download(guid:, session_name:, filename: nil)
-      rebind_on_unauthorized do
-        coordinator!.claim_orphan_download(token: computer_token, guid: guid, session_name: session_name, filename: filename)
-      end
-    end
-
-    def discard_orphan_download(guid)
-      rebind_on_unauthorized { coordinator!.discard_orphan_download(token: computer_token, guid: guid) }
-    end
-
     # Preserve the current sessions, capabilities and live process memory.
     # These bounded calls wait for observed completion; neither rebinds.
     def pause(timeout: 360)
-      raise ArgumentError, "Computer has no runtime" unless @sandbox
+      raise ArgumentError, "Computer has no binding" unless @sandbox
 
       @sandbox.pause(timeout: timeout)
       self
     end
 
     def resume(timeout: 360)
-      raise ArgumentError, "Computer has no retained runtime" unless @sandbox
+      raise ArgumentError, "Computer has no binding" unless @sandbox
 
       @sandbox.resume(timeout: timeout)
       self
@@ -576,7 +599,8 @@ module PineSandbox
 
     # Stop is owned by the server after acceptance. A timeout only ends this
     # wait; another backend using the saved handle can observe or retry it.
-    # true confirms compute release; final save is unknown after record removal.
+    # true confirms the Computer has shut down; if it was already gone, its
+    # final save is unknown.
     def stop(wait_timeout: 390)
       return true unless @sandbox
 
@@ -585,8 +609,8 @@ module PineSandbox
       gone
     end
 
-    # Force-terminate the runtime: UNGRACEFUL, no wait. The escape hatch for a stuck
-    # runtime — it may lose state written since the last checkpoint. #stop
+    # Force-terminate the Computer: UNGRACEFUL, no wait. The escape hatch for a stuck
+    # Computer — it may lose state written since the last checkpoint. #stop
     # is the normal path. (Computers should always terminate gracefully; reach
     # for #kill only to recover.)
     #
@@ -604,7 +628,7 @@ module PineSandbox
     end
 
     # PERMANENTLY delete this Computer: its identity and saved state end (see
-    # Client#delete_computer). A still-attached runtime is killed first (no
+    # Client#delete_computer). A running Computer is killed first (no
     # final save). Needs the connection this Computer was attached or adopted
     # through; for an id alone use Client#delete_computer. Returns true.
     def delete
@@ -626,37 +650,38 @@ module PineSandbox
 
     # Observe the saved binding through the lifecycle service. Unlike #alive?,
     # absence and transport/auth failures remain distinct errors. This never
-    # clears a binding, resumes memory or allocates a replacement runtime.
+    # clears a binding, resumes memory or starts the Computer again.
     def status
-      raise BindError, "Computer has no runtime binding" unless @sandbox
+      raise BindError, "Computer has no binding" unless @sandbox
 
       @sandbox.status
     end
 
-    # Observe this exact runtime through the lifecycle API, including while
-    # paused. No Portal lookup, rebind or replacement follows an absent runtime.
-    def runtime_details
-      raise BindError, "Computer has no runtime binding" unless @sandbox
+    # Observe the Computer this binding names through the lifecycle API,
+    # including while paused. If it has stopped, no Portal lookup, rebind or
+    # restart follows.
+    def sandbox_details
+      raise BindError, "Computer has no binding" unless @sandbox
 
-      info = @sandbox.runtime_details
-      RuntimeDetails.from_runtime(info)
+      info = @sandbox.sandbox_details
+      SandboxDetails.from_info(info)
     end
 
     # An unchanged value is not a heartbeat. On conflict or a lost reply,
-    # observe runtime_details before deciding whether another edit is needed.
+    # observe sandbox_details before deciding whether another edit is needed.
     def set_idle_timeout(seconds:)
-      raise BindError, "Computer has no runtime binding" unless @sandbox
+      raise BindError, "Computer has no binding" unless @sandbox
       raise ArgumentError, "idle timeout must be an integer of at least 60 seconds" unless seconds.is_a?(Integer) && seconds >= 60
 
-      RuntimeDetails.from_runtime(@sandbox.set_idle_timeout(seconds: seconds))
+      SandboxDetails.from_info(@sandbox.set_idle_timeout(seconds: seconds))
     end
 
     # Save after Create/Start, alongside the durable credentials. Never log JSON:
     # it contains the live Computer token. Stop clears this object's binding.
     def binding
-      raise BindError, "Computer has no runtime binding" unless @sandbox && @computer_token
+      raise BindError, "Computer has no binding" unless @sandbox && @computer_token
 
-      Binding.new(computer_id: id.dup, runtime_id: @sandbox.id.dup,
+      Binding.new(computer_id: id.dup, sandbox_id: @sandbox.id.dup,
                   computer_token: @computer_token.dup, binding_revision: @binding_revision).validate!
     end
 
@@ -666,11 +691,11 @@ module PineSandbox
     # needs a public method for that cross-object call).
     #
     # A 401 on a bound Computer means the binding-lifetime ct_ is no longer
-    # recognized (runtime replaced or its binding lost). There is ONE recovery path —
+    # recognized (Computer sandbox replaced or its binding lost). There is ONE recovery path —
     # rebind through portal attach-credentials, i.e. a plain re-attach — so
     # surface a typed TokenRejectedError rather than a generic auth error.
     # Deliberately NOT an automatic rebind: a rebind always lands on a FRESH
-    # runtime (each runtime binds once), invalidating every session/ps_ the
+    # Computer sandbox (each one binds once), invalidating every session/ps_ the
     # caller holds, so the re-attach must be the caller's explicit move.
     # The data-plane client already classifies its own responses by token
     # (a ps_ 401 stays UnauthorizedError); this maps a 401 that a custom
@@ -685,6 +710,11 @@ module PineSandbox
 
     private
 
+    # A Computer has no default session: its session helpers need the name.
+    def require_session_name!(name)
+      raise ArgumentError, "session name is required" if name.to_s.empty?
+    end
+
     def decide_passkey_ceremony(ceremony_id, decision)
       raise ArgumentError, "ceremony_id is required" if ceremony_id.to_s.empty?
 
@@ -726,8 +756,8 @@ module PineSandbox
       @snapshot = nil
     end
 
-    # The caller-owned part of a Computer create. Runtime selection belongs to
-    # the project policy and is never serialized by this SDK.
+    # The caller-owned part of a Computer create. Everything else about how it
+    # starts belongs to the project policy and is never serialized by this SDK.
     def build_computer_create_body(timeout:, metadata:)
       body = { timeout: timeout }
       body[:metadata] = metadata if metadata
@@ -879,7 +909,7 @@ module PineSandbox
       # provider response. If an in-process/custom issuer returns an incomplete
       # receipt, the caller still needs this revision to reconcile safely.
       @binding_revision = committed_revision
-      @last_authorized_runtime_id = @sandbox.id
+      @last_authorized_sandbox_id = @sandbox.id
       if creds.key?("location")
         begin
           committed_location = normalize_location(creds.fetch("location"))
@@ -972,9 +1002,9 @@ module PineSandbox
       problem == "/errors/bind-restore-failed" && status >= 500 && !err.message.to_s.include?("epoch")
     end
 
-    # The just-allocated runtime isn't routable through the gateway YET —
+    # The just-started Computer sandbox isn't routable through the gateway YET —
     # NOT a bind rejection. These are the not-ready signals (all clear as the
-    # runtime starts serving, so retry within the attach deadline):
+    # Computer starts serving, so retry within the attach deadline):
     #   404 — not yet routable (brief post-create window);
     #   503 — routable but not yet ready;
     #   409 /errors/bind-in-progress — an in-flight bind settling.
@@ -1005,7 +1035,7 @@ module PineSandbox
     # returns 409 + Retry-After. It settles once the in-flight bind/restore
     # finishes — which can outlast a few attempts — so it rides the attach
     # DEADLINE, not max_bind_attempts. Re-running run_bind is safe: the guard
-    # serializes binds per runtime and a settled bind answers consistently.
+    # serializes binds per Computer sandbox and a settled bind answers consistently.
     def bind_in_progress?(err)
       (err.respond_to?(:problem_type) ? err.problem_type : nil) == "/errors/bind-in-progress"
     end
@@ -1039,20 +1069,20 @@ module PineSandbox
       when "/errors/bind-rejected"
         BindAuthError.new("the Computer rejected the bind_token: #{message}", status: status, cause: err)
       when "/errors/bind-not-configured"
-        BindError.new("this runtime cannot be bound: #{message}", status: status, cause: err)
+        BindError.new("this Computer sandbox cannot be attached: #{message}", status: status, cause: err)
       when "/errors/bind-lease-unenforceable"
         # Structural deployment misconfiguration (lease relay unconfigured on
         # a portal-trusting pod) — a bind retry cannot fix it, and it must
         # not masquerade as a broker outage.
-        BindError.new("this runtime cannot enforce the access lease: #{message}", status: status, cause: err)
+        BindError.new("this Computer cannot enforce the access lease: #{message}", status: status, cause: err)
       when "/errors/already-bound-different-cid", "/errors/pod-tainted"
         # Terminal: a prior bind tainted this pod (bound to another Computer,
         # or failed after restore). The pod is single-use, so recovery is a
         # fresh #attach on a fresh pod — never a same-pod replay.
-        RuntimeUnusableError.new("this runtime cannot be bound again; attach a fresh one (#{problem}): #{message}", status: status, cause: err)
+        SandboxUnusableError.new("this Computer sandbox cannot be attached again; start the Computer again (#{problem}): #{message}", status: status, cause: err)
       when "/errors/bind-restore-failed"
         if message.include?("epoch")
-          ComputerAlreadyAttachedError.new("another runtime holds this Computer's epoch lease: #{message}", status: status, cause: err)
+          ComputerAlreadyAttachedError.new("this Computer is already attached elsewhere: #{message}", status: status, cause: err)
         else
           SavedStateUnavailableError.new("restoring saved state failed during bind: #{message}", status: status, cause: err)
         end

data/lib/pinesandbox/computer_binding.rb

@@ -2,18 +2,22 @@ require "json"
 
 module PineSandbox
   class Computer
-    # A saved connection to one runtime. Store with Credentials in encrypted
-    # application storage. Importing it neither contacts nor replaces the runtime.
-    class Binding < Struct.new(:computer_id, :runtime_id, :computer_token,
+    # A saved connection to the running Computer. Store with Credentials in
+    # encrypted application storage. Importing it neither contacts nor restarts
+    # the Computer. Bindings saved as schema 1, which named the sandbox id
+    # `runtime_id`, still load.
+    class Binding < Struct.new(:computer_id, :sandbox_id, :computer_token,
                                :binding_revision, keyword_init: true)
-      SCHEMA = 1
+      SCHEMA = 2
+      # The key each schema stores the sandbox id under.
+      SANDBOX_ID_KEYS = { 1 => "runtime_id", SCHEMA => "sandbox_id" }.freeze
 
       def self.from_json(json)
         data = JSON.parse(json)
-        unless data.is_a?(Hash) && data["schema"].is_a?(Integer) && data["schema"] == SCHEMA
+        unless data.is_a?(Hash) && data["schema"].is_a?(Integer) && SANDBOX_ID_KEYS.key?(data["schema"])
           raise ArgumentError, "unsupported Computer binding schema"
         end
-        new(computer_id: data["computer_id"], runtime_id: data["runtime_id"],
+        new(computer_id: data["computer_id"], sandbox_id: data[SANDBOX_ID_KEYS.fetch(data["schema"])],
             computer_token: data["computer_token"], binding_revision: data["binding_revision"]).validate!
       rescue JSON::ParserError
         raise ArgumentError, "Computer binding must be valid JSON"
@@ -23,8 +27,8 @@ module PineSandbox
         unless computer_id.is_a?(String) && computer_id.match?(Computer::UUID_V7)
           raise ArgumentError, "binding computer_id must be a lowercase UUIDv7"
         end
-        unless runtime_id.is_a?(String) && runtime_id.length <= 63 && runtime_id.match?(Zone::RUNTIME_ID_RE)
-          raise ArgumentError, "binding runtime_id must be a runtime identifier"
+        unless sandbox_id.is_a?(String) && sandbox_id.length <= 63 && sandbox_id.match?(Zone::SANDBOX_ID_RE)
+          raise ArgumentError, "binding sandbox_id must be a sandbox id"
         end
         unless computer_token.is_a?(String) && computer_token.match?(/\Act_[!-~]+\z/)
           raise ArgumentError, "binding computer_token must be a Computer token"
@@ -37,10 +41,10 @@ module PineSandbox
 
       def to_json(*args)
         validate!
-        { schema: SCHEMA, computer_id:, runtime_id:, computer_token:, binding_revision: }.to_json(*args)
+        { schema: SCHEMA, computer_id:, sandbox_id:, computer_token:, binding_revision: }.to_json(*args)
       end
 
-      def inspect = "#<PineSandbox::Computer::Binding computer_id=#{computer_id} runtime_id=#{runtime_id} token=[redacted]>"
+      def inspect = "#<PineSandbox::Computer::Binding computer_id=#{computer_id} sandbox_id=#{sandbox_id} token=[redacted]>"
       alias_method :to_s, :inspect
     end
   end