@tryarcanist/cli 0.1.166 → 0.1.168

package/README.md

@@ -53,9 +53,12 @@ Supported environment variables:
 ```bash
 export ARCANIST_TOKEN=arc_...
 export ARCANIST_API_URL=https://api.tryarcanist.com
+export ARCANIST_HTTP_TIMEOUT_MS=30000
 ```
 
 `--token` and `--api-url` are available for one-off invocations. Prefer `ARCANIST_TOKEN` over `--token` for persistent use; CLI flags can appear in shell history and process lists.
+Each HTTP request times out after `ARCANIST_HTTP_TIMEOUT_MS` milliseconds, default `30000`.
+The value must be between `1000` and `600000`; invalid values fail closed instead of falling back silently.
 
 Non-local API URLs must use HTTPS and must not embed credentials.
 
@@ -89,10 +92,18 @@ With `--json`, successful command output is machine-readable and newline-termina
 
 ```json
 {
-  "error": { "code": "auth", "message": "Not logged in.", "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`." }
+  "error": {
+    "code": "auth",
+    "message": "Not logged in.",
+    "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`.",
+    "data": { "serverCode": "token_revoked" }
+  }
 }
 ```
 
+`error.data` is omitted when there is no structured recovery data.
+Stable fields are `serverCode` for server-provided error codes and `sessionId`/`sessionUrl` when `sessions create` created the session but failed to enqueue the prompt.
+
 Exit codes:
 
 ```text
@@ -159,12 +170,45 @@ Repeatable `--uploaded-file <path>` flags attach local UTF-8 text files to the p
 
 `--cold` is a deprecated no-op retained for backward compatibility. Sessions always start from a fresh sandbox (the warm sandbox pool was removed), so the flag has no effect.
 
-`--idempotency-key <uuid>` is for manually retrying a create request that may have reached the server. The CLI derives separate session and prompt idempotency keys from the provided value.
+`--idempotency-key <uuid>` is for manually retrying a create request that may have reached the server.
+The CLI derives separate session and prompt idempotency keys from the provided value.
 
 `--onboarding` creates an onboarding session: the agent authors the repo's `.arcanist.json`, `.arcanist/` runtime files, `ARCANIST.md`, and conditionally `.arcanist/sandbox.yaml` + `.arcanist/sandbox.layer.Dockerfile` (when the base sandbox lacks a needed toolchain), proves what it can inside its sandbox, and opens the setup PR ready for review. The onboarding behavior is driven by the bridge's canonical onboarding playbook, not the prompt, so `--onboarding` needs no prompt: `arcanist sessions create <repo> --onboarding --wait`. Any prompt supplied alongside `--onboarding` is ignored. Team use; not part of the external API surface.
 
 JSON mode returns `{sessionId, sessionUrl?, repoUrl, model?, agentRuntimeBackend?, reasoningEffort?, baseBranch?, startBranch?, continuePrUrl?, continueMode?, onboarding?, promptId?}`. `sessionUrl` is emitted only when the server returns it; `agentRuntimeBackend` only when `--backend` is passed. With `--wait`, JSON mode also includes best-effort result fields when available: `prUrl?`, `publishedBranch?`, and `lastBranch?`.
 
+### `arcanist sessions qa <pr-url>`
+
+Starts a QA verification session for an existing GitHub pull request.
+
+```bash
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --model gpt-5.4
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --backend claude_code --model claude-opus-4-8
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --reasoning-effort xhigh
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --wait
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --idempotency-key 1f0e6f1a-...
+```
+
+The PR URL must be `https://github.com/<owner>/<repo>/pull/<number>`.
+The CLI derives the repo from that URL, creates a QA session with `qa: true` and `targetPrUrl`, then enqueues the verifier prompt.
+Inspect progress with the session URL or the session events stream.
+
+`--backend` picks the agent runtime backend: `codex` (default), `claude_code`, or `opencode`.
+`--model` must be valid for the chosen backend, and the CLI rejects mismatches before any network call.
+When `--model` is omitted, the backend default is used.
+
+`--wait` blocks until the enqueued QA prompt finishes and exits non-zero if the prompt fails.
+JSON mode waits quietly and prints the create payload after the prompt completes successfully.
+`--poll-interval <ms>` tunes completion polling.
+
+`--idempotency-key <uuid>` is for manually retrying a QA request that may have reached the server.
+The CLI derives separate session and prompt idempotency keys from the provided value.
+If session creation succeeds but prompt enqueue fails, retry the same command with the same `--idempotency-key`.
+
+JSON mode returns `{sessionId, sessionUrl?, repoUrl, targetPrUrl, model?, agentRuntimeBackend?, reasoningEffort?, promptId?}`.
+Active-verifier and per-PR run-limit conflicts both use exit code `4`; active-verifier errors include the existing session handle when the server returns it.
+
 ### `arcanist sessions send <session-id> [prompt]`
 
 Sends a follow-up message to an existing session.

package/dist/index.js

@@ -24,6 +24,7 @@ var CliError = class extends Error {
   exitCode;
   hint;
   requestId;
+  data;
   constructor(code, message, options = {}) {
     super(message);
     this.name = "CliError";
@@ -31,17 +32,20 @@ var CliError = class extends Error {
     this.exitCode = options.exitCode ?? exitCodeForErrorCode(code);
     this.hint = options.hint;
     this.requestId = options.requestId;
+    this.data = options.data;
   }
 };
 var ApiError = class extends CliError {
   status;
   body;
-  constructor(status, body, requestId) {
+  constructor(status, body, requestId, resourceNoun) {
     const code = codeForHttpStatus(status);
-    super(code, messageForApiError(status, body), {
+    const parsed = parseApiErrorBody(body);
+    super(code, messageForApiError(status, body, parsed), {
       exitCode: exitCodeForHttpStatus(status),
-      hint: hintForHttpStatus(status),
-      requestId
+      hint: hintForHttpStatus(status, resourceNoun),
+      requestId,
+      data: parsed?.serverCode ? { serverCode: parsed.serverCode } : void 0
     });
     this.name = "ApiError";
     this.status = status;
@@ -73,9 +77,9 @@ function codeForHttpStatus(status) {
 function exitCodeForHttpStatus(status) {
   return exitCodeForErrorCode(codeForHttpStatus(status));
 }
-function messageForApiError(status, body) {
-  const parsed = parseApiErrorBody(body);
-  if (parsed) return parsed;
+function messageForApiError(status, body, parsed = parseApiErrorBody(body)) {
+  if (parsed?.message) return parsed.message;
+  if (parsed?.serverCode) return parsed.serverCode;
   return body ? `API error ${status}: ${body}` : `API error ${status}`;
 }
 function parseApiErrorBody(body) {
@@ -83,14 +87,36 @@ function parseApiErrorBody(body) {
     const parsed = JSON.parse(body);
     if (!parsed || typeof parsed !== "object") return null;
     const error = parsed.error;
-    return typeof error === "string" && error.length > 0 ? error : null;
+    if (typeof error === "string" && error.length > 0) {
+      const message2 = parsed.message;
+      const code = parsed.code;
+      return {
+        serverCode: typeof code === "string" && code ? code : error,
+        ...typeof message2 === "string" && message2 ? { message: message2 } : { message: error }
+      };
+    }
+    if (error && typeof error === "object") {
+      const code = error.code;
+      const message2 = error.message;
+      return {
+        ...typeof message2 === "string" && message2 ? { message: message2 } : {},
+        ...typeof code === "string" && code ? { serverCode: code } : {}
+      };
+    }
+    const message = parsed.message;
+    return typeof message === "string" && message.length > 0 ? { message } : null;
   } catch {
     return null;
   }
 }
-function hintForHttpStatus(status) {
+function hintForHttpStatus(status, resourceNoun) {
   if (status === 401 || status === 403) return "Run `arcanist auth login` or set `ARCANIST_TOKEN`.";
-  if (status === 404) return "List sessions with `arcanist sessions list`.";
+  if (status === 404) {
+    if (resourceNoun === "token") return "List tokens with `arcanist tokens list`.";
+    if (resourceNoun === "sandbox") return "Check sandbox state with `arcanist sandbox status`.";
+    if (resourceNoun === "repo") return "Check accessible repositories with `arcanist repos list`.";
+    return "List sessions with `arcanist sessions list`.";
+  }
   if (status === 409) return "Check the current resource state and retry the command when it is ready.";
   if (status >= 500) return "Retry later or check the control-plane logs.";
   return void 0;
@@ -106,7 +132,8 @@ function formatJsonError(err) {
       code: err.code,
       message: err.message,
       ...err.hint ? { hint: err.hint } : {},
-      ...err.requestId ? { requestId: err.requestId } : {}
+      ...err.requestId ? { requestId: err.requestId } : {},
+      ...err.data ? { data: err.data } : {}
     }
   });
 }
@@ -115,33 +142,72 @@ function formatJsonError(err) {
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 var CLI_USER_AGENT = `arcanist-cli/${version}`;
-async function apiRequest(config, path, init) {
-  let res;
+var DEFAULT_HTTP_TIMEOUT_MS = 3e4;
+var MIN_HTTP_TIMEOUT_MS = 1e3;
+var MAX_HTTP_TIMEOUT_MS = 6e5;
+var HTTP_TIMEOUT_ENV = "ARCANIST_HTTP_TIMEOUT_MS";
+function parseHttpTimeoutMs(env = process.env) {
+  const raw = env[HTTP_TIMEOUT_ENV];
+  if (!raw) return DEFAULT_HTTP_TIMEOUT_MS;
+  if (!/^\d+$/.test(raw)) {
+    throw new CliError("user", `${HTTP_TIMEOUT_ENV} must be a positive integer between 1000 and 600000.`);
+  }
+  const value = Number(raw);
+  if (value < MIN_HTTP_TIMEOUT_MS || value > MAX_HTTP_TIMEOUT_MS) {
+    throw new CliError("user", `${HTTP_TIMEOUT_ENV} must be between 1000 and 600000 milliseconds.`);
+  }
+  return value;
+}
+function isAbortError(err) {
+  return err instanceof DOMException && err.name === "AbortError";
+}
+function timeoutError(timeoutMs) {
+  return new CliError("server", `Network timeout after ${timeoutMs}ms.`, {
+    hint: `Increase ${HTTP_TIMEOUT_ENV} for slow links, or check the API connection.`
+  });
+}
+async function apiRequest(config, path, init, read) {
+  const timeoutMs = parseHttpTimeoutMs();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const headers = new Headers(init?.headers);
     headers.set("Content-Type", "application/json");
     headers.set("User-Agent", CLI_USER_AGENT);
     headers.set("Authorization", `Bearer ${config.token}`);
-    res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
+    const res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
       ...init,
-      headers
+      headers,
+      signal: controller.signal
     });
+    if (!res.ok) {
+      const body = await res.text().catch((err) => {
+        if (isAbortError(err)) throw timeoutError(timeoutMs);
+        return "";
+      });
+      throw new ApiError(res.status, body, res.headers.get("x-request-id") ?? void 0, resourceNounForPath(path));
+    }
+    return await read(res);
   } catch (err) {
+    if (err instanceof CliError) throw err;
+    if (isAbortError(err)) throw timeoutError(timeoutMs);
     throw new CliError("server", `Network error: ${stringifyError(err)}`);
+  } finally {
+    clearTimeout(timeout);
   }
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new ApiError(res.status, body, res.headers.get("x-request-id") ?? void 0);
-  }
-  return res;
+}
+function resourceNounForPath(path) {
+  if (path.startsWith("/api/cli-tokens")) return "token";
+  if (path.startsWith("/api/repos")) return "repo";
+  if (path.startsWith("/api/sandbox")) return "sandbox";
+  if (path.startsWith("/api/sessions")) return "session";
+  return void 0;
 }
 async function apiFetch(config, path, init) {
-  const res = await apiRequest(config, path, init);
-  return res.json();
+  return apiRequest(config, path, init, (res) => res.json());
 }
 async function apiFetchText(config, path, init) {
-  const res = await apiRequest(config, path, init);
-  return res.text();
+  return apiRequest(config, path, init, (res) => res.text());
 }
 async function resolveBusinessId(config, options) {
   if (options.business && options.business.trim()) return options.business.trim();
@@ -1126,8 +1192,9 @@ function isTerminalPhase(phase, _sessionKind) {
 }
 
 // src/constants/watch.ts
-var MIN_WATCH_POLL_INTERVAL_MS = 1;
+var MIN_WATCH_POLL_INTERVAL_MS = 250;
 var DEFAULT_WATCH_POLL_INTERVAL_MS = 1e3;
+var MAX_WATCH_POLL_INTERVAL_MS = 6e4;
 var WATCH_REPLAY_PAGE_SIZE = 200;
 function isWatchTerminal(phase) {
   return isTerminalPhase(phase);
@@ -2655,6 +2722,31 @@ function renderWatchEvent(event, state) {
   }
 }
 
+// src/commands/model-options.ts
+function resolveModelAndBackend(options) {
+  let agentRuntimeBackend = CODEX_AGENT_RUNTIME_BACKEND;
+  if (options.backend !== void 0) {
+    if (!isAgentRuntimeBackend(options.backend)) {
+      throw new CliError(
+        "user",
+        `Invalid --backend '${options.backend}'. Expected ${AGENT_RUNTIME_BACKENDS.join(", ")}.`
+      );
+    }
+    agentRuntimeBackend = options.backend;
+  }
+  if (options.model !== void 0) {
+    const normalizedModel = extractModelId(options.model);
+    if (normalizedModel === void 0 || !isSessionStartModelAllowedForBackend(normalizedModel, agentRuntimeBackend)) {
+      const allowed = getSessionStartModelIdsForBackend(agentRuntimeBackend).join(", ");
+      throw new CliError(
+        "user",
+        `Model '${options.model}' is not selectable for backend '${agentRuntimeBackend}'. Allowed: ${allowed}.`
+      );
+    }
+  }
+  return agentRuntimeBackend;
+}
+
 // ../../shared/session/transient-disconnect.ts
 var TRANSIENT_DISCONNECT_VISIBILITY_MS = 15e3;
 function nextDisconnectMask(mask, previous, current, now) {
@@ -2677,7 +2769,14 @@ function parsePollInterval(raw) {
   if (!/^\d+$/.test(raw)) {
     throw new CliError("user", "Polling interval must be a non-negative integer.");
   }
-  return Number(raw);
+  const value = Number(raw);
+  if (value < MIN_WATCH_POLL_INTERVAL_MS || value > MAX_WATCH_POLL_INTERVAL_MS) {
+    throw new CliError(
+      "user",
+      `Polling interval must be between ${MIN_WATCH_POLL_INTERVAL_MS} and ${MAX_WATCH_POLL_INTERVAL_MS} milliseconds.`
+    );
+  }
+  return value;
 }
 function parseNonNegativeInteger(raw, name, defaultValue) {
   if (!raw) return defaultValue;
@@ -2737,7 +2836,6 @@ async function watchCommand(sessionId, options, command) {
   const runtime = getRuntimeOptions(command, options);
   const config = requireConfig(runtime);
   const pollIntervalMs = parsePollInterval(options.pollInterval);
-  const effectivePollIntervalMs = Math.max(pollIntervalMs, MIN_WATCH_POLL_INTERVAL_MS);
   const initialAfterSequence = parseNonNegativeInteger(options.afterSequence, "--after-sequence", 0);
   const pageSize = parseNonNegativeInteger(options.limit, "--limit", WATCH_REPLAY_PAGE_SIZE);
   if (pageSize === 0) {
@@ -2820,7 +2918,7 @@ async function watchCommand(sessionId, options, command) {
         }
         break;
       }
-      await sleep(effectivePollIntervalMs);
+      await sleep(pollIntervalMs);
     }
   } finally {
     if (textOpen) process.stdout.write("\n");
@@ -2930,26 +3028,7 @@ async function createCommand(repoUrl, promptArg, options, command) {
   const runtime = getRuntimeOptions(command, options);
   assertArcanistSessionMutationAllowed("create");
   const config = requireConfig(runtime);
-  let agentRuntimeBackend = CODEX_AGENT_RUNTIME_BACKEND;
-  if (options.backend !== void 0) {
-    if (!isAgentRuntimeBackend(options.backend)) {
-      throw new CliError(
-        "user",
-        `Invalid --backend '${options.backend}'. Expected ${AGENT_RUNTIME_BACKENDS.join(", ")}.`
-      );
-    }
-    agentRuntimeBackend = options.backend;
-  }
-  if (options.model !== void 0) {
-    const normalizedModel = extractModelId(options.model);
-    if (normalizedModel === void 0 || !isSessionStartModelAllowedForBackend(normalizedModel, agentRuntimeBackend)) {
-      const allowed = getSessionStartModelIdsForBackend(agentRuntimeBackend).join(", ");
-      throw new CliError(
-        "user",
-        `Model '${options.model}' is not selectable for backend '${agentRuntimeBackend}'. Allowed: ${allowed}.`
-      );
-    }
-  }
+  const agentRuntimeBackend = resolveModelAndBackend(options);
   const prompt = options.onboarding ? ONBOARDING_PROMPT : await resolvePromptInput(promptArg, options);
   const waitPollIntervalMs = options.wait ? parsePollInterval(options.pollInterval) : null;
   const repoError = validateRepoUrl(repoUrl);
@@ -3014,7 +3093,12 @@ async function createCommand(repoUrl, promptArg, options, command) {
       {
         exitCode: err instanceof CliError ? err.exitCode : void 0,
         hint: `Retry with: arcanist sessions send ${sessionId} --prompt-stdin`,
-        requestId: err instanceof CliError ? err.requestId : void 0
+        requestId: err instanceof CliError ? err.requestId : void 0,
+        data: {
+          ...err instanceof CliError && err.data ? err.data : {},
+          sessionId,
+          ...sessionData.sessionUrl ? { sessionUrl: sessionData.sessionUrl } : {}
+        }
       }
     );
   }
@@ -3226,16 +3310,16 @@ async function loginCommand(options, command) {
     console.log(`Logged in. API: ${apiUrl}`);
   }
   try {
-    const res = await fetch(`${apiUrl}/api/cli-tokens`, {
-      headers: { Authorization: `Bearer ${token}`, "User-Agent": CLI_USER_AGENT }
-    });
-    if (res.ok && !runtime.json && !runtime.quiet) {
-      console.log("Token verified.");
-    } else if (res.status === 401 && !runtime.json && !runtime.quiet) {
-      console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
+    await apiFetch({ apiUrl, token }, "/api/cli-tokens");
+    if (!runtime.json && !runtime.quiet) console.log("Token verified.");
+  } catch (err) {
+    if (!runtime.json && !runtime.quiet) {
+      if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
+        console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
+      } else {
+        console.warn("Warning: Could not reach API to verify token.");
+      }
     }
-  } catch {
-    if (!runtime.json && !runtime.quiet) console.warn("Warning: Could not reach API to verify token.");
   }
 }
 
@@ -3263,6 +3347,137 @@ async function messageCommand(sessionId, promptArg, options = {}, command) {
   console.log(`Message sent to session ${sessionId}.`);
 }
 
+// ../../shared/agent/verify-directive.ts
+var MAX_TARGET_PR_URL_LENGTH = 500;
+function normalizeGithubPullRequestUrl(rawUrl) {
+  if (typeof rawUrl !== "string") return null;
+  const trimmed = rawUrl.trim();
+  if (!trimmed || trimmed.length > MAX_TARGET_PR_URL_LENGTH) return null;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.hostname.toLowerCase() !== "github.com") return null;
+  const pathParts = url.pathname.split("/").filter(Boolean);
+  if (pathParts.length !== 4 || pathParts[2] !== "pull" || !/^\d+$/.test(pathParts[3])) return null;
+  if (!/^[A-Za-z0-9_.-]+$/.test(pathParts[0]) || !/^[A-Za-z0-9_.-]+$/.test(pathParts[1])) return null;
+  return `https://github.com/${pathParts[0]}/${pathParts[1]}/pull/${pathParts[3]}`;
+}
+
+// src/commands/qa.ts
+var QA_PROMPT = "Verify this pull request.";
+function parseCanonicalPrUrl(prUrl) {
+  const targetPrUrl = normalizeGithubPullRequestUrl(prUrl);
+  if (!targetPrUrl) {
+    throw new CliError(
+      "user",
+      `Invalid pull request URL: "${prUrl}". Expected https://github.com/<owner>/<repo>/pull/<number>.`
+    );
+  }
+  const url = new URL(targetPrUrl);
+  const [owner, repo] = url.pathname.split("/").filter(Boolean);
+  return {
+    targetPrUrl,
+    repoUrl: `https://github.com/${owner}/${repo}`
+  };
+}
+function parseCreateConflict(error) {
+  let message = error.message;
+  let sessionId;
+  let sessionUrl;
+  try {
+    const parsed = JSON.parse(error.body);
+    const parsedMessage = typeof parsed.error === "string" ? parsed.error : typeof parsed.error?.message === "string" ? parsed.error.message : void 0;
+    if (parsedMessage) message = parsedMessage;
+    if (typeof parsed.sessionId === "string") sessionId = parsed.sessionId;
+    if (typeof parsed.sessionUrl === "string") sessionUrl = parsed.sessionUrl;
+  } catch {
+  }
+  const location = sessionUrl ? ` (${sessionUrl})` : "";
+  const existing = sessionId ? ` Existing verifier session: ${sessionId}${location}.` : "";
+  return new CliError("conflict", `${message}${existing}`, {
+    hint: error.hint,
+    requestId: error.requestId
+  });
+}
+async function qaCommand(prUrl, options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  assertArcanistSessionMutationAllowed("qa");
+  const config = requireConfig(runtime);
+  const { targetPrUrl, repoUrl } = parseCanonicalPrUrl(prUrl);
+  const agentRuntimeBackend = resolveModelAndBackend(options);
+  const idempotencyKey = options.idempotencyKey ?? randomIdempotencyKey();
+  const sessionIdempotencyKey = `${idempotencyKey}:session`;
+  const promptIdempotencyKey = `${idempotencyKey}:prompt`;
+  const body = {
+    context: { repoUrl },
+    qa: true,
+    targetPrUrl
+  };
+  if (options.model) body.model = options.model;
+  if (options.backend) body.agentRuntimeBackend = agentRuntimeBackend;
+  if (options.reasoningEffort) body.reasoningEffort = options.reasoningEffort;
+  let sessionData;
+  try {
+    sessionData = await apiFetch(config, "/api/sessions", {
+      method: "POST",
+      headers: { "Idempotency-Key": sessionIdempotencyKey },
+      body: JSON.stringify(body)
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 409) throw parseCreateConflict(err);
+    throw err;
+  }
+  const sessionId = sessionData.sessionId;
+  let promptId;
+  try {
+    const promptData = await apiFetch(config, `/api/sessions/${sessionId}/prompts`, {
+      method: "POST",
+      headers: { "Idempotency-Key": promptIdempotencyKey },
+      body: JSON.stringify({ prompt: QA_PROMPT })
+    });
+    promptId = promptData.prompt?.promptId ?? promptData.prompt?.id;
+  } catch (err) {
+    throw new CliError(
+      err instanceof CliError ? err.code : "server",
+      `QA session created (${sessionId}) but prompt enqueue failed: ${stringifyError(err)}`,
+      {
+        exitCode: err instanceof CliError ? err.exitCode : void 0,
+        hint: `Retry with: arcanist sessions qa ${targetPrUrl} --idempotency-key ${idempotencyKey}`,
+        requestId: err instanceof CliError ? err.requestId : void 0
+      }
+    );
+  }
+  if (options.wait) {
+    const waitPollIntervalMs = parsePollInterval(options.pollInterval);
+    if (!isJson(command, options)) {
+      console.log(`Session: ${sessionId}`);
+      if (sessionData.sessionUrl) console.log(`URL: ${sessionData.sessionUrl}`);
+    }
+    await waitForCreatedPrompt(sessionId, promptId, sessionData.sessionUrl, waitPollIntervalMs, runtime, command);
+    if (!isJson(command, options)) {
+      console.log(`Target PR: ${targetPrUrl}`);
+    }
+  }
+  if (isJson(command, options)) {
+    const output = { sessionId, repoUrl, targetPrUrl };
+    if (sessionData.sessionUrl) output.sessionUrl = sessionData.sessionUrl;
+    if (options.model) output.model = options.model;
+    if (options.backend) output.agentRuntimeBackend = agentRuntimeBackend;
+    if (options.reasoningEffort) output.reasoningEffort = options.reasoningEffort;
+    if (promptId) output.promptId = promptId;
+    writeJson(output);
+    return;
+  }
+  if (options.wait) return;
+  console.log(`Session: ${sessionId}`);
+  if (sessionData.sessionUrl) console.log(`URL: ${sessionData.sessionUrl}`);
+  console.log(`Target PR: ${targetPrUrl}`);
+  console.log(`Follow with: arcanist sessions events ${sessionId} --follow --json`);
+}
+
 // src/commands/sandbox.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
@@ -4682,6 +4897,25 @@ JSON mode returns {sessionId, promptId?}
 `
   );
 }
+function addQaOptions(cmd) {
+  return cmd.argument("<pr-url>", "GitHub pull request URL to QA").option("--model <model>", "Model to use").option("--backend <backend>", "Agent runtime backend: codex (default), claude_code, or opencode").option("--reasoning-effort <effort>", "Reasoning effort to use for models that support it").option("--wait", "Wait for the QA prompt to finish and exit non-zero if it fails").option(
+    "--poll-interval <ms>",
+    "Polling interval in milliseconds while waiting",
+    String(DEFAULT_WATCH_POLL_INTERVAL_MS)
+  ).option("--idempotency-key <uuid>", "Request idempotency key for safe manual retries").addHelpText(
+    "after",
+    `
+Examples:
+  arcanist sessions qa https://github.com/org/repo/pull/123
+  arcanist sessions qa https://github.com/org/repo/pull/123 --model gpt-5.4 --wait
+  arcanist sessions qa https://github.com/org/repo/pull/123 --idempotency-key 1f0e6f1a-...
+
+JSON:
+JSON mode returns {sessionId, sessionUrl?, repoUrl, targetPrUrl, model?, agentRuntimeBackend?, reasoningEffort?, promptId?}
+  Inspect progress with the session URL or the session events stream.
+`
+  );
+}
 var auth = program.command("auth").description("Authentication commands");
 auth.command("login").description("Authenticate with a personal access token").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").addHelpText(
   "after",
@@ -4707,6 +4941,9 @@ addCreateOptions(sessions.command("create").description("Create a session and se
 addSendOptions(sessions.command("send").description("Send a message to an existing session")).action(
   (sessionId, prompt, options, command) => messageCommand(sessionId, prompt, options, command)
 );
+addQaOptions(sessions.command("qa").description("Start a QA verification session for a GitHub pull request")).action(
+  (prUrl, options, command) => qaCommand(prUrl, options, command)
+);
 sessions.command("stop").description("Stop the active run for a session").argument("<session-id>", "Session ID").addHelpText(
   "after",
   `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.166",
+  "version": "0.1.168",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {