@runalabs/rill-cli 0.1.14 → 0.1.16

package/README.md

@@ -25,6 +25,10 @@ The following local-recording instructions remain available through `record star
 
 ## Install and verify
 
+Check `node --version`, `node -p "process.platform"`, and `rill --version` before installing. Reuse an installed compatible CLI. Commands execute in the agent's environment, which may be a separate sandbox from the user's desktop. Chrome must be accessible there, and the agent must be able to attach over CDP; doctor does not verify browser-control capability.
+
+If the CLI is missing, check npm with `npm ping --fetch-timeout=5000 --fetch-retries=0` before installation. See the [canonical skill](https://userill.dev/skill.md) for the bounded Rill connectivity check and Windows Terminal fallback. Report blocked network access instead of repeating installation attempts.
+
 Browser recording runs on macOS, Linux, and Windows. Install Node.js 22+ and Google Chrome or Chromium. Rill encodes recordings remotely by default; local FFmpeg is optional. Chrome stays on your machine and can access localhost. Raw frames upload after recording stops.
 
 Then install the scoped package:
@@ -42,7 +46,7 @@ Do not use `npx rill`: the unscoped package belongs to a different product. Doct
 
 ### 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:
+`rill whoami` shows a short account summary without starting sign-in. Agents should use `rill whoami --json` for verified identity fields. `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
@@ -124,7 +128,7 @@ 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.
+Capture follows the 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
 
@@ -135,12 +139,32 @@ Capture follows the first page selected at recording start. Keep the flow in tha
 | `--title <title>` | Name the run; defaults to a timestamped title. |
 | `--description <text>` | Describe what the run demonstrates. |
 | `--headed` | Show the managed browser; default is headless. |
-| `--cdp-url <url>` | Attach to an existing Chromium browser and record its first open page. Navigate that page with your browser tool. |
+| `--cdp-url <url>` | Attach to an existing Chromium CDP endpoint. Select a tab when several are open. |
+| `--tab-id <id>` | Record the stable target ID returned by `record tabs`; requires `--cdp-url`. |
 | `--width <pixels>` / `--height <pixels>` | Managed viewport; defaults to 1280 × 720. |
 | `--max-duration <seconds>` | Automatically finalize local capture; defaults to 600. Still call `record stop` to upload. |
 
 Rill closes browsers it launches during finalization. Attached browsers remain open.
 
+### Record a tab you already use
+
+Your Chromium browser must already expose a CDP endpoint; Rill cannot attach to an ordinary unexposed tab. Keep the endpoint local or otherwise access-controlled. This does not launch a second browser, switch tabs automatically or provide Safari/Firefox support.
+
+```bash
+rill record tabs --cdp-url http://127.0.0.1:9222
+rill record start --cdp-url http://127.0.0.1:9222 --tab-id <tab-id> --title "Checkout review"
+# Continue your flow in that exact tab, then finalize/upload:
+rill record stop <recording-id>
+```
+
+Discovery requires no Rill sign-in and returns `tabId`, title and a sanitized URL. Query values, credentials and fragments are removed; embedded data/file URLs are omitted. Tab titles can still contain private content. Start returns the selected `tabId` at the top level and in `browserAttachment`. If only one page is open, `--tab-id` is optional. Several pages without a selection, or a closed/missing ID, fail instead of recording a different page. A tab ID remains tied to that tab across navigation; relist after closing it.
+
+Keep automation on the selected target. For Playwright, inspect each page with `context.newCDPSession(page)`, call `Target.getTargetInfo`, match `targetInfo.targetId` to the returned `tabId`, and detach that inspection session. Do not assume `context.pages()[0]` is the recorded tab. `--url` deliberately navigates the selected tab when supplied; omit it to record the page as it is. Capture stays on this tab; popups and other tabs are not fully covered.
+
+An older running recorder service cannot honor tab selection. Start detects this and fails before sending capture instructions. Finish active recordings first; the service exits after five idle minutes when it has no retained recoverable captures. For an immediate manual restart, inspect the local `/health` response over the configured Rill socket, verify its recorder PID, and terminate only that idle recorder process. Restarting it interrupts active captures; this release does not restart it automatically.
+
+The CDP connection and disconnect behavior follow the [Playwright browser API](https://playwright.dev/docs/api/class-browser#browser-close).
+
 ## Set up a coding agent
 
 Install and authenticate the CLI where the agent runs. No separate skill installation is required. Optionally save the following workflow in your agent's project instructions or skill setup; it is also available in the [public agent instructions](https://userill.dev/docs/cli#agents):
@@ -187,6 +211,7 @@ Use `rill --help` or `<command> --help` for supported flags.
 | `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 tabs --cdp-url <url>` | List existing Chromium tabs without starting a recording. |
 | `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 remote state first, then local capture for unsubmitted recordings; local completion is `captured`. |
@@ -200,7 +225,20 @@ Use `rill --help` or `<command> --help` for supported flags.
 
 ## Output and errors
 
-Data commands emit JSON on stdout and human progress on stderr. Use global `--pretty` for indented JSON. Help and version commands print plain text.
+`whoami` shows a concise human summary by default. Use `rill whoami --json` for the existing schema-versioned identity response, including email, workspace, scopes and expiry. Its exit codes are unchanged: missing credentials exit 1; connected and anonymous access exit 0.
+
+Doctor and local recording commands retain JSON on stdout by default. Use `--human` for readable doctor, login, recording start/stop/status/retry summaries and errors. Doctor shows the command execution OS, named prerequisite checks, recovery guidance, and a pass/fail/warning count. Recording summaries show the ID, status, duration when available, share URL when returned, and the exact next command. Pending processing is distinct from a ready recording; a private recording may have no share URL.
+
+Explicit `--json` or `--pretty` takes precedence over `--human`. Use `--pretty` for indented JSON. Human output uses restrained terminal color only on a TTY, respects `NO_COLOR` and `TERM=dumb`, and retains status symbols and text without color. Human errors go to stderr; JSON errors remain on stdout. Help and version commands print plain text. Feedback and attachment metadata remain available in JSON; selecting a human view does not disable workspace feedback.
+
+```sh
+rill whoami
+rill whoami --json
+rill --human doctor
+rill --human record start --url https://example.com --title "Smoke test" --headed
+rill --human record stop <recording-id>
+rill --human record status <recording-id>
+```
 
 ```sh
 rill --pretty record status <recording-id>
@@ -336,10 +374,16 @@ Use `rill record list` to list accessible recordings and `rill inspect <recordin
 
 ### Check the connected account
 
-Run `rill whoami` (or `rill --pretty whoami`) to verify your current identity. JSON output includes status, account email when available, workspace, scopes, and access expiry. It uses RILL_TOKEN when set, otherwise the saved OS credential. Existing access can renew automatically; it never creates an identity or opens an approval flow. Missing credentials return `not_connected` and exit 1. Invalid or revoked credentials return an error.
+Run `rill whoami` for a short human account summary, or `rill whoami --json` (also `rill --pretty whoami`) for structured identity fields. JSON includes status, account email when available, workspace, scopes, and access expiry. It uses RILL_TOKEN when set, otherwise the saved OS credential. Existing access can renew automatically; it never creates an identity or opens an approval flow. Missing credentials return `not_connected` in JSON and exit 1. Invalid or revoked credentials return an error.
 
 ### Capture time and upload progress (0.1.14)
 
 `record start` and active local `record status` return `startedAt`, `stopsAt`, `maxDurationSeconds`, `elapsedSeconds`, and `remainingSeconds`. Use the remaining time to budget retries. After automatic capture stop, status reports `captured` with the stop/upload command; zero remaining time does not mean playback is ready. Fields may be absent for recovered drafts or an older daemon.
 
 Remote frame uploads write accepted/total MiB, transfer speed and an approximate remaining transfer time to stderr. Estimates use this attempt's observed transfers, including retry delays, and exclude previously uploaded bytes. They do not estimate queue or encoding time. JSON stdout stays machine readable. Failed local captures offer an explicit cancellation command for their remote slot; local drafts are retained.
+
+### Failed local capture recovery
+
+If the local recorder reports a terminal failure without a finalized artifact, `rill record stop <id>` attempts to release its unused server reservation and preserves the capture error. The JSON error uses `local_capture_failed` with `details.reservationReleased`; a failed cleanup includes the status command for the selected API origin.
+
+When `record start` is blocked by a recording concurrency slot, it checks the reported blocking recording in the local daemon. A confirmed failed capture with no artifact can release its own unused reservation, then retry creation once with the same request ID. Missing/active local state, retained artifacts, other credentials, Stream uploads, encoding jobs and quota-counted reservations are preserved. Older servers or unavailable networks leave the original quota error and manual recovery guidance intact. Daily upload/storage limits still apply. This change does not resume a failed capture, import missing diagnostics, or add Windows recording support.

package/dist/cli.js

@@ -116,12 +116,13 @@ function recordingNextStep(apiUrl, recordingId, status, options = {}) {
   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) {
+function browserAttachment(cdpUrl, tabId) {
   return {
     protocol: "cdp",
     cdpUrl,
+    ...tabId ? { tabId } : {},
     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.",
+    instructions: (tabId ? "Record only the returned tabId. Match it using a page CDP session and Target.getTargetInfo; do not pick the first page. " : "") + "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."
   };
 }
@@ -441,7 +442,7 @@ var ControlPlaneClient = class {
     return this.request(`/api/cloud/runs/${encodeURIComponent(id)}/cancel`, { method: "POST" });
   }
   health() {
-    return this.request("/api/health", {}, false);
+    return this.request("/api/health", { signal: AbortSignal.timeout(5e3) }, false);
   }
   agentSession() {
     return this.request("/api/agent/session", { signal: AbortSignal.timeout(5e3) });
@@ -452,6 +453,9 @@ var ControlPlaneClient = class {
   createRecording(input) {
     return this.request("/api/recordings", { method: "POST", body: JSON.stringify(input) });
   }
+  failLocalCapture(recordingId) {
+    return this.request(`/api/recordings/${encodeURIComponent(recordingId)}/local-failed`, { method: "POST", body: "{}" });
+  }
   markRecordingStarted(recordingId, input) {
     return this.request(`/api/recordings/${recordingId}/local-started`, {
       method: "POST",
@@ -15147,19 +15151,20 @@ var frameManifestSchema = external_exports.object({
 });
 
 // src/remote-encoding.ts
-async function withFrameUploadRetry(upload, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+async function withFrameUploadRetry(upload, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), canRetry = () => true) {
   for (let attempt = 0; ; attempt++) {
     try {
       return await upload();
     } catch (error51) {
       const status = error51 instanceof ControlPlaneError || error51 instanceof ControlPlaneHttpError ? error51.httpStatus : void 0;
       const transient = status !== void 0 ? status === 408 || status === 429 || status >= 500 : error51 instanceof TypeError || error51 instanceof DOMException && ["TimeoutError", "AbortError"].includes(error51.name);
-      if (!transient || attempt >= 7) throw error51;
+      if (!transient || attempt >= 7 || !canRetry()) throw error51;
       const delay = Math.min(15e3, 1e3 * 2 ** attempt);
       process.stderr.write(`
 Frame upload interrupted; retrying in ${delay / 1e3}s.
 `);
       await sleep(delay);
+      if (!canRetry()) throw error51;
     }
   }
 }
@@ -15175,8 +15180,12 @@ async function submitFrameCapture(client, id, directory) {
   try {
     const total = manifest.frames.reduce((n, f) => n + f.size, 0);
     if ((await file2.stat()).size !== total) throw new Error("Capture bytes do not match the manifest.");
-    const uploaded = new Set(status.uploadedParts);
-    let acceptedBytes = [...uploaded].reduce((sum, part) => sum + (Number.isInteger(part) && part >= 0 && part < Math.ceil(total / ENCODING_PART_BYTES) ? Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES) : 0), 0);
+    const parts = Math.ceil(total / ENCODING_PART_BYTES);
+    const uploaded = new Set(status.uploadedParts.filter((part) => Number.isInteger(part) && part >= 0 && part < parts));
+    const missing = Array.from({ length: parts }, (_, part) => part).filter((part) => !uploaded.has(part));
+    let next = 0, failed = false;
+    let firstFailure;
+    let acceptedBytes = [...uploaded].reduce((sum, part) => sum + Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES), 0);
     let transferredBytes = 0;
     const startedAt = Date.now();
     const progress = () => {
@@ -15186,20 +15195,34 @@ async function submitFrameCapture(client, id, directory) {
       process.stderr.write(`\ruploading frames ${Math.floor(acceptedBytes / total * 100)}% \xB7 ${(acceptedBytes / 1048576).toFixed(2)}/${(total / 1048576).toFixed(2)} MiB${rate > 0 ? ` \xB7 ${(rate / 1048576).toFixed(2)} MiB/s` : ""}${remaining}`);
     };
     progress();
-    for (let part = 0; part < Math.ceil(total / ENCODING_PART_BYTES); part++) {
-      if (uploaded.has(part)) continue;
-      const bytes = Buffer.alloc(Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES));
-      let offset = 0;
-      while (offset < bytes.length) {
-        const r = await file2.read(bytes, offset, bytes.length - offset, part * ENCODING_PART_BYTES + offset);
-        if (!r.bytesRead) throw new Error("Incomplete capture bytes.");
-        offset += r.bytesRead;
-      }
-      await withFrameUploadRetry(() => client.uploadEncodingPart(id, part, bytes));
-      acceptedBytes += bytes.length;
-      transferredBytes += bytes.length;
-      progress();
-    }
+    const transfer = async () => {
+      while (!failed) {
+        const part = missing[next++];
+        if (part === void 0) return;
+        try {
+          const bytes = Buffer.alloc(Math.min(ENCODING_PART_BYTES, total - part * ENCODING_PART_BYTES));
+          let offset = 0;
+          while (offset < bytes.length) {
+            const r = await file2.read(bytes, offset, bytes.length - offset, part * ENCODING_PART_BYTES + offset);
+            if (!r.bytesRead) throw new Error("Incomplete capture bytes.");
+            offset += r.bytesRead;
+          }
+          if (failed) return;
+          await withFrameUploadRetry(() => client.uploadEncodingPart(id, part, bytes), void 0, () => !failed);
+          acceptedBytes += bytes.length;
+          transferredBytes += bytes.length;
+          progress();
+        } catch (error51) {
+          if (!failed) {
+            firstFailure = error51;
+            failed = true;
+          }
+          throw error51;
+        }
+      }
+    };
+    await Promise.allSettled(Array.from({ length: Math.min(3, missing.length) }, transfer));
+    if (failed) throw firstFailure;
   } finally {
     await file2.close();
   }
@@ -15221,7 +15244,7 @@ async function waitForEncoding(client, id, timeoutMs = 30 * 6e4) {
 // src/cli.ts
 import { spawn as spawn8 } from "child_process";
 import { hostname as hostname4, tmpdir as tmpdir3 } from "os";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { basename, dirname as dirname2, join as join11 } from "path";
 import { readdir as readdir2, rm as rm7, stat as stat5 } from "fs/promises";
 
@@ -15327,11 +15350,118 @@ async function windowsIpcIdentity(directory = join5(rillDirectory(), "windows-ip
 // ../recorder/src/client.ts
 import { request as request2 } from "http";
 import { spawn as spawn4 } from "child_process";
-async function ensureDaemon(cliEntryPath) {
+
+// ../recorder/src/browser-tabs.ts
+import { chromium } from "playwright-core";
+
+// ../recorder/src/redaction.ts
+var secretKeyPattern = /(?:pass(?:word)?|secret|token|api[_-]?key|authorization|cookie|session|access[_-]?token|refresh[_-]?token|client[_-]?secret)/i;
+var tokenValuePattern = /\b(?:sk|pk|ghp|github_pat|xox[baprs]|eyJ)[-_a-zA-Z0-9.]{16,}\b/g;
+function sanitizeUrl(input) {
   try {
-    await callDaemon("GET", "/health");
-    return;
+    const url2 = new URL(input);
+    url2.username = "";
+    url2.password = "";
+    url2.hash = "";
+    for (const key2 of [...url2.searchParams.keys()]) url2.searchParams.set(key2, "[REDACTED]");
+    return url2.toString();
   } catch {
+    return "[invalid-url]";
+  }
+}
+function redactText(value, maxLength = 8e3) {
+  return value.replace(tokenValuePattern, "[REDACTED]").slice(0, maxLength);
+}
+function redactBody(value, contentType, maxBytes = 65536) {
+  if (Buffer.byteLength(value) > maxBytes) return { body: void 0, omittedReason: "body_too_large" };
+  if (!isAllowedBodyType(contentType)) return { body: void 0, omittedReason: "unsupported_content_type" };
+  if (contentType?.includes("json")) {
+    try {
+      const parsed = JSON.parse(value);
+      return { body: JSON.stringify(redactJson(parsed)) };
+    } catch {
+      return { body: redactText(value) };
+    }
+  }
+  return { body: redactText(value) };
+}
+function isAllowedBodyType(contentType) {
+  if (!contentType) return false;
+  const normalized = contentType.toLowerCase();
+  return normalized.includes("application/json") || normalized.includes("application/problem+json") || normalized.includes("application/graphql-response+json") || normalized.includes("text/plain") || normalized.includes("application/xml") || normalized.includes("text/xml");
+}
+function redactJson(value, depth = 0) {
+  if (depth > 12) return "[TRUNCATED]";
+  if (Array.isArray(value)) return value.slice(0, 100).map((item) => redactJson(item, depth + 1));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).slice(0, 200).map(([key2, child]) => [key2, secretKeyPattern.test(key2) ? "[REDACTED]" : redactJson(child, depth + 1)]));
+  }
+  if (typeof value === "string") return redactText(value, 8e3);
+  return value;
+}
+
+// ../recorder/src/browser-tabs.ts
+function validateTabSelection(options) {
+  if (options.tabId && !options.cdpUrl) throw new Error("validation_failed: --tab-id requires --cdp-url.");
+}
+async function tabs(browser) {
+  const result = [];
+  for (const context of browser.contexts()) for (const page of context.pages()) {
+    if (page.isClosed()) continue;
+    const session = await context.newCDPSession(page).catch(() => null);
+    if (!session) {
+      if (page.isClosed()) continue;
+      throw new Error("browser_unavailable: Could not inspect an open tab.");
+    }
+    try {
+      const { targetInfo } = await session.send("Target.getTargetInfo");
+      result.push({ page, context, tab: { tabId: targetInfo.targetId, url: /^(?:https?:|about:)/i.test(page.url()) ? sanitizeUrl(page.url()) : `[${page.url().split(":", 1)[0]} URL omitted]`, title: redactText(targetInfo.title, 200) } });
+    } catch (error51) {
+      if (!page.isClosed()) throw error51;
+    } finally {
+      await session.detach().catch(() => void 0);
+    }
+  }
+  return result;
+}
+async function listBrowserTabs(cdpUrl) {
+  const browser = await chromium.connectOverCDP(cdpUrl, { noDefaults: true });
+  try {
+    return (await tabs(browser)).map((entry) => entry.tab);
+  } finally {
+    await browser.close();
+  }
+}
+async function connectRecordingTab(cdpUrl, outputDirectory, tabId) {
+  const browser = await chromium.connectOverCDP(cdpUrl, { artifactsDir: outputDirectory, isLocal: true, noDefaults: true });
+  try {
+    const available = await tabs(browser);
+    const selected = tabId ? available.find((entry) => entry.tab.tabId === tabId) : available.length === 1 ? available[0] : void 0;
+    if (!selected) {
+      if (tabId) throw new Error("browser_unavailable: The selected tab is no longer available. Run record tabs --cdp-url <endpoint> and choose an open tab.");
+      if (!available.length) throw new Error("browser_unavailable: The attached browser has no page target to record.");
+      throw new Error("validation_failed: Several tabs are open. Run record tabs --cdp-url <endpoint>, then record start --cdp-url <endpoint> --tab-id <tab-id>.");
+    }
+    return { cdpUrl, browser, context: selected.context, page: selected.page, tabId: selected.tab.tabId };
+  } catch (error51) {
+    await browser.close().catch(() => void 0);
+    throw error51;
+  }
+}
+
+// ../recorder/src/client.ts
+async function ensureDaemon(cliEntryPath, requireTabSelection = false) {
+  const check2 = (health2) => {
+    if (requireTabSelection && !health2.capabilities?.includes("tab-selection-v1")) throw new Error("browser_unavailable: The running Rill recorder predates tab selection. Stop active recordings, then restart the recorder service before attaching.");
+  };
+  let health;
+  try {
+    health = await callDaemon("GET", "/health");
+  } catch {
+  }
+  if (health) {
+    check2(health);
+    return;
   }
   const child = spawn4(process.execPath, [cliEntryPath, "daemon"], { detached: true, stdio: "ignore", env: process.env, windowsHide: true });
   let startupError;
@@ -15343,11 +15473,13 @@ async function ensureDaemon(cliEntryPath) {
   while (Date.now() < deadline) {
     if (startupError) throw startupError;
     try {
-      await callDaemon("GET", "/health");
-      return;
+      health = await callDaemon("GET", "/health");
     } catch {
       await new Promise((resolve) => setTimeout(resolve, 100));
+      continue;
     }
+    check2(health);
+    return;
   }
   throw new Error("The local recorder service did not start.");
 }
@@ -15424,6 +15556,55 @@ import { createServer as createServer2 } from "http";
 import { mkdir as mkdir7, readFile as readFile7, unlink, writeFile as writeFile6, rename as rename2, stat as stat4, chmod } from "fs/promises";
 import { dirname, join as join10 } from "path";
 
+// ../recorder/src/click-capture.ts
+import { randomUUID as randomUUID2 } from "crypto";
+async function captureClicks(page, session, onClick) {
+  const binding = `__rillClick_${randomUUID2().replaceAll("-", "")}`;
+  const source = `(() => {
+    const key = ${JSON.stringify(binding)};
+    if (window[key + '_listener']) return;
+    const listener = event => {
+      const target = event.target;
+      const label = target?.innerText?.trim().slice(0, 80) || target?.getAttribute?.('aria-label') || target?.tagName || 'Element';
+      try { window[key](JSON.stringify({ x: event.clientX, y: event.clientY, label })); } catch {}
+    };
+    window[key + '_listener'] = listener;
+    document.addEventListener('click', listener, { capture: true });
+  })();`;
+  const receive = (event) => {
+    if (event.name !== binding) return;
+    try {
+      const value = JSON.parse(event.payload);
+      if (typeof value.x === "number" && Number.isFinite(value.x) && typeof value.y === "number" && Number.isFinite(value.y) && typeof value.label === "string") onClick({ x: value.x, y: value.y, label: value.label.slice(0, 80) });
+    } catch {
+    }
+  };
+  let identifier;
+  session.on("Runtime.bindingCalled", receive);
+  const cleanup = async () => {
+    session.off("Runtime.bindingCalled", receive);
+    if (identifier) await session.send("Page.removeScriptToEvaluateOnNewDocument", { identifier }).catch(() => void 0);
+    await Promise.all(page.frames().map((frame) => frame.evaluate((key2) => {
+      const target = window;
+      const listener = target[key2 + "_listener"];
+      if (typeof listener === "function") document.removeEventListener("click", listener, { capture: true });
+      delete target[key2 + "_listener"];
+      delete target[key2];
+    }, binding).catch(() => void 0)));
+    await session.send("Runtime.removeBinding", { name: binding }).catch(() => void 0);
+  };
+  try {
+    await session.send("Runtime.enable");
+    await session.send("Runtime.addBinding", { name: binding });
+    ({ identifier } = await session.send("Page.addScriptToEvaluateOnNewDocument", { source }));
+    await Promise.all(page.frames().map((frame) => frame.evaluate(source)));
+    return cleanup;
+  } catch (error51) {
+    await cleanup();
+    throw error51;
+  }
+}
+
 // ../contracts/src/cloud-blocklist.ts
 var blockedCloudDomains = [
   // Torrent indexes and unofficial software-download destinations.
@@ -15764,7 +15945,7 @@ async function attachCursorOverlay(page, cdp, input) {
 }
 
 // ../recorder/src/session.ts
-import { chromium } from "playwright-core";
+import { chromium as chromium2 } from "playwright-core";
 import { spawn as spawn6 } from "child_process";
 import { createServer } from "net";
 import { mkdir as mkdir6, mkdtemp, rm as rm5, writeFile as writeFile5 } from "fs/promises";
@@ -15806,52 +15987,6 @@ function findChromeExecutable(platform = process.platform, env = process.env, ex
   return candidates.find(exists) ?? "google-chrome";
 }
 
-// ../recorder/src/redaction.ts
-var secretKeyPattern = /(?:pass(?:word)?|secret|token|api[_-]?key|authorization|cookie|session|access[_-]?token|refresh[_-]?token|client[_-]?secret)/i;
-var tokenValuePattern = /\b(?:sk|pk|ghp|github_pat|xox[baprs]|eyJ)[-_a-zA-Z0-9.]{16,}\b/g;
-function sanitizeUrl(input) {
-  try {
-    const url2 = new URL(input);
-    url2.username = "";
-    url2.password = "";
-    url2.hash = "";
-    for (const key2 of [...url2.searchParams.keys()]) url2.searchParams.set(key2, "[REDACTED]");
-    return url2.toString();
-  } catch {
-    return "[invalid-url]";
-  }
-}
-function redactText(value, maxLength = 8e3) {
-  return value.replace(tokenValuePattern, "[REDACTED]").slice(0, maxLength);
-}
-function redactBody(value, contentType, maxBytes = 65536) {
-  if (Buffer.byteLength(value) > maxBytes) return { body: void 0, omittedReason: "body_too_large" };
-  if (!isAllowedBodyType(contentType)) return { body: void 0, omittedReason: "unsupported_content_type" };
-  if (contentType?.includes("json")) {
-    try {
-      const parsed = JSON.parse(value);
-      return { body: JSON.stringify(redactJson(parsed)) };
-    } catch {
-      return { body: redactText(value) };
-    }
-  }
-  return { body: redactText(value) };
-}
-function isAllowedBodyType(contentType) {
-  if (!contentType) return false;
-  const normalized = contentType.toLowerCase();
-  return normalized.includes("application/json") || normalized.includes("application/problem+json") || normalized.includes("application/graphql-response+json") || normalized.includes("text/plain") || normalized.includes("application/xml") || normalized.includes("text/xml");
-}
-function redactJson(value, depth = 0) {
-  if (depth > 12) return "[TRUNCATED]";
-  if (Array.isArray(value)) return value.slice(0, 100).map((item) => redactJson(item, depth + 1));
-  if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).slice(0, 200).map(([key2, child]) => [key2, secretKeyPattern.test(key2) ? "[REDACTED]" : redactJson(child, depth + 1)]));
-  }
-  if (typeof value === "string") return redactText(value, 8e3);
-  return value;
-}
-
 // ../recorder/src/encoding.ts
 import { open as open2, writeFile as writeFile3, mkdir as mkdir4 } from "fs/promises";
 import { spawn as spawn5 } from "child_process";
@@ -16009,6 +16144,7 @@ var RecordingSession = class _RecordingSession {
   recordingId;
   startedAt = /* @__PURE__ */ new Date();
   cdpUrl;
+  tabId;
   browser;
   context;
   page;
@@ -16023,6 +16159,7 @@ var RecordingSession = class _RecordingSession {
   stopPromise;
   maxTimer;
   maxDurationSeconds;
+  removeClickCapture;
   removeCursorOverlay;
   diagnosticsPaused = false;
   secretValues = [];
@@ -16039,6 +16176,7 @@ var RecordingSession = class _RecordingSession {
     this.captureSignal = options.signal;
     this.recordingId = options.recordingId;
     this.cdpUrl = runtime.cdpUrl;
+    this.tabId = runtime.tabId;
     this.browser = runtime.browser;
     this.context = runtime.context;
     this.page = runtime.page;
@@ -16048,16 +16186,25 @@ var RecordingSession = class _RecordingSession {
     this.outputDirectory = options.outputDirectory;
   }
   static async start(options) {
+    validateTabSelection(options);
     const width = options.width ?? 1280;
     const height = options.height ?? 720;
     await mkdir6(options.outputDirectory, { recursive: true, mode: 448 });
     if (options.encoding === "remote") await writeFile5(join9(options.outputDirectory, "remote-capture.json"), JSON.stringify({ expiresAt: Date.now() + 864e5 }), { mode: 384 });
-    const runtime = options.cdpUrl ? await connectAttached(options.cdpUrl, options.outputDirectory) : await launchManaged({ headed: options.headed ?? false, width, height, outputDirectory: options.outputDirectory, proxyServer: options.proxyServer, blockServiceWorkers: options.blockServiceWorkers });
-    const cdpSession = await runtime.context.newCDPSession(runtime.page);
+    const runtime = options.cdpUrl ? await connectRecordingTab(options.cdpUrl, options.outputDirectory, options.tabId) : await launchManaged({ headed: options.headed ?? false, width, height, outputDirectory: options.outputDirectory, proxyServer: options.proxyServer, blockServiceWorkers: options.blockServiceWorkers });
+    let cdpSession;
+    try {
+      cdpSession = await runtime.context.newCDPSession(runtime.page);
+    } catch (error51) {
+      await runtime.browser.close().catch(() => void 0);
+      if ("browserProcess" in runtime && runtime.browserProcess) await terminateBrowser(runtime.browserProcess);
+      if ("profileDirectory" in runtime && runtime.profileDirectory) await rm5(runtime.profileDirectory, { recursive: true, force: true }).catch(() => void 0);
+      throw error51;
+    }
     const screencast = new ScreencastRecorder(cdpSession, join9(options.outputDirectory, "frames"), width, height);
     const session = new _RecordingSession(options, { ...runtime, screencast });
     try {
-      await session.attachDiagnostics(options.captureNetworkBodies ?? false);
+      await session.attachDiagnostics(options.captureNetworkBodies ?? false, cdpSession);
       if (!options.hideCursor) session.removeCursorOverlay = await attachCursorOverlay(runtime.page, cdpSession, options.cursorAppearance);
       await options.beforeCapture?.(runtime.page);
       session.startedAt = /* @__PURE__ */ new Date();
@@ -16082,6 +16229,7 @@ var RecordingSession = class _RecordingSession {
     return {
       recordingId: this.recordingId,
       cdpUrl: this.cdpUrl,
+      ...this.tabId ? { tabId: this.tabId } : {},
       startedAt: this.startedAt.toISOString(),
       maxDurationSeconds: this.maxDurationSeconds,
       elapsedSeconds,
@@ -16118,9 +16266,10 @@ var RecordingSession = class _RecordingSession {
       await writeBundle(safeBundle, diagnosticsPath);
       await this.screencast.stop(videoPath, durationSeconds, this.encoding === "remote", this.captureSignal);
     } finally {
-      await this.removeCursorOverlay?.();
+      await this.removeClickCapture?.().catch(() => void 0);
+      await this.removeCursorOverlay?.().catch(() => void 0);
+      await this.browser.close().catch(() => void 0);
       if (this.browserProcess) {
-        await this.browser.close().catch(() => void 0);
         await terminateBrowser(this.browserProcess);
         if (this.profileDirectory) await rm5(this.profileDirectory, { recursive: true, force: true }).catch(() => void 0);
       }
@@ -16135,7 +16284,7 @@ var RecordingSession = class _RecordingSession {
   videoFormat = "webm";
   encoding = "local";
   outputDirectory = "";
-  async attachDiagnostics(captureNetworkBodies) {
+  async attachDiagnostics(captureNetworkBodies, cdpSession) {
     this.captureNetworkBodies = captureNetworkBodies;
     const offset = () => Date.now() - this.startedAt.getTime();
     const pushTimeline = (event) => {
@@ -16146,14 +16295,7 @@ var RecordingSession = class _RecordingSession {
       }
       this.timelineEvents.push({ id: `time_${this.timelineEvents.length + 1}`, ...event });
     };
-    await this.page.exposeFunction("__rillClick", (payload) => pushTimeline({ offsetMs: offset(), type: "click", label: `${payload.label || "Element"} at ${Math.round(payload.x)},${Math.round(payload.y)}` })).catch(() => void 0);
-    await this.page.addInitScript(() => {
-      document.addEventListener("click", (event) => {
-        const target = event.target;
-        const label = target?.innerText?.trim().slice(0, 80) || target?.getAttribute("aria-label") || target?.tagName || "Element";
-        void window.__rillClick?.({ x: event.clientX, y: event.clientY, label });
-      }, { capture: true });
-    });
+    this.removeClickCapture = await captureClicks(this.page, cdpSession, (payload) => pushTimeline({ offsetMs: offset(), type: "click", label: `${payload.label || "Element"} at ${Math.round(payload.x)},${Math.round(payload.y)}` }));
     this.page.on("framenavigated", (frame) => {
       if (frame === this.page.mainFrame()) pushTimeline({ offsetMs: offset(), type: "navigation", label: sanitizeUrl(frame.url()) });
     });
@@ -16264,7 +16406,7 @@ async function launchManaged(options) {
   const cdpUrl = `http://127.0.0.1:${port}`;
   try {
     await waitForCdp(cdpUrl, browserProcess);
-    const browser = await chromium.connectOverCDP(cdpUrl, { artifactsDir: options.outputDirectory, isLocal: true });
+    const browser = await chromium2.connectOverCDP(cdpUrl, { artifactsDir: options.outputDirectory, isLocal: true });
     const context = options.blockServiceWorkers ? await browser.newContext({ serviceWorkers: "block" }) : browser.contexts()[0];
     const page = context.pages()[0] ?? await context.newPage();
     await page.setViewportSize({ width: options.width, height: options.height });
@@ -16275,13 +16417,6 @@ async function launchManaged(options) {
     throw error51;
   }
 }
-async function connectAttached(cdpUrl, outputDirectory) {
-  const browser = await chromium.connectOverCDP(cdpUrl, { artifactsDir: outputDirectory, isLocal: true, noDefaults: true });
-  const context = browser.contexts()[0];
-  const page = context.pages()[0];
-  if (!page) throw new Error("The attached browser has no page target to record.");
-  return { cdpUrl, browser, context, page };
-}
 async function getAvailablePort() {
   const server = createServer();
   await new Promise((resolve, reject) => server.listen(0, "127.0.0.1", resolve).once("error", reject));
@@ -16366,7 +16501,7 @@ async function runDaemon() {
 async function route(request3, response) {
   lastActivity = Date.now();
   const url2 = new URL(request3.url ?? "/", "http://daemon.local");
-  if (request3.method === "GET" && url2.pathname === "/health") return json2(response, 200, { ok: true, pid: process.pid });
+  if (request3.method === "GET" && url2.pathname === "/health") return json2(response, 200, { ok: true, pid: process.pid, capabilities: ["tab-selection-v1"] });
   if (request3.method === "POST" && url2.pathname === "/sessions") {
     if ([...sessions.values()].filter((entry) => entry.state === "recording").length >= 2) return json2(response, 429, { error: { code: "quota_exceeded", message: "This recorder already has two active sessions." } });
     try {
@@ -16375,7 +16510,7 @@ async function route(request3, response) {
       const outputDirectory = join10(recordingTempRoot(), input.recordingId);
       const session = await RecordingSession.start({ ...input, outputDirectory });
       const status = session.status();
-      const entry = { session, base: { recordingId: status.recordingId, cdpUrl: status.cdpUrl, startedAt: status.startedAt }, state: "recording" };
+      const entry = { session, base: { recordingId: status.recordingId, cdpUrl: status.cdpUrl, tabId: status.tabId, startedAt: status.startedAt }, state: "recording" };
       sessions.set(input.recordingId, entry);
       const maxTimer = setTimeout(() => void finalizeEntry(entry, "max_duration"), Math.max(0, Date.parse(status.stopsAt) - Date.now()) + 250);
       maxTimer.unref();
@@ -16426,7 +16561,7 @@ async function restoreRecoverableSessions() {
     const value = JSON.parse(await readFile7(daemonStatePath(), "utf8"));
     for (const [id, entry] of Object.entries(value)) {
       if (entry.status !== "ready" && entry.status !== "failed") continue;
-      sessions.set(id, { base: { recordingId: entry.recordingId, cdpUrl: entry.cdpUrl, startedAt: entry.startedAt }, state: entry.status, result: entry.result, error: entry.error });
+      sessions.set(id, { base: { recordingId: entry.recordingId, cdpUrl: entry.cdpUrl, tabId: entry.tabId, startedAt: entry.startedAt }, state: entry.status, result: entry.result, error: entry.error });
     }
   } catch {
   }
@@ -16502,7 +16637,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", "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 knownCodes = /* @__PURE__ */ new Set(["authentication_required", "authorization_not_found", "expired_token", "access_denied", "unsupported_platform", "scope_denied", "quota_exceeded", "browser_unavailable", "local_capture_failed", "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 } : {} } };
@@ -16512,6 +16647,72 @@ function fail(error51) {
   process.exitCode = 1;
 }
 
+// src/human-output.ts
+function terminalColor(enabled = Boolean(process.stdout.isTTY) && !("NO_COLOR" in process.env) && process.env.TERM !== "dumb") {
+  return (text, code) => enabled ? `\x1B[${code}m${text}\x1B[0m` : text;
+}
+function formatIdentity(identity, color = terminalColor()) {
+  if (identity.status === "not_connected") return `${color("! Not connected to Rill", 33)}
+
+Sign in: ${cliCommand(identity.apiUrl, "login")}
+`;
+  if (identity.status === "anonymous") return `${color("\u2713 Using Rill anonymously", 32)}
+
+Connect your account: ${cliCommand(identity.apiUrl, "connect", "--email", "<your-email>")}
+`;
+  return `${color("\u2713 Connected to Rill", 32)}
+Account: ${identity.email ?? "Email unavailable"}
+`;
+}
+function formatDoctor(result, color = terminalColor()) {
+  const labels = { node: "Node.js", api: "API connectivity", cli_version: "CLI version", authentication: "Authentication", chrome: "Browser", ffmpeg: "FFmpeg", encoding: "Encoding", recorder_transport: "Recorder transport" };
+  const symbols = { pass: "\u2713", fail: "\xD7", warn: "!", skip: "\u2013" };
+  const colors = { pass: 32, fail: 31, warn: 33, skip: 90 };
+  const lines = [color("Rill CLI Doctor", 34), `Execution environment: ${result.environment.platform}`, ""];
+  for (const check2 of result.checks) {
+    lines.push(color(`${symbols[check2.status]} ${labels[check2.name]}: ${check2.message}`, colors[check2.status]));
+    if (check2.recovery) lines.push(`  \u2192 ${check2.recovery}`);
+  }
+  const warnings = result.checks.filter((c) => c.status === "warn").length;
+  lines.push(
+    "",
+    "Browser control: not verified. Your agent must attach to the returned CDP endpoint.",
+    "",
+    `${result.checks.filter((c) => c.status === "pass").length} passed \xB7 ${result.checks.filter((c) => c.status === "fail").length} failed \xB7 ${warnings} ${warnings === 1 ? "warning" : "warnings"}`
+  );
+  return lines.join("\n") + "\n";
+}
+function formatRecording(value, apiUrl, color = terminalColor()) {
+  const artifact = value.result && typeof value.result === "object" ? value.result : {};
+  const id = String(value.recordingId ?? value.id ?? "");
+  const status = String(value.status ?? "unknown");
+  const titles = { recording: "Recording started", ready: "Recording ready", captured: "Captured locally \xB7 upload required", uploading: "Uploading recording", queued: "Recording queued for encoding", encoding: "Encoding recording", processing: "Processing recording", finalizing: "Finalizing recording", failed: "Recording failed", cancelled: "Recording cancelled", expired: "Recording expired" };
+  const lines = [color(`${["recording", "ready"].includes(status) ? "\u2713" : ["failed", "expired"].includes(status) ? "\xD7" : "\u2013"} ${titles[status] ?? `Recording status: ${status}`}`, ["failed", "expired"].includes(status) ? 31 : status === "ready" || status === "recording" ? 32 : 33)];
+  if (id) lines.push(`ID: ${id}`);
+  const duration3 = value.durationSeconds ?? value.duration_seconds ?? artifact.durationSeconds;
+  if (typeof duration3 === "number" && Number.isFinite(duration3)) lines.push(`Duration: ${Math.floor(duration3 / 60)}m ${Math.floor(duration3 % 60)}s`);
+  if (typeof value.remainingSeconds === "number") lines.push(`Time remaining: ${Math.max(0, Math.ceil(value.remainingSeconds))}s`);
+  if (typeof value.cdpUrl === "string") lines.push(`Browser connection: ${value.cdpUrl}`);
+  if (typeof value.tabId === "string") lines.push(`Recorded tab: ${value.tabId}`);
+  if (typeof value.shareUrl === "string" && value.shareUrl) lines.push("", `Share: ${value.shareUrl}`);
+  else if (status === "ready") lines.push("", "Ready. No share link returned; open this recording in your Rill account.");
+  const message = value.message ?? value.error;
+  if (typeof message === "string" && message) lines.push("", message);
+  const next = typeof value.nextCommand === "string" ? value.nextCommand : status === "recording" && id ? cliCommand(apiUrl, "record", "stop", id) : void 0;
+  if (next) lines.push("", status === "recording" ? "Perform your test, then stop and upload:" : "Next:", `  ${next}`);
+  return lines.join("\n") + "\n";
+}
+function formatFailure(error51, color = terminalColor()) {
+  const { error: failure } = failureValue(error51);
+  let message = failure.message.startsWith(`${failure.code}: `) ? failure.message.slice(failure.code.length + 2) : failure.message;
+  if (failure.recovery && message.endsWith(`: ${failure.recovery}`)) message = message.slice(0, -failure.recovery.length - 2);
+  const lines = [color(`\xD7 ${message}`, 31)];
+  if (typeof failure.details?.recordingId === "string") lines.push(`ID: ${failure.details.recordingId}`);
+  if (failure.recovery) lines.push("", `Next: ${failure.recovery}`);
+  else if (typeof failure.details?.nextCommand === "string") lines.push("", `Next: ${failure.details.nextCommand}`);
+  return lines.join("\n") + "\n";
+}
+
 // src/feedback-protocol.ts
 function suggestedFeedbackAction(recordingId) {
   return {
@@ -16606,9 +16807,11 @@ async function runDoctor(apiUrl, overrides = {}) {
     if (!health.ok || health.service !== "rill") throw new Error("The endpoint did not identify itself as Rill.");
     checks.push({ name: "api", status: "pass", message: `Rill API is reachable at ${apiUrl}.` });
   } catch (error51) {
-    checks.push({ name: "api", status: "fail", message: `Rill API is unreachable: ${errorMessage(error51)}`, recovery: `Check the network and API URL, then rerun \`rill --api-url ${apiUrl} doctor\`.` });
+    checks.push({ name: "api", status: "fail", message: `Rill API is unreachable: ${errorMessage(error51)}`, recovery: `Check network access in this ${dependencies.platform} execution environment and the API URL, then rerun \`rill --api-url ${apiUrl} doctor\`. An agent sandbox may have different network access from your desktop.` });
   }
-  if (!health?.minimumCliVersion || !health.recommendedCliVersion) {
+  if (!health) {
+    checks.push({ name: "cli_version", status: "skip", message: `CLI ${dependencies.cliVersion} compatibility was not checked because the API is unreachable.`, version: dependencies.cliVersion });
+  } else if (!health.minimumCliVersion || !health.recommendedCliVersion) {
     checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} could not be checked against the API compatibility policy.`, version: dependencies.cliVersion, recovery: "Deploy a Rill API that advertises minimumCliVersion and recommendedCliVersion." });
   } else if (compareVersions(dependencies.cliVersion, health.minimumCliVersion) < 0) {
     checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} is older than the minimum supported version ${health.minimumCliVersion}.`, version: dependencies.cliVersion, recovery: `Run \`npm install --global @runalabs/rill-cli@${health.recommendedCliVersion}\`.` });
@@ -16643,20 +16846,23 @@ async function runDoctor(apiUrl, overrides = {}) {
       }
     }
   }
-  checks.push(await executableCheck("chrome", dependencies.chromePath, ["--version"], dependencies.commandVersion, "Install Google Chrome or Chromium, or set RILL_CHROME_PATH to its executable."));
+  checks.push(await executableCheck("chrome", dependencies.chromePath, ["--version"], dependencies.commandVersion, `Chrome must be available in this ${dependencies.platform} execution environment. Install Chrome/Chromium here or set RILL_CHROME_PATH. A browser on a separate desktop is not automatically accessible; use that desktop's terminal to record locally.`));
   if (dependencies.encoding === "local") {
     checks.push(await executableCheck("ffmpeg", dependencies.ffmpegPath, ["-version"], dependencies.commandVersion, dependencies.platform === "darwin" ? "Install ffmpeg with `brew install ffmpeg`, or set RILL_FFMPEG." : "Install ffmpeg using the system package manager, or set RILL_FFMPEG."));
   } else {
     checks.push({ name: "ffmpeg", status: "skip", message: "Remote encoding does not require local FFmpeg." });
-    try {
-      const token = await dependencies.loadCredential(apiUrl);
-      if (!(token ? (await dependencies.encodingCapabilities(apiUrl, token)).enabled : health?.anonymousAccess && health.anonymousRemoteEncoding)) throw new Error("Remote encoding is not enabled for this workspace.");
-      checks.push({ name: "encoding", status: "pass", message: token ? "Remote encoding is enabled." : "Remote encoding is available for the first anonymous recording." });
-    } catch (error51) {
-      checks.push({ name: "encoding", status: "fail", message: errorMessage(error51), recovery: "Run doctor --encoding local to check local FFmpeg, then record start --encoding local, or ask the workspace owner to enable remote encoding." });
+    if (!health) checks.push({ name: "encoding", status: "skip", message: "Remote encoding was not checked because the API is unreachable." });
+    else {
+      try {
+        const token = await dependencies.loadCredential(apiUrl);
+        if (!(token ? (await dependencies.encodingCapabilities(apiUrl, token)).enabled : health?.anonymousAccess && health.anonymousRemoteEncoding)) throw new Error("Remote encoding is not enabled for this workspace.");
+        checks.push({ name: "encoding", status: "pass", message: token ? "Remote encoding is enabled." : "Remote encoding is available for the first anonymous recording." });
+      } catch (error51) {
+        checks.push({ name: "encoding", status: "fail", message: errorMessage(error51), recovery: "Run doctor --encoding local to check local FFmpeg, then record start --encoding local, or ask the workspace owner to enable remote encoding." });
+      }
     }
   }
-  return { schemaVersion: 1, status: checks.some((check2) => check2.status === "fail") ? "error" : "ok", apiUrl, checks, ...runFeedbackFields(feedbackEnabled) };
+  return { schemaVersion: 1, status: checks.some((check2) => check2.status === "fail") ? "error" : "ok", apiUrl, environment: { platform: dependencies.platform }, checks, ...runFeedbackFields(feedbackEnabled) };
 }
 async function executableCheck(name, path, args, run2, recovery) {
   try {
@@ -16778,6 +16984,48 @@ async function remoteAwareRecordingStatus(recordingId, dependencies, apiUrl = "h
     return remoteView;
   }
 }
+async function releaseFailedLocalCapture(id, dependencies) {
+  const local = await dependencies.localStatus(id).catch(() => null);
+  if (!local || local.recordingId !== id || local.status !== "failed" || local.result) return false;
+  try {
+    await dependencies.failRemote(id);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function createRecordingWithRecovery(dependencies) {
+  try {
+    return await dependencies.createRemote();
+  } catch (error51) {
+    if (!(error51 instanceof ControlPlaneError) || error51.code !== "quota_exceeded") throw error51;
+    const quota = error51.details?.quota;
+    if (!quota || !["credential_concurrency", "workspace_concurrency"].includes(String(quota.type)) || typeof quota.blockingRecordingId !== "string" || !/^rec_[a-zA-Z0-9_-]+$/.test(quota.blockingRecordingId)) throw error51;
+    if (!await releaseFailedLocalCapture(quota.blockingRecordingId, dependencies)) throw error51;
+    dependencies.onRecovered?.(quota.blockingRecordingId);
+    return dependencies.createRemote();
+  }
+}
+async function stopRecordingWithCompensation(id, dependencies, apiUrl) {
+  let local;
+  try {
+    local = await dependencies.stopLocal(id);
+  } catch (error51) {
+    const known = await dependencies.localStatus(id).catch(() => null);
+    if (!known || known.recordingId !== id || known.status !== "failed" || known.result) throw error51;
+    local = known;
+  }
+  if (local.recordingId === id && local.status === "failed" && !local.result) {
+    const released = await releaseFailedLocalCapture(id, dependencies);
+    throw new ControlPlaneError(
+      "local_capture_failed",
+      local.error ?? "The local capture could not be finalized.",
+      released ? "Its unused recording slot was released. Start a new recording." : `The recording slot could not be released automatically. Check ${cliCommand(apiUrl, "record", "status", id)} before cancelling it.`,
+      { recordingId: id, reservationReleased: released }
+    );
+  }
+  return local;
+}
 
 // src/config.ts
 var PRODUCTION_API_URL = "https://userill.dev";
@@ -16797,13 +17045,23 @@ function watchEncoding(apiUrl, id) {
   child.unref();
 }
 var program = new Command();
-program.name("rill").description("Record, inspect, and share agent browser runs.").version(CLI_VERSION).option("--api-url <url>", "Rill control plane", controlPlaneUrl(process.env.RILL_API_URL)).option("--pretty", "Pretty-print JSON output", false).option("--json", "Output cloud run results as JSON", false);
+program.name("rill").description("Record, inspect, and share agent browser runs.").version(CLI_VERSION).option("--api-url <url>", "Rill control plane", controlPlaneUrl(process.env.RILL_API_URL)).option("--pretty", "Pretty-print JSON output", false).option("--json", "Output machine-readable JSON (including whoami)", false).option("--human", "Readable doctor, login, whoami and recording start/stop/status/retry output", false);
+program.configureOutput({ outputError: () => void 0 }).exitOverride();
+function humanOutput(identity = false) {
+  const options = program.opts();
+  return !options.json && !options.pretty && (identity || options.human);
+}
+function emitRecording(value, pretty) {
+  if (humanOutput()) process.stdout.write(formatRecording(value, program.opts().apiUrl));
+  else emit(value, pretty);
+}
 var activeTelemetry = null;
 program.command("daemon", { hidden: true }).action(() => runDaemon());
 program.command("doctor").description("Validate Rill prerequisites before recording.").option("--encoding <mode>", "remote or local", "remote").action(async (commandOptions) => {
   const options = program.opts();
   const result = await runDoctor(options.apiUrl, { encoding: commandOptions.encoding });
-  emit(result, options.pretty);
+  if (humanOutput()) process.stdout.write(formatDoctor(result));
+  else emit(result, options.pretty);
   if (result.status === "error") process.exitCode = 1;
 });
 async function authorize(quiet = false) {
@@ -16824,15 +17082,19 @@ async function authorize(quiet = false) {
     if (result.status === "pending") continue;
     if (result.status !== "approved" || !result.token) throw new Error(`Device authorization ${result.status}.`);
     await saveCredential(options.apiUrl, result.token);
-    if (!quiet) emit({ schemaVersion: 1, status: "authenticated", expiresAt: result.expiresAt, apiUrl: options.apiUrl }, options.pretty);
+    if (!quiet) {
+      if (humanOutput()) process.stdout.write("\u2713 Signed in to Rill\nCheck your account: rill whoami\n");
+      else emit({ schemaVersion: 1, status: "authenticated", expiresAt: result.expiresAt, apiUrl: options.apiUrl }, options.pretty);
+    }
     return result.token;
   }
   throw new Error("Device authorization expired.");
 }
-program.command("whoami").description("Show the current verified agent identity without starting sign-in.").action(async () => {
+program.command("whoami").description("Show the current verified identity without starting sign-in.").addHelpText("after", "\nShows a short account summary by default. Use rill whoami --json for agents, or rill --pretty whoami for indented JSON.").action(async () => {
   const options = program.opts();
   const identity = await whoami(options.apiUrl);
-  emit(identity, options.pretty);
+  if (humanOutput(true)) process.stdout.write(formatIdentity(identity));
+  else emit(identity, options.pretty);
   if (!identity.authenticated) process.exitCode = 1;
 });
 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) => {
@@ -16881,9 +17143,14 @@ for (const action of ["status", "cancel"]) cloudRun.command(action).argument("<r
   if (options.json || options.pretty) emit(customerRun(run2), options.pretty);
   else process.stdout.write(formatCloudRun(run2));
 });
-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) => {
+record2.command("tabs").requiredOption("--cdp-url <url>", "Existing Chromium CDP endpoint").action(async (commandOptions) => {
+  const options = program.opts();
+  emit({ schemaVersion: 1, tabs: await listBrowserTabs(commandOptions.cdpUrl) }, options.pretty);
+});
+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("--tab-id <id>", "Record this existing tab from record tabs").option("--width <pixels>", "", "1280").option("--height <pixels>", "", "720").option("--max-duration <seconds>", "", "600").action(async (commandOptions) => {
   const options = program.opts();
   assertRecorderTransport();
+  validateTabSelection(commandOptions);
   await ensureAnonymousCredential(options.apiUrl);
   const client = new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl));
   const result = await withRunFeedback(() => client.agentSession(), async (rememberRecording) => {
@@ -16892,12 +17159,21 @@ record2.command("start").option("--encoding <mode>", "remote or local", "remote"
     if (!Number.isFinite(Number(commandOptions.maxDuration)) || Number(commandOptions.maxDuration) < 1 || Number(commandOptions.maxDuration) > 600) throw new Error("Recording duration must be between 1 and 600 seconds.");
     const width = Number(commandOptions.width);
     const height = Number(commandOptions.height);
-    const remote = await client.createRecording({ title: commandOptions.title ?? `Browser recording \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`, description: commandOptions.description, sourceUrl: commandOptions.url ?? null, width, height });
+    const metadata = { requestId: crypto.randomUUID(), title: commandOptions.title ?? `Browser recording \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`, description: commandOptions.description, sourceUrl: commandOptions.url ?? null, width, height };
+    const remote = await createRecordingWithRecovery({
+      createRemote: () => client.createRecording(metadata),
+      localStatus: recordingStatus,
+      failRemote: (id) => client.failLocalCapture(id),
+      onRecovered: (id) => {
+        process.stderr.write(`Released the unused slot for failed local capture ${id}.
+`);
+      }
+    });
     rememberRecording(remote.recordingId);
     const local = await startRecordingWithCompensation(remote, {
       startLocal: async () => {
-        await ensureDaemon(process.argv[1]);
-        return startRecording({ encoding: commandOptions.encoding, recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600), captureNetworkBodies: remote.bodyCaptureEnabled, cursorAppearance: remote.cursorAppearance });
+        await ensureDaemon(process.argv[1], Boolean(commandOptions.cdpUrl));
+        return startRecording({ encoding: commandOptions.encoding, recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, tabId: commandOptions.tabId, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600), captureNetworkBodies: remote.bodyCaptureEnabled, cursorAppearance: remote.cursorAppearance });
       },
       cancelRemote: (recordingId, reason) => client.cancelRecording(recordingId, reason)
     }, options.apiUrl);
@@ -16908,16 +17184,20 @@ 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, browserAttachment: browserAttachment(local.cdpUrl), startedAt: local.startedAt, stopsAt: local.stopsAt, elapsedSeconds: local.elapsedSeconds, remainingSeconds: local.remainingSeconds, 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, ...local.tabId ? { tabId: local.tabId } : {}, browserAttachment: browserAttachment(local.cdpUrl, local.tabId), startedAt: local.startedAt, stopsAt: local.stopsAt, elapsedSeconds: local.elapsedSeconds, remainingSeconds: local.remainingSeconds, bodyCaptureEnabled: remote.bodyCaptureEnabled, anonymous: remote.anonymous ?? false, expiresAt: remote.expiresAt ?? null, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600) };
   });
-  emit(result, options.pretty);
+  emitRecording(result, options.pretty);
 });
 record2.command("stop").argument("<recording-id>").option("--no-wait").option("--no-feedback", "Disable feedback only when the user explicitly requests it").action(async (recordingId, commandOptions) => {
   const options = program.opts();
   await ensureDaemon(process.argv[1]);
-  const local = await stopRecording(recordingId);
-  if (!local.result) throw new Error(local.error ?? "The recorder did not produce an artifact.");
   const client = new ControlPlaneClient(options.apiUrl, () => loadCredential(options.apiUrl));
+  const local = await stopRecordingWithCompensation(recordingId, {
+    stopLocal: stopRecording,
+    localStatus: recordingStatus,
+    failRemote: (id) => client.failLocalCapture(id)
+  }, options.apiUrl);
+  if (!local.result) throw new Error(local.error ?? "The recorder did not produce an artifact.");
   const stopped = await client.markRecordingStopped(recordingId, {
     durationSeconds: local.result.durationSeconds,
     stoppedReason: local.result.stoppedReason,
@@ -16928,7 +17208,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, ...recordingNextStep(options.apiUrl, recordingId, result2.status, { resumableFrames: true }), ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false) }, options.pretty);
+    emitRecording({ schemaVersion: 1, ...result2, recordingId, ...recordingNextStep(options.apiUrl, recordingId, result2.status, { resumableFrames: true }), ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false) }, options.pretty);
     if (result2.status === "ready") await rm7(dirname2(local.result.videoPath), { recursive: true, force: true });
     else watchEncoding(options.apiUrl, recordingId);
     return;
@@ -16950,7 +17230,7 @@ record2.command("stop").argument("<recording-id>").option("--no-wait").option("-
     ...recordingNextStep(options.apiUrl, recordingId, remote ? "ready" : "processing"),
     ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false)
   };
-  emit(result, options.pretty);
+  emitRecording(result, options.pretty);
   if (remote) await rm7(dirname2(local.result.videoPath), { recursive: true, force: true });
 });
 record2.command("retry").argument("<recording-id>").option("--no-wait").action(async (recordingId, commandOptions) => {
@@ -16971,7 +17251,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, ...recordingNextStep(options.apiUrl, recordingId, result.status, { resumableFrames: true }) }, options.pretty);
+  emitRecording({ schemaVersion: 1, ...result, recordingId, ...recordingNextStep(options.apiUrl, recordingId, result.status, { resumableFrames: true }) }, options.pretty);
   if (result.status === "ready") await removeLocalCapture(recordingId);
   else watchEncoding(options.apiUrl, recordingId);
 });
@@ -17013,7 +17293,7 @@ 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", ...recordingNextStep(options.apiUrl, recordingId, encoding.status, { resumableFrames: true }) }, options.pretty);
+    emitRecording({ 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) {
@@ -17026,7 +17306,7 @@ record2.command("status").argument("<recording-id>").action(async (recordingId)
     },
     remoteStatus: (id) => client.recordingStatus(id)
   }, options.apiUrl);
-  emit({ schemaVersion: 1, ...status }, options.pretty);
+  emitRecording({ schemaVersion: 1, ...status, recordingId }, options.pretty);
 });
 record2.command("cancel").argument("<recording-id>").description("Cancel an active recording and release its remote quota slot.").action(async (recordingId) => {
   const options = program.opts();
@@ -17106,8 +17386,20 @@ program.hook("postAction", async () => {
   await finishCliTelemetry(process.exitCode ? new Error("command_reported_failure: Command returned a failure status.") : null);
 });
 program.parseAsync().catch(async (error51) => {
+  if (error51 instanceof CommanderError && error51.exitCode === 0) return;
+  if (error51 instanceof CommanderError) {
+    const action = program.args[0] === "record" ? program.args[1] : void 0;
+    const missingRecording = error51.code === "commander.missingArgument" && ["stop", "status", "retry", "cancel"].includes(action ?? "");
+    error51 = Object.assign(new Error(`validation_failed: ${missingRecording ? "A recording ID is required." : error51.message.replace(/^error: /, "")}`), {
+      code: "validation_failed",
+      recovery: missingRecording ? `Run rill record ${action} <recording-id>. Use rill record list to find the ID.` : "Run rill --help for available commands and options."
+    });
+  }
   await finishCliTelemetry(error51);
-  fail(error51);
+  if (humanOutput(program.args[0] === "whoami")) {
+    process.stderr.write(formatFailure(error51));
+    process.exitCode = 1;
+  } else fail(error51);
 });
 function commandPath(actionCommand) {
   const path = [];

package/package.json

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