@qawolf/cli 1.17.1 → 1.19.0

package/dist/cli.js

@@ -326107,6 +326107,8 @@ var interactMessages = {
   inspectNeedsABrowserRunner: "This runner is a mobile device, and element and page HTML are a browser's shapes. Retrying will never help. Launch a playwright runner to inspect one.",
   nothingToInspect: (errorMessage2) => `The runner had nothing to inspect${errorMessage2 === undefined ? "" : `: ${errorMessage2}`}. There is no live page, nothing matched the selector, or no variable has that name; a runner cannot tell those apart. Run a flow on it first, or check the selector or name.`,
   inspectAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
+  inspectMobileAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
+  runnerIsNotMobile: "This runner is not a mobile device, so there is nothing here to inspect. Retrying will never help: launch an android or ios runner instead.",
   screenNeedsARun: "This runner has not run anything yet, so its screen has never started. Waiting will not clear this and there is nothing to retry: run a flow on it with qawolf runner run, then ask again. Evaluating a snippet does not start a screen.",
   screenNotReady: "The runner has a screen and cannot serve this yet. Its virtual desktop restarts when a run changes the display size, and it serves one request at a time, so something already in flight is the usual reason. Retry in a second or two.",
   screenshotNotAnImage: "The screen was captured but did not arrive as a JPEG, so nothing was written. Nothing about the command needs changing: try it again, and report it if it keeps happening.",
@@ -326161,6 +326163,13 @@ var lifecycleMessages = {
   runnerUnreachable: "The runner could not be reached. It may still be starting, or it may have terminated after inactivity. Retry, or launch it again."
 };
 
+// src/core/messages/interactiveRunner/list.ts
+var listMessages = {
+  noRunners: "This directory has no runner running. Launch one with qawolf runner launch, or pass --runner to address a runner started elsewhere.",
+  runnerCount: (count) => count === 1 ? "1 runner" : `${String(count)} runners`,
+  title: "Runners"
+};
+
 // src/core/messages/interactiveRunner/run.ts
 var runMessages = {
   envFileUnparseable: (reason) => `The --env-file could not be read. ${reason}`,
@@ -326198,6 +326207,7 @@ var runMessages = {
 // src/core/messages/interactiveRunner/index.ts
 var interactiveRunnerMessages = {
   ...lifecycleMessages,
+  ...listMessages,
   ...runMessages,
   ...interactMessages
 };
@@ -342543,7 +342553,6 @@ var makeInspectMobileOnRunnerContract = () => {
     output
   };
 };
-
 // node_modules/@qawolf/api-contracts/dist/v1/runner/journal.js
 var journalEntrySchema = exports_external.object({
   payload: exports_external.unknown(),
@@ -343242,6 +343251,25 @@ var makeEvaluateSnippetOnRunnerContract = () => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/runner/get.js
+var makeGetRunnerContract = () => {
+  const input = exports_external.object({
+    id: runnerIdSchema.describe("Id of the runner to look up.")
+  });
+  const output = exports_external.object({
+    id: runnerIdSchema.describe("Id of the runner the call addressed."),
+    outcome: exports_external.literal("success"),
+    running: exports_external.boolean().describe("False when no runner is running under this id: it was never launched, it was terminated, or it terminated on its own after inactivity. These are not distinguished, because the run system keeps no record of a runner once it is gone.")
+  });
+  return {
+    description: "Report whether a runner is running under this id on the caller's team. This is a lookup: it never starts a runner, and it does not reset a runner's inactivity clock the way reading its journal does. An id that is not running is a success with `running: false` rather than an error, so this is how to check a runner is still there before addressing it.",
+    input,
+    kind: "read",
+    name: "runner.get",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/highlightSelector.js
 var maxHighlightSelectorLength = 2000;
 var makeHighlightSelectorOnRunnerContract = () => {
@@ -343563,6 +343591,7 @@ var makeContractsV1 = (ids) => {
     },
     runner: {
       evaluateSnippet: makeEvaluateSnippetOnRunnerContract(),
+      get: makeGetRunnerContract(),
       highlightSelector: makeHighlightSelectorOnRunnerContract(),
       importPackage: makeImportPackageOnRunnerContract(),
       inspect: makeInspectOnRunnerContract(),
@@ -346098,7 +346127,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.17.1",
+  version: "1.19.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -346158,7 +346187,7 @@ var package_default = {
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.34.0",
+    "@qawolf/api-contracts": "0.35.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -348590,28 +348619,35 @@ Examples:
 // src/domains/flows/list.ts
 import path2 from "node:path";
 
-// src/domains/flows/renderListTable.ts
-var columns = ["name", "target", "file"];
+// src/core/renderTable.ts
 var ansiBold = "\x1B[1m";
 var ansiReset = "\x1B[0m";
-function renderListTable(rows, boldHeader) {
-  const widths = {
-    name: Math.max("name".length, ...rows.map((r2) => r2.name.length)),
-    target: Math.max("target".length, ...rows.map((r2) => r2.target.length)),
-    file: Math.max("file".length, ...rows.map((r2) => r2.file.length))
-  };
-  const header = {
-    name: "name",
-    target: "target",
-    file: "file"
-  };
-  const renderRow = (cells) => columns.map((c3) => cells[c3].padEnd(widths[c3])).join("  ").trimEnd();
-  const headerLine = boldHeader ? `${ansiBold}${renderRow(header)}${ansiReset}` : renderRow(header);
-  return [headerLine, ...rows.map(renderRow)].join(`
+function renderTable(options) {
+  const { boldHeader, columns, rows } = options;
+  const measured = columns.map((column) => ({
+    column,
+    width: Math.max(column.header.length, ...rows.map((row) => column.value(row).length))
+  }));
+  const renderRow = (cell) => measured.map(({ column, width }) => cell(column).padEnd(width)).join("  ").trimEnd();
+  const header = renderRow((column) => column.header);
+  return [
+    boldHeader ? `${ansiBold}${header}${ansiReset}` : header,
+    ...rows.map((row) => renderRow((column) => column.value(row)))
+  ].join(`
 `) + `
 `;
 }
 
+// src/domains/flows/renderListTable.ts
+var columns = [
+  { header: "name", value: (row) => row.name },
+  { header: "target", value: (row) => row.target },
+  { header: "file", value: (row) => row.file }
+];
+function renderListTable(rows, boldHeader) {
+  return renderTable({ boldHeader, columns, rows });
+}
+
 // src/domains/flows/list.ts
 async function flowsList(ctx, pattern, deps) {
   const patterns = pattern ? [pattern] : [];
@@ -348672,7 +348708,8 @@ async function flowsListRemote(ctx, pattern, options) {
     file: f2.path,
     name: f2.name,
     tags: f2.tags,
-    target: typeof f2.executionTarget === "string" ? f2.executionTarget : JSON.stringify(f2.executionTarget)
+    target: typeof f2.executionTarget === "string" ? f2.executionTarget : JSON.stringify(f2.executionTarget),
+    url: f2.url
   }));
   if (ctx.ui.mode === "json") {
     ctx.ui.json(items);
@@ -356592,6 +356629,7 @@ async function handlePublicApiCommand(ctx, spec, options) {
 var skippedContractNames = new Set([
   "flow.list",
   "runner.evaluateSnippet",
+  "runner.get",
   "runner.highlightSelector",
   "runner.importPackage",
   "runner.inspect",
@@ -356660,21 +356698,7 @@ function registerPublicApiCommands(program2, signals, options = {}) {
 // src/domains/interactiveRunner/runnerCallOptions.ts
 var runnerCallOptions = { timeoutMs: 90000 };
 
-// src/domains/interactiveRunner/runnerIds.ts
-function parseRunnerId(id) {
-  const parsed = runnerIdSchema.safeParse(id);
-  if (!parsed.success)
-    return { error: exports_external.prettifyError(parsed.error), ok: false };
-  return { id: parsed.data, ok: true };
-}
-function parseRunnerName(runnerName) {
-  const parsed = runnerNameSchema.safeParse(runnerName);
-  if (!parsed.success)
-    return { error: exports_external.prettifyError(parsed.error), ok: false };
-  return { ok: true, runnerName: parsed.data };
-}
-
-// src/domains/interactiveRunner/launch.ts
+// src/domains/interactiveRunner/launchAndRemember.ts
 async function launchRunner(ctx, options) {
   const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.launch, {
     id: options.id,
@@ -356694,38 +356718,50 @@ async function launchAndRemember(ctx, options, deps) {
   const priorDefault = await deps.store.readDefaultRunnerId().catch(() => {
     return;
   });
-  const remembered = await deps.store.writeDefaultRunnerId(options.id).then(() => true).catch(() => {
+  const remembered = await deps.store.rememberLaunch({ id: options.id, runnerName: options.runnerName }).then(() => true).catch(() => {
     ctx.ui.warn(interactiveRunnerMessages.defaultNotRemembered(options.id));
     return false;
   });
   const launched = await launchRunner(ctx, options);
-  if (launched.ok)
+  if (launched.ok) {
+    if (remembered) {
+      await deps.store.rememberLaunch({
+        id: options.id,
+        runnerName: launched.value.runnerName
+      }).catch(() => {
+        return;
+      });
+    }
     return launched;
+  }
   if (remembered && !launched.mayHaveArrived) {
-    await (priorDefault === undefined ? deps.store.clearDefaultRunnerId() : deps.store.writeDefaultRunnerId(priorDefault)).catch(() => {
+    await deps.store.forgetRunner(options.id).catch(() => {
       return;
     });
+    if (priorDefault !== undefined) {
+      await deps.store.writeDefaultRunnerId(priorDefault).catch(() => {
+        return;
+      });
+    }
   }
   return {
     ...launched,
     error: launched.mayHaveArrived ? interactiveRunnerMessages.launchLost(options.id, launched.error) : interactiveRunnerMessages.launchFailed(options.id, launched.error)
   };
 }
-async function handleRunnerLaunch(ctx, options, deps) {
-  const chosenId = options.id ?? deps.makeRunnerId();
-  const id = parseRunnerId(chosenId);
-  if (!id.ok)
-    return { error: id.error, exitCode: exitCodes.invalidArgs };
-  const runnerName = options.name === undefined ? undefined : parseRunnerName(options.name);
-  if (runnerName !== undefined && !runnerName.ok) {
-    return { error: runnerName.error, exitCode: exitCodes.invalidArgs };
-  }
-  const launched = await launchAndRemember(ctx, { id: id.id, runnerName: runnerName?.runnerName }, deps);
-  if (!launched.ok) {
-    return { ...failureFields(launched), exitCode: launched.exitCode };
-  }
-  ctx.ui.output(launched.value, launched.value.alreadyRunning ? interactiveRunnerMessages.alreadyRunning(launched.value.id) : interactiveRunnerMessages.launched(launched.value.id));
-  return;
+
+// src/domains/interactiveRunner/runnerIds.ts
+function parseRunnerId(id) {
+  const parsed = runnerIdSchema.safeParse(id);
+  if (!parsed.success)
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  return { id: parsed.data, ok: true };
+}
+function parseRunnerName(runnerName) {
+  const parsed = runnerNameSchema.safeParse(runnerName);
+  if (!parsed.success)
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  return { ok: true, runnerName: parsed.data };
 }
 
 // src/domains/interactiveRunner/resolveRunner.ts
@@ -357077,7 +357113,14 @@ function parseJson(text3) {
 // src/shell/interactiveRunner/runnerStore.ts
 import { join as join47 } from "node:path";
 var storeFileName = "runner.json";
-var storeSchema = exports_external.object({ defaultRunnerId: exports_external.string().optional() });
+var runnersDirName = "runners";
+var storedRunnerSchema = exports_external.object({
+  id: exports_external.string(),
+  runnerName: exports_external.string().optional()
+});
+var storeSchema = exports_external.object({
+  defaultRunnerId: exports_external.string().optional()
+});
 function parseJson2(text3) {
   try {
     return JSON.parse(text3);
@@ -357085,30 +357128,81 @@ function parseJson2(text3) {
     return;
   }
 }
+var pendingWrites = 0;
 function makeRunnerStore(options) {
   const directory = join47(options.cwd, qawolfDir);
   const path9 = join47(directory, storeFileName);
-  let pendingWrites = 0;
-  const nextPendingPath = () => `${path9}.${process.pid}.${++pendingWrites}.tmp`;
+  const runnersDir = join47(directory, runnersDirName);
+  const nextPendingPath = (target) => `${target}.${process.pid}.${++pendingWrites}.tmp`;
+  const runnerPath = (runnerId) => join47(runnersDir, `${encodeURIComponent(runnerId)}.json`);
+  const writeAtomically = async (target, contents2) => {
+    const pendingPath = nextPendingPath(target);
+    await options.fs.writeFile(pendingPath, `${JSON.stringify(contents2, undefined, 2)}
+`);
+    await options.fs.rename(pendingPath, target);
+  };
+  const readDefaultRunnerId = async () => {
+    const contents2 = await options.fs.readFile(path9).catch(() => {
+      return;
+    });
+    if (contents2 === undefined)
+      return;
+    const parsed = storeSchema.safeParse(parseJson2(contents2));
+    return parsed.success ? parsed.data.defaultRunnerId : undefined;
+  };
+  const writeDefaultRunnerId = async (runnerId) => {
+    await options.fs.mkdir(directory, { recursive: true });
+    await writeAtomically(path9, { defaultRunnerId: runnerId });
+  };
+  const readRunnerFileNames = async () => {
+    try {
+      const names = await options.fs.readdir(runnersDir);
+      return names.filter((name) => name.endsWith(".json"));
+    } catch {
+      return [];
+    }
+  };
   return {
-    async clearDefaultRunnerId() {
-      await options.fs.rm(path9, { force: true });
+    async forgetRunner(runnerId) {
+      await options.fs.rm(runnerPath(runnerId), { force: true });
+      if (await readDefaultRunnerId() === runnerId)
+        await writeDefaultRunnerId(undefined);
     },
-    async readDefaultRunnerId() {
-      const contents2 = await options.fs.readFile(path9).catch(() => {
-        return;
-      });
-      if (contents2 === undefined)
-        return;
-      const parsed = storeSchema.safeParse(parseJson2(contents2));
-      return parsed.success ? parsed.data.defaultRunnerId : undefined;
+    readDefaultRunnerId,
+    async readRunners() {
+      const runners = await Promise.all((await readRunnerFileNames()).map(async (name) => {
+        const contents2 = await options.fs.readFile(join47(runnersDir, name)).catch(() => {
+          return;
+        });
+        if (contents2 === undefined)
+          return;
+        const parsed = storedRunnerSchema.safeParse(parseJson2(contents2));
+        return parsed.success ? parsed.data : undefined;
+      }));
+      return runners.filter((runner) => !!runner).sort((left, right) => left.id.localeCompare(right.id));
+    },
+    async rememberLaunch(runner) {
+      await options.fs.mkdir(runnersDir, { recursive: true });
+      await writeAtomically(runnerPath(runner.id), runner);
+      await writeDefaultRunnerId(runner.id);
+    },
+    async dropRunners(runnerIds) {
+      await Promise.all(runnerIds.map((runnerId) => options.fs.rm(runnerPath(runnerId), { force: true })));
+      const names = await readRunnerFileNames();
+      await Promise.all(names.map(async (name) => {
+        const runnerFile = join47(runnersDir, name);
+        const contents2 = await options.fs.readFile(runnerFile).catch(() => {
+          return;
+        });
+        if (contents2 === undefined)
+          return;
+        if (storedRunnerSchema.safeParse(parseJson2(contents2)).success)
+          return;
+        await options.fs.rm(runnerFile, { force: true });
+      }));
     },
     async writeDefaultRunnerId(runnerId) {
-      const pendingPath = nextPendingPath();
-      await options.fs.mkdir(directory, { recursive: true });
-      await options.fs.writeFile(pendingPath, `${JSON.stringify({ defaultRunnerId: runnerId }, undefined, 2)}
-`);
-      await options.fs.rename(pendingPath, path9);
+      await writeDefaultRunnerId(runnerId);
     }
   };
 }
@@ -357353,14 +357447,190 @@ async function handleRunnerInspect(ctx, options, deps) {
   return;
 }
 
+// src/core/interactiveRunner/inspectMobileRequest.ts
+function toNumber(value) {
+  return value.trim() === "" ? Number.NaN : Number(value);
+}
+function buildInspectMobileRequest(what, flags) {
+  if (flags.by === "point" && (flags.text !== undefined || flags.partial !== undefined)) {
+    return {
+      error: "--by point matches by pixel, so --text/--partial would be ignored rather than searching by text. Pass --by text instead, or drop --text/--partial.",
+      ok: false
+    };
+  }
+  if (flags.by === "text" && (flags.x !== undefined || flags.y !== undefined)) {
+    return {
+      error: "--by text matches by text, so --x/--y would be ignored rather than matching a point. Pass --by point instead, or drop --x/--y.",
+      ok: false
+    };
+  }
+  const candidate = {
+    what,
+    ...flags.by === undefined ? {} : { by: flags.by },
+    ...flags.context === undefined ? {} : { context: flags.context },
+    ...flags.partial === undefined ? {} : { partial: flags.partial },
+    ...flags.text === undefined ? {} : { text: flags.text },
+    ...flags.x === undefined ? {} : { x: toNumber(flags.x) },
+    ...flags.y === undefined ? {} : { y: toNumber(flags.y) }
+  };
+  const parsed = inspectMobileRequestSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  }
+  return { ok: true, request: parsed.data };
+}
+
+// src/domains/interactiveRunner/inspectMobile.ts
+function describeSession(session) {
+  switch (session.type) {
+    case "ready":
+      return session.deviceName === undefined ? `Session ready: ${session.platformName} (${session.sessionId}).` : `Session ready: ${session.platformName} on ${session.deviceName} (${session.sessionId}).`;
+    case "unreachable":
+      return `Session unreachable: ${session.error}`;
+    case "ambiguous":
+      return `${String(session.sessionCount)} Appium sessions are live; expected one.`;
+    case "no-session":
+      return "No Appium session is live.";
+  }
+}
+function streamLine(value) {
+  switch (value.what) {
+    case "contexts":
+      return JSON.stringify({
+        contexts: value.contexts,
+        current: value.current
+      });
+    case "page":
+      return JSON.stringify({
+        context: value.context,
+        orientation: value.orientation,
+        pageSource: value.pageSource
+      });
+    case "elements":
+      return JSON.stringify({ matches: value.matches });
+  }
+}
+async function handleRunnerInspectMobile(ctx, options, deps) {
+  const built = buildInspectMobileRequest(options.what, options.flags);
+  if (!built.ok)
+    return { error: built.error, exitCode: exitCodes.invalidArgs };
+  const resolved = await resolveRunner(ctx, {
+    autoLaunch: false,
+    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForInspect,
+    runner: options.runner
+  }, deps);
+  if (resolved.type === "failed") {
+    return { ...failureFields(resolved), exitCode: resolved.exitCode };
+  }
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.inspectMobile, { id: resolved.runnerId, request: built.request }, runnerCallOptions);
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  if (result.value.outcome === "success") {
+    const value = result.value;
+    if (value.what === "session") {
+      ctx.ui.output(value, describeSession(value.session));
+    } else {
+      ctx.ui.stream(value, streamLine(value));
+    }
+    return;
+  }
+  const { failureReason } = result.value;
+  switch (failureReason) {
+    case "runner-is-not-mobile":
+      return {
+        error: interactiveRunnerMessages.runnerIsNotMobile,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "screen-needs-a-run":
+      return {
+        error: interactiveRunnerMessages.screenNeedsARun,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "screen-not-ready":
+      return {
+        error: interactiveRunnerMessages.screenNotReady,
+        exitCode: exitCodes.network
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.runnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    default: {
+      return {
+        error: interactiveRunnerMessages.inspectMobileAnsweredUnknown(failureReason),
+        exitCode: exitCodes.network
+      };
+    }
+  }
+}
+
+// src/commands/runner/inspectMobile.register.ts
+function registerRunnerInspectMobileCommands(inspect, signals) {
+  declareCommandKind(inspect.command("session"), "read").description("Print the Appium session's status: ready, or why not").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: undefined,
+      context: undefined,
+      partial: undefined,
+      text: undefined,
+      x: undefined,
+      y: undefined
+    },
+    runner: opts.runner,
+    what: "session"
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(inspect.command("contexts"), "read").description("List the WebView contexts available, and which is current").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: undefined,
+      context: undefined,
+      partial: undefined,
+      text: undefined,
+      x: undefined,
+      y: undefined
+    },
+    runner: opts.runner,
+    what: "contexts"
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(inspect.command("page-source"), "read").description("Print the current context's page source, as a tree").option("--context <name>", "Read this context instead of the current one").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: undefined,
+      context: opts.context,
+      partial: undefined,
+      text: undefined,
+      x: undefined,
+      y: undefined
+    },
+    runner: opts.runner,
+    what: "page"
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(inspect.command("elements"), "read").description("Find elements at a screen point, or elements carrying some text").requiredOption("--by <by>", "point or text").option("--context <name>", "Read this context instead of the current one").option("--partial", "text: match text containing this, rather than exactly this").option("--runner <id>", runnerFlagDescription).option("--text <text>", "text: the text to match").option("--x <pixels>", "point: whole pixels on the device's own screen").option("--y <pixels>", "point: whole pixels on the device's own screen").action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: opts.by,
+      context: opts.context,
+      partial: opts.partial,
+      text: opts.text,
+      x: opts.x,
+      y: opts.y
+    },
+    runner: opts.runner,
+    what: "elements"
+  }, runnerDeps(ctx)))(opts, command));
+}
+
 // src/commands/runner/inspect.register.ts
 var inspectExamples = `
 Examples:
   $ qawolf runner inspect element-html --selector "#email"
   $ qawolf runner inspect page-html > page.html
-  $ qawolf runner inspect variable --name cart | jq .total`;
+  $ qawolf runner inspect variable --name cart | jq .total
+  $ qawolf runner inspect session
+  $ qawolf runner inspect contexts
+  $ qawolf runner inspect page-source --context WEBVIEW_1
+  $ qawolf runner inspect elements --by point --x 200 --y 400
+  $ qawolf runner inspect elements --by text --text "Sign in" --partial`;
 function registerRunnerInspectCommands(runner, signals) {
-  const inspect = runner.command("inspect").description("Read one thing off a runner's live page").addHelpText("after", inspectExamples);
+  const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples);
   declareCommandKind(inspect.command("element-html"), "read").description("Print the HTML of the first element a selector matches").requiredOption("--selector <selector>", "Playwright selector to inspect").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspect(ctx, {
     flags: { name: undefined, selector: opts.selector },
     runner: opts.runner,
@@ -357376,6 +357646,7 @@ function registerRunnerInspectCommands(runner, signals) {
     runner: opts.runner,
     what: "variable"
   }, runnerDeps(ctx)))(opts, command));
+  registerRunnerInspectMobileCommands(inspect, signals);
 }
 
 // src/core/interactiveRunner/runFiles.ts
@@ -357513,46 +357784,6 @@ async function handleRunnerExec(ctx, options, deps) {
   }
 }
 
-// src/core/interactiveRunner/browserAction.ts
-function parseJsonPath(path9) {
-  try {
-    return { ok: true, value: JSON.parse(path9) };
-  } catch {
-    return {
-      error: `--path must be a JSON array of points, for example '[{"x":10,"y":20},{"x":80,"y":90}]'.`,
-      ok: false
-    };
-  }
-}
-function toNumber(value) {
-  return value.trim() === "" ? Number.NaN : Number(value);
-}
-function buildBrowserAction(type, flags) {
-  const parsedPath = flags.path === undefined ? undefined : parseJsonPath(flags.path);
-  if (parsedPath !== undefined && !parsedPath.ok)
-    return parsedPath;
-  const candidate = {
-    type,
-    ...flags.button === undefined ? {} : { button: flags.button },
-    ...flags.keys === undefined ? {} : { keys: flags.keys },
-    ...parsedPath === undefined ? {} : { path: parsedPath.value },
-    ...flags.scrollX === undefined ? {} : { scroll_x: toNumber(flags.scrollX) },
-    ...flags.scrollY === undefined ? {} : { scroll_y: toNumber(flags.scrollY) },
-    ...flags.text === undefined ? {} : { text: flags.text },
-    ...flags.url === undefined ? {} : { url: flags.url },
-    ...flags.x === undefined ? {} : { x: toNumber(flags.x) },
-    ...flags.y === undefined ? {} : { y: toNumber(flags.y) }
-  };
-  return parseBrowserAction(candidate);
-}
-function parseBrowserAction(candidate) {
-  const parsed = browserActionSchema.safeParse(candidate);
-  if (!parsed.success) {
-    return { error: exports_external.prettifyError(parsed.error), ok: false };
-  }
-  return { action: parsed.data, ok: true };
-}
-
 // src/domains/interactiveRunner/performActionFailure.ts
 function describePerformActionFailure(options) {
   const { actionType, failure } = options;
@@ -357597,7 +357828,47 @@ function describePerformActionFailure(options) {
   }
 }
 
-// src/domains/interactiveRunner/performAction.ts
+// src/core/interactiveRunner/browserAction.ts
+function parseJsonPath(path9) {
+  try {
+    return { ok: true, value: JSON.parse(path9) };
+  } catch {
+    return {
+      error: `--path must be a JSON array of points, for example '[{"x":10,"y":20},{"x":80,"y":90}]'.`,
+      ok: false
+    };
+  }
+}
+function toNumber2(value) {
+  return value.trim() === "" ? Number.NaN : Number(value);
+}
+function buildBrowserAction(type, flags) {
+  const parsedPath = flags.path === undefined ? undefined : parseJsonPath(flags.path);
+  if (parsedPath !== undefined && !parsedPath.ok)
+    return parsedPath;
+  const candidate = {
+    type,
+    ...flags.button === undefined ? {} : { button: flags.button },
+    ...flags.keys === undefined ? {} : { keys: flags.keys },
+    ...parsedPath === undefined ? {} : { path: parsedPath.value },
+    ...flags.scrollX === undefined ? {} : { scroll_x: toNumber2(flags.scrollX) },
+    ...flags.scrollY === undefined ? {} : { scroll_y: toNumber2(flags.scrollY) },
+    ...flags.text === undefined ? {} : { text: flags.text },
+    ...flags.url === undefined ? {} : { url: flags.url },
+    ...flags.x === undefined ? {} : { x: toNumber2(flags.x) },
+    ...flags.y === undefined ? {} : { y: toNumber2(flags.y) }
+  };
+  return parseBrowserAction(candidate);
+}
+function parseBrowserAction(candidate) {
+  const parsed = browserActionSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  }
+  return { action: parsed.data, ok: true };
+}
+
+// src/domains/interactiveRunner/readAction.ts
 var stdinArgument2 = "-";
 async function readAction(type, flags, deps) {
   if (type !== stdinArgument2)
@@ -357615,6 +357886,8 @@ async function readAction(type, flags, deps) {
     return { error: interactiveRunnerMessages.actionNotJson, ok: false };
   }
 }
+
+// src/domains/interactiveRunner/performAction.ts
 async function handleRunnerAct(ctx, options, deps) {
   const built = await readAction(options.type, options.flags, deps);
   if (!built.ok)
@@ -357728,7 +358001,7 @@ Examples:
   $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts`;
 function registerRunnerInteractCommands(runner, signals) {
   declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file").option("--out <path>", "File to write the image to", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left, right, wheel, back or forward").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through").option("--runner <id>", runnerFlagDescription).option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--text <text>", "type: the text to type").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "pointer x, in screenshot pixels").option("--y <pixels>", "pointer y, in screenshot pixels").addHelpText("after", actExamples).action((action2, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
+  declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile").option("--button <button>", "click: left, right, wheel, back or forward (mobile: left only)").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through (mobile: only the first and last are used)").option("--runner <id>", runnerFlagDescription).option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--text <text>", "type: the text to type").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "pointer x, in screenshot pixels").option("--y <pixels>", "pointer y, in screenshot pixels").addHelpText("after", actExamples).action((action2, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
     flags: {
       button: opts.button,
       keys: opts.keys,
@@ -357795,6 +358068,92 @@ async function handleRunnerKeepalive(ctx, options, deps) {
   return;
 }
 
+// src/domains/interactiveRunner/launch.ts
+async function handleRunnerLaunch(ctx, options, deps) {
+  const chosenId = options.id ?? deps.makeRunnerId();
+  const id = parseRunnerId(chosenId);
+  if (!id.ok)
+    return { error: id.error, exitCode: exitCodes.invalidArgs };
+  const runnerName = options.name === undefined ? undefined : parseRunnerName(options.name);
+  if (runnerName !== undefined && !runnerName.ok) {
+    return { error: runnerName.error, exitCode: exitCodes.invalidArgs };
+  }
+  const launched = await launchAndRemember(ctx, { id: id.id, runnerName: runnerName?.runnerName }, deps);
+  if (!launched.ok) {
+    return { ...failureFields(launched), exitCode: launched.exitCode };
+  }
+  ctx.ui.output(launched.value, launched.value.alreadyRunning ? interactiveRunnerMessages.alreadyRunning(launched.value.id) : interactiveRunnerMessages.launched(launched.value.id));
+  return;
+}
+
+// src/domains/interactiveRunner/list.ts
+var columns2 = [
+  { header: "id", value: (row) => row.id },
+  { header: "family", value: (row) => row.runnerName ?? "" },
+  { header: "default", value: (row) => row.isDefault ? "yes" : "" }
+];
+var probeBatchSize = 8;
+async function readCandidates(deps) {
+  const held = await deps.store.readRunners();
+  const storedDefault = await deps.store.readDefaultRunnerId();
+  const environmentValue = deps.env[runnerIdEnvironmentVariable]?.trim();
+  const fromEnvironment = environmentValue ? environmentValue : undefined;
+  const candidates = [...held];
+  for (const id of [storedDefault, fromEnvironment]) {
+    if (id !== undefined && !candidates.some((runner) => runner.id === id)) {
+      candidates.push({ id });
+    }
+  }
+  return { candidates, defaultRunnerId: fromEnvironment ?? storedDefault };
+}
+async function probeRunner(ctx, runner) {
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.get, { id: runner.id }, runnerCallOptions);
+  if (!result.ok)
+    return { ...failureFields(result), ok: false };
+  return { ok: true, runner, running: result.value.running };
+}
+async function handleRunnerList(ctx, deps) {
+  const { candidates, defaultRunnerId } = await readCandidates(deps);
+  const running = [];
+  const gone = [];
+  for await (const probe of batchMap(candidates, (runner) => probeRunner(ctx, runner), probeBatchSize)) {
+    if (!probe.ok) {
+      return { ...failureFields(probe), exitCode: exitCodes.network };
+    }
+    if (probe.running)
+      running.push(probe.runner);
+    else
+      gone.push(probe.runner.id);
+  }
+  await deps.store.dropRunners(gone).catch(() => {
+    return;
+  });
+  const items = [
+    ...running.filter((runner) => runner.id === defaultRunnerId),
+    ...running.filter((runner) => runner.id !== defaultRunnerId)
+  ].map((runner) => ({
+    id: runner.id,
+    isDefault: runner.id === defaultRunnerId,
+    runnerName: runner.runnerName
+  }));
+  if (ctx.ui.mode === "json") {
+    ctx.ui.json(items);
+    return;
+  }
+  if (items.length === 0) {
+    ctx.ui.info(interactiveRunnerMessages.noRunners);
+    return;
+  }
+  if (ctx.ui.mode === "agent") {
+    ctx.ui.write(renderTable({ boldHeader: false, columns: columns2, rows: items }));
+    return;
+  }
+  ctx.ui.gap();
+  ctx.ui.intro(interactiveRunnerMessages.title);
+  ctx.ui.write(renderTable({ boldHeader: true, columns: columns2, rows: items }));
+  ctx.ui.outro(interactiveRunnerMessages.runnerCount(items.length));
+}
+
 // src/domains/interactiveRunner/stopRun.ts
 async function handleRunnerStopRun(ctx, options, deps) {
   const resolved = await resolveRunner(ctx, { autoLaunch: false, runner: options.runner }, deps);
@@ -357828,11 +358187,7 @@ async function handleRunnerTerminate(ctx, options, deps) {
   if (!result.ok) {
     return { ...failureFields(result), exitCode: exitCodes.network };
   }
-  await deps.store.readDefaultRunnerId().then(async (storedDefault) => {
-    if (storedDefault === resolved.runnerId) {
-      await deps.store.clearDefaultRunnerId();
-    }
-  }).catch(() => {
+  await deps.store.forgetRunner(resolved.runnerId).catch(() => {
     ctx.ui.warn(interactiveRunnerMessages.defaultNotForgotten(resolved.runnerId));
   });
   ctx.ui.output(result.value, result.value.wasRunning ? interactiveRunnerMessages.terminated(result.value.id) : interactiveRunnerMessages.wasNotRunning(result.value.id));
@@ -357845,12 +358200,17 @@ Examples:
   $ qawolf runner launch
   $ qawolf runner launch --name android
   $ qawolf runner launch --id ci`;
+var listExamples2 = `
+Examples:
+  $ qawolf runner list
+  $ qawolf runner list --json`;
 var keepaliveExamples = `
 Examples:
   $ qawolf runner keepalive
   $ qawolf runner keepalive --runner ci`;
 function registerRunnerLifecycleCommands(runner, signals) {
   declareCommandKind(runner.command("launch"), "write").description("Launch an interactive runner and make it this directory's default").option("--id <id>", "Id to launch under. Relaunching an id attaches to that runner").option("--name <family>", "Runner family to run, e.g. playwright").addHelpText("after", launchExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("list"), "read").description("List the runners this directory holds that are still running").addHelpText("after", listExamples2).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, runnerDeps(ctx)))(opts, command));
   declareCommandKind(runner.command("terminate"), "write").description("End an interactive runner, and the pod it runs on with it").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerTerminate(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
   declareCommandKind(runner.command("stop-run"), "write").description("Stop what a runner is currently executing, leaving the runner up").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerStopRun(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
   declareCommandKind(runner.command("keepalive"), "read").description("Reset a runner's inactivity clock, for a caller that pauses between actions").option("--runner <id>", runnerFlagDescription).addHelpText("after", keepaliveExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerKeepalive(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
@@ -358648,4 +359008,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=C71E3AC48D2D260064756E2164756E21
+//# debugId=C46D821567854FC564756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.17.1",
+  "version": "1.19.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -60,7 +60,7 @@
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.34.0",
+    "@qawolf/api-contracts": "0.35.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -105,6 +105,17 @@ Inspect `git status` before publishing. Stage and commit only files changed for
 the current task, preserve unrelated worktree changes, then push the task's
 current branch.
 
+The platform reads flows from the environment's flow code branch, not from your
+task branch. `qawolf --json environment get` reports it as `flowCodeBranch`
+(`name`, `syncStatus`, `lastSyncedCommitHash`). A flow has a platform page, an
+id, and a place in `qawolf flows list --remote` only once it is on that branch
+and the environment has reconciled the commit. To link or run a new flow on the
+platform: integrate the flow code branch into your work, push the flow to that
+branch, poll `environment get` until `lastSyncedCommitHash` includes your
+commit, then read the flow's `flowId` and `url` from
+`qawolf --json flows list --remote --env <environment> --include-drafts`. Send
+that `url`; never guess a route and never send a repository link in its place.
+
 ## Commands
 
 <!-- commands-table:start — generated by `bun run generate`, do not edit -->
@@ -144,16 +155,21 @@ current branch.
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
 | `qawolf run get` | read | Get a run's status, per-flow results, and links. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
-| `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin |
+| `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile |
 | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
 | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |
 | `qawolf runner highlight-selector` | write | Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight |
 | `qawolf runner import-package` | write | Install a package into a runner's live run, so a snippet or a selection can import it |
+| `qawolf runner inspect contexts` | read | List the WebView contexts available, and which is current |
 | `qawolf runner inspect element-html` | read | Print the HTML of the first element a selector matches |
+| `qawolf runner inspect elements` | read | Find elements at a screen point, or elements carrying some text |
 | `qawolf runner inspect page-html` | read | Print the page's HTML, simplified for a model to read |
+| `qawolf runner inspect page-source` | read | Print the current context's page source, as a tree |
+| `qawolf runner inspect session` | read | Print the Appium session's status: ready, or why not |
 | `qawolf runner inspect variable` | read | Print a top-level variable's value from the running workflow |
 | `qawolf runner keepalive` | read | Reset a runner's inactivity clock, for a caller that pauses between actions |
 | `qawolf runner launch` | write | Launch an interactive runner and make it this directory's default |
+| `qawolf runner list` | read | List the runners this directory holds that are still running |
 | `qawolf runner promote-snapshot` | write | Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it |
 | `qawolf runner run` | write | Run a flow on an interactive runner, shipping the flow and what it imports |
 | `qawolf runner screenshot` | read | Save a JPEG of an interactive runner's screen to a file |

package/skills/qawolf-cli/references/runner.md

@@ -41,6 +41,41 @@ No `read` command ever launches a runner. `screenshot`, `events` and `keepalive`
 tell you there is no runner rather than quietly billing one, and so does
 `terminate`, since starting a pod in order to end it would be absurd.
 
+`--name` also chooses between a browser and a mobile device:
+`qawolf runner launch --name android` or `--name ios` starts an Appium session
+instead of a browser. A command built for the other kind answers a
+`failureReason` naming the mismatch rather than doing something approximate —
+`runner-is-not-mobile` from `inspect session`/`contexts`/`page-source`/`elements`
+on a browser runner, `runner-is-not-a-browser` from `inspect element-html`/
+`page-html` on a mobile one — so launch the right family up front rather than
+discovering it from a refusal mid-session.
+
+## Knowing what you are holding
+
+`qawolf runner list` names the runners this directory has launched that are
+still running, and marks the one a command with no `--runner` would reach:
+
+```text
+id                   family      default
+tester-abc-main      playwright  yes
+tester-abc-checkout  playwright
+```
+
+Every runner is looked up before it is listed, so a runner that idled out is
+absent rather than reported. The lookup neither starts a runner nor resets an
+inactivity clock, which is what separates `list` from `keepalive`: listing tells
+you what is there and changes nothing, and holding a runner open is still
+`keepalive`'s job. A lookup that cannot be answered fails the command rather
+than returning a shorter list, because a short list reads as the whole truth.
+
+Nothing is billed by listing, but everything in the list is billing. Terminate
+what you are done with.
+
+The list includes the runner named by `QAWOLF_RUNNER_ID` even though this
+directory did not launch it, so a harness handed a runner sees it alongside the
+ones it started itself. Use the `id` column with `--runner` to address any of
+them; addressing one does not make it the default.
+
 ## The order that matters
 
 A freshly launched runner has no screen. The virtual desktop starts with the
@@ -112,6 +147,14 @@ taken effect. On a `4` from `act`, take a screenshot before repeating a click.
 looks the same from outside, so treat a `4` from a snippet that changes something
 as "may have run" rather than "did not run".
 
+A mobile runner has a touchscreen, not a mouse, so only three of the eight
+actions have a touchscreen equivalent and go through: `click` with
+`button: "left"` taps, `drag` swipes, and `type` types into whatever the last
+tap focused. The rest — `double_click`, `scroll`, `move`, `keypress`,
+`navigate` — answer `action-not-supported-on-mobile` rather than doing
+something approximate. `navigate` is the one to watch for, since it works on a
+browser runner without a run first but has no meaning on mobile at all.
+
 ## The recorder: what you cannot get from pixels
 
 `qawolf runner events recorder` is the capability that has no equivalent in a
@@ -159,6 +202,52 @@ Use `inspect` before reaching for `exec`. Reading a value through a snippet
 means printing it and then fishing it back out of the `console` stream, which is
 two calls and a marker; `inspect variable` is one call and the value.
 
+## Reading a mobile screen: `inspect session`/`contexts`/`page-source`/`elements`
+
+`element-html`, `page-html` and `variable` are a browser's shapes. A mobile
+runner answers four different ones instead, one subcommand per question:
+
+```sh
+qawolf runner inspect session
+qawolf runner inspect contexts
+qawolf runner inspect page-source
+qawolf runner inspect page-source --context WEBVIEW_1     # a specific context, not the current one
+qawolf runner inspect elements --by point --x 240 --y 480
+qawolf runner inspect elements --by text --text "Sign in" --partial
+```
+
+`session` prints one summary line — ready, or why not — because that line is
+the whole answer. `contexts`, `page-source` and `elements` instead print their
+answer as JSON on stdout, on its own like `inspect element-html`, so you can
+redirect or pipe it (`| jq .current`, `| jq .matches`, `| jq .pageSource`)
+rather than getting a count with no way to see what was actually found.
+
+`session` is also the one subcommand that never answers `screen-needs-a-run`:
+readiness is the question it exists to answer, so it reports one of `ready`
+(with the platform, device and session id), `unreachable`, `ambiguous` (more
+than one session is somehow live) or `no-session`, rather than refusing until a
+run has happened. The other three need a live session first and share the same
+readiness contract `act` and `screenshot` use on a browser runner:
+`screen-needs-a-run` exits `2` and means no Appium session has started on this
+runner yet — run a flow that opens one, then inspect again; `screen-not-ready`
+exits `4` and means the session exists but did not answer this instant, or more
+than one is somehow live — retry once, and relaunch the runner if it persists.
+
+`elements` takes one of two ways to search, chosen with `--by`: `point` needs
+whole-pixel `--x`/`--y` on the device's own screen, the same coordinates a
+screenshot is measured in; `text` needs `--text` and matches it exactly unless
+`--partial` is passed. The two do not mix — `--by point` with `--text` set, or
+`--by text` with `--x`/`--y` set, is refused before a runner is addressed
+rather than silently searching by the one it picked, since the schema itself
+just strips whichever field the chosen `by` does not define. `--context` on
+`page-source` or `elements` reads a context other than the current one —
+useful once `contexts` has told you which are available.
+
+A browser runner answers `runner-is-not-mobile` to all four, exit `2`, since
+retrying never helps: launch with `--name android` or `--name ios` instead.
+`runner-unreachable` exits `4` and is worth retrying, same as everywhere else
+on this surface.
+
 ## Checking a selector: `highlight-selector`
 
 `inspect element-html` tells you what a selector matched. `highlight-selector`