@qawolf/cli 1.9.2 → 1.11.0

package/dist/cli.js

@@ -156412,12 +156412,14 @@ var interactiveRunnerMessages = {
   launched: (id) => `Launched runner ${id}.`,
   launchedForCommand: (id) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is stopped or idles out, so stop it with qawolf runner stop --runner ${id} when you are done.`,
   followEventsTimedOut: (stream, seconds) => `Stopped following ${stream} after ${formatSeconds(seconds * 1000)}: reading keeps the runner alive and billing, so a follow does not run unbounded. Pass --timeout to wait longer, or follow again to continue.`,
+  followEndCutShort: "The run settled, but the last window of its followed streams could not be read, so the output above may be missing its final lines.",
   followTimedOut: (runId, runnerId, seconds) => `Stopped following run ${runId} after ${formatSeconds(seconds * 1000)}. The run may still be going: read it with qawolf runner events run-status --run ${runId}, and stop the runner with qawolf runner stop --runner ${runnerId} when you are done. Pass --timeout to wait longer.`,
   missingPackageJson: "No package.json in the current directory. A run reads its npm dependencies from one, so it has to travel with the flow.",
   noRunnerIdForScreenshot: `${noRunnerId} A screenshot also needs a screen, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
   noRunnerId,
   notRunning: (id) => `Runner ${id} was not running.`,
   runFailed: (errorMessage2) => errorMessage2 === undefined ? "The run failed and reported no reason." : `The run failed: ${errorMessage2}`,
+  runInProgress: "The run is in progress.",
   runPassed: "The run passed.",
   runSettledUnknown: (status) => `The run settled as "${status}", which this version of the CLI does not recognize. Upgrade to read it.`,
   runSubmitAnsweredUnknown: (outcome) => `The runner answered the submission with "${outcome}", which this version of the CLI does not recognize. Upgrade to read it.`,
@@ -175909,7 +175911,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.9.2",
+  version: "1.11.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -185968,6 +185970,14 @@ function flagUsage(field, kind) {
     return `${name} <KEY=VALUE...>`;
   return `${name} <value>`;
 }
+function describeFlag(schema) {
+  const description = schema.description ?? "";
+  const values = schema.enum ?? schema.items?.enum;
+  if (!values?.length)
+    return description;
+  const choices = `One of: ${values.join(", ")}`;
+  return description ? `${description} ${choices}` : choices;
+}
 function buildFlagSpecs(inputSchema) {
   const jsonSchema = exports_external.toJSONSchema(inputSchema, {
     io: "input"
@@ -185983,7 +185993,7 @@ function buildFlagSpecs(inputSchema) {
     flags.push({
       field,
       flag: flagUsage(field, kind.kind),
-      description: fieldSchema.description ?? "",
+      description: describeFlag(fieldSchema),
       required: result.shape.required.has(field),
       kind: kind.kind
     });
@@ -186090,7 +186100,7 @@ async function handlePublicApiCommand(ctx, spec, options) {
 }
 
 // src/domains/publicApi/skippedContracts.ts
-var handWrittenContractNames = new Set([
+var skippedContractNames = new Set([
   "flow.list",
   "runner.evaluateSnippet",
   "runner.launch",
@@ -186100,13 +186110,6 @@ var handWrittenContractNames = new Set([
   "runner.stop",
   "runner.takeScreenshot"
 ]);
-var unexpressibleContractNames = new Set([
-  "issue.update"
-]);
-var skippedContractNames = new Set([
-  ...handWrittenContractNames,
-  ...unexpressibleContractNames
-]);
 
 // src/commands/publicApi/index.ts
 var groupDescriptions = {
@@ -186853,6 +186856,20 @@ function readRunSettlement(payload) {
     type: "settled"
   };
 }
+function findSettlement(entries) {
+  for (const entry of entries) {
+    const settlement = readRunSettlement(entry.payload);
+    if (settlement.type !== "settled")
+      continue;
+    if (settlement.status === "passed")
+      return { type: "passed" };
+    if (settlement.status === "failed") {
+      return { errorMessage: settlement.errorMessage, type: "failed" };
+    }
+    return { status: settlement.status, type: "unrecognized" };
+  }
+  return;
+}
 var runLogPayloadSchema = exports_external.object({ message: exports_external.string() });
 function formatRunLogLine(payload) {
   const parsed = runLogPayloadSchema.safeParse(payload);
@@ -186915,6 +186932,18 @@ function createJournalCursor(ctx, runnerId, request) {
     return { entries: window2.value.entries, type: "entries" };
   };
 }
+function createPrintingCursor(ctx, runnerId, request, format) {
+  const read = createJournalCursor(ctx, runnerId, request);
+  return async () => {
+    const window2 = await read();
+    if (window2.type !== "entries")
+      return window2;
+    for (const entry of window2.entries) {
+      ctx.ui.stream(entry, format(entry.payload));
+    }
+    return window2;
+  };
+}
 var unreachableGraceMs = 60000;
 function createUnreachableBudget(pollIntervalMs2) {
   const limit = Math.ceil(unreachableGraceMs / pollIntervalMs2);
@@ -186996,22 +187025,49 @@ function readErrorPath(error51) {
   return typeof path9 === "string" ? path9 : undefined;
 }
 
-// src/domains/interactiveRunner/followRun.ts
-var pollIntervalMs3 = 1000;
-function findSettlement(entries) {
-  for (const entry of entries) {
-    const settlement = readRunSettlement(entry.payload);
-    if (settlement.type !== "settled")
-      continue;
-    if (settlement.status === "passed")
-      return { type: "passed" };
-    if (settlement.status === "failed") {
-      return { errorMessage: settlement.errorMessage, type: "failed" };
+// src/domains/interactiveRunner/followPrinters.ts
+var anchorPollIntervalMs = 1000;
+async function resolveRecorderAnchor(ctx, resolved, deps) {
+  if (resolved.type === "launched")
+    return { ok: true, sinceSequence: 0 };
+  return anchorRecorderCursor(ctx, resolved.runnerId, deps);
+}
+async function anchorRecorderCursor(ctx, runnerId, deps) {
+  const unreachable = createUnreachableBudget(anchorPollIntervalMs);
+  for (;; ) {
+    const anchor = await readJournal(ctx, runnerId, {
+      stream: "recorder",
+      tail: 1
+    });
+    if (anchor.type === "read") {
+      return { ok: true, sinceSequence: anchor.value.nextSequence };
     }
-    return { status: settlement.status, type: "unrecognized" };
+    if (anchor.type === "failed") {
+      return { failure: journalReadFailure(anchor), ok: false };
+    }
+    if (unreachable.exhausted()) {
+      return { failure: { ...unreachableFailure }, ok: false };
+    }
+    await deps.sleep(anchorPollIntervalMs);
   }
-  return;
 }
+function createFollowPrinters(ctx, options) {
+  const jsonLine = (payload) => JSON.stringify(payload);
+  const printers = [];
+  if (options.logs) {
+    printers.push(createPrintingCursor(ctx, options.runnerId, { runId: options.runId, stream: "run-logs" }, formatRunLogLine));
+  }
+  if (options.runEvents) {
+    printers.push(createPrintingCursor(ctx, options.runnerId, { runId: options.runId, stream: "run-events" }, jsonLine));
+  }
+  if (options.recorderSinceSequence !== undefined) {
+    printers.push(createPrintingCursor(ctx, options.runnerId, { sinceSequence: options.recorderSinceSequence, stream: "recorder" }, jsonLine));
+  }
+  return printers;
+}
+
+// src/domains/interactiveRunner/followRun.ts
+var pollIntervalMs3 = 1000;
 function reportSettlement(ctx, settlement) {
   if (settlement.type === "passed") {
     ctx.ui.success(interactiveRunnerMessages.runPassed);
@@ -187023,40 +187079,49 @@ function reportSettlement(ctx, settlement) {
   };
 }
 async function followRun(ctx, options, deps) {
-  const readLogs = createJournalCursor(ctx, options.runnerId, {
-    runId: options.runId,
-    stream: "run-logs"
-  });
+  const printers = createFollowPrinters(ctx, options);
   const readStatus = createJournalCursor(ctx, options.runnerId, {
     runId: options.runId,
     stream: "run-status"
   });
   const unreachable = createUnreachableBudget(pollIntervalMs3);
-  const printLogs = async () => {
-    const logs = await readLogs();
-    if (logs.type !== "entries")
-      return logs;
-    for (const entry of logs.entries) {
-      ctx.ui.stream(entry, formatRunLogLine(entry.payload));
+  const printAll = async () => {
+    for (const print of printers) {
+      const window2 = await print();
+      if (window2.type !== "entries")
+        return window2;
     }
-    return logs;
+    return;
+  };
+  let progressReported = false;
+  const printProgress = (entries) => {
+    if (printers.length > 0 || progressReported)
+      return;
+    const entry = entries.find((e) => readRunSettlement(e.payload).type === "in-progress");
+    if (entry === undefined)
+      return;
+    progressReported = true;
+    ctx.ui.stream(entry, interactiveRunnerMessages.runInProgress);
   };
   const maxPolls = Math.max(1, Math.ceil(options.timeoutSeconds * 1000 / pollIntervalMs3));
   for (let poll = 1;; poll++) {
-    const logs = await printLogs();
-    if (logs.type === "failed")
-      return journalReadFailure(logs);
-    const status = logs.type === "unreachable" ? logs : await readStatus();
+    const interrupted = await printAll();
+    if (interrupted?.type === "failed")
+      return journalReadFailure(interrupted);
+    const status = interrupted?.type === "unreachable" ? interrupted : await readStatus();
     if (status.type === "failed")
       return journalReadFailure(status);
-    if (logs.type === "unreachable" || status.type === "unreachable") {
+    if (status.type === "unreachable") {
       if (unreachable.exhausted())
         return { ...unreachableFailure };
     } else {
       unreachable.reset();
+      printProgress(status.entries);
       const settlement = findSettlement(status.entries);
       if (settlement !== undefined) {
-        await printLogs();
+        if (await printAll() !== undefined) {
+          ctx.ui.warn(interactiveRunnerMessages.followEndCutShort);
+        }
         return reportSettlement(ctx, settlement);
       }
     }
@@ -187094,6 +187159,13 @@ async function handleRunnerRun(ctx, options, deps) {
     return { ...failureFields(resolved), exitCode: resolved.exitCode };
   }
   announceRunner(ctx, resolved);
+  let recorderSinceSequence;
+  if (options.recorderEvents) {
+    const anchor = await resolveRecorderAnchor(ctx, resolved, deps);
+    if (!anchor.ok)
+      return { ...anchor.failure };
+    recorderSinceSequence = anchor.sinceSequence;
+  }
   const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.runFlow, { entryPointPath, files, id: resolved.runnerId }, runnerCallOptions);
   if (!result.ok) {
     return { ...failureFields(result), exitCode: exitCodes.network };
@@ -187111,12 +187183,16 @@ async function handleRunnerRun(ctx, options, deps) {
       };
     case "submitted": {
       const runId = result.value.runId;
-      if (!options.follow) {
+      const follow = options.follow || options.logs || options.runEvents || options.recorderEvents;
+      if (!follow) {
         ctx.ui.output({ runId, runnerId: resolved.runnerId }, interactiveRunnerMessages.runSubmitted(runId));
         return;
       }
       ctx.ui.info(interactiveRunnerMessages.runSubmitted(runId));
       return followRun(ctx, {
+        logs: options.logs,
+        recorderSinceSequence,
+        runEvents: options.runEvents,
         runId,
         runnerId: resolved.runnerId,
         timeoutSeconds: timeout.seconds
@@ -187136,16 +187212,20 @@ async function handleRunnerRun(ctx, options, deps) {
 var runExamples2 = `
 Examples:
   $ qawolf runner run flows/checkout.flow.ts
-  $ qawolf runner run flows/checkout.flow.ts --follow`;
+  $ qawolf runner run flows/checkout.flow.ts --follow
+  $ qawolf runner run flows/checkout.flow.ts --follow --logs`;
 var eventsExamples = `
 Examples:
   $ qawolf runner events recorder --tail 5
   $ qawolf runner events run-logs --run <runId> --follow
   $ qawolf runner events console --since 120 --json`;
 function registerRunnerRunCommands(runner, signals) {
-  declareCommandKind(runner.command("run <file>"), "write").description("Run a flow on an interactive runner, shipping the current directory's files with it").option("--follow", "Stream the run's logs until it settles", false).option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).action((file2, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
+  declareCommandKind(runner.command("run <file>"), "write").description("Run a flow on an interactive runner, shipping the current directory's files with it").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).action((file2, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
     entryPoint: file2,
     follow: opts.follow,
+    logs: opts.logs,
+    recorderEvents: opts.recorderEvents,
+    runEvents: opts.runEvents,
     runner: opts.runner,
     timeout: opts.timeout
   }, runnerDeps(ctx)))(opts, command));
@@ -187205,4 +187285,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=80A0CD4106C384B664756E2164756E21
+//# debugId=229B48C8231EE6BC64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.9.2",
+  "version": "1.11.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",

package/skills/qawolf-cli/SKILL.md

@@ -72,6 +72,15 @@ each printed line from the payload alone to the whole envelope (`sequence`,
 `recordedAt`, `payload`). Both are JSON. Pass it when you want to page by
 sequence, omit it when you want the payloads themselves.
 
+A `--json` response shows you most of its own shape, so read it first.
+
+`qawolf run get` is the exception worth reading about before you use it. Its
+artifact URLs expire, its failure fields are absent from a passing run, and its
+`traceUrl` downloads a Playwright trace that you can read as JSON without
+opening the trace viewer. **Read
+[`references/run-results.md`](references/run-results.md) before reporting on a
+run's outcome or opening its trace.**
+
 ## Safety: reads vs writes
 
 Read commands do not change team data, but some have operational effects noted
@@ -127,6 +136,7 @@ current branch.
 | `qawolf issue create` | write | Create a bug or coverage request issue for the caller's team. Maintenance issues cannot be created through the public API. |
 | `qawolf issue find` | read | List the team's bug reports, maintenance reports, or coverage requests, newest first. |
 | `qawolf issue get` | read | Get an issue by id. |
+| `qawolf issue update` | write | Update an issue owned by the caller's team. Omitted fields remain unchanged. |
 | `qawolf run create` | write | Create a run for the selected flows and/or tags in an environment. |
 | `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. |

package/skills/qawolf-cli/references/run-results.md

@@ -0,0 +1,169 @@
+# Reading a run's results
+
+How to use what `qawolf run get --run-id <id> --json` returns, and how to read
+the Playwright trace it links to.
+
+Call `run get` with `--json` and you see most of the response immediately. Read
+this file for the parts a single response cannot show you: fields that appear
+only when something fails, rules about the artifact URLs, and how to read a
+trace without opening the trace viewer.
+
+## The shape
+
+A run holds flows, a flow holds attempts, and artifacts hang off an attempt:
+
+```text
+run
+└── flows[]
+    ├── failure          only when the flow failed
+    └── attempts[]       oldest first
+        ├── logsUrl
+        ├── traceUrl
+        └── videoUrl
+```
+
+`runId` in the response is canonical and can differ from the id you asked for.
+Use the returned value for follow-up calls.
+
+Poll `status` until it reaches `passed`, `failed` or `canceled`. The other
+values mean the run is still going.
+
+## Fields a passing run does not show you
+
+- `flows[].failure` exists only when a flow failed. Every flow passing means
+  there is no failure object at all, so its diagnosis and issue id are invisible
+  until something breaks. Do not conclude the field does not exist.
+- `git` is populated only when a deploy notification started the run. A run
+  started manually or with `run create` has an empty object here.
+- An attempt's `kind` and `status` select which other fields it has. Only
+  automated attempts that reached a verdict carry artifact URLs; canceled
+  attempts and manual Wolf Browser attempts carry none.
+- A flow that passed after a retry still lists its failed attempts. Read the
+  last attempt for the outcome, and the earlier ones to see what went wrong.
+
+## Artifact URLs
+
+Each automated attempt links `logsUrl` (execution logs), `videoUrl` (screen
+recording) and `traceUrl` (a Playwright `trace.zip`).
+
+1. They are signed URLs with a limited life. The contract guarantees at least a
+   day. Call `run get` again for fresh ones instead of storing them; a stored
+   URL becomes a dead link.
+2. A URL can return 404 when that attempt did not produce that artifact. Handle
+   the 404 rather than treating the URL's presence as a guarantee of content.
+3. Download with a plain HTTP GET. The signature is in the URL, so no
+   authentication header is needed and no QA Wolf credentials are involved.
+
+```bash
+qawolf run get --run-id "$RUN_ID" --json \
+  | jq -r '.flows[].attempts[-1].traceUrl // empty' \
+  | head -1 \
+  | xargs -r curl -sS -o trace.zip
+```
+
+## Reading the Playwright trace
+
+The usual advice is `npx playwright show-trace trace.zip`, which opens a
+browser window. That is useless in a shell and unnecessary: the zip holds
+newline-delimited JSON files, and reading them directly is faster than
+downloading a viewer.
+
+The zip holds `trace.trace` (the events), `trace.network` (one request and
+response per line) and a `resources/` directory of screencast frames. The
+frames are most of the size, so extract only what you need.
+
+### The event types
+
+Every line of `trace.trace` is one JSON object with a `type`:
+
+- `before` — a call started. Carries `callId`, `startTime`, `class`, `method`
+  and `params`. `params.selector` or `params.url` is usually the target.
+- `after` — that call finished. Matched to its `before` by `callId`. Carries
+  `endTime` and `result`, and an `error` when the call failed.
+- `console` — a browser console message, with `messageType` and `text`.
+- `log` — Playwright's own progress notes for a call.
+- `screencast-frame`, `frame-snapshot` — the filmstrip and DOM snapshots the
+  viewer renders. Usually not worth reading directly.
+
+Two details cost time if you miss them:
+
+- **Times are monotonic milliseconds, not seconds.** A `goto` whose `startTime`
+  and `endTime` differ by `161.6` took 161 milliseconds. Subtract the smallest
+  `startTime` to get an offset from the start of the trace.
+- **Return values use a serialized envelope.** `{"value":{"s":"passed"}}` is
+  the string `passed`, `{"n":640}` is the number `640`, and `{"o":[...]}` is an
+  object as a list of key and value pairs.
+
+### A worked example
+
+Pairing `before` with `after` gives an action timeline with durations and
+failures:
+
+```python
+import json, sys, zipfile
+
+with zipfile.ZipFile(sys.argv[1]) as z:
+    events = [json.loads(line) for line in z.read("trace.trace").decode().splitlines()]
+
+starts = {e["callId"]: e for e in events if e["type"] == "before"}
+ends = {e["callId"]: e for e in events if e["type"] == "after"}
+t0 = min(e["startTime"] for e in starts.values())
+
+for call_id, before in starts.items():
+    after = ends.get(call_id, {})
+    params = before.get("params", {})
+    target = params.get("selector") or params.get("url") or ""
+    error = after.get("error")
+    print(
+        f'{(before["startTime"] - t0) / 1000:7.2f}s'
+        f' {after.get("endTime", before["startTime"]) - before["startTime"]:7.1f}ms'
+        f'  {before["class"]}.{before["method"]:<18} {target[:40]}'
+        f'{"  FAILED: " + json.dumps(error)[:60] if error else ""}'
+    )
+
+for e in events:
+    if e["type"] == "console" and e["messageType"] == "error":
+        print(f'console error: {e["text"][:70]}')
+```
+
+It prints one line per call, in order:
+
+```text
+   0.00s   161.6ms  Frame.goto               https://example.com/
+   0.17s    28.3ms  Frame.waitForSelector    #screen
+   0.20s     4.2ms  Frame.innerText          #fps_stats
+console error: Failed to load resource: the server responded with a status of 404 ()
+```
+
+To find why an attempt failed, read the last `after` that carries an `error`,
+then the `console` errors near it in time. To see what the page did, read
+`trace.network`.
+
+## Response fields
+
+Every documented field of the `run.get` response. `[]` marks an array, so
+`flows[].attempts[].traceUrl` is the trace URL of one attempt of one flow.
+
+<!-- fields:start — generated by `bun run generate`, do not edit -->
+
+- `completedAt` — When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped).
+- `git` — The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create.
+- `git.commitUrl` — Link to the commit on the code host.
+- `runId` — The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.
+- `status` — One of: queued, running, passed, failed, canceled
+- `flows` — The run's flows, ordered alphabetically by name.
+- `flows[].attempts` — The flow's finished execution attempts, oldest first, including manual Wolf Browser attempts. Present once at least one attempt has finished, so a flow that passed after retries also lists its failed attempts. Artifact URLs appear only on automated attempts that reached a verdict, stay valid for at least a day (call run.get again for fresh ones), and can return 404 when the attempt did not produce that artifact.
+- `flows[].attempts[].logsUrl` — Signed URL for the attempt's execution logs.
+- `flows[].attempts[].traceUrl` — Signed URL for the attempt's Playwright trace (a trace.zip; open it with `npx playwright show-trace`).
+- `flows[].attempts[].videoUrl` — Signed URL for the attempt's screen recording.
+- `flows[].attempts[].kind` — One of: automated, manual
+- `flows[].attempts[].startedAt` — Absent when the attempt failed before it could start.
+- `flows[].attempts[].status` — One of: passed, failed, canceled
+- `flows[].failure.diagnosis` — QA Wolf's investigation verdict for the failure: `bug` means the application is broken, `maintenance` means the test needed an update and the failure does not indicate an application problem. Absent until the investigation reaches a verdict. Pass issueId to issue.get for details.
+- `flows[].failure.diagnosis.issueId` — The id of the issue.
+- `flows[].failure.diagnosis.type` — One of: bug, maintenance
+- `flows[].flowId` — The id of the flow.
+- `flows[].status` — One of: failed, queued, running, passed, canceled
+- `url` — Absolute URL of the run page.
+
+<!-- fields:end -->

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

@@ -166,13 +166,23 @@ The call answers with a run id as soon as the run is accepted. **The outcome is
 not in that answer**, it is in the `run-status` stream, whose entries carry
 `runId`, `status` and an `errorMessage` when there is one.
 
-**Pass `--follow` to `run` and let it wait for you.** It streams the run's logs
-and ends on the settled status, never on the logs, so a run that prints nothing
+**Pass `--follow` to `run` and let it wait for you.** It reports the run's
+status — in progress, then passed or failed — and ends on the settled status.
+Exit code `1` means the run did not pass. Three flags mirror more streams into
+the follow, and each implies `--follow` on its own: `--logs` streams every log
+line the run produces, `--run-events` streams the run's progress events as JSON
+lines, and `--recorder-events` streams the browser actions the runner records
+as JSON lines — the recorder is runner-wide rather than run-scoped, so that one
+carries whatever is recorded after an anchor taken just before submission. Whatever mirrors are on, the
+follow still ends on the status, never on them, so a run that prints nothing
 still terminates the follow and a run that dies mid-sentence still reports how.
-Exit code `1` means the run did not pass.
+Combining mirror flags interleaves their lines with nothing saying which stream
+a line came from — fine for eyeballs; when parsing, follow one stream at a time.
 
 ```sh
 qawolf runner run flows/checkout.flow.ts --follow
+qawolf runner run flows/checkout.flow.ts --follow --logs
+qawolf runner run flows/checkout.flow.ts --follow --recorder-events
 ```
 
 If you would rather submit and come back later, note that `--follow` on `events`