pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/computer.rb

@@ -0,0 +1,1075 @@
+require "base64"
+require "json"
+require "securerandom"
+require "digest"
+require_relative "errors"
+require_relative "connection"
+require_relative "bind_hpke"
+require_relative "capture_keypair"
+require_relative "adapters/coordinator_adapter"
+require_relative "adapters/snapshot_adapter"
+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.
+  #
+  #   computer = PineSandbox::Computer.new("0190…", key: secret_32_bytes)
+  #   computer.attach(connection)
+  #   session  = computer.create_session(name: "main", browser: true)
+  #   session.create_tab(url: "https://example.com")
+  #   computer.stop
+  #
+  # `id`, `key`, and the asymmetric capture keypair are the caller-owned
+  # per-Computer inputs; the attach authorizer (the pk_-backed portal
+  # 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.
+  class Computer
+    CURRENT_KEY_VERSION = 1
+    DEFAULT_MAX_BIND_ATTEMPTS = 3
+    # Allocation and runtime readiness; independent of the sandbox lifetime.
+    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.
+    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
+    # accepting connections yet (connection refused / TLS not up) — the same
+    # convergence window as 404/503.
+    TRANSIENT_BIND_ERRORS = [
+      Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError,
+      PineSandbox::TimeoutError, PineSandbox::ConnectionError
+    ].freeze
+
+    attr_reader :id, :binding_revision, :last_authorized_runtime_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
+
+    # @api private — internal plumbing, NOT a supported end-user surface. It is
+    # public only because `Session` reaches it via `parent.coordinator` (Ruby
+    # needs a public accessor for that cross-object call) and the wire-level
+    # OpenAPI conformance test drives raw routes through it. Use the typed
+    # Session (ps_) / Computer (ct_) methods, which attach the right token.
+    # Exposing it is NOT a privilege bypass: the Computer authorizes every
+    # route by token class (`/exec` is ps_-only; ps_ is bound to its own
+    # session), so a raw call here can only do what the caller's own token
+    # already permits.
+    attr_reader :coordinator
+
+    # A fresh Computer identity: a UUIDv7 `id` + a 32-byte state `key` — the SAME
+    # pair create_computer generates internally, exposed as the SDK's built-in
+    # generator so a client backend can mint + PERSIST them up front (crash-safe,
+    # and the required id format is guaranteed) and pass them into
+    # create_computer. The SDK never stores them; the integrator owns both (the
+    # `id` to address/adopt the Computer, the `key` to decrypt restored state).
+    # `ephemeral: true` mints an access-lease-only identity — no capture
+    # keypair, since an ephemeral Computer persists nothing.
+    def self.generate_credentials(ephemeral: false)
+      Credentials.new(
+        id: SecureRandom.uuid_v7,
+        key: SecureRandom.random_bytes(32),
+        capture_keypair: ephemeral ? nil : CaptureKeypair.generate(generation: 1),
+        ephemeral: ephemeral
+      )
+    end
+
+    # @param id  [String] lowercase UUIDv7 — a non-secret, stable handle.
+    # @param key [String] 32 raw bytes, the per-Computer secret (REQUIRED).
+    # @param ephemeral [Boolean] when true the Computer binds an access lease
+    #   ONLY — no state persistence: it submits no capture public key, seals no
+    #   computer_key into the bind payload, carries no key_assertion, and #stop
+    #   skips the pre-stop checkpoint. Default false is the persistent behavior.
+    def initialize(id, key:, binding_revision: 0, ephemeral: false)
+      raise ArgumentError, "id required" if id.to_s.empty?
+      raise ArgumentError, "id must be a lowercase UUIDv7" unless id.to_s.match?(UUID_V7)
+      raise ArgumentError, "key must be 32 raw bytes" unless key.is_a?(String) && key.bytesize == 32
+      unless binding_revision.is_a?(Integer) && binding_revision >= 0
+        raise ArgumentError, "binding_revision must be a non-negative integer"
+      end
+
+      @id = id.to_s
+      @key = key
+      @ephemeral = ephemeral ? true : false
+      @prior_keys = {} # version(Integer) => 32 raw bytes; rotation only
+      @capture_keypairs = {} # generation(Integer) => CaptureKeypair; asymmetric envelope v3
+      @capture_generation = 0
+      @binding_revision = binding_revision
+      reset_bound_state
+    end
+
+    # Register a prior key version so restore can decrypt a snapshot captured
+    # before a key rotation. Opt-in; steady state never calls
+    # it. Returns self for chaining.
+    def add_prior_key(version, bytes)
+      raise ArgumentError, "version must be an Integer" unless version.is_a?(Integer)
+      raise ArgumentError, "version must differ from the current key version" if version == CURRENT_KEY_VERSION
+      raise ArgumentError, "bytes must be 32 raw bytes" unless bytes.is_a?(String) && bytes.bytesize == 32
+
+      @prior_keys[version] = bytes
+      self
+    end
+
+    # Opt this Computer into asymmetric state encryption (component envelope v3):
+    # keypair.pk is submitted at the next attach, the platform seals every
+    # capture to it, and the bind runs the two-round restore (this SDK
+    # unwraps the per-component secrets with keypair.sk). Becomes the
+    # CURRENT generation; previously set generations stay registered for
+    # restores of pre-rotation state. Returns self for chaining.
+    def set_capture_keypair(keypair)
+      raise ArgumentError, "keypair must be a PineSandbox::CaptureKeypair" unless keypair.is_a?(CaptureKeypair)
+      if keypair.generation < @capture_generation
+        raise ArgumentError, "capture keypair generation #{keypair.generation} below the current generation #{@capture_generation} (rotations only move forward)"
+      end
+      existing = @capture_keypairs[keypair.generation]
+      if existing && (existing.pk != keypair.pk || existing.sk != keypair.sk)
+        raise ArgumentError, "capture keypair generation #{keypair.generation} is already registered with different key material"
+      end
+
+      @capture_keypairs[keypair.generation] = keypair
+      @capture_generation = keypair.generation
+      self
+    end
+
+    def capture_keypair
+      @capture_keypairs[@capture_generation]
+    end
+
+    # Caller-owned credentials, independent of this live handle. Save them before
+    # Create, and again only if you change keys. Start reads the binding itself.
+    def credentials
+      current = capture_keypair
+      Credentials.new(
+        id: @id.dup, key: @key.dup, ephemeral: @ephemeral,
+        capture_keypair: current&.dup,
+        prior_capture_keypairs: @capture_keypairs.values.reject { |pair| pair.equal?(current) }.map(&:dup),
+        prior_keys: @prior_keys.to_h { |version, bytes| [version, bytes.dup] }
+      )
+    end
+
+    # Register a SUPERSEDED capture keypair so a restore of state sealed
+    # under it can still unwrap its secrets. Never changes the current
+    # generation. Returns self for chaining.
+    def add_prior_capture_keypair(keypair)
+      raise ArgumentError, "keypair must be a PineSandbox::CaptureKeypair" unless keypair.is_a?(CaptureKeypair)
+      if @capture_generation.positive? && keypair.generation >= @capture_generation
+        raise ArgumentError, "prior capture keypair generation #{keypair.generation} must be below the current generation #{@capture_generation}"
+      end
+      existing = @capture_keypairs[keypair.generation]
+      if existing && (existing.pk != keypair.pk || existing.sk != keypair.sk)
+        raise ArgumentError, "capture keypair generation #{keypair.generation} is already registered with different key material"
+      end
+
+      @capture_keypairs[keypair.generation] = keypair
+      self
+    end
+
+    # Allocate a runtime and bind this Computer 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
+    # 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.
+    #
+    # @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.
+    # @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,
+               max_bind_attempts: DEFAULT_MAX_BIND_ATTEMPTS,
+               bind_ready_timeout: DEFAULT_BIND_READY_TIMEOUT)
+      unless config.respond_to?(:attach_provider) && config.respond_to?(:control_plane) && config.respond_to?(:zone)
+        raise ArgumentError, "config must be a PineSandbox::Connection (got #{config.class})"
+      end
+      unless max_bind_attempts.is_a?(Integer) && max_bind_attempts.positive?
+        raise ArgumentError, "max_bind_attempts must be a positive integer"
+      end
+      unless pod_env.nil? || pod_env == {}
+        raise ArgumentError, "pod_env is unsupported for Computer attach; omit it or pass an empty hash"
+      end
+      unless (ready_timeout.is_a?(Integer) || ready_timeout.is_a?(Float)) && ready_timeout.finite? && ready_timeout.positive?
+        raise ArgumentError, "ready_timeout must be a positive finite number of seconds"
+      end
+
+      # Refuse to re-attach a live Computer: silently tearing down the prior pod
+      # here would force-kill it (ungraceful) and lose state since the last
+      # checkpoint. Make the teardown an explicit caller choice — #stop (graceful,
+      # persist) or #kill (discard) — then attach again.
+      raise BindError.new("Computer already attached — call #stop (graceful) or #kill first") if @sandbox
+      # A persistent attach requires the capture keypair (it seals every capture
+      # to it); an ephemeral Computer persists nothing, so it binds without one.
+      if @capture_generation.zero? && !@ephemeral
+        raise ArgumentError, "v3 attach requires a capture_keypair (persist both halves)"
+      end
+      # Preserve omission as omission. @location is only the last Portal
+      # 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
+      @connection = config
+      @clock = config.respond_to?(:clock) ? config.clock : PineSandbox::SYSTEM_CLOCK
+
+      # Provision via the project-scoped control plane (api.<zone>, project JWS).
+      create_id = SecureRandom.uuid
+      ready_deadline = monotonic_now + ready_timeout
+      info = config.control_plane.create_computer(
+        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)
+      # 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.
+      begin
+        @sandbox.wait_until_running(timeout: [ready_deadline - monotonic_now, 0].max)
+      rescue StandardError
+        reset_bound_state
+        raise
+      end
+      # Drive the Computer at its runtime's gateway host `https://<runtime_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)
+
+      # Two retry budgets converge on the bind handshake:
+      #  - readiness (DEADLINE-bounded): the runtime was just allocated, 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
+      #    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
+      #    with the same committed token/JTI/ciphertext. No Portal re-mint.
+      # Terminal bind errors (pod identity shift, epoch conflict, pod-tainted, auth, coord's own
+      # problem+json 503 bind-not-configured) never retry: the pod is
+      # single-use, so recovery is a fresh #attach on a fresh pod.
+      deadline = monotonic_now + bind_ready_timeout
+      restore_attempts = 1
+      converge_waits = 0
+      begin
+        raise BindTimeoutError.new("Computer did not become bindable within its bind budget") if monotonic_now >= deadline
+        run_bind(config, requested_location: requested_location)
+      rescue PineSandbox::ApiError => e
+        if coord_not_ready_via_ingress?(e) || transient_bind_restore?(e)
+          if monotonic_now < deadline
+            converge_waits += 1
+            sleep(bind_convergence_backoff(converge_waits))
+            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)
+        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.
+          restore_attempts += 1
+          @bind_envelope&.delete(:restore_secrets)
+          sleep(0.5 * (restore_attempts - 1))
+          retry
+        end
+        reset_bound_state
+        raise map_bind_error(e)
+      rescue *TRANSIENT_BIND_ERRORS => e
+        # A just-created pod's coord may not be listening yet (connection
+        # refused / TLS not up) — the same convergence window as 404/503,
+        # so bound by the same deadline rather than a few attempts.
+        if monotonic_now < deadline
+          converge_waits += 1
+          sleep(bind_convergence_backoff(converge_waits))
+          retry
+        end
+        reset_bound_state
+        raise BindTimeoutError.new("bind handshake did not complete within #{bind_ready_timeout}s: #{e.class}: #{e.message}", cause: e)
+      rescue StandardError
+        reset_bound_state
+        raise
+      end
+
+      self
+    end
+
+    # attach + auto-stop. Yields self; stops the Computer (saving supported
+    # state) when the block returns or raises.
+    def with_attached(config, **opts)
+      PineSandbox.deprecated_name("Computer#with_attached", "Client#with_computer")
+      attach(config, **opts)
+      yield self
+    ensure
+      # Graceful by default: persist state on the way out (no-op if attach
+      # already cleaned up after a bind failure — @sandbox is nil then).
+      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,
+    # 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,
+              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, "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"
+      end
+
+      @connection = config
+      @clock = config.respond_to?(:clock) ? config.clock : PineSandbox::SYSTEM_CLOCK
+      @coordinator = Adapters::CoordinatorAdapter.new(runtime_id: runtime_id, zone: config.zone,
+                                                      discovery_token: computer_token, clock: @clock)
+      @sandbox = RuntimeHandle.new(control_plane: config.control_plane, runtime_id: runtime_id, status: status)
+      @computer_token = computer_token
+      @binding_revision = binding_revision
+      self
+    end
+
+    # The Computer-tier token (`ct_*`) delivered in the bind response. Raises
+    # if called before #attach (or after #stop).
+    def computer_token
+      @computer_token || raise(BindError.new("Computer is not attached — call #attach first"))
+    end
+
+    # INFORMATIONAL ONLY: the `expires_at` returned with the ct_ in the bind
+    # response. Deprecated: ct_ is binding-lifetime (no idle expiry, no
+    # renewal), so current Computers omit the field and this is nil.
+    # The SDK keeps no timers and never refreshes either way. nil on adopted
+    # Computers too (the bind response isn't available there).
+    attr_reader :computer_token_expires_at
+
+    # The persistence mode recorded for this binding, read back from the
+    # bind response ("ephemeral" for an access-lease-only Computer). A response that
+    # omits the field leaves this nil; adopted Computers (no bind response) are
+    # nil too. Informational — the SDK acts on its own @ephemeral intent.
+    attr_reader :persistence_mode
+
+    # Whether this Computer was bound as ephemeral (access-lease only, no state
+    # persistence). Set at construction; the persistent default is false.
+    def ephemeral?
+      @ephemeral
+    end
+
+    # --- driving the powered-on Computer (sessions hold the `ps_*` token) ---
+
+    # `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)
+      rebind_on_unauthorized do
+        payload = coordinator!.create_session(
+          token: computer_token, name: name, label: label, browser: browser, blind: blind
+        )
+        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
+    # 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)
+      s =
+        begin
+          session(name)
+        rescue PineSandbox::NotFoundError
+          raise unless create
+
+          create_session(name: name, browser: browser)
+        end
+      s.delegate
+    end
+
+    def session(name)
+      rebind_on_unauthorized do
+        Session.new(parent: self, payload: coordinator!.get_session(token: computer_token, name: name))
+      end
+    end
+
+    # Reconstruct the same session from credentials saved with this binding.
+    # No request, session creation or token refresh; authorization is checked
+    # on first use. Metadata remains available through #session(name).
+    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 })
+    end
+
+    # computer.skills.* — the Computer's learned-skill lifecycle (Computer Skills): list/get the
+    # served skills, review pending drafts (with bodies), activate/deactivate. Skills are
+    # computer-global; the authoring TRIGGERS are session-scoped — see Session#learn / #teach.
+    def skills
+      @skills ||= Skills.new(self)
+    end
+
+    # capabilities — the product features this Computer can use for its binding, and the limits
+    # it enforces on your calls.
+    def capabilities
+      rebind_on_unauthorized { coordinator!.capabilities(token: computer_token) }
+    end
+
+    # Qualify the current public agent contract before a workflow changes
+    # control or submits work. Unsupported runtimes raise 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) }
+      self
+    end
+
+    def sessions
+      rebind_on_unauthorized do
+        coordinator!.list_sessions(token: computer_token).map { |payload| Session.new(parent: self, payload: payload) }
+      end
+    end
+
+    def destroy_session(name, clean: false)
+      rebind_on_unauthorized do
+        coordinator!.destroy_session(token: computer_token, name: name, clean: clean)
+      end
+    end
+
+    # --- control lease (drive ⇔ view), Computer-level facade ---
+    # The desktop stream forwards input only while a person holds control.
+    # A viewer (browser, dt_) can't take it; your backend brokers it here
+    # 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")
+      rebind_on_unauthorized { session(name).take_control(actor_type: actor_type) }
+    end
+
+    def release_control(name: "main", actor_type: "user_click")
+      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
+    # stale one.
+    def snapshot
+      @snapshot ||= Adapters::SnapshotAdapter.new(coordinator: coordinator!, token_provider: -> { computer_token })
+    end
+
+    # Save a restore point NOW — a synchronous, durable capture of this
+    # 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.
+    # 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
+    # refresh it — the last stopped-capture value is preserved and restored.
+    def checkpoint
+      rebind_on_unauthorized { coordinator!.capture(token: computer_token) }
+    end
+
+    # Metadata-only inventory of durable custodial passkeys held by this
+    # Computer. The private keys remain inside the Computer and its encrypted state.
+    def passkeys
+      rebind_on_unauthorized { coordinator!.list_passkeys(token: computer_token) }
+    end
+
+    def delete_passkey(credential_id)
+      raise ArgumentError, "credential_id is required" if credential_id.to_s.empty?
+
+      rebind_on_unauthorized do
+        coordinator!.delete_passkey(token: computer_token, credential_id: credential_id)
+      end
+    end
+
+    # Pending first-enrollment ceremonies require an explicit Computer-owner
+    # decision. Assertions for already-held credentials remain automatic.
+    def pending_passkey_ceremonies
+      rebind_on_unauthorized { coordinator!.list_passkey_ceremonies(token: computer_token) }
+    end
+
+    def approve_passkey_ceremony(ceremony_id)
+      decide_passkey_ceremony(ceremony_id, "approve_custodial")
+    end
+
+    def decline_passkey_ceremony(ceremony_id)
+      decide_passkey_ceremony(ceremony_id, "decline")
+    end
+
+    # Browser tabs no session owns (for example a page a site opened in a new
+    # window after its session ended). Returns the response Hash.
+    def orphan_tabs
+      rebind_on_unauthorized { coordinator!.list_orphan_tabs(token: computer_token) }
+    end
+
+    def close_orphan_tab(target_id)
+      raise ArgumentError, "target_id is required" if target_id.to_s.empty?
+
+      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
+
+      @sandbox.pause(timeout: timeout)
+      self
+    end
+
+    def resume(timeout: 360)
+      raise ArgumentError, "Computer has no retained runtime" unless @sandbox
+
+      @sandbox.resume(timeout: timeout)
+      self
+    end
+
+    # 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.
+    def stop(wait_timeout: 390)
+      return true unless @sandbox
+
+      gone = @sandbox.stop(wait_timeout: wait_timeout)
+      clear_bound_state if gone
+      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
+    # is the normal path. (Computers should always terminate gracefully; reach
+    # for #kill only to recover.)
+    #
+    # NOTE: there is intentionally no #destroy alias. The lifecycle verbs are
+    # distinct by intent: #stop saves supported state before shutdown;
+    # #kill is ungraceful force-recovery. The "done forever" verb —
+    # permanent delete, which ends the identity and purges saved state — is
+    # Client#delete_computer (it kills a still-attached Computer first).
+    def kill
+      return true unless @sandbox
+
+      deleted = @sandbox.kill
+      clear_bound_state if deleted
+      deleted
+    end
+
+    # PERMANENTLY delete this Computer: its identity and saved state end (see
+    # Client#delete_computer). A still-attached runtime 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
+      provider = @connection&.attach_provider
+      unless provider.respond_to?(:delete_computer)
+        raise ComputerDeletionError,
+              @connection ? "computer deletion is unavailable from the custom attach credentials provider" :
+                            "this Computer was never attached; delete it with Client#delete_computer(id)"
+      end
+
+      kill
+      provider.delete_computer(id)
+      true
+    end
+
+    def alive?
+      @sandbox ? @sandbox.alive? : false
+    end
+
+    # 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.
+    def status
+      raise BindError, "Computer has no runtime 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
+
+      info = @sandbox.runtime_details
+      RuntimeDetails.from_runtime(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.
+    def set_idle_timeout(seconds:)
+      raise BindError, "Computer has no runtime 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))
+    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
+
+      Binding.new(computer_id: id.dup, runtime_id: @sandbox.id.dup,
+                  computer_token: @computer_token.dup, binding_revision: @binding_revision).validate!
+    end
+
+    # @api private — internal plumbing, NOT a supported end-user surface. Public
+    # only because the Computer's facade objects (e.g. Skills) wrap their own
+    # ct_-authenticated calls in the same 401→TokenRejectedError mapping (Ruby
+    # 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 —
+    # 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
+    # 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
+    # coordinator raises for the ct_ the block used.
+    def rebind_on_unauthorized
+      yield
+    rescue PineSandbox::UnauthorizedError => e
+      raise unless e.status.to_i == 401
+
+      raise TokenRejectedError.for_api_error(e)
+    end
+
+    private
+
+    def decide_passkey_ceremony(ceremony_id, decision)
+      raise ArgumentError, "ceremony_id is required" if ceremony_id.to_s.empty?
+
+      rebind_on_unauthorized do
+        coordinator!.decide_passkey_ceremony(
+          token: computer_token, ceremony_id: ceremony_id, decision: decision
+        )
+      end
+    end
+
+    # The bound coordinator, or a clear error if powered-off. Keeps every
+    # drive method from NoMethodError-ing on a nil coordinator.
+    def coordinator!
+      @coordinator || raise(BindError.new("Computer is not attached — call #attach first"))
+    end
+
+    # Ungraceful tear-down: best-effort kill (no wait) + drop the local binding.
+    # Used at attach-entry (re-attach), on bind failure, and by #kill. The nils
+    # always run so the SDK object never holds a half-binding. (#stop uses the
+    # graceful Sandbox#terminate instead, then clear_bound_state.)
+    def reset_bound_state
+      begin
+        @sandbox&.kill
+      rescue StandardError
+        nil
+      end
+      clear_bound_state
+    end
+
+    # Drop the local binding WITHOUT touching the pod — used after a graceful
+    # #stop has already terminated it (so we don't double-DELETE).
+    def clear_bound_state
+      @sandbox = nil
+      @coordinator = nil
+      @computer_token = nil
+      @computer_token_expires_at = nil
+      @persistence_mode = nil
+      @bind_envelope = nil
+      @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.
+    def build_computer_create_body(timeout:, metadata:)
+      body = { timeout: timeout }
+      body[:metadata] = metadata if metadata
+      body
+    end
+
+    # Client bind sequence (AUTH_REDESIGN attach flow): fetch pubkey → call
+    # the portal attach-credentials provider with the pod coordinates →
+    # HPKE-seal {key, broker_grant} → POST the portal bind_token (no
+    # client-side signing, no hash attestations) → store ct_ + expires_at.
+    #
+    # Re-runnable, with one load-bearing rule: a CONVERGENCE retry (lost
+    # response, transient transport, bind-in-progress) re-POSTs the SAME
+    # minted envelope byte-for-byte. coord keys bind idempotency on
+    # (jti, ciphertext) — re-sending the identical pair after a committed
+    # bind replays the cached ct_, while a fresh mint (new jti) on a bound
+    # pod is a terminal 409. Portal authorizes a sandbox exactly once, so
+    # this method never re-mints after an envelope has been committed.
+    # Bounds the two-round restore's challenge-answer loop client-side.
+    # Coord's own generation cap (4) refuses first in any legitimate run;
+    # this is the local backstop against a server challenging forever.
+    MAX_RESTORE_ROUNDS = 6
+
+    def run_bind(config, requested_location:)
+      envelope = @bind_envelope ||= mint_bind_envelope(
+        config, requested_location: requested_location
+      )
+      @bind_envelope = envelope
+
+      restore_secrets = envelope[:restore_secrets]
+      rounds = 0
+      loop do
+        bind_kwargs = {
+          bind_token: envelope.fetch(:bind_token), pod_uid: envelope.fetch(:pod_uid),
+          coord_boot_id: envelope.fetch(:coord_boot_id), ciphertext: envelope.fetch(:ciphertext)
+        }
+        bind_kwargs[:key_assertion] = envelope[:key_assertion] if envelope[:key_assertion]
+        bind_kwargs[:restore_secrets] = restore_secrets if restore_secrets
+        response = @coordinator.bind(**bind_kwargs)
+        challenge = response["restore_challenge"]
+        unless challenge
+          @bind_envelope = nil
+          @computer_token = response.fetch("computer_token")
+          @computer_token_expires_at = response["expires_at"]
+          @persistence_mode = response["persistence_mode"]
+          return
+        end
+        # The two-round v3 restore: unwrap each component's secret with the
+        # matching keypair generation and re-send the SAME envelope with the
+        # sealed answer. Every resumable outcome (initial challenge,
+        # rechallenge after latest moved, a superseded answer) is another
+        # challenge on this same loop. The built answer is held ON the
+        # envelope so a convergence retry after a transport fault re-sends
+        # it verbatim (idempotent replay).
+        rounds += 1
+        raise BindError.new("bind restore did not converge after #{MAX_RESTORE_ROUNDS} challenges") if rounds > MAX_RESTORE_ROUNDS
+
+        restore_secrets = answer_restore_challenge(envelope, challenge)
+        envelope[:restore_secrets] = restore_secrets
+      end
+    end
+
+    # Unwrap each challenged component's secret and seal the set to the
+    # pod's bind key under the RESTORE domain. Failures are terminal — a
+    # missing superseded generation or corrupt material never self-heals.
+    def answer_restore_challenge(envelope, challenge)
+      secrets = {}
+      challenge.fetch("components").each do |comp|
+        generation = comp.fetch("recipient_key_version")
+        keypair = @capture_keypairs[generation]
+        unless keypair
+          raise BindError.new(
+            "restore needs capture keypair generation #{generation} for component #{comp["component"]} — " \
+            "register the superseded keypair (add_prior_capture_keypair) or its state cannot be restored"
+          )
+        end
+        if keypair.fingerprint != comp.fetch("pk_fingerprint")
+          raise BindError.new(
+            "restore challenge for component #{comp["component"]} names fingerprint #{comp["pk_fingerprint"]} " \
+            "but keypair generation #{generation} has #{keypair.fingerprint} — wrong keypair registered"
+          )
+        end
+        begin
+          s = StateHPKE.open_component_secret(
+            keypair.sk,
+            Base64.urlsafe_decode64(comp.fetch("hpke_enc")),
+            Base64.urlsafe_decode64(comp.fetch("hpke_sealed_s")),
+            cid: @id, component: comp.fetch("component"), id: comp.fetch("id"),
+            attach_epoch: comp.fetch("attach_epoch"), key_version: generation,
+            fingerprint: comp.fetch("pk_fingerprint")
+          )
+        rescue KeyError
+          raise
+        rescue StandardError => e
+          raise BindError.new(
+            "restore challenge for component #{comp["component"]} could not be unwrapped " \
+            "with capture keypair generation #{generation}",
+            cause: e
+          )
+        end
+        secrets[comp.fetch("component")] = Base64.urlsafe_encode64(s, padding: false)
+      rescue KeyError => e
+        raise BindError.new("restore challenge malformed: #{e.message}")
+      end
+      plaintext = JSON.generate(challenge_id: challenge.fetch("challenge_id"), secrets: secrets)
+      sealed = BindHPKE.seal(
+        Base64.urlsafe_decode64(envelope.fetch(:ephem_pub)), plaintext,
+        BindHPKE.restore_info(envelope.fetch(:pod_uid), envelope.fetch(:coord_boot_id))
+      )
+      Base64.urlsafe_encode64(sealed, padding: false)
+    end
+
+    # Fetch the pod's bind identity, mint single-use portal attach
+    # credentials for it, and HPKE-seal the payload — everything a bind
+    # POST needs, held together so retries can re-send it verbatim.
+    def mint_bind_envelope(config, requested_location:)
+      pubkey = @coordinator.bind_pubkey
+      ephem_pub = Base64.urlsafe_decode64(pubkey.fetch("ephem_pub_x25519"))
+      pod_uid = pubkey.fetch("pod_uid")
+      coord_boot_id = pubkey.fetch("coord_boot_id")
+
+      # sandbox_id rides along so the portal can attribute the sandbox to
+      # this computer/project at the ONE moment it learns the pairing — the
+      # renew-relay revocation gate keys off that attribution.
+      mint_kwargs = {
+        computer_id: @id, pod_uid: pod_uid, coord_boot_id: coord_boot_id,
+        sandbox_id: @sandbox.id,
+        expected_binding_revision: @binding_revision,
+        idempotency_key: attach_idempotency_key(@sandbox.id, pod_uid, coord_boot_id)
+      }
+      mint_kwargs[:location] = requested_location if requested_location
+      # A persistent attach submits the capture public key so the portal advances
+      # its per-Computer key floor and returns a signed key_assertion. An
+      # ephemeral Computer has no capture keypair and persists nothing, so both
+      # pk_computer and key_generation are omitted.
+      unless @ephemeral
+        current = @capture_keypairs.fetch(@capture_generation)
+        mint_kwargs[:pk_computer] = Base64.urlsafe_encode64(current.pk, padding: false)
+        mint_kwargs[:key_generation] = current.generation
+      end
+      creds = config.attach_provider.credentials(**mint_kwargs)
+      committed_revision = Integer(creds.fetch("binding_revision"))
+      unless committed_revision > @binding_revision
+        raise AttachCredentialsError.new(
+          "attach_credentials_provider returned a non-advancing binding_revision"
+        )
+      end
+      # Record the committed CAS winner before validating the rest of the
+      # 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
+      if creds.key?("location")
+        begin
+          committed_location = normalize_location(creds.fetch("location"))
+        rescue ArgumentError => e
+          raise AttachCredentialsError.new(
+            "attach_credentials_provider returned an invalid location: #{e.message}"
+          )
+        end
+        if requested_location && committed_location != requested_location
+          raise AttachCredentialsError.new(
+            "attach_credentials_provider returned a location different from the requested Computer location"
+          )
+        end
+        @location = committed_location
+      end
+      # key_assertion accompanies the capture public key on a persistent attach;
+      # an ephemeral attach neither submits pk_computer nor requires it back.
+      if creds["bind_token"].to_s.empty? || creds["broker_grant"].to_s.empty? ||
+         (!@ephemeral && creds["key_assertion"].to_s.empty?)
+        raise AttachCredentialsError.new(
+          "attach_credentials_provider result missing bind_token/broker_grant/key_assertion"
+        )
+      end
+      # The HPKE-sealed bind payload. A persistent Computer ships its state key
+      # (current + optional prior-for-restore) alongside the broker grant; an
+      # ephemeral Computer seals ONLY the broker grant — it holds no state to
+      # decrypt. broker_grant is always present.
+      #
+      # Only integrator-custodied material belongs here. Platform-internal
+      # credentials — the coordinator's accounting grant among them — are
+      # obtained by coord over its own internal rail, because routing one
+      # through this payload made metering depend on the SDK version an
+      # integrator had pinned.
+      plaintext =
+        if @ephemeral
+          JSON.generate(broker_grant: creds.fetch("broker_grant"))
+        else
+          restore_version, restore_bytes = @prior_keys.max_by { |version, _| version }
+          JSON.generate(
+            computer_key_current: wire_key(CURRENT_KEY_VERSION, @key),
+            computer_key_for_restore: restore_bytes ? wire_key(restore_version, restore_bytes) : nil,
+            broker_grant: creds.fetch("broker_grant")
+          )
+        end
+      ciphertext = BindHPKE.seal(ephem_pub, plaintext, BindHPKE.info(pod_uid, coord_boot_id))
+
+      {
+        bind_token: creds.fetch("bind_token"),
+        pod_uid: pod_uid,
+        coord_boot_id: coord_boot_id,
+        ciphertext: Base64.urlsafe_encode64(ciphertext, padding: false),
+        key_assertion: @ephemeral ? nil : creds["key_assertion"],
+        ephem_pub: pubkey.fetch("ephem_pub_x25519")
+      }
+    end
+
+    def attach_idempotency_key(sandbox_id, pod_uid, coord_boot_id)
+      material = [ @id, sandbox_id, pod_uid, coord_boot_id ].join("\0")
+      "attach-#{Digest::SHA256.hexdigest(material)}"
+    end
+
+    def wire_key(version, bytes)
+      {version: version, bytes: Base64.urlsafe_encode64(bytes, padding: false)}
+    end
+
+    def normalize_location(value)
+      unless value.is_a?(Hash)
+        raise ArgumentError, "location must be a Hash with country: or mode: \"direct\""
+      end
+      normalized = value.transform_keys(&:to_s)
+      return { mode: "direct" }.freeze if normalized == { "mode" => "direct" }
+      unless normalized.keys == [ "country" ] &&
+             normalized["country"].is_a?(String) &&
+             normalized["country"].match?(/\A[A-Z]{2}\z/)
+        raise ArgumentError, "location must contain an ISO alpha-2 country or mode: \"direct\", exclusively"
+      end
+      { country: normalized.fetch("country") }.freeze
+    end
+
+    def restore_no_challenge?(err)
+      problem = err.respond_to?(:problem_type) ? err.problem_type : nil
+      problem == "/errors/bind-restore-no-challenge"
+    end
+
+    # A broker/restore 5xx can converge by replaying the SAME committed
+    # envelope. An epoch conflict is terminal because another pod won.
+    def transient_bind_restore?(err)
+      problem = err.respond_to?(:problem_type) ? err.problem_type : nil
+      status = err.respond_to?(:status) ? err.status.to_i : 0
+      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 —
+    # NOT a bind rejection. These are the not-ready signals (all clear as the
+    # runtime 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.
+    # The gateway now types its two routing decisions. They remain readiness
+    # signals ONLY inside this attach deadline; on ordinary data-plane calls a
+    # sandbox-not-found response means the bound sandbox is gone. Other typed
+    # coord failures (bind-not-configured, epoch-conflict, pod-tainted, auth)
+    # are bind verdicts and fall through to transient_bind_restore?/
+    # map_bind_error. Plain 404/503 remain compatible with older gateways.
+    def coord_not_ready_via_ingress?(err)
+      return true if bind_in_progress?(err)
+      return false unless err.respond_to?(:status)
+
+      problem = err.respond_to?(:problem_type) ? err.problem_type : nil
+      return true if [
+        "/errors/sandbox-not-found",
+        "/errors/sandbox-not-ready",
+        "/errors/egress-activation-failed"
+      ].include?(problem)
+      return false unless problem.nil?
+
+      status = err.status.to_i
+      status == 404 || status == 503
+    end
+
+    # coord's bindGuard is mid-flight completing a bind for this pod (a prior
+    # attempt of THIS attach whose response we lost, or a racing caller); coord
+    # 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.
+    def bind_in_progress?(err)
+      (err.respond_to?(:problem_type) ? err.problem_type : nil) == "/errors/bind-in-progress"
+    end
+
+    # Monotonic seconds — immune to wall-clock jumps during a long attach.
+    def monotonic_now
+      (@clock || PineSandbox::SYSTEM_CLOCK).monotonic
+    end
+
+    # Every attach wait goes through the connection's clock.
+    def sleep(seconds)
+      (@clock || PineSandbox::SYSTEM_CLOCK).sleep(seconds)
+    end
+
+    # Capped linear backoff (0.5s..3s) for the convergence wait, so a slow
+    # cold pod is polled steadily without hammering the ingress.
+    def bind_convergence_backoff(wait_count)
+      [0.5 * wait_count, 3.0].min
+    end
+
+    # Maps a terminal bind failure to the SDK's typed bind errors. Prefer the
+    # RFC 9457 problem-type slug (coord sets it on the
+    # problem+json body); fall back to the HTTP status tier for older coords
+    # or client-side faults (malformed-request / hpke-decrypt-failed / etc).
+    def map_bind_error(err)
+      status = err.respond_to?(:status) ? err.status : nil
+      problem = err.respond_to?(:problem_type) ? err.problem_type : nil
+      message = err.message.to_s
+
+      case problem
+      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)
+      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)
+      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)
+      when "/errors/bind-restore-failed"
+        if message.include?("epoch")
+          ComputerAlreadyAttachedError.new("another runtime holds this Computer's epoch lease: #{message}", status: status, cause: err)
+        else
+          SavedStateUnavailableError.new("restoring saved state failed during bind: #{message}", status: status, cause: err)
+        end
+      else
+        case status
+        when 401, 403
+          BindAuthError.new("the Computer rejected the bind_token (#{status}): #{message}", status: status, cause: err)
+        when 409
+          BindError.new("bind rejected (409): #{message}", status: status, cause: err)
+        when 503
+          SavedStateUnavailableError.new("saved state was unreachable during bind: #{message}", status: status, cause: err)
+        else
+          BindError.new("bind failed (status=#{status || 'n/a'}): #{message}", status: status, cause: err)
+        end
+      end
+    end
+  end
+end
+
+require_relative "computer_credentials"