@revyl/verify 0.1.0 → 0.3.0

package/dist/session.d.ts

@@ -1,6 +1,6 @@
 import { RevylClient } from './api/client.js';
 import type { LiveStepType, Platform } from './api/types.js';
-import type { ResolvedDeviceTarget } from './config.js';
+import type { HostedTargetConfig, ResolvedDeviceTarget } from './config.js';
 export type StepType = LiveStepType;
 /** The outcome of one instruction or validation, as Revyl's agent reported it. */
 export interface StepResult {
@@ -45,6 +45,11 @@ export interface ComputerProcess {
     state: 'running' | 'exited';
     exitCode?: number;
 }
+export interface ComputerRecording {
+    url: string;
+    durationSeconds?: number;
+    startedAt?: Date;
+}
 /**
  * One live Revyl session: a cloud browser, an iOS or Android device, or a computer.
  * A call the session's platform does not offer throws NOT_AVAILABLE_ON_PLATFORM.
@@ -60,6 +65,8 @@ export interface Session {
     /** Every instruction and validation run on this session, in order. */
     readonly steps: StepResult[];
     readonly closed: boolean;
+    readonly expiresAt?: Date;
+    recording(): Promise<ComputerRecording | null>;
     /** Asks Revyl's agent to do something on the app. Browsers and devices only. */
     instruction(text: string, options?: StepOptions): Promise<StepResult>;
     /** Asks Revyl's agent whether something holds on screen. Browsers and devices only. */
@@ -84,9 +91,21 @@ export interface Session {
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }
+export interface OpenedSession extends Session {
+    report(): Promise<Record<string, unknown>>;
+    navigate(url: string): Promise<void>;
+    open(target: HostedTargetConfig): Promise<OpenedSession>;
+}
 export interface SessionOptions {
     stepTimeout: number;
     log: ((line: string) => void) | undefined;
+    appUrl?: string;
+}
+export interface HostingParent {
+    id: string;
+    signal: AbortSignal;
+    expiresAt?: Date;
+    register(session: Session): void;
 }
 /** A Revyl cloud browser or iOS or Android device. */
 export declare class DeviceSession implements Session {
@@ -104,8 +123,12 @@ export declare class DeviceSession implements Session {
     private workflowRunId;
     private closePromise;
     private stepRunning;
+    private parent?;
+    private readySignal?;
+    get expiresAt(): Date | undefined;
     private constructor();
-    static start(client: RevylClient, target: ResolvedDeviceTarget, options: SessionOptions): Promise<DeviceSession>;
+    static start(client: RevylClient, target: ResolvedDeviceTarget, options: SessionOptions, parent?: HostingParent): Promise<DeviceSession>;
+    private static startHosted;
     get closed(): boolean;
     /** Asks Revyl's agent to do something on the app, such as "add the first product to the cart". Throws INSTRUCTION_FAILED when it cannot. */
     instruction(text: string, options?: StepOptions): Promise<StepResult>;
@@ -118,7 +141,11 @@ export declare class DeviceSession implements Session {
     screenshot(options?: {
         path?: string;
     }): Promise<Uint8Array>;
+    report(): Promise<Record<string, unknown>>;
+    navigate(url: string): Promise<void>;
     exec(): Promise<ExecResult>;
+    open(): Promise<never>;
+    recording(): Promise<never>;
     readFile(): Promise<Buffer>;
     writeFile(): Promise<void>;
     stat(): Promise<FileStat>;
@@ -130,6 +157,7 @@ export declare class DeviceSession implements Session {
     private step;
     private runStep;
     private launch;
+    private waitForScreenContent;
     private log;
     private computerOnly;
     private worker;

package/dist/session.js

@@ -2,9 +2,10 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { apiError, parseJson, responseDetail, responseErrorCode, sessionViewerUrl, } from './api/client.js';
+import { apiError, edgeBlockedError, parseJson, responseDetail, responseErrorCode, responseRefusalReason, sessionViewerUrl, } from './api/client.js';
 import { trackSession, untrackSession } from './cleanup.js';
 import { VerifyError, errorMessage, isVerifyError } from './errors.js';
+import { screenHasContent } from './screen-readiness.js';
 const POLL_INTERVAL_MS = 2_000;
 const DEVICE_CONNECT_TIMEOUT_MS = 90_000;
 const STEP_POLL_BASE_MS = 500;
@@ -31,6 +32,11 @@ export class DeviceSession {
     workflowRunId;
     closePromise;
     stepRunning = false;
+    parent;
+    readySignal;
+    get expiresAt() {
+        return this.parent?.expiresAt;
+    }
     constructor(client, target, id, workflowRunId, options) {
         this.client = client;
         this.options = options;
@@ -38,10 +44,12 @@ export class DeviceSession {
         this.target = target.name;
         this.id = id;
         this.workflowRunId = workflowRunId;
-        this.viewerUrl = sessionViewerUrl(id);
+        this.viewerUrl = sessionViewerUrl(id, undefined, options.appUrl);
     }
-    static async start(client, target, options) {
-        const deadline = Date.now() + target.startTimeout;
+    static async start(client, target, options, parent) {
+        const deadline = Math.min(Date.now() + target.startTimeout, parent?.expiresAt?.getTime() ?? Infinity);
+        if (parent)
+            return DeviceSession.startHosted(client, target, options, parent, deadline);
         if (target.platform === 'web') {
             const buildId = await resolveWebBuildId(client, target);
             const sessionId = randomUUID();
@@ -94,9 +102,77 @@ export class DeviceSession {
             await session.waitForDeviceReady(deadline);
             if (app.bundleId)
                 await session.launch(app.bundleId);
+            await session.waitForScreenContent(deadline);
         });
         return session;
     }
+    static async startHosted(client, target, options, parent, deadline) {
+        const id = randomUUID();
+        const session = new DeviceSession(client, target, id, '', options);
+        session.parent = parent;
+        session.readySignal = AbortSignal.any([parent.signal, AbortSignal.timeout(Math.max(0, deadline - Date.now()))]);
+        const request = {
+            platform: target.platform,
+            session_id: id,
+            computer_session_id: parent.id,
+            app_id: target.app.appId,
+            build_id: target.app.buildId,
+            idle_timeout_seconds: target.idleTimeoutSeconds,
+            ...(target.platform === 'web' ? { web: {
+                    ...(target.viewport ? { viewport: { width: target.viewport.width, height: target.viewport.height, device_scale_factor: target.viewport.deviceScaleFactor } } : {}),
+                    ...(target.signIn ? { sign_in: { path: target.signIn.path, secret_name: target.signIn.secret, persona: target.signIn.persona } } : {}),
+                } } : { is_simulation: true }),
+        };
+        let submitted = false;
+        let refused = false;
+        try {
+            session.readySignal.throwIfAborted();
+            submitted = true;
+            const response = await client.send('POST', '/api/v1/execution/start_device', { body: request, retry: false, signal: session.readySignal, timeoutMs: 120_000 });
+            if (response.status < 200 || response.status >= 300) {
+                const reason = responseRefusalReason(response);
+                refused = [400, 401, 403, 404, 405, 409, 422, 429].includes(response.status) || (response.status === 503 && reason !== undefined && reason !== 'request_timeout' && reason !== 'protocol_error');
+                const blocked = edgeBlockedError(response);
+                if (blocked)
+                    throw blocked;
+                const code = response.status === 401 || response.status === 403 ? 'AUTH_REJECTED'
+                    : reason === 'computer_not_found' || response.status === 404 ? 'NOT_FOUND'
+                        : reason === 'computer_not_running' ? 'SESSION_ENDED'
+                            : reason === 'computer_cannot_host_platform' || reason === 'computer_runtime_unavailable' || reason === 'web_runtime_unavailable' || reason === 'web_runtime_not_configured' || reason === 'runtime_unavailable' || reason === 'not_available_on_platform' ? 'NOT_AVAILABLE_ON_PLATFORM'
+                                : reason === 'computer_at_capacity' || reason === 'computer_limit' ? 'COMPUTER_LIMIT'
+                                    : response.status === 422 || response.status === 400 ? 'INVALID_ARGUMENT'
+                                        : response.status === 409 ? 'SESSION_BUSY'
+                                            : response.status === 408 || response.status >= 500 ? 'ACTION_UNCERTAIN' : 'API_ERROR';
+                throw new VerifyError(code, `Revyl refused the hosted session start (${reason ?? `HTTP ${response.status}`}).`, { reason, httpStatus: response.status });
+            }
+            const start = parseJson(response, 'hosted session start');
+            if (!start || typeof start !== 'object' || Array.isArray(start))
+                throw new VerifyError('API_ERROR', 'Revyl returned an invalid hosted session response.');
+            if (start.session_id !== id || typeof start.workflow_run_id !== 'string' || !/^[A-Za-z0-9_-]{1,255}$/.test(start.workflow_run_id) || (start.platform !== undefined && start.platform !== target.platform))
+                throw new VerifyError('SESSION_START_FAILED', 'Revyl did not acknowledge the hosted session identity.');
+            session.workflowRunId = start.workflow_run_id;
+            parent.register(session);
+            await session.untilReady(async () => {
+                if (target.platform === 'web')
+                    await session.waitForWebReady(deadline);
+                else {
+                    await session.waitForDeviceReady(deadline);
+                    await session.waitForScreenContent(deadline);
+                }
+            });
+            session.readySignal.throwIfAborted();
+            return session;
+        }
+        catch (error) {
+            if (submitted && !refused) {
+                parent.register(session);
+                await session.close().catch(() => undefined);
+            }
+            if (session.readySignal.aborted)
+                throw new VerifyError('TIMEOUT', `Hosted startup was cancelled or exceeded its deadline. See ${session.viewerUrl}`, { cause: error });
+            throw error;
+        }
+    }
     get closed() {
         return this.closePromise !== undefined;
     }
@@ -131,9 +207,44 @@ export class DeviceSession {
         }
         return response.body;
     }
+    async report() {
+        if (!this.id)
+            throw new VerifyError('NOT_FOUND', 'Cannot report a session without a known session ID.');
+        const report = await this.client.getDeviceSession(this.id);
+        if (!report || typeof report !== 'object' || Array.isArray(report))
+            throw new VerifyError('API_ERROR', 'Revyl returned an invalid session report.');
+        return report;
+    }
+    async navigate(url) {
+        if (this.platform !== 'web')
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'navigate() is available only on web sessions.');
+        if (typeof url !== 'string' || url.length > 2048 || /[\x00-\x20\x7f-\x9f\s\\]/.test(url))
+            throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires an http(s) URL without credentials, whitespace, or backslashes.');
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires a valid http(s) URL.');
+        }
+        if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password)
+            throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires an http(s) URL without credentials.');
+        const response = await this.worker('POST', 'open_url', { body: { url }, retry: false });
+        const result = parseJson(response, 'open_url');
+        if (!result || typeof result !== 'object' || typeof result.success !== 'boolean' || (result.action !== undefined && result.action !== 'navigate') || (result.status_code !== undefined && (!Number.isInteger(result.status_code) || result.status_code < 100 || result.status_code > 599)))
+            throw new VerifyError('API_ERROR', 'Revyl returned an invalid navigation response.');
+        if (!result.success)
+            throw new VerifyError('ACTION_FAILED', `Revyl did not confirm navigation. See ${this.viewerUrl}`);
+    }
     exec() {
         return this.computerOnly('exec');
     }
+    open() {
+        return this.computerOnly('open');
+    }
+    recording() {
+        return this.computerOnly('recording');
+    }
     readFile() {
         return this.computerOnly('readFile');
     }
@@ -154,7 +265,7 @@ export class DeviceSession {
         this.closePromise ??= (async () => {
             try {
                 if (this.id)
-                    await this.client.stopDeviceSession(this.id);
+                    await this.client.stopDeviceSession(this.id, this.parent === undefined);
                 else
                     await this.client.cancelDevice(this.workflowRunId);
                 this.log('closed');
@@ -261,6 +372,33 @@ export class DeviceSession {
             throw new VerifyError('SESSION_START_FAILED', `Could not launch ${bundleId} on the ${this.target} device: ${result.error ?? 'no reason given'}`);
         }
     }
+    async waitForScreenContent(startDeadline) {
+        const deadline = Math.min(startDeadline, Date.now() + 10_000);
+        while (Date.now() < deadline) {
+            try {
+                const response = await this.client.worker(this.workflowRunId, 'screenshot', {
+                    method: 'GET', retry: false, signal: AbortSignal.any([AbortSignal.timeout(Math.max(1, deadline - Date.now())), ...(this.readySignal ? [this.readySignal] : [])]),
+                });
+                if (response.status === 200) {
+                    const content = screenHasContent(response.body);
+                    if (content === true)
+                        return;
+                    if (content === undefined)
+                        break;
+                }
+                else if (response.status !== 409 && response.status !== 503) {
+                    break;
+                }
+            }
+            catch {
+                break;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining > 0)
+                await delay(Math.min(500, remaining));
+        }
+        this.log('debug: best-effort first-screen wait ended without non-blank content; the runtime has no rendered-readiness signal');
+    }
     log(line) {
         this.options.log?.(`${this.target}: ${line}`);
     }
@@ -268,11 +406,24 @@ export class DeviceSession {
         return Promise.reject(new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `${call}() runs on computer targets (platform 'mac' or 'linux'), not on ${this.platform} sessions.`));
     }
     async worker(method, action, options) {
-        if (this.closePromise)
-            throw new VerifyError('SESSION_ENDED', `The ${this.target} session was closed.`);
-        const response = await this.client.worker(this.workflowRunId, action, { method, ...options });
+        if (this.closePromise || this.parent?.signal.aborted || (this.parent?.expiresAt && Date.now() >= this.parent.expiresAt.getTime()))
+            throw new VerifyError('SESSION_ENDED', `The ${this.target} session was closed or its parent expired.`);
+        const signal = this.parent ? AbortSignal.any([
+            this.parent.signal,
+            ...(this.parent.expiresAt ? [AbortSignal.timeout(Math.max(0, this.parent.expiresAt.getTime() - Date.now()))] : []),
+            ...(options.signal ? [options.signal] : []),
+        ]) : options.signal;
+        const response = await this.client.worker(this.workflowRunId, action, { method, ...options, signal });
         if (response.status >= 200 && response.status < 300)
             return response;
+        if (action === 'open_url') {
+            const error = this.workerError(method, action, response);
+            const reason = responseRefusalReason(response);
+            const message = error.code === 'ACTION_UNCERTAIN' && reason === 'request_timeout'
+                ? `Web navigation did not confirm within the action budget and may still complete. The session is still open; Verify did not replay the request. See ${this.viewerUrl}`
+                : `Web navigation failed (HTTP ${response.status}). See ${this.viewerUrl}`;
+            throw new VerifyError(error.code, message, { reason, httpStatus: response.status });
+        }
         throw this.workerError(method, action, response);
     }
     workerError(method, action, response) {
@@ -316,13 +467,14 @@ export class DeviceSession {
     }
     async waitForWebReady(deadline) {
         for (;;) {
-            const detail = await this.client.getDeviceSession(this.id);
+            this.readySignal?.throwIfAborted();
+            const detail = await this.client.getDeviceSession(this.id, this.readySignal);
             if (ENDED_STATUSES.has(detail.status)) {
                 throw new VerifyError('SESSION_START_FAILED', `The ${this.target} web session ended before it was ready (${detail.status}): ${detail.error_message ?? 'no reason given'}. See ${this.viewerUrl}`);
             }
             if (detail.status === 'running' && detail.workflow_run_id) {
                 this.workflowRunId = detail.workflow_run_id;
-                const response = await this.client.worker(this.workflowRunId, 'screenshot', { method: 'GET' });
+                const response = await this.client.worker(this.workflowRunId, 'screenshot', { method: 'GET', signal: this.readySignal });
                 if (response.status === 200 && pngSize(response.body))
                     return;
                 if (response.status !== 503 && response.status !== 409 && responseErrorCode(response) !== 'not_ready') {
@@ -334,7 +486,8 @@ export class DeviceSession {
     }
     async waitForDeviceReady(deadline) {
         for (;;) {
-            const connection = await this.client.getWorkerConnection(this.workflowRunId);
+            this.readySignal?.throwIfAborted();
+            const connection = await this.client.getWorkerConnection(this.workflowRunId, this.readySignal);
             if (connection.status === 'ready' && connection.worker_ws_url)
                 break;
             if (connection.status === 'cancelled' || connection.status === 'stopped' || connection.status === 'failed') {
@@ -344,7 +497,7 @@ export class DeviceSession {
         }
         const connectDeadline = Math.min(deadline, Date.now() + DEVICE_CONNECT_TIMEOUT_MS);
         for (;;) {
-            const response = await this.client.worker(this.workflowRunId, 'health', { method: 'GET', retry: true });
+            const response = await this.client.worker(this.workflowRunId, 'health', { method: 'GET', retry: true, signal: this.readySignal });
             if (response.status === 200 && parseJson(response, 'health').device_connected)
                 return;
             if (response.status !== 200 && response.status !== 503)

package/docs/README.md

@@ -4,13 +4,13 @@ These files ship inside the npm package at `node_modules/@revyl/verify/docs/`, s
 
 | File | Read it when you want to |
 | --- | --- |
+| [end-to-end.md](end-to-end.md) | Review live verification scope, observed outcomes, and evidence limits |
 | [getting-started.md](getting-started.md) | Install Verify, authenticate, and run a first script |
 | [api.md](api.md) | Look up session lifecycle, agent steps, screenshots, commands, files, and processes |
 | [configuration.md](configuration.md) | Look up every option in `verify.config.ts`, the environment variables, and the CLI |
 | [web.md](web.md) | Open a web app in a Revyl cloud browser |
 | [mobile.md](mobile.md) | Open an iOS or Android app on a Revyl cloud device |
-| [computers.md](computers.md) | Open a Mac computer for commands, files, processes, and screenshots |
-| [linux-computers-contract.md](linux-computers-contract.md) | Read the deferred Linux request/response contract and unconfirmed assumptions |
+| [computers.md](computers.md) | Open a Mac or Linux computer for commands, files, processes, screenshots, and optional recording metadata |
 | [ci.md](ci.md) | Call Verify from CI or from a test runner you already use |
 | [errors.md](errors.md) | Understand an error code and fix it |
 | [agents.md](agents.md) | Use Verify as a coding agent |

package/docs/agents.md

@@ -1,29 +1,34 @@
 # For coding agents
 
-This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that use Verify to check an app on a cloud browser/device or run commands and files on a Mac computer. The rest of this folder describes the API in full; this page is the workflow.
+This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that use Verify to check an app on a cloud browser/device or run commands and files on a Mac or Linux computer. The rest of this folder describes the API in full; this page is the workflow.
 
 ## Workflow
 
 1. Read `verify.config.ts` to learn the target names and their platforms. If there is none, run `npx @revyl/verify init --platform <web|ios|android> --app-id <id>`, or `npx @revyl/verify init --platform mac` without an app id. You can also pass a target object to `open()`.
-2. Check the credentials once with `npx verify whoami`. It starts no session.
+2. Check the credentials once with `npx @revyl/verify whoami`. It starts no session.
 3. Write a short script, or extend an existing one, that opens one target, runs the steps you need, and closes:
    ```ts
    import { open } from '@revyl/verify';
 
    const session = await open('ios');
-   await session.instruction('Sign in as the demo user');
-   await session.validation('The dashboard shows at least one project card');
-   await session.screenshot({ path: '.verify/dashboard.png' });
-   await session.close();
+   try {
+     await session.instruction('Sign in as the demo user');
+     await session.validation('The dashboard shows at least one project card');
+     await session.screenshot({ path: '.verify/dashboard.png' });
+   } finally {
+     await session.close();
+   }
    ```
 4. Run it with `node path/to/script.ts`. Share the session link from the first `[verify]` line with the user, so they can watch.
 5. Read the outcome from the exit code and stderr. Each step prints `✓` or `✗` with its text; a failure prints `CODE: message`, ending with the session link. Look at any screenshot you saved before changing the script or the app.
 
 ## Rules
 
-Mac computers are early access and not yet available in Revyl production. They work only on Revyl staging for enabled organizations through the optional `REVYL_BACKEND_URL` override with matching staging credentials. Read [availability and errors](computers.md#availability-and-errors) before starting a computer; do not try production or repeat an uncertain start/stop to probe availability.
+Mac and Linux computers are early access. Ask support@revyl.ai about access before starting a computer; do not repeat an uncertain start/stop to probe availability.
 
-For Mac work, use structured `exec(['program', 'arg'])`, `readFile`, `writeFile`, `stat`, and run-owned handles from `processes()`/`terminate(id)`. Check command output with ordinary assertions and close in `finally`; screenshots are supported, but instruction/validation are not. Do not fall back to agent steps on computers or shell/file methods on mobile/web. See [computers.md](computers.md) for limits and staging setup. Linux is a contract only: opening it fails before auth/network, so do not probe it with live calls. Starting a computer is a paid external action and needs the same approval as starting a device.
+For computer work, use structured `exec(['program', 'arg'])`, `readFile`, `writeFile`, `stat`, and run-owned handles from `processes()`/`terminate(id)`. Check command output with ordinary assertions and close in `finally`; screenshots are supported, but instruction/validation are not. Do not fall back to agent steps on computers or shell/file methods on mobile/web. See [computers.md](computers.md) for limits. Linux uses inline targets or config entries; Linux init is intentionally unavailable. Starting a computer is a paid external action and needs the same approval as starting a device.
+
+Computers have a hard 60-minute lifetime from create, not from readiness or activity. `expiresAt` is optional on older APIs; expiry does not prevent close. After terminal state and confirmed release, `recording()` can return private signed metadata or null, including after close. Never log or share its signed URL/query. Do not automatically wait for recordings or retry `COMPUTER_LIMIT` starts: queued work (including iOS) or the concurrency limit may be responsible.
 
 - Write steps the way you would brief a person: what to do, or what should be true, in one sentence. Name visible things ("the blue Save button in the footer"), not implementation details.
 - Use `instruction` for doing and `validation` for checking. Do not ask an instruction to check something, or a validation to change anything.
@@ -33,6 +38,6 @@ For Mac work, use structured `exec(['program', 'arg'])`, `readFile`, `writeFile`
 - Await each step. Two steps at once on one session throw `INVALID_ARGUMENT`.
 - Do not catch `VerifyError` to make a check pass. A `NOT_AVAILABLE_ON_PLATFORM` error means the call is not offered on that platform; see [web.md](web.md) and [computers.md](computers.md). A `STEP_FAILED` error means the step did not run to an outcome, not that the app is wrong.
 - Never automatically repeat a computer mutation after `ACTION_UNCERTAIN` or a timeout: the command may have run, and timeout does not prove termination or rollback. Do not log argv, stdin, file contents, or credentials.
-- Always close what you open. Each open session is a paid cloud browser, device, or computer.
+- Always close what you open in `try/finally`. Each open session is paid. Automatic cleanup is best effort with a 15-second bound and skips signal/error events that already have listeners. Device close acknowledges stop, while computer close requires confirmed terminal release.
 - Never put secrets in scripts or config. Credentials come from `REVYL_API_KEY` or a Revyl CLI login; web sign-in uses the **name** of a Revyl organization secret.
 - Step descriptions are sent to Revyl and logged to stderr by default. Do not include private credentials or customer data in instruction or validation text; use test-only sign-in and synthetic data instead. `log: false` suppresses local progress, not remote processing or reports.

package/docs/api.md

@@ -1,19 +1,22 @@
 # API
 
 ```ts
-import { open, defineConfig, VerifyError, isVerifyError } from '@revyl/verify';
+import { attach, open, defineConfig, VerifyError, isVerifyError } from '@revyl/verify';
 ```
 
 ## open(target, options?)
 
-Starts a Revyl cloud browser, device, or Mac computer and resolves with a `Session` once it is ready. Starting usually takes from a few seconds to a couple of minutes. Linux targets are accepted in config/types but opening them throws `NOT_AVAILABLE_ON_PLATFORM` before credentials or network access.
+Linux targets are supported **since 0.2.0**; 0.1.0 includes the target type but rejects Linux locally.
 
-Mac computers are early access on staging only for enabled organizations, not yet available in Revyl production. Use the optional `REVYL_BACKEND_URL` override and staging credentials described in [computer availability](computers.md#availability-and-errors).
+Starts a Revyl cloud browser, device, or Mac or Linux computer. Mobile first-screen readiness is [best-effort](mobile.md#steps), not a foreground/rendered-readiness guarantee. Computer starts retain a 10-minute default timeout; an unclaimed start may fail after 120 seconds with no-host context.
+
+Both computer operating systems are early access. Ask support@revyl.ai about access.
 
 ```ts
 const web = await open('web');                                       // a target named in verify.config.ts
 const ios = await open({ platform: 'ios', app: { appId: '…' } });    // or a target object, no config needed
 const mac = await open({ platform: 'mac' });                        // computer, no app needed
+const linux = await open({ platform: 'linux' });                    // same computer surface
 ```
 
 - `target`: a target name from `verify.config.ts`, or a target object with the same shape as a config entry (see [configuration.md](configuration.md)). Verify reads the nearest `verify.config.ts` at or above the current folder.
@@ -22,6 +25,68 @@ const mac = await open({ platform: 'mac' });                        // computer,
 
 `open` needs credentials: `REVYL_API_KEY` or a Revyl CLI login. It throws `AUTH_MISSING` without them, `CONFIG_NOT_FOUND` or `CONFIG_INVALID` for config problems, and `SESSION_START_FAILED` or `TIMEOUT` when the browser or device does not start.
 
+## Inside a revyl-macos GitHub Actions job
+
+`currentComputer(options?)` attaches to `REVYL_COMPUTER_ID` using normal credential resolution. It is non-owning by default: close cleans up hosted children, while the job's owner releases the computer. It never creates a computer and throws `COMPUTER_ID_MISSING` when the ID is unset or blank. Invalid IDs fail with `INVALID_ARGUMENT`.
+
+This helper is included in the TypeScript 0.3.0 release and requires a runner configured to inject `REVYL_COMPUTER_ID` and a short-lived `REVYL_API_KEY`. A workflow can supply its own `REVYL_API_KEY` instead. After installing the project dependencies and selecting Node.js ≥22.18, add this step to a job with `runs-on: revyl-macos`:
+
+```yaml
+- name: Run Verify
+  run: |
+    node --input-type=module <<'JS'
+    import { currentComputer } from '@revyl/verify';
+    const computer = await currentComputer();
+    try {
+      await computer.screenshot({ path: 'computer.png' });
+    } finally {
+      await computer.close();
+    }
+    JS
+```
+
+The helper accepts the same options as `attach`, including explicit `backendUrl` and `appUrl`; it does not read URL environment variables. `stopOnClose: true` explicitly takes ownership and can end the job's computer when closed. Use `computer.open(target)` with an exact app/build pair for hosted app sessions.
+
+## attach(computerId, options?)
+
+The attachment, hosted-child and navigation APIs below are included in the TypeScript 0.3.0 release.
+
+`open()` and `computer.open()` return the extended `OpenedSession` interface. The original `Session` interface keeps its existing required members, so applications implementing or mocking it do not need to add the new methods. Use `OpenedSession` when explicitly annotating a value that calls `report`, `navigate` or `open`.
+
+Attaches to an active Mac or Linux computer in your organization without creating a new one. `options.log` controls progress. The returned computer owns cleanup by default: `close()` stops it, and automatic cleanup also applies. Attaching requires a valid expiry and does not extend the lifetime. Invalid, inaccessible, inactive or expired computers fail without sending a stop request.
+
+When attaching to a computer you do not own, such as a CI runner, pass `attach(computerId, { stopOnClose: false })`. The attachment is not registered for automatic cleanup. Its `close()` still cancels pending child starts and gives hosted children the same five-second cleanup phase, but never stops the computer; its owner must release it. Child cleanup failures remain observable. This option is explicit and is never inferred from the environment.
+
+## computer.open(target)
+
+Starts a child app session inside this computer, returning the normal session API. It inherits the parent's authenticated client, logging and step timeout; callers cannot route a child to another backend. Both `target.app.appId` and `target.app.buildId` are required. Web accepts an existing external HTTPS build, plus optional viewport/sign-in settings; native builds use the computer's fixed device profile and accept no bundle, artifact or device override. Named targets and initial URL overrides are not supported here.
+
+Mac supports Web and iOS children. Linux supports Android and may support Web when its runtime advertises that capability; Linux Web currently has a runtime limitation, so do not rely on it without confirming availability. The server remains authoritative for access, capability and capacity. Children require and share the parent's known deadline. Closing a child leaves the parent running; closing the parent cancels pending starts and gives child cleanup at most five seconds total before requesting confirmed computer release. The parent stop also stops any remaining children, so a slow child cannot prevent that request. A failed child start never closes the parent.
+
+```ts
+const computer = await attach(existingComputerId, { log: false });
+try {
+  const web = await computer.open({
+    platform: 'web',
+    app: { appId: webAppId, buildId: externalBuildId },
+  });
+  await web.navigate('http://localhost:3000');
+  await web.validation('The home page is visible');
+} finally {
+  await computer.close();
+}
+```
+
+This requires an already-running service on the computer. The initial Web build still uses HTTPS; navigation after start can reach the computer's localhost. No localhost-start option is implied.
+
+## session.navigate(url)
+
+Web only, hosted or normal. Sends one deterministic `open_url` action and checks the returned navigation outcome. Accepts an HTTP(S) URL without credentials, whitespace, control characters or backslashes. Loopback addresses are accepted on every Web session: a hosted browser can reach its parent computer's loopback address; a normal cloud browser's localhost is its own runtime, not your machine. A cold development server may need a warm-up request before navigation succeeds; after an uncertain timeout, re-navigating is the caller's choice because the original request may still commit. The runtime is responsible for enforcing its navigation network policy. Navigation is not replayed by Verify and does not run an agent step. It resolves with no value, or throws a typed error. Computer and native sessions reject it locally.
+
+## session.report()
+
+Returns authenticated JSON metadata: `/execution/device-sessions/{id}` for normal and hosted app sessions, or the computer report for computers. It works after close, but fails locally with `NOT_FOUND` when no session ID is known. It does not download recordings or turn a device stop acknowledgment into proof of physical release. Treat returned metadata as private.
+
 ## session.instruction(text, options?)
 
 Available on web/iOS/Android only. Computers throw `NOT_AVAILABLE_ON_PLATFORM` without sending an agent request.
@@ -58,19 +123,27 @@ interface StepResult {
 
 `session.steps` lists every step run on the session, in order.
 
+When inspecting `revyl device report --session-id <id>`, read validation verdicts from the step's `effective_status` and `validation_result`, with `validations_passed` / `total_validations` for the validation summary. `passed_steps` / `failed_steps` and transport `status` are not enough: a successfully executed validation can have a false verdict. The SDK's `StepResult.passed` reflects that verdict, not just transport success.
+
 ## session.screenshot(options?)
 
 Resolves with a PNG of the screen as a `Uint8Array`. With `options.path`, also writes it there, creating folders as needed.
 
 ## session.close()
 
-Stops the session on Revyl. It is safe to call more than once, and steps after it throw `SESSION_ENDED`. A `Session` also works with `await using`, which closes it at the end of the block.
+Requests that Revyl stop the session. For web/mobile, success acknowledges the stop request rather than proving physical release. It is safe to call more than once, and steps after it throw `SESSION_ENDED`. A `Session` also works with `await using`, which closes it at the end of the block.
 
-For computers, cleanup must be confirmed; a terminal state alone does not prove physical release. Uncertain release throws `ACTION_UNCERTAIN`.
+For owning computers, cleanup must be confirmed; a terminal state alone does not prove physical release. Uncertain release throws `ACTION_UNCERTAIN`. A non-owning attachment closes its children and local handle without requesting computer release.
 
 ## Computer commands, files, and processes
 
-Mac sessions provide `exec(argv: string[], options?)`, `readFile(path, options?)` returning `Buffer`, `writeFile(path, string | Uint8Array, options?)`, `stat(path, options?)` returning `{ kind, size }`, `processes(options?)` returning `{ id, state, exitCode? }[]`, and `terminate(id, options?)`. They throw `NOT_AVAILABLE_ON_PLATFORM` on web/iOS/Android. See [computers.md](computers.md) for complete signatures, limits, timeouts, and examples. Mac also supports `screenshot()`; instruction/validation do not run on computers.
+Mac and Linux sessions provide `exec(argv: string[], options?)`, `readFile(path, options?)` returning `Buffer`, `writeFile(path, string | Uint8Array, options?)`, `stat(path, options?)` returning `{ kind, size }`, `processes(options?)` returning `{ id, state, exitCode? }[]`, and `terminate(id, options?)`. They throw `NOT_AVAILABLE_ON_PLATFORM` on web/iOS/Android. See [computers.md](computers.md) for complete signatures, limits, timeouts, and examples. Both support `screenshot()`; instruction/validation do not run on computers.
+
+### `session.recording(): Promise<ComputerRecording | null>`
+
+**Since 0.2.0.** This method is not available in 0.1.0.
+
+Computers only. First reads the report and requires terminal state plus confirmed release, otherwise throws `SESSION_BUSY`. Returns `{ url: string, durationSeconds?: number, startedAt?: Date }` or null for an unavailable recording. Nullable optional wire fields are omitted. This method works after `close()`, does not wait for upload, and does not download or fetch the URL. Keep the signed HTTPS URL and its query private. Request fresh metadata when the URL expires. The normal report has no recording URL. Devices reject this call locally with `NOT_AVAILABLE_ON_PLATFORM`.
 
 ## Other session properties
 
@@ -78,7 +151,8 @@ Mac sessions provide `exec(argv: string[], options?)`, `readFile(path, options?)
 | --- | --- |
 | `viewerUrl` | The session in Revyl: a live view while it runs, its recording/report after. Use `revyl device report --session-id <id>` for web/mobile, or `revyl computer report <id>` for computers. |
 | `id` | Revyl's session id |
-| `platform` | `'web'`, `'ios'`, `'android'`, `'mac'`, or the reserved `'linux'` type (opening Linux is unavailable) |
+| `platform` | `'web'`, `'ios'`, `'android'`, `'mac'`, or `'linux'` |
+| `expiresAt` | **Since 0.2.0.** Validated API expiry as a `Date`, or undefined for devices and older APIs. Computers have a hard 60-minute lifetime from create. Operations/screenshot observation are bounded by expiry; close and recording remain possible. |
 | `target` | The target name, or the platform for a target object |
 | `closed` | Whether `close()` was called |
 
@@ -91,13 +165,13 @@ Mac sessions provide `exec(argv: string[], options?)`, `readFile(path, options?)
 
 ## Cleanup
 
-While a session is open, Verify closes it before the process ends:
+While a session is open, Verify attempts best-effort cleanup with a 15-second budget:
 
-- on Ctrl+C or SIGTERM: it closes open sessions, then exits with 130 or 143 (a second Ctrl+C exits at once);
-- on an uncaught error, such as a failed validation that nothing catches: it prints the error, closes open sessions, then exits with 1;
-- when the script finishes without calling `close()`: it closes the sessions and prints a reminder.
+- on Ctrl+C or SIGTERM: it attempts to close open sessions, then exits with 130 or 143 (a second Ctrl+C exits at once);
+- on an uncaught error, such as a failed validation that nothing catches: it prints the error, attempts cleanup, then exits with 1;
+- when the script finishes without calling `close()`: it attempts cleanup and prints a reminder.
 
-Verify only takes over a signal or error event that nothing else in the process listens to, so test runners and apps that manage their own shutdown keep control of it; there, close sessions in `finally` or an `after` hook. A process that is killed outright, or calls `process.exit()` with sessions open, leaves browser/mobile sessions running until their idle timeout (10 minutes by default). Computers have a server-bounded one-hour lifetime instead; no idle timeout is configurable.
+Verify skips installing a signal or error handler when that event already has listeners, so test runners and apps that manage their own shutdown keep control of it. Always close in `try/finally` or an `after` hook; automatic cleanup cannot guarantee success. A process that is killed outright, or calls `process.exit()` with sessions open, leaves browser/mobile sessions running until their idle timeout (10 minutes by default). Computers have a server-bounded one-hour lifetime instead; no idle timeout is configurable.
 
 ## defineConfig(config)
 

package/docs/ci.md

@@ -1,6 +1,6 @@
 # CI and test runners
 
-Verify is a library, so it runs wherever your code runs. Browsers, devices, and computers run in Revyl's cloud, so the runner needs nothing but Node.js and an API key. A Mac target works from a Linux runner; no local macOS host is needed. Use the same staging URL overrides and organization enablement as [computers.md](computers.md).
+Verify is a library, so it runs wherever your code runs. Browsers, devices, and computers run in Revyl's cloud, so the runner needs Node.js and an API key. Install it with `npm install @revyl/verify`; in CI, `npm ci` and a `REVYL_API_KEY` secret are enough.
 
 ## A script in GitHub Actions