@runalabs/rill-cli 0.1.12 → 0.1.13

package/README.md

@@ -40,6 +40,17 @@ Do not use `npx rill`: the unscoped package belongs to a different product. Doct
 
 ## Authenticate
 
+### Connect with pollable approval
+
+`rill whoami` verifies the current account without starting sign-in. `rill connect --email you@example.com` waits for human approval by default. For agents that cannot hold a foreground command open:
+
+```sh
+rill connect --email you@example.com --no-wait
+rill connect status <authorization-id>
+```
+
+The first response contains `authorizationId`, `verificationUri`, `userCode`, `expiresAt`, `retryAfterSeconds`, and the exact `nextCommand`. The human opens the URL and approves their own request. Poll no faster than `retryAfterSeconds`; each status command returns once. States are `pending`, `authenticated` (approved and credentials saved), `expired`, or `denied` (including revoked claims). Expired and denied status commands exit 1. Pending state and polling backoff survive process exit in the OS credential store; claim/access tokens are never returned. Repeating connect with the same email resumes an unexpired pending request. Only the latest authorization ID for that API URL can be polled.
+
 ### Interactive login
 
 `rill login` prints a verification URL and device code. Open the URL, sign in, and approve the request. The CLI waits for approval and stores the credential in macOS Keychain or Linux Secret Service using `secret-tool`. Linux needs an available Secret Service keyring; use token authentication on headless machines without one.
@@ -66,6 +77,8 @@ New browser recordings include a visible cursor and click pulses by default. In
 
 ### Connect Playwright
 
+Start also returns `browserAttachment` with the CDP endpoint, protocol, Playwright method, and attachment instructions. Browser tools must explicitly support attaching to that endpoint; Rill does not automatically expose its browser to every tool.
+
 In a project with `playwright-core` installed, save this as `rill-run.mjs`:
 
 ```js
@@ -86,6 +99,31 @@ try {
 
 Run `node rill-run.mjs "<cdpUrl>"` with the exact endpoint from start. Then run `rill record stop <recording-id>`, including when your verification fails. A page title alone does not verify your app's behavior.
 
+For a shell-only macOS/Linux agent with no project Playwright dependency, use a temporary directory. This installs the automation client without changing the project's manifest or launching another browser:
+
+```sh
+rill_automation_dir=$(mktemp -d)
+npm install --prefix "$rill_automation_dir" --no-save --package-lock=false playwright-core
+cat > "$rill_automation_dir/run.mjs" <<'JS'
+import { chromium } from 'playwright-core';
+const browser = await chromium.connectOverCDP(process.argv[2]);
+try {
+  const page = browser.contexts()[0]?.pages()[0];
+  if (!page) throw new Error('The recorded page is unavailable.');
+  await page.waitForLoadState('domcontentloaded');
+  // Add the agreed interactions and assertions on this page.
+  console.log(await page.title());
+} finally {
+  await browser.close(); // Disconnect this CDP client; preserve the recorded browser.
+}
+JS
+node "$rill_automation_dir/run.mjs" "<cdpUrl>"
+rill record stop <recording-id> --no-wait
+rill record status <recording-id>
+```
+
+Replace the placeholders with start's actual values. This snippet verifies attachment only until you add your flow assertions. Keep the directory for retries and remove it when finished. Playwright documents the [connected-browser disconnect behavior](https://playwright.dev/docs/api/class-browser#browser-close).
+
 Capture follows the first page selected at recording start. Keep the flow in that page: new tabs and popups do not receive complete video and diagnostic coverage. Keep the recorded page open until Rill stops.
 
 ### Recording options
@@ -145,10 +183,13 @@ Use `rill --help` or `<command> --help` for supported flags.
 | Command | Behavior |
 | --- | --- |
 | `rill login` | Authorize a device code and store a credential. |
+| `rill whoami` | Verify the saved identity and account email. |
+| `rill connect --email <email> [--no-wait]` | Start or resume account approval. |
+| `rill connect status <authorization-id>` | Poll a saved approval once; obey `retryAfterSeconds`. |
 | `rill doctor` | Check prerequisites, API compatibility, and authentication. |
 | `rill record start [options]` | Start a managed or attached browser recording. |
 | `rill record stop <recording-id>` | Finalize and upload; supports `--no-wait` and `--no-feedback`. |
-| `rill record status <recording-id>` | Read the remote encoding job first; otherwise check local capture state with a remote fallback. |
+| `rill record status <recording-id>` | Read remote state first, then local capture for unsubmitted recordings; local completion is `captured`. |
 | `rill record retry <recording-id>` | Resume a retained remote capture or retry a failed encode; supports `--no-wait`. |
 | `rill record cancel <recording-id>` | Abandon a run created by this credential and release its remote quota reservation. |
 | `rill upload <video-file>` | Upload video-only evidence; supports `--title` and `--no-wait`. |
@@ -182,14 +223,18 @@ Success exits 0; command failures exit 1. Runtime failures emit an `error` objec
 
 Check the exit status first, then structured fields. Known codes include `authentication_required`, `scope_denied`, `quota_exceeded`, `browser_unavailable`, `recording_not_found`, `upload_interrupted`, `processing_failed`, `share_revoked`, `validation_failed`, and the fallback `internal_error`. Not every failure has a specific code; avoid branching on message text.
 
+Lifecycle recovery also distinguishes `unsupported_platform`, `processing_pending`, `authorization_not_found`, `expired_token`, and `access_denied`. An elapsed playback wait is pending, while a confirmed remote failure remains `processing_failed`.
+
 ## Recovery and troubleshooting
 
 - **Doctor fails:** read the failed check's recovery field. Correct the credential, API connectivity, or executable path before recording.
-- **Quota exceeded:** inspect `error.details.quota.type` and `blockingRecordingId` when present. Check the blocking recording; cancel only an abandoned run. Review storage and daily allowance in Billing.
+- **Quota exceeded:** inspect `error.details.quota.type` and `blockingRecordingId` when present. Uploading and processing recordings still hold the concurrency slot. Run the returned status command and wait for `ready`; if it reports `captured`, run its stop command to upload. Cancel only an abandoned run. Review storage and daily allowance in Billing.
 - **Remote upload interrupted or encoding failed:** keep the recording ID and local capture files. Run `rill record status <recording-id>`, then `rill record retry <recording-id>` with the original credential before capture expiry. Retry resumes accepted chunks or requeues the encode without repeating browser actions. A `ready` result needs a share URL before you return it as evidence.
-- **Duration limit reached:** local capture finalizes automatically, but `record stop` is still needed to upload.
+- **Duration limit reached:** local capture finalizes automatically. Status reports `captured`, `source: "local"`, and the exact `nextCommand` to upload. It is not a playable share. Run `record stop <recording-id> --no-wait`, then poll status.
+- **Upload reached 100%:** transfer has finished; encoding/playback processing may continue. `--no-wait` returns after submission with a status command. A polling timeout reports `processing_pending`, not a confirmed processing failure.
+- **Windows:** doctor reports `recorder_transport` failure, and local record start rejects before reserving a recording. Use macOS/Linux for browser recording. Windows can use `RILL_TOKEN` with video-only `upload`; setting `RILL_SOCKET` does not add named-pipe/TCP support.
 - **Terminal closed:** after upload acceptance, the server finishes independently; retrieve the result with `record status`. Before acceptance, retry from the original machine while its captured frames remain available.
-- **Local session missing:** `record status` checks for a remote encoding job before falling back to local or remote recording state. `drafts list` locates local directories, which may be incomplete. There is no `drafts resume` command.
+- **Local session missing:** `record status` checks remote encoding and recording state. Remote processing/completion takes precedence over retained local artifacts. For captures not submitted, it checks the local recorder. Remote authorization/network errors are surfaced rather than being masked by local readiness. `drafts list` locates local directories, which may be incomplete. There is no `drafts resume` command.
 - **Share cannot be inspected:** open the complete URL in a browser; ask the owner for a current link if needed.
 
 A failed local startup automatically attempts to cancel the remote reservation it just created. `record cancel` changes remote state and does not stop the local browser; finish local capture before abandoning the remote reservation.

package/dist/cli.js

@@ -10,6 +10,37 @@ import { hostname, homedir } from "os";
 import { mkdir, rm, stat } from "fs/promises";
 import { join } from "path";
 import { createHash, randomBytes } from "crypto";
+
+// src/recording-guidance.ts
+function cliCommand(apiUrl, ...args) {
+  const quote = (value) => /^[a-zA-Z0-9_./:@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+  return ["rill", "--api-url", apiUrl, ...args].map(quote).join(" ");
+}
+var transportRecovery = "Use macOS or Linux for browser recording. On Windows, use RILL_TOKEN with rill upload <video-file> for video-only sharing; diagnostics are not imported. RILL_SOCKET does not enable Windows named-pipe or TCP support in this release.";
+function recorderTransportCheck(platform = process.platform) {
+  return platform === "win32" ? { name: "recorder_transport", status: "fail", message: "The local recorder transport does not support Windows.", recovery: transportRecovery } : { name: "recorder_transport", status: "pass", message: "The local recorder uses a Unix-domain socket." };
+}
+function assertRecorderTransport(platform = process.platform) {
+  const check2 = recorderTransportCheck(platform);
+  if (check2.status === "fail") throw Object.assign(new Error(`unsupported_platform: ${check2.message}`), { code: "unsupported_platform", recovery: check2.recovery });
+}
+function recordingNextStep(apiUrl, recordingId, status, options = {}) {
+  if (status === "uploading" && options.resumableFrames) return { nextCommand: cliCommand(apiUrl, "record", "retry", recordingId, "--no-wait"), message: "Frame upload is incomplete. If the uploader is still running, let it finish. If it exited or was interrupted, run nextCommand to resume missing parts and finalize the upload. Do not start a second uploader while the first is active." };
+  if (status === "captured") return { nextCommand: cliCommand(apiUrl, "record", "stop", recordingId, "--no-wait"), message: "Captured locally; upload required. This is not a playable share yet." };
+  if (["uploading", "queued", "encoding", "processing", "finalizing"].includes(status)) return { nextCommand: cliCommand(apiUrl, "record", "status", recordingId), message: "Finalizing recordings hold a concurrency slot. Wait for ready; cancel only if abandoning the recording." };
+  return {};
+}
+function browserAttachment(cdpUrl) {
+  return {
+    protocol: "cdp",
+    cdpUrl,
+    playwrightMethod: "chromium.connectOverCDP",
+    instructions: "Attach to this endpoint and use the existing browser context. A browser tool must explicitly support CDP attachment; do not drive a separate browser. Disconnect the automation client without closing the recorded browser, then run record stop.",
+    shellFallback: "See the shell-only Playwright example in the Rill CLI README; install playwright-core in a temporary directory outside the project."
+  };
+}
+
+// src/agent-session.ts
 var JWT_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
 var CLAIM_GRANT = "urn:workos:agent-auth:grant-type:claim";
 var AgentAuthError = class extends Error {
@@ -52,17 +83,7 @@ async function loadAgentCredential(apiUrl) {
   if (process.env.RILL_TOKEN) return process.env.RILL_TOKEN;
   const inFlight = pending.get(apiUrl);
   if (inFlight) return inFlight;
-  const promise2 = (async () => {
-    const raw = await loadStoredCredential(apiUrl);
-    const saved = parseAuthorization(raw);
-    if (!saved) return raw;
-    if (saved.accessToken && (saved.accessExpiresAt ?? 0) > Date.now() + 6e4) return saved.accessToken;
-    if (!saved.identityAssertion && saved.anonymous && saved.registrationToken) return null;
-    if (!saved.identityAssertion) throw new Error("Connection is awaiting approval. Run rill connect --email <your-email>.");
-    const tokens = await request(apiUrl, "/oauth2/token", { grant_type: JWT_GRANT, assertion: saved.identityAssertion }, true);
-    await save(apiUrl, withTokens(saved, tokens));
-    return tokens.access_token;
-  })();
+  const promise2 = withAuthorizationLock(apiUrl, () => readAgentCredential(apiUrl));
   pending.set(apiUrl, promise2);
   try {
     return await promise2;
@@ -70,7 +91,22 @@ async function loadAgentCredential(apiUrl) {
     pending.delete(apiUrl);
   }
 }
+async function readAgentCredential(apiUrl) {
+  if (process.env.RILL_TOKEN) return process.env.RILL_TOKEN;
+  const raw = await loadStoredCredential(apiUrl);
+  const saved = parseAuthorization(raw);
+  if (!saved) return raw;
+  if (saved.accessToken && (saved.accessExpiresAt ?? 0) > Date.now() + 6e4) return saved.accessToken;
+  if (!saved.identityAssertion && saved.anonymous && saved.registrationToken) return null;
+  if (!saved.identityAssertion) throw new Error(saved.connection ? `Connection is ${saved.connection.status}. Run ${cliCommand(apiUrl, "connect", "status", saved.connection.id)}.` : "Connection is awaiting approval. Run rill connect --email <your-email>.");
+  const tokens = await request(apiUrl, "/oauth2/token", { grant_type: JWT_GRANT, assertion: saved.identityAssertion }, true);
+  await save(apiUrl, withTokens(saved, tokens));
+  return tokens.access_token;
+}
 async function ensureAnonymousCredential(apiUrl) {
+  return withAuthorizationLock(apiUrl, () => createAnonymousCredential(apiUrl));
+}
+async function withAuthorizationLock(apiUrl, action) {
   const root = join(homedir(), ".rill", "auth-locks");
   await mkdir(root, { recursive: true, mode: 448 });
   const lock = join(root, createHash("sha256").update(apiUrl).digest("hex"));
@@ -91,13 +127,13 @@ async function ensureAnonymousCredential(apiUrl) {
     }
   }
   try {
-    return await createAnonymousCredential(apiUrl);
+    return await action();
   } finally {
     await rm(lock, { recursive: true, force: true });
   }
 }
 async function createAnonymousCredential(apiUrl) {
-  const existing = await loadAgentCredential(apiUrl);
+  const existing = await readAgentCredential(apiUrl);
   if (existing) return existing;
   const stored = parseAuthorization(await loadStoredCredential(apiUrl));
   const initial = stored?.registrationToken ? stored : { version: 1, anonymous: true, registrationToken: randomBytes(32).toString("hex") };
@@ -106,11 +142,29 @@ async function createAnonymousCredential(apiUrl) {
   const saved = { ...initial, registrationToken: void 0, identityAssertion: registered.identity_assertion, assertionExpires: registered.assertion_expires, claimToken: registered.claim_token };
   await save(apiUrl, saved);
   process.stderr.write("Recording anonymously: three recordings, up to five minutes each. Recordings and share links expire after seven days. Run rill connect --email <your-email> to keep them.\n");
-  return await loadAgentCredential(apiUrl);
+  return await readAgentCredential(apiUrl);
+}
+async function connectAgent(apiUrl, email3, options = {}) {
+  let result = await withAuthorizationLock(apiUrl, () => beginConnection(apiUrl, email3));
+  if (options.wait === false) return result;
+  while (result.status === "pending") {
+    await new Promise((resolve) => setTimeout(resolve, result.retryAfterSeconds * 1e3));
+    result = await pollConnection(apiUrl, result.authorizationId);
+  }
+  if (result.status === "expired") throw new AgentAuthError("expired_token", "Connection request expired. Run rill connect again using the same saved identity.");
+  if (result.status === "denied") throw new AgentAuthError("access_denied", "Connection request was denied or revoked. Run rill connect again only when ready to request approval.");
+  return result;
 }
-async function connectAgent(apiUrl, email3) {
+async function beginConnection(apiUrl, email3) {
   if (process.env.RILL_TOKEN) throw new Error("Unset RILL_TOKEN before connecting a local identity.");
   let saved = parseAuthorization(await loadStoredCredential(apiUrl));
+  if (saved?.connection?.status === "pending" && saved.connection.expiresAt > Date.now()) {
+    if (saved.connection.email !== email3) throw new Error("A connection for another email is pending. Let it expire before starting a different connection.");
+    process.stderr.write(`Open ${saved.connection.verificationUri}
+Sign in as ${email3} and enter ${saved.connection.userCode}. Approve only the request you started.
+`);
+    return connectionView(apiUrl, saved);
+  }
   let claim;
   if (saved?.claimToken && saved.anonymous) {
     try {
@@ -130,26 +184,65 @@ async function connectAgent(apiUrl, email3) {
   process.stderr.write(`Open ${claim.verification_uri}
 Sign in as ${email3} and enter ${claim.user_code}. Approve only the request you started.
 `);
-  const deadline = Date.now() + claim.expires_in * 1e3;
-  let interval = claim.interval;
-  while (Date.now() < deadline) {
-    await new Promise((resolve) => setTimeout(resolve, interval * 1e3));
-    try {
-      const tokens = await request(apiUrl, "/oauth2/token", { grant_type: CLAIM_GRANT, claim_token: saved.claimToken }, true);
-      const connected = withTokens({ version: 1, anonymous: false }, tokens);
-      await save(apiUrl, connected);
-      return { status: "authenticated", expiresAt: connected.assertionExpires, apiUrl };
-    } catch (error51) {
-      if (error51 instanceof AgentAuthError && error51.code === "expired_token") throw new AgentAuthError("expired_token", "The approval attempt expired. Run rill connect again to request a fresh code using the same saved claim token.");
-      if (error51 instanceof AgentAuthError && error51.code === "authorization_pending") continue;
-      if (error51 instanceof AgentAuthError && error51.code === "slow_down") {
-        interval += 5;
-        continue;
-      }
-      throw error51;
-    }
+  saved = { ...saved, connection: {
+    id: randomBytes(16).toString("hex"),
+    email: email3,
+    verificationUri: claim.verification_uri,
+    userCode: claim.user_code,
+    expiresAt: Date.now() + claim.expires_in * 1e3,
+    interval: claim.interval,
+    nextPollAt: Date.now() + claim.interval * 1e3,
+    status: "pending"
+  } };
+  await save(apiUrl, saved);
+  return connectionView(apiUrl, saved);
+}
+function connectionView(apiUrl, saved) {
+  const connection = saved.connection;
+  return {
+    status: connection.status,
+    authorizationId: connection.id,
+    apiUrl,
+    expiresAt: connection.status === "authenticated" ? saved.assertionExpires : new Date(connection.expiresAt).toISOString(),
+    retryAfterSeconds: connection.status === "pending" ? Math.max(0, Math.ceil((connection.nextPollAt - Date.now()) / 1e3)) : 0,
+    ...connection.status === "pending" ? {
+      verificationUri: connection.verificationUri,
+      userCode: connection.userCode,
+      nextCommand: cliCommand(apiUrl, "connect", "status", connection.id)
+    } : connection.status === "authenticated" ? {} : { nextCommand: cliCommand(apiUrl, "connect", "--email", connection.email) }
+  };
+}
+async function pollConnection(apiUrl, authorizationId) {
+  return withAuthorizationLock(apiUrl, () => pollSavedConnection(apiUrl, authorizationId));
+}
+async function pollSavedConnection(apiUrl, authorizationId) {
+  if (process.env.RILL_TOKEN) throw new Error("Unset RILL_TOKEN before polling a local connection.");
+  let saved = parseAuthorization(await loadStoredCredential(apiUrl));
+  if (!saved?.connection || saved.connection.id !== authorizationId) throw new AgentAuthError("authorization_not_found", "No matching saved connection for this API URL. Use the latest connect response.");
+  const connection = saved.connection;
+  if (connection.status !== "pending") return connectionView(apiUrl, saved);
+  if (Date.now() >= connection.expiresAt) {
+    connection.status = "expired";
+    await save(apiUrl, saved);
+    return connectionView(apiUrl, saved);
+  }
+  if (Date.now() < connection.nextPollAt) return connectionView(apiUrl, saved);
+  connection.nextPollAt = Date.now() + connection.interval * 1e3;
+  await save(apiUrl, saved);
+  try {
+    const tokens = await request(apiUrl, "/oauth2/token", { grant_type: CLAIM_GRANT, claim_token: saved.claimToken }, true);
+    saved = withTokens({ version: 1, anonymous: false, connection: { ...connection, status: "authenticated", userCode: "" } }, tokens);
+  } catch (error51) {
+    if (!(error51 instanceof AgentAuthError)) throw error51;
+    if (error51.code === "expired_token" || error51.code === "claim_expired") connection.status = "expired";
+    else if (error51.code === "access_denied" || error51.code === "claim_revoked") connection.status = "denied";
+    else if (error51.code === "slow_down") {
+      connection.interval += 5;
+      connection.nextPollAt = Date.now() + connection.interval * 1e3;
+    } else if (error51.code !== "authorization_pending") throw error51;
   }
-  throw new AgentAuthError("expired_token", "Connection request expired. Run rill connect again to restart the approval attempt using the same saved claim token.");
+  await save(apiUrl, saved);
+  return connectionView(apiUrl, saved);
 }
 
 // src/keychain.ts
@@ -221,6 +314,9 @@ var ControlPlaneClient = class {
     this.apiUrl = apiUrl;
     this.token = token;
   }
+  recordingStatusCommand(id) {
+    return cliCommand(this.apiUrl, "record", "status", id);
+  }
   encodingCapabilities() {
     return this.request("/api/encoding/capabilities");
   }
@@ -299,17 +395,18 @@ var ControlPlaneClient = class {
         return { ...recording, shareUrl: new URL(recording.shareUrl, this.apiUrl).toString() };
       }
       if (recording.status === "failed") throw new Error(`processing_failed: ${recording.failure_message ?? "Cloudflare Stream could not process the recording."}`);
-      process.stderr.write(`\rprocessing ${recording.status.padEnd(12)}`);
+      process.stderr.write("\rUpload complete; waiting for playable video.          ");
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
       intervalMs = Math.min(5e3, Math.round(intervalMs * 1.4));
     }
-    throw new Error("processing_failed: Timed out waiting for the recording to become playable. Run `rill record status <recording-id>` to continue checking.");
+    throw new ControlPlaneError("processing_pending", "Upload complete; the recording is not playable yet.", `Run ${cliCommand(this.apiUrl, "record", "status", recordingId)} to continue checking.`, { recordingId, nextCommand: cliCommand(this.apiUrl, "record", "status", recordingId) });
   }
   async uploadVideo(uploadUrl, filePath) {
     const file2 = await stat2(filePath);
     if (uploadUrl.startsWith(this.apiUrl)) {
       const response = await fetch(uploadUrl, { method: "PUT", headers: { "Content-Length": String(file2.size) }, body: createReadStream(filePath), duplex: "half" });
       if (!response.ok) throw new Error(`Video upload failed (${response.status}).`);
+      process.stderr.write("Upload complete; playback processing may continue.\n");
       return;
     }
     await new Promise((resolve, reject) => {
@@ -324,7 +421,7 @@ var ControlPlaneClient = class {
       });
       upload.start();
     });
-    process.stderr.write("\n");
+    process.stderr.write("\nUpload complete; playback processing may continue.\n");
   }
   async uploadDiagnostics(recordingId, filePath, summary) {
     const body = await readFile(filePath);
@@ -339,16 +436,29 @@ var ControlPlaneClient = class {
   pollDeviceAuthorization(deviceCode) {
     return this.request("/api/device/token", { method: "POST", body: JSON.stringify({ deviceCode }) }, false);
   }
-  inspect(shareUrl) {
+  inspect(shareUrl, cursor) {
     if (/^rec_[a-zA-Z0-9_-]+$/.test(shareUrl)) return this.request(`/api/recordings/${encodeURIComponent(shareUrl)}`);
     const url2 = new URL(shareUrl);
     const slug = url2.pathname.split("/").filter(Boolean).at(-1);
     if (!slug) throw new Error("The share URL does not contain a slug.");
-    return fetch(`${url2.origin}/api/public/shares/${encodeURIComponent(slug)}/context`, { headers: { Accept: "application/json" } }).then(async (response) => {
+    return fetch(`${url2.origin}/api/public/shares/${encodeURIComponent(slug)}/context${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`, { headers: { Accept: "application/json" } }).then(async (response) => {
       if (!response.ok) throw new Error(`Could not inspect the share link (${response.status}).`);
       return response.json();
     });
   }
+  reviewPath(shareUrl) {
+    const url2 = new URL(shareUrl);
+    if (url2.origin !== new URL(this.apiUrl).origin) throw new Error("The share URL must match --api-url before sending agent credentials.");
+    const match = /^\/s\/([^/]+)\/?$/.exec(url2.pathname);
+    if (!match) throw new Error("Expected a Rill /s/<slug> review link.");
+    return `/api/review/shares/${encodeURIComponent(decodeURIComponent(match[1]))}`;
+  }
+  reply(shareUrl, discussionId, body, requestId) {
+    return this.request(`${this.reviewPath(shareUrl)}/discussions/${encodeURIComponent(discussionId)}/replies`, { method: "POST", body: JSON.stringify({ body, requestId }) });
+  }
+  editReply(shareUrl, commentId, body) {
+    return this.request(`${this.reviewPath(shareUrl)}/comments/${encodeURIComponent(commentId)}`, { method: "PATCH", body: JSON.stringify({ body }) });
+  }
   async request(path, init = {}, authenticated = true) {
     const headers = new Headers(init.headers);
     if (init.body && !headers.has("Content-Type")) headers.set("Content-Type", "application/json");
@@ -360,7 +470,11 @@ var ControlPlaneClient = class {
     const response = await fetch(`${this.apiUrl}${path}`, { ...init, headers });
     const value = await response.json().catch(() => null);
     if (!response.ok && value?.error?.code && value.error.message) {
-      throw new ControlPlaneError(value.error.code, value.error.message, value.error.recovery, value.error.details, response.status);
+      const quota = value.error.details?.quota;
+      const blockingId = quota?.blockingRecordingId;
+      const concurrency = quota?.type === "credential_concurrency" || quota?.type === "workspace_concurrency";
+      const recovery = value.error.code === "quota_exceeded" && concurrency && blockingId ? `Run ${cliCommand(this.apiUrl, "record", "status", blockingId)}. Uploading and processing recordings hold a concurrency slot: wait for ready. If captured locally, run record stop to upload. Cancel only an abandoned recording.` : value.error.recovery;
+      throw new ControlPlaneError(value.error.code, value.error.message, recovery, value.error.details, response.status);
     }
     if (!response.ok) throw new ControlPlaneHttpError(response.status);
     return value;
@@ -14963,6 +15077,7 @@ async function submitFrameCapture(client, id, directory) {
   } finally {
     await file2.close();
   }
+  process.stderr.write("\nFrame upload complete; submitting for encoding.\n");
   return client.completeEncoding(id);
 }
 async function waitForEncoding(client, id, timeoutMs = 30 * 6e4) {
@@ -14974,7 +15089,7 @@ async function waitForEncoding(client, id, timeoutMs = 30 * 6e4) {
     process.stderr.write(`\r${status.status.padEnd(20)}`);
     await new Promise((r) => setTimeout(r, 2e3));
   }
-  throw new Error(`Encoding continues remotely. Check rill record status ${id}.`);
+  throw new ControlPlaneError("processing_pending", "Encoding continues remotely.", `Run ${client.recordingStatusCommand(id)}.`, { recordingId: id, nextCommand: client.recordingStatusCommand(id) });
 }
 
 // src/cli.ts
@@ -15910,7 +16025,7 @@ function emit(value, pretty = false) {
 function failureValue(error51) {
   const message = error51 instanceof Error ? error51.message : String(error51);
   const [candidate] = message.split(":", 1);
-  const knownCodes = /* @__PURE__ */ new Set(["authentication_required", "scope_denied", "quota_exceeded", "browser_unavailable", "recording_not_found", "upload_interrupted", "processing_failed", "share_revoked", "validation_failed"]);
+  const knownCodes = /* @__PURE__ */ new Set(["authentication_required", "authorization_not_found", "expired_token", "access_denied", "unsupported_platform", "scope_denied", "quota_exceeded", "browser_unavailable", "recording_not_found", "upload_interrupted", "processing_pending", "processing_failed", "share_revoked", "validation_failed"]);
   const structured = error51 && typeof error51 === "object" ? error51 : {};
   const code = structured.code && knownCodes.has(structured.code) ? structured.code : knownCodes.has(candidate) ? candidate : "internal_error";
   return { error: { code, message, ...structured.recovery ? { recovery: structured.recovery } : {}, ...structured.details ? { details: structured.details } : {} } };
@@ -15986,6 +16101,7 @@ var CLI_VERSION = packageJson.version;
 
 // src/doctor.ts
 var defaultDependencies = {
+  platform: process.platform,
   encoding: "remote",
   encodingCapabilities: (apiUrl, token) => new ControlPlaneClient(apiUrl, token).encodingCapabilities(),
   nodeVersion: process.version,
@@ -16001,6 +16117,7 @@ async function runDoctor(apiUrl, overrides = {}) {
   const dependencies = { ...defaultDependencies, ...overrides };
   const checks = [];
   let feedbackEnabled = false;
+  checks.push(recorderTransportCheck(dependencies.platform));
   if (compareVersions(normalizeVersion(dependencies.nodeVersion), "22.0.0") >= 0) {
     checks.push({ name: "node", status: "pass", message: `Node.js ${dependencies.nodeVersion} is supported.`, version: dependencies.nodeVersion });
   } else {
@@ -16028,8 +16145,16 @@ async function runDoctor(apiUrl, overrides = {}) {
   if (!health) {
     checks.push({ name: "authentication", status: "skip", message: "Authentication was not checked because the API is unreachable.", recovery: `Restore API reachability, then run \`rill --api-url ${apiUrl} doctor\` again.` });
   } else {
-    const token = await dependencies.loadCredential(apiUrl);
-    if (!token) {
+    let token = null;
+    let credentialError;
+    try {
+      token = await dependencies.loadCredential(apiUrl);
+    } catch (error51) {
+      credentialError = error51;
+    }
+    if (credentialError) {
+      checks.push({ name: "authentication", status: "fail", message: errorMessage(credentialError), recovery: "Unlock the OS credential store, or use RILL_TOKEN. Windows local recording remains unsupported." });
+    } else if (!token) {
       checks.push({ name: "authentication", status: health.anonymousAccess ? "warn" : "fail", message: health.anonymousAccess ? "The first recording will create an anonymous identity in your OS credential store. Anonymous recordings expire after seven days." : "No Rill agent credential is available.", recovery: `Run \`rill --api-url ${apiUrl} login\` or set RILL_TOKEN.` });
     } else {
       try {
@@ -16142,16 +16267,21 @@ async function startRecordingWithCompensation(remote, dependencies) {
     throw startupError;
   }
 }
-async function remoteAwareRecordingStatus(recordingId, dependencies) {
+async function remoteAwareRecordingStatus(recordingId, dependencies, apiUrl = "https://userill.dev") {
+  const remote = await dependencies.remoteStatus(recordingId);
+  const remoteView = {
+    ...remote,
+    recordingId: typeof remote.recordingId === "string" ? remote.recordingId : remote.id ?? recordingId,
+    source: "remote",
+    ...recordingNextStep(apiUrl, recordingId, String(remote.status))
+  };
+  if (["uploading", "processing", "ready", "failed", "expired", "cancelled"].includes(String(remote.status))) return remoteView;
   try {
-    return { ...await dependencies.localStatus(recordingId), source: "local" };
+    const local = await dependencies.localStatus(recordingId);
+    const status = local.status === "ready" ? "captured" : local.status;
+    return { ...local, status, source: "local", ...recordingNextStep(apiUrl, recordingId, String(status)) };
   } catch {
-    const remote = await dependencies.remoteStatus(recordingId);
-    return {
-      ...remote,
-      recordingId: typeof remote.recordingId === "string" ? remote.recordingId : remote.id ?? recordingId,
-      source: "remote"
-    };
+    return remoteView;
   }
 }
 
@@ -16211,9 +16341,16 @@ program.command("whoami").description("Show the current verified agent identity
   emit(identity, options.pretty);
   if (!identity.authenticated) process.exitCode = 1;
 });
-program.command("connect").description("Connect this agent once, with renewable account access.").requiredOption("--email <email>", "Email of the Rill account approving access").action(async (input) => {
+var connect = program.command("connect").description("Connect this agent once, with renewable account access.").option("--email <email>", "Email of the Rill account approving access").option("--no-wait", "Return approval instructions immediately; poll with connect status").action(async (input) => {
+  if (!input.email) throw new Error("validation_failed: Supply --email <email> to start a connection.");
   const options = program.opts();
-  emit({ schemaVersion: 1, ...await connectAgent(options.apiUrl, input.email) }, options.pretty);
+  emit({ schemaVersion: 1, ...await connectAgent(options.apiUrl, input.email, { wait: input.wait }) }, options.pretty);
+});
+connect.command("status").argument("<authorization-id>").description("Poll a saved connection once without starting another approval.").action(async (id) => {
+  const options = program.opts();
+  const result = await pollConnection(options.apiUrl, id);
+  emit({ schemaVersion: 1, ...result }, options.pretty);
+  if (result.status === "expired" || result.status === "denied") process.exitCode = 1;
 });
 program.command("login").description("Authorize Rill using the existing device login flow.").action(async () => {
   await authorize();
@@ -16252,6 +16389,7 @@ for (const action of ["status", "cancel"]) cloudRun.command(action).argument("<r
 });
 record2.command("start").option("--encoding <mode>", "remote or local", "remote").option("--url <url>").option("--title <title>").option("--description <description>", "").option("--headed").option("--cdp-url <url>").option("--width <pixels>", "", "1280").option("--height <pixels>", "", "720").option("--max-duration <seconds>", "", "600").action(async (commandOptions) => {
   const options = program.opts();
+  assertRecorderTransport();
   await ensureAnonymousCredential(options.apiUrl);
   const client = new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl));
   const result = await withRunFeedback(() => client.agentSession(), async (rememberRecording) => {
@@ -16276,7 +16414,7 @@ record2.command("start").option("--encoding <mode>", "remote or local", "remote"
       headed: Boolean(commandOptions.headed),
       attached: Boolean(commandOptions.cdpUrl)
     }).catch(() => void 0);
-    return { schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, bodyCaptureEnabled: remote.bodyCaptureEnabled, anonymous: remote.anonymous ?? false, expiresAt: remote.expiresAt ?? null, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600) };
+    return { schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, browserAttachment: browserAttachment(local.cdpUrl), bodyCaptureEnabled: remote.bodyCaptureEnabled, anonymous: remote.anonymous ?? false, expiresAt: remote.expiresAt ?? null, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600) };
   });
   emit(result, options.pretty);
 });
@@ -16296,7 +16434,7 @@ record2.command("stop").argument("<recording-id>").option("--no-wait").option("-
     await client.uploadDiagnostics(recordingId, local.result.diagnosticsPath, local.result.diagnostics);
     const accepted = await submitFrameCapture(client, recordingId, local.result.frameDirectory);
     const result2 = commandOptions.wait && record2.opts().wait !== false ? await waitForEncoding(client, recordingId) : accepted;
-    emit({ schemaVersion: 1, ...result2, ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false) }, options.pretty);
+    emit({ schemaVersion: 1, ...result2, ...recordingNextStep(options.apiUrl, recordingId, result2.status, { resumableFrames: true }), ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false) }, options.pretty);
     if (result2.status === "ready") await rm5(dirname2(local.result.videoPath), { recursive: true, force: true });
     else watchEncoding(options.apiUrl, recordingId);
     return;
@@ -16315,6 +16453,7 @@ record2.command("stop").argument("<recording-id>").option("--no-wait").option("-
     durationSeconds: local.result.durationSeconds,
     stoppedReason: local.result.stoppedReason,
     diagnostics: local.result.diagnostics,
+    ...recordingNextStep(options.apiUrl, recordingId, remote ? "ready" : "processing"),
     ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false)
   };
   emit(result, options.pretty);
@@ -16338,7 +16477,7 @@ record2.command("retry").argument("<recording-id>").option("--no-wait").action(a
   if (!accepted) throw new Error("Encoding job is unavailable.");
   if (["expired", "cancelled"].includes(accepted.status)) throw new Error(`Recording ${accepted.status}.`);
   const result = commandOptions.wait && record2.opts().wait !== false ? await waitForEncoding(client, recordingId) : accepted;
-  emit({ schemaVersion: 1, ...result }, options.pretty);
+  emit({ schemaVersion: 1, ...result, ...recordingNextStep(options.apiUrl, recordingId, result.status, { resumableFrames: true }) }, options.pretty);
   if (result.status === "ready") await removeLocalCapture(recordingId);
   else watchEncoding(options.apiUrl, recordingId);
 });
@@ -16380,11 +16519,11 @@ record2.command("status").argument("<recording-id>").action(async (recordingId)
   try {
     const encoding = await client.encodingStatus(recordingId);
     const remote = encoding.status === "ready" ? await client.recordingStatus(recordingId) : {};
-    emit({ schemaVersion: 1, ...encoding, ...remote, recordingId, source: "remote" }, options.pretty);
+    emit({ schemaVersion: 1, ...encoding, ...remote, recordingId, source: "remote", ...recordingNextStep(options.apiUrl, recordingId, encoding.status, { resumableFrames: true }) }, options.pretty);
     if (encoding.status === "ready") await removeLocalCapture(recordingId);
     return;
   } catch (error51) {
-    if (!(error51 instanceof Error) || !error51.message.includes("recording_not_found")) throw error51;
+    if (!(error51 instanceof ControlPlaneError) || error51.code !== "recording_not_found") throw error51;
   }
   const status = await remoteAwareRecordingStatus(recordingId, {
     localStatus: async (id) => {
@@ -16392,7 +16531,7 @@ record2.command("status").argument("<recording-id>").action(async (recordingId)
       return recordingStatus(id);
     },
     remoteStatus: (id) => client.recordingStatus(id)
-  });
+  }, options.apiUrl);
   emit({ schemaVersion: 1, ...status }, options.pretty);
 });
 record2.command("cancel").argument("<recording-id>").description("Cancel an active recording and release its remote quota slot.").action(async (recordingId) => {
@@ -16411,11 +16550,25 @@ program.command("upload").argument("<video-file>").option("--title <title>").opt
   await client.uploadVideo(upload.uploadUrl, videoFile);
   const remote = commandOptions.wait === false ? null : await client.waitUntilPlayable(recording.recordingId);
   if (remote) process.stderr.write("\n");
-  emit({ schemaVersion: 1, recordingId: recording.recordingId, status: remote ? "ready" : "processing", shareUrl: remote?.shareUrl ?? null, expiresAt: remote?.expires_at ?? recording.expiresAt ?? null, diagnosticsAvailable: false }, options.pretty);
+  emit({ schemaVersion: 1, recordingId: recording.recordingId, status: remote ? "ready" : "processing", shareUrl: remote?.shareUrl ?? null, expiresAt: remote?.expires_at ?? recording.expiresAt ?? null, diagnosticsAvailable: false, ...recordingNextStep(options.apiUrl, recording.recordingId, remote ? "ready" : "processing") }, options.pretty);
 });
-program.command("inspect").argument("<share-url>").action(async (shareUrl) => {
+program.command("inspect").argument("<share-url>").option("--cursor <cursor>", "Read the next page of discussions").action(async (shareUrl, commandOptions) => {
   const options = program.opts();
-  emit(await new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl)).inspect(shareUrl), options.pretty);
+  emit(await new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl)).inspect(shareUrl, commandOptions.cursor), options.pretty);
+});
+var comments = program.command("comments").description("Reply to pinned review discussions.");
+comments.command("reply").argument("<share-url>").requiredOption("--discussion <id>").requiredOption("--body <text>").option("--request-id <uuid>", "Reuse on retry to prevent duplicate replies").action(async (shareUrl, input) => {
+  const options = program.opts();
+  const requestId = input.requestId ?? crypto.randomUUID();
+  process.stderr.write(`Reply request ID: ${requestId} (reuse with --request-id when retrying)
+`);
+  const client = new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl));
+  emit(await client.reply(shareUrl, input.discussion, input.body, requestId), options.pretty);
+});
+comments.command("edit").argument("<share-url>").requiredOption("--comment <id>").requiredOption("--body <text>").action(async (shareUrl, input) => {
+  const options = program.opts();
+  const client = new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl));
+  emit(await client.editReply(shareUrl, input.comment, input.body), options.pretty);
 });
 var drafts = program.command("drafts");
 drafts.command("list").action(async () => {
@@ -16440,6 +16593,7 @@ drafts.command("purge").action(async () => {
   emit({ schemaVersion: 1, purged }, options.pretty);
 });
 program.hook("preAction", async (_command, actionCommand) => {
+  if (commandPath(actionCommand).join(" ") === "record start") assertRecorderTransport();
   const command = cliCommandCategory(commandPath(actionCommand));
   if (!command) return;
   const options = program.opts();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runalabs/rill-cli",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Record, inspect, and share agent-controlled browser runs with Rill.",
   "license": "Apache-2.0",
   "repository": {