pinesandbox 0.3.18 → 0.3.20

data/README.md

@@ -1,36 +1,34 @@
-# PineSandbox Computer SDK (Ruby)
+# Pine Computer Ruby SDK
 
 `pinesandbox` is the Ruby server SDK for Pine Computers. Create and reconnect
 Computers, run agent tasks, manage files, and authorize desktop access from
 your backend. Stop/Start restores saved cookies, learned skills, and localStorage.
 Pause/Resume retains live tabs, sessions, and memory when enabled for your project.
 
-See the [integration guide](https://pinesandbox.io/docs/integration) for setup,
+See the [integration guide](https://console.pinecomputer.io/docs/integration) for setup,
 authentication, and examples. This README covers the Ruby API.
 
 ## Install
 
-Admitted users download the versioned Ruby SDK bundle from
-<https://pinesandbox.io/sdks/ruby>. Extract it under `vendor/`, then reference
-the bundle from your `Gemfile`:
-
-```ruby
-gem "pinesandbox", path: "vendor/pinesandbox-ruby-sdk-<version>"
+```sh
+bundle add pinesandbox
 ```
 
-Use the directory name of the bundle you extracted; the download page shows the
-exact line for the latest release.
-
-No GitHub account or package token is required. See the
-[integration guide §Install](https://pinesandbox.io/docs/integration#1-install)
-for the download and extraction commands.
+Bundler pins it to the latest release's compatibility line (`"~> 0.3.<patch>"`), so
+`bundle update` takes later patches but not a new minor version. Using it needs a project key (`pk_…`) from the
+[Console](https://console.pinecomputer.io). Pine Computer is in beta:
+[request access](https://pinecomputer.io/#access) if you don't have one yet. Each
+release is also an archive on the [Ruby SDK page](https://console.pinecomputer.io/sdks/ruby),
+for vendoring.
 
 The current beta SDK is on the `0.3` compatibility line.
 
 ## Create a Computer
 
-A **Computer** is the identity and saved browser state you keep. A **runtime** is
-one running allocation of it. A **session** is work inside that runtime.
+A **Computer** is the identity and saved browser state you keep. A **session** is
+work inside the running Computer.
+[Terms](https://console.pinecomputer.io/docs/how-a-computer-works#terms) defines
+the rest.
 
 The examples use `store` for your application's encrypted database; it is not an
 SDK object. Save credentials **before** Create, then save the returned binding.
@@ -49,7 +47,7 @@ store.save_credentials(credentials.id, credentials.to_json)
 computer = client.create_computer(credentials)
 store.save_binding(computer.id, computer.binding.to_json)
 
-session = computer.create_session(name: "main", browser: true)
+session = computer.create_session # Pine picks the name: save session.name
 session.create_tab(url: "https://example.com")
 ```
 
@@ -58,11 +56,12 @@ The two records have different lifetimes:
 | Save | When | Used for |
 |---|---|---|
 | `credentials.to_json` | Before Create; again if you change keys | Starting this Computer again and decrypting its saved state |
-| `computer.binding.to_json` | After each successful Create or Start | Reconnecting to that exact runtime from any backend |
+| `computer.binding.to_json` | After each successful Create or Start | Reconnecting to the running Computer from any backend |
 
 Both contain secrets. Keep them encrypted on your backend, never in a browser.
 For a one-off script, `client.with_computer { |computer| … }` creates and stops the
-Computer for you, raising if Stop cannot be confirmed.
+Computer for you, raising if Stop cannot be confirmed. When the block raises, its
+error propagates and an unconfirmed Stop is only warned about.
 
 ## Reuse it from another backend
 
@@ -75,12 +74,13 @@ state = computer.status  # e.g. :running, :paused, :resuming
 ```
 
 Reconnect reconstructs a handle locally. It makes no request, creates nothing,
-and does not replay work. Its next call targets the saved runtime, even if another
-backend has since replaced it. Store the binding revision alongside its JSON in
-your existing Computer record. Save a replacement only if its revision is newer
-(or it is the identical binding); a delayed reply must not overwrite a newer one.
-After confirmed Stop, clear the binding only if the stored revision and runtime
-still match the one stopped. Keep that revision and the durable credentials.
+and does not replay work. Its next call goes to the Computer sandbox the binding
+names, even if another backend has since started the Computer again. Store the binding
+revision alongside its JSON in your existing Computer record. Save a replacement
+only if its revision is newer (or it is the identical binding); a delayed reply
+must not overwrite a newer one.
+After confirmed Stop, clear the binding only if the stored revision and sandbox
+id still match the one stopped. Keep that revision and the durable credentials.
 Session records belong to a binding revision and cannot be reused after Start.
 
 To continue a session, also save its name and token when you create it, then use
@@ -93,10 +93,10 @@ worker can wait for existing work rather than submit it again. See
 
 | Intent | Call | Result |
 |---|---|---|
-| Finish using compute | `computer.stop` | Saves supported state, releases the runtime and ends its sessions |
-| Start a stopped Computer | `client.start_computer(credentials)` | Restores saved state into a new runtime; create new sessions |
-| Keep live memory for later | `computer.pause` | Retains the runtime and sessions; requires project opt-in |
-| Continue paused work | `computer.resume` | Restores the retained runtime and sessions |
+| Finish using compute | `computer.stop` | Saves supported state, shuts the Computer down and ends its sessions |
+| Start a stopped Computer | `client.start_computer(credentials)` | Runs the Computer from its saved state; create new sessions |
+| Keep live memory for later | `computer.pause` | Keeps the Computer and its sessions in memory; requires project opt-in |
+| Continue paused work | `computer.resume` | Brings back the paused Computer and its sessions |
 | Observe after a connection failure | `computer.status` | Reads state without changing or renewing it |
 
 ```ruby
@@ -107,13 +107,14 @@ computer = client.start_computer(credentials)
 store.save_binding(computer.id, computer.binding.to_json)
 ```
 
-Stop/Start is also how an application replaces an old runtime. An SDK upgrade or
+Stop/Start is also how an application updates a Computer. An SDK upgrade or
 Pine image rollout does not replace a running Computer. Start can receive a
 compatible older warm revision during rollout; it does not guarantee a build.
 
-`attach_computer` remains an alias for Start. **Use Reconnect for an existing
-runtime.** A failed Resume does not fall back to Start. Stop/Start restores saved
-browser state, not live tabs, session files or page memory. Export files first.
+`attach_computer` remains an alias for Start. **Use Reconnect for a Computer
+that's running or paused.** A failed Resume does not fall back to Start.
+Stop/Start restores saved browser state, not live tabs, session files or page
+memory. Export files first.
 [Persistence and teardown](#persistence--teardown) covers completion, recovery and
 permanent deletion.
 
@@ -121,19 +122,17 @@ permanent deletion.
 
 `timeout:` is the inactivity window (default five minutes), not an HTTP request
 timeout. Work renews it; reading status, watching events and other observation do
-not. It starts at allocation, so a one-minute window can expire during slow setup.
+not. It starts when the Computer starts, so a one-minute window can expire during
+slow setup.
 
-Projects can opt into a lifetime policy. The standard allowance is one minute to
-24 hours of idle time and seven days of maximum runtime age; approved project
-limits can be higher. Existing allocations retain their admitted terms.
-Enrollment applies to new allocations from Ruby 0.3.13 / Go 0.3.15 and later,
-including integrations that do not use the new policy methods. A requested
-timeout above the allowance, including the SDK default, is rejected. Before
-enrolling a project, check its integrations' requested timeouts and handling of
-maximum age. Deployment alone does not enroll projects or alter existing runtimes.
+Projects have a lifetime policy unless Pine removed it for one. The standard
+allowance is one minute to 24 hours of idle time and seven days of maximum age;
+approved project limits can be higher. A project without one has no maximum age
+and no idle maximum. A running Computer keeps the terms it started with.
+A requested timeout above the allowance, including the SDK default, is rejected.
 
 ```ruby
-details = computer.runtime_details
+details = computer.sandbox_details
 if details.lifecycle
   updated = computer.set_idle_timeout(seconds: 3600)
   puts updated.lifecycle.idle_timeout_seconds
@@ -141,67 +140,71 @@ if details.lifecycle
 end
 ```
 
-For an enrolled runtime, changing idle timeout takes effect now while running,
-or on the next Resume while paused. It cannot extend maximum age or snapshot
-retention. Legacy runtimes keep their previous expiry clock while paused; enrolled
-runtimes use snapshot retention and maximum age. An identical value does nothing.
+For a Computer started after enrollment, changing idle timeout takes effect now
+while running, or on the next Resume while paused. It cannot extend maximum age or
+snapshot retention. Computers started before enrollment keep their previous expiry
+clock while paused; those started after use snapshot retention and maximum age. An
+identical value does nothing.
 After a conflict or lost response,
-read `runtime_details` before deciding whether to edit again.
+read `sandbox_details` before deciding whether to edit again.
 
 Maximum age includes paused time. Graceful Stop begins twelve minutes before the
 hard deadline; expiry is not proof that a final save succeeded. Plan Stop/Start
 at a safe point before that deadline when you need uninterrupted work.
 
-`runtime_details` describes the current allocation, including optional lifecycle
-terms and its opaque `runtime_revision`. Missing lifecycle means the runtime
-has no admitted project lifetime policy. `client.project_policy` optionally reads
-allowances for future allocations; ordinary operations do not require that call.
+`sandbox_details` describes the current Computer sandbox, including optional
+lifecycle terms and its opaque `runtime_revision`. Missing lifecycle means the Computer
+was started without a project lifetime policy. `client.project_policy` optionally reads
+allowances for future starts; ordinary operations do not require that call.
 
-`ready_timeout:` bounds allocation/readiness and `bind_ready_timeout:` bounds the
-following handshake. They do not change runtime expiry. For example,
-`timeout: 28_800, ready_timeout: 120` requests eight hours of idle time with a
-two-minute readiness wait. These waits are separate from transport retries and
-cleanup; see the [integration guide](https://pinesandbox.io/docs/integration).
+`ready_timeout:` bounds waiting for the Computer to start and become ready, and
+`bind_ready_timeout:` bounds the following handshake. They do not change the
+Computer's expiry. For example, `timeout: 28_800, ready_timeout: 120` requests
+eight hours of idle time with a two-minute readiness wait. These waits are
+separate from transport retries and cleanup; see the
+[integration guide](https://console.pinecomputer.io/docs/integration).
 
 ## Handle failures without replacing live work
 
-- A network error or `alive? == false` does not prove the runtime is gone.
-  Read `status`; its `NotFoundError` confirms runtime-record absence. A
-  data-plane `RuntimeGoneError` alone does not: paused/restoring Computers can
+- A network error or `alive? == false` does not prove the Computer has stopped.
+  Read `status`; its `NotFoundError` confirms that it has. A
+  data-plane `SandboxGoneError` alone does not: paused/restoring Computers can
   temporarily have no route.
-- `RuntimeRetainedError` (a `BindError`) means Start found an existing runtime.
-  Match its `runtime_id` to your saved binding, or reload the latest binding from
+- `SandboxRetainedError` (a `BindError`) means Start found the Computer still
+  running or paused.
+  Match its `sandbox_id` to your saved binding, or reload the latest binding from
   your database. Reconnect, Resume or finish Stop as appropriate; an ID alone
   cannot reconstruct a missing token.
 - A Stop timeout means completion is unconfirmed, not canceled. Keep the binding
   and observe or retry Stop. Older servers report `StopSaveError` for a failed or
-  unconfirmed save; current servers still release the runtime.
+  unconfirmed save; current servers still shut the Computer down.
 - Serialize Create/Start per Computer in your application. On
   `BindingRevisionConflictError`, reload the winner's saved binding instead of
   retrying with a higher revision.
 - If a registered Computer's Start reply is lost before saving its binding,
   serialize recovery, call `client.stop_computer(id)`, then Start separately with
-  the saved credentials. This releases the runtime whose token was lost.
+  the saved credentials. This stops the Computer whose token was lost.
 - An interrupted first Create can fail before registering the Computer. Stop-by-ID
   then returns true, but Start raises `UnknownComputerError`. For that initial
   creation, retry Create with your saved credentials after confirming the project
   and ID are correct and the identity was not deleted. Do not treat every unknown
-  ID as permission to create. An allocation abandoned before registration may
-  remain until expiry; Stop-by-ID cannot discover it.
+  ID as permission to create. A Computer sandbox started before registration may
+  run until it expires; Stop-by-ID cannot find it.
 - On `AttachAuthorizationCommittedError`, registration has succeeded. Retain its
   non-nil credentials and reconcile the registered Computer before Start. Private
   keys cannot be recovered from an ID.
 
-Allocation retries within one call reuse its create ID. A fresh call is a new
-attempt. Failed attach attempts clean up known allocations best-effort; process
-crashes rely on expiry. Longer requested timeouts can leave abandoned compute
-running longer. See [Errors](#errors) for the error types.
+Retries within one call reuse its create ID. A fresh call is a new attempt. A
+failed attach shuts down the Computer sandbox it started, on a best-effort
+basis; after a process crash, that Computer sandbox runs until it expires.
+Longer requested timeouts can leave abandoned compute running longer. See
+[Errors](#errors) for the error types.
 
 ## Stored credentials and older integrations
 
 The project API key stays on your backend. Computer credentials contain the state
 key, current and retained capture keys, prior state keys and ephemeral mode.
-Bindings contain the runtime ID, Computer token and binding revision. The SDK
+Bindings contain the sandbox ID, Computer token and binding revision. The SDK
 handles short-lived project and attach authorization internally.
 
 `computer.credentials` returns an independent copy. Credentials and bindings use
@@ -219,22 +222,41 @@ For integrations using older storage or field-based methods:
 - Starting from a credentials value requires custom credential providers to
   implement `current_binding` and `credentials`. Bare callables still support
   Create and the field-based Attach form with an explicit binding revision.
-- `control_plane` and sandbox handles are SDK internals. Integrations use the
-  Computer methods above.
+- `control_plane` and the handles it returns are SDK internals. Integrations use
+  the Computer methods above.
 
 ## Sessions
 
-A session is the unit of work — a browser context + bash terminal. Create one, then
-drive it (next two sections). A Computer runs up to 3 sessions at once by default;
+A session is the unit of work: its own browser window and bash terminal. Create one,
+then drive it (next two sections). A Computer runs up to 3 sessions at once by default;
 `computer.capabilities` reports the limit (`sessions.concurrent`).
 
 ```ruby
-session = computer.create_session(name: "researcher-1", browser: true)
+session = computer.create_session(name: "researcher-1")
 computer.session("researcher-1")            # metadata by name; token is redacted
 computer.sessions                           # list all on this Computer
 computer.destroy_session("researcher-1")    # tear down (keeps on-disk dir; clean: true to GC)
 ```
 
+A session's agent can use the Computer's [artifacts](#artifacts) only when you create
+the session with `artifact_access: "read_only"` (list and read files) or
+`artifact_access: "read_write"` (also save and delete files and make public links).
+The default is `"none"`. `session.artifact_access` reports the access it was created
+with, and is `nil` for a session from `computer.adopt_session`, whose access only the
+Computer knows (`computer.session(name).artifact_access` reads it). Your own access
+with the project key, through `client.artifacts`, is the same either way.
+
+```ruby
+session = computer.create_session(name: "analyst", artifact_access: "read_only")
+session.artifact_access                     # => "read_only"
+```
+
+A person who must type a password or an MFA code takes control of the session
+(`session.take_control`, then `release_control`) and types it over the desktop while
+the agent waits. A secret your application already holds goes in the task instead
+(`session.agent.run(goal, secrets: {...})`): the agent reads it from
+`$SESSION_SECRETS`.
+
 ## Drive — Pine's agent (hand off the loop)
 
 For an attached Computer, `computer.require_agent_protocol!` checks public agent
@@ -312,7 +334,7 @@ same.
 
 `run` raises `409` if a turn is already running, or a person or your own agent
 holds the drive slot. Routes: `/v2/sessions/{name}/agent/*` in the
-[Computer API reference](https://pinesandbox.io/spec/computer).
+[Computer API reference](https://console.pinecomputer.io/spec/computer).
 
 ### Activity
 
@@ -350,11 +372,11 @@ observation; do not guess from nearby events. A text-only update leaves the last
 captured screen and its original attribution visible. Keep historical selection
 separate from following new frames; the event ID identifies each image for replay.
 
-This SDK requires a Computer runtime with the public V2 agent contract. There is
+This SDK requires a Computer that serves the public V2 agent contract. There is
 no fallback to native trace. Activity includes progress, questions and results;
 native commands, reasoning and provider metadata are internal-only. Upgrade
-agent consumers before moving them to the new runtime: its legacy agent routes
-reject ordinary bindings.
+agent consumers before you restart their Computers on the new release: its legacy
+agent routes reject ordinary bindings.
 
 Paged history uses the same typed events as streaming. Scope every saved cursor
 to its Task; after a session replacement, discover the new Task before replaying
@@ -387,47 +409,82 @@ drive.upload_file("input[type=file]", "resume.pdf")   # set a file input (deposi
 
 `observe` is read-only (allowed even while Pine's agent runs — you can watch);
 `computer_use` / `upload_file` take the drive slot (`409` if Pine's agent or a person
-holds it). Pine's resident agent can use private DOM/browser tools through
-`session.delegate`; direct customer shell execution runs public programs and
-works with session files. It cannot invoke Pine's private browser implementation.
-Raw CDP is an image-owned runtime transport and is intentionally absent from
-the SDK surface. Tab helpers
+holds it). Shell commands run ordinary programs and work with the session's
+files. Tab helpers
 (`create_tab`/`tabs`/`patch_tab`/`close_tab`), `focus!`, and `epoch` round out the manual
 surface. Public routes are defined by the
-[Computer API reference](https://pinesandbox.io/spec/computer).
+[Computer API reference](https://console.pinecomputer.io/spec/computer).
 
-## Files & artifacts
+## Files
 
-A session has a **workdir** (where `exec` runs and the agent works), an inbound
-**attachments** root (files you hand the agent), and an **artifact registry** (the
-session's managed outputs).
+A session has a **workdir** (where `exec` runs and the agent works) and an inbound
+**attachments** root (files you hand the agent), which appears inside the workdir as
+`attachments/`.
 
 ```ruby
 # Read the workdir (what the agent produced / your shell wrote):
 session.list_files(pattern: "*.csv")             # => [FileEntry, ...]
 session.read_file("out/report.csv")              # => bytes (binary encoding)
+session.open_file("out/export.zip") { |chunk| io.write(chunk) }  # stream it without buffering
 
-# Deposit a material the agent should use. It lands in attachments/ and surfaces
-# to the agent via the materials preamble — a sibling of the workdir, so it is NOT
-# read_file-able (read_file serves the workdir).
+# Give the agent an input file. It lands in attachments/ (readable as
+# read_file("attachments/brief.md")), and the agent sees it when its next turn starts.
 session.write_file("brief.md", File.read("brief.md"))
 
-# Artifacts — the session's managed outputs, each with metadata + a download.
-art = session.upload_artifact("logo.png", File.binread("logo.png"))  # => Models::Artifact
-session.list_artifacts                            # all, newest-first
-session.list_artifacts(turn_id: "turn_…")         # just one agent turn's outputs
-session.read_artifact(art.id)                     # => bytes
-session.zip_artifacts                             # => a .zip of all artifacts (bytes)
-session.open_artifact(art.id) { |chunk| io.write(chunk) }  # stream it without buffering
+# The files an ended turn produced, by workdir path:
+turn.result.artifacts.each do |file|
+  path = file.fetch("relative_path")
+  save(path, session.read_file(path))
+end
 ```
 
-`created_by` names the producer: `upload` (you), `download` (a browser download,
-auto-indexed), `agent` (a turn's outputs, durably captured at the turn's result). Only
-`agent` artifacts carry a `turn_id`, so the `turn_id` filter scopes to one turn's
-outputs; uploads/downloads always appear unfiltered. Uploads are immutable +
-id-addressed (a repeated filename yields a distinct artifact). Routes: `/files`,
-`/artifacts[/{zip,artifact_id}]` in the
-[Computer API reference](https://pinesandbox.io/spec/computer).
+A turn's result lists its files by `relative_path` in the workdir, with size, SHA-256
+and media type. They aren't copies: read them when the turn ends, because a later turn
+or shell command can change them. A browser download isn't one of them; to get one
+back, ask for it in the goal, and the agent copies it into the workdir and lists it.
+Without a block, `open_file` returns an Enumerator of the chunks. Session files last
+until the Computer stops; save what you need first. Routes: `/files` in the
+[Computer API reference](https://console.pinecomputer.io/spec/computer).
+
+## Artifacts
+
+A Computer's **artifacts** are the files it keeps beyond its sessions. Reach them
+with the project key, whether the Computer is running or stopped. A session's agent
+can use them only when the session was created with `artifact_access: "read_only"`
+or `"read_write"` (see [Sessions](#sessions)); that choice doesn't change your own
+access here.
+
+```ruby
+artifacts = client.artifacts(computer_id)
+
+page = artifacts.list(prefix: "research/")       # one page: files, folders, next_page_token
+page.files.each { |file| puts "#{file.path} #{file.size} #{file.note}" }
+
+artifacts.upload("inputs/brief.pdf", Pathname("brief.pdf"), note: "the brief")
+artifacts.upload("inputs/notes.txt", "plain bytes")
+artifacts.download("reports/q3.pdf", "q3.pdf")   # => bytes written
+artifacts.open("reports/q3.csv") { |chunk| io.write(chunk) }
+artifacts.copy(other_computer_id, "templates/form.pdf", "inputs/form.pdf")
+artifacts.delete("inputs/notes.txt")
+
+# A public link, served by the running Computer until it stops:
+computer.artifact_link("reports/q3.pdf", expires_in_seconds: 86_400)  # => { "url" => ..., "expires_at" => ... }
+```
+
+The SDK gets one short-lived storage token from Pine and sends the files straight to
+and from storage, never through Pine; it renews the token before it lapses. An upload
+takes a String of bytes, a `Pathname` or an IO with a known size, and resumes after a
+dropped connection; without `content_type:` it is typed by its path's extension, the
+same way in every Pine SDK. A download writes beside the destination and renames into
+place. `download` and `open` resume after a dropped connection, a request timeout, a
+429 or a 5xx other than 501, from where they stopped and from the same version of the
+file (one replaced meanwhile raises `PineSandbox::PreconditionFailedError`). `copy` also copies within the
+Computer, given its own id. A missing file raises `PineSandbox::ArtifactNotFoundError`
+(`#path`); while the Computer's artifacts are over their limit, `upload` and `copy`
+raise `PineSandbox::ArtifactStorageFullError` without sending anything, and check
+again on the next call, so deleting files makes room. `open` passes each chunk on as it
+arrives with faraday-net_http 3.0 or later; an older faraday-net_http gives the body
+only once it is complete, so `open` writes it to a temporary file first.
 
 ## Skills — `learn` / `teach` (and when each blocks)
 
@@ -477,20 +534,20 @@ gate: nothing learned reaches another agent until you activate it.
 
 ```ruby
 computer.checkpoint     # synchronous state save (content-hash dedup) — before a risky step
-computer.stop           # save cookies, learned skills and localStorage, then delete the sandbox
-computer.kill           # delete without an acknowledged save
+computer.stop           # save cookies, learned skills and localStorage, then shut the Computer down
+computer.kill           # shut the Computer down without waiting for a save
 client.delete_computer(computer)  # PERMANENT: kill if attached, then delete id + saved state
 ```
 
 `stop` and `kill` keep the Computer's identity and saved state; `delete_computer`
 (a `Computer` or its id) ends both. The id is refused for every later attach, saved
-state is purged after 24 hours, and the id is never reusable. Deleting an unknown,
+state is purged after 25 hours, and the id is never reusable. Deleting an unknown,
 already-deleted, or other project's id also returns `true`. There is no undelete.
 
-`stop` submits graceful Stop to the runtime controller, then waits up to 390s
-(`wait_timeout:`) for compute release. The controller tries to save supported state
+`stop` submits graceful Stop to Pine's controller, then waits up to 390s
+(`wait_timeout:`) for the Computer to shut down. The controller tries to save supported state
 before deletion and continues if the SDK process disappears. Saving is best effort:
-a save that fails or is not confirmed by the deadline still releases the runtime,
+a save that fails or is not confirmed by the deadline still shuts the Computer down,
 and `stop` returns true; the next Start restores the last saved state. Reconstruct
 the saved handle with `reconnect_computer` to observe or join the same operation from
 another backend. Only an older server keeps the source and raises
@@ -498,49 +555,49 @@ another backend. Only an older server keeps the source and raises
 failure from an unconfirmed outcome after the Computer's services restart.
 A `false` return means completion is unconfirmed. Keep the saved binding for retry.
 After Stop returns true, clear the stored binding only if its revision and
-runtime still match the handle stopped; a concurrent Start may have replaced it.
+sandbox id still match the handle stopped; a concurrent Start may have replaced it.
 Keep the revision fence, identity, state key and capture keypairs for future Start. Ephemeral
-bindings skip persistence; the runtime's binding record decides this.
+bindings skip persistence; Pine's binding record decides this.
 
-If a Start response was lost before saving the runtime token, use
-`client.stop_computer(id)` to stop the currently bound runtime with project
+If a Start response was lost before saving the Computer token, use
+`client.stop_computer(id)` to stop the Computer with project
 authorization alone, then call Start separately. This lookup selects one binding;
 it never follows a concurrent newer binding. Private keys remain necessary for
 Start and cannot be recovered from the ID.
 
-A true result proves compute release or authoritative runtime absence. It does
-not prove a final save by a runtime that disappeared, and provider snapshot cleanup
-can still be running. Start restores only the latest committed state. Cookies,
-learned skills and compatible localStorage survive supported saved-state recovery;
-tabs, session files, page memory and IndexedDB do not.
+A true result proves the Computer has shut down or was already gone.
+It does not prove a final save when the Computer had already gone, and provider
+snapshot cleanup can still be running. Start restores only the latest committed
+state. Cookies, learned skills and compatible localStorage survive supported
+saved-state recovery; tabs, session files, page memory and IndexedDB do not.
 
-`start_computer` reads the current binding revision once, checks that the old
-runtime is gone or released, waiting for an already accepted deletion if needed,
+`start_computer` reads the current binding revision once, checks that the
+Computer has stopped, waiting for an already accepted shutdown if needed,
 and creates a new binding. A conflict stays a conflict;
 it never adopts a newer revision and displaces another worker's winner. For a
-recorded failed runtime, explicitly call
-`client.recover_computer(id, key: key, capture_keypair: keypair)`.
-Recovery accepts possible unsaved-state loss, releases the observed failed runtime
-with a version precondition, waits up to 90s for compute release, then Starts. It
-refuses healthy running/paused runtimes and an unresolved capture timeout. If
-release times out, retry later; no replacement has been allocated. `kill` remains
+Computer you recorded as failed, explicitly call
+`client.recover_computer(credentials)`.
+Recovery accepts possible unsaved-state loss, shuts the failed Computer down
+with a version precondition, waits up to 90s for it to shut down, then Starts. It
+refuses healthy running or paused Computers and an unresolved capture timeout. If
+shutting it down times out, retry later; nothing new has been started. `kill` remains
 an unconditional destructive operation.
 
-This SDK's retryable allocation and server-owned Stop require the updated backend
-and a compatible Computer runtime; neither requires Pause opt-in. Existing
+This SDK's retryable Start and server-owned Stop require the updated backend
+and a compatible Computer; neither requires Pause opt-in. Existing
 Computer create, capture/Finish and delete calls remain supported for applications
 keeping their prior SDK. Complete the backend rollout before upgrading, including
 the conditional-release support used by recovery. A pool image update does not
 upgrade an already-running Computer: stop old-image bindings with the prior SDK
 before upgrading their caller. Integrations using the removed generic
-public sandbox operations must migrate to the Computer contract; the private Ruby
+public lifecycle operations must migrate to the Computer contract; the private Ruby
 `ControlPlane#create` adapter is removed as well.
 
-For projects opted in to Pause/Resume on snapshot-capable runtimes:
+For projects opted in to Pause/Resume, on Computers that support snapshots:
 
 ```ruby
 computer.pause(timeout: 360)  # waits for capture and confirmed source stop
-computer.resume(timeout: 360) # waits for restored routing and runtime recovery
+computer.resume(timeout: 360) # waits until the Computer is restored and reachable
 ```
 
 Pause is disabled by default. Pine enables it for a project on request;
@@ -548,41 +605,45 @@ refresh the project token after it is enabled. Disabling the
 feature prevents new pauses but preserves Resume and Stop for retained memory.
 Ordinary Stop/Start remains available without the opt-in.
 
-The same sandbox handle, session capabilities and retained process memory remain.
-A pool image update does not change the captured runtime. Calls include acceptance
+The same Computer handle, session capabilities and retained process memory remain.
+A pool image update does not change a paused Computer. Calls include acceptance
 and completion in one bounded timeout. A timeout leaves the outcome unconfirmed;
-retry against the retained handle. The controller restores the same paused
-runtime before Stop can save it. Snapshot retention and admitted maximum age still apply; legacy expiry is unchanged.
+retry against the retained handle. The controller restores the paused Computer
+before Stop can save it. Snapshot retention and admitted maximum age still apply;
+legacy expiry is unchanged.
 
 Do not rescue a failed `resume` by automatically calling `start_computer`.
 Retrying Resume keeps the existing memory-recovery intent; Start explicitly
 accepts recovery from the last saved state with new sessions and possible loss
 of unsaved work. An unavailable status or timeout alone does not prove that
-memory is lost. The [Computer API reference](https://pinesandbox.io/spec/computer)
+memory is lost. The [Computer API reference](https://console.pinecomputer.io/spec/computer)
 defines the observed states and recovery choices: retry Resume, refresh the
 status, or Start from saved state.
 
 ## Errors
 
+[Troubleshooting](https://console.pinecomputer.io/docs/troubleshooting) says what
+each common error means and how to fix it.
+
 Three typed families, one per credential exchange (see `lib/pinesandbox/errors.rb`):
 
-Data-plane runtime loss raises `PineSandbox::RuntimeGoneError`; it preserves the
-wire diagnostics and original `ApiError` cause. Errors about a resource on a
-live Computer remain distinct, including `PineSandbox::SessionNotFound` and
-`PineSandbox::ControlNotHeld`.
+A Computer that can no longer be reached raises `PineSandbox::SandboxGoneError`;
+it preserves the wire diagnostics and original `ApiError` cause. Errors about a
+resource on a live Computer remain distinct, including
+`PineSandbox::SessionNotFound` and `PineSandbox::ControlNotHeld`.
 
 - **`BindError`** — `Computer#attach` outcomes: `BindAuthError`,
-  `ComputerAlreadyAttachedError`, `RuntimeUnusableError`, `SavedStateUnavailableError`,
+  `ComputerAlreadyAttachedError`, `SandboxUnusableError`, `SavedStateUnavailableError`,
   `BindTimeoutError`; plus `TokenRejectedError` on a post-bind 401 for the
-  Computer token (`ct_` not recognized — on a live runtime it is
-  `binding_auth_lost`; re-attach only when the runtime is confirmed gone). A 401
+  Computer token (`ct_` not recognized — on a running Computer it is
+  `binding_auth_lost`; re-attach only when the Computer is confirmed stopped). A 401
   for a session token is an ordinary `UnauthorizedError`. If `create_computer` raises
-  `AttachAuthorizationCommittedError`, retain its non-nil `#credentials` and inspect `#runtime_id` before deciding
-  whether to stop or recover the failed runtime. Credential inspection redacts private material.
+  `AttachAuthorizationCommittedError`, retain its non-nil `#credentials` and inspect `#sandbox_id` before deciding
+  whether to stop or recover the failed Computer. Credential inspection redacts private material.
 - **`AttachCredentialsError`** — the portal attach-credentials flow:
   `UnknownComputerError` (404 — deleted or cross-project),
   `ProjectAccessDenied` (403), and `BindingRevisionConflictError` (412 — another start changed the binding; `#current_binding_revision` /
-  `#current_runtime_id` identify the winner. Do not retry automatically). A bad `pk_` (401),
+  `#current_sandbox_id` identify the winner. Do not retry automatically). A bad `pk_` (401),
   rate limit (429), and server errors are the base `AttachCredentialsError`.
   Inspect the stable problem `#problem_type` and optional safe `#reason`; raw
   internal exceptions are never part of the API contract.
@@ -591,9 +652,9 @@ live Computer remain distinct, including `PineSandbox::SessionNotFound` and
   A `Retry-After` longer than the mint's 10-second backoff cap ends the mint at
   once with that error instead of retrying early.
 
-The old names `SandboxGoneError`, `SandboxFailedError`, `PodPoisonedError`,
-`BrokerUnreachableError`, `SandboxHandle` and the `sandbox_id` readers keep
-working as deprecated aliases; they warn when Ruby's deprecation warnings are on.
+The old names `PodPoisonedError` (now `SandboxUnusableError`) and
+`BrokerUnreachableError` (now `SavedStateUnavailableError`) keep working as
+deprecated aliases; they warn when Ruby's deprecation warnings are on.
 
 ## Troubleshooting — reporting an issue
 
@@ -601,7 +662,7 @@ The SDK supports saved Computer diagnostics. They require the diagnostics backen
 
 ```ruby
 # Persist one key per logical request if you need to retry after a lost response.
-report = client.create_diagnostic(computer_id: saved_id, session: "main",
+report = client.create_diagnostic(computer_id: saved_id, session: saved_session_name,
                                   idempotency_key: diagnostic_request_key)
 support_reference = report.fetch("id")
 # Read later. Only poll queued/running reports, with a bounded deadline.
@@ -628,17 +689,17 @@ begin
   session.agent.run("book the 9am slot")
 rescue PineSandbox::ApiError => e
   logger.error(e.message)
-  # => "… (runtime=sbx_abc123, op=POST /v2/sessions/main/agent/run, request_id=req_abc123)"
+  # => "… (sandbox=<sandbox-id>, op=POST /v2/sessions/main/agent/run, request_id=req_abc123)"
   Report.open(computer_id: computer.id, session: session.name,
               at: Time.now.utc, request_id: e.request_id, op: e.op)
 end
 ```
 
 Each error class exposes exactly its own typed context (the message always carries the same
-data): Computer API **`ApiError`** → `#runtime_id` / `#op` / `#request_id`; control-plane errors
+data): Computer API **`ApiError`** → `#sandbox_id` / `#op` / `#request_id`; control-plane errors
 → `#op` / `#request_id`; portal **`ControlTokenError`** / **`AttachCredentialsError`** → `#op`
 / `#request_id`. The suffix grammar is uniform `key=value` across the Go and Ruby SDKs; Ruby
-Computer API errors use **`runtime=`** because the Ruby SDK holds the runtime id, where the Go SDK
+Computer API errors use **`sandbox=`** because the Ruby SDK holds the sandbox id, where the Go SDK
 uses **`host=`** because its client holds the Computer host (same Computer, different handle
 each SDK already has).
 
@@ -655,10 +716,10 @@ to find the failure:
 
 ## Known limitations
 
-- Pause/Resume requires a qualified snapshot-capable Computer runtime.
-  Other runtimes reject it as unsupported. Snapshot loss, expiry or
-  failed recovery surfaces an error; it never silently falls back to a fresh
-  runtime. Enrolled runtimes use snapshot retention and maximum age while paused; legacy expiry is unchanged.
+- Pause/Resume requires a Computer that supports snapshots; others reject it as
+  unsupported. Snapshot loss, expiry or failed recovery surfaces an error; it
+  never silently falls back to a fresh start. Computers started after enrollment
+  use snapshot retention and maximum age while paused; legacy expiry is unchanged.
 
 ## Develop