@qawolf/cli 1.8.1 → 1.9.0

package/dist/cli.js

@@ -156391,6 +156391,60 @@ var installMessages = {
     appiumNotFound: (appiumPath) => toolNotInstalled("Appium", appiumPath)
   }
 };
+// src/core/messages/interactiveRunner.ts
+var noRunnerId = "No runner id. Pass --runner, set QAWOLF_RUNNER_ID, or run qawolf runner launch first.";
+var interactiveRunnerMessages = {
+  actionFailed: (errorMessage2) => `The action reached the runner and did not take effect: ${errorMessage2}`,
+  actionFlagsWithStdin: '"-" reads the whole action from stdin, so an action flag passed alongside it would be ignored. Pipe the action in on its own, or name the action type and use flags.',
+  actionMayHaveHappened: "The runner could not be reached, which does not mean the action was not performed: it may have stopped answering mid-action. Take a screenshot before repeating it.",
+  actionNotJson: `Stdin did not hold a JSON action. Pipe one object, for example '{"type":"click","button":"left","x":480,"y":260}'.`,
+  actionPerformed: (type) => `Performed ${type}.`,
+  alreadyRunning: (id) => `Runner ${id} was already running.`,
+  defaultNotRemembered: (id) => `Runner ${id} could not be written to .qawolf as this directory's default, so later commands will not find it on their own. Pass --runner ${id}, or set QAWOLF_RUNNER_ID=${id}.`,
+  defaultNotForgotten: (id) => `Runner ${id} was stopped, but it could not be removed from .qawolf as this directory's default, so later commands will still be sent to it. Pass --runner, or launch a new runner.`,
+  fileNotCollected: (path) => `"${path}" is not one of the files that travel to a runner. It must be inside the current directory and end in .ts, .tsx, .js, .mjs, .cjs or .json.`,
+  fileUnreadable: (path, reason) => `${path} is one of the files that travel to a runner, but it could not be read: ${reason}. Move it out of the current directory, or make it readable.`,
+  filesUnreadable: (reason) => `One of the files that travel to a runner could not be read: ${reason}.`,
+  filesTooLarge: (byteLength, maxByteLength, largest) => `The collected files carry ${String(byteLength)} bytes, over the ${String(maxByteLength)} a single run may ship. The largest are ${largest.map((file) => `${file.path} (${String(file.byteLength)} bytes)`).join(", ")}. Every .ts, .tsx, .js, .mjs, .cjs and .json file under the current directory travels, build output included, so run from a directory holding only the flow and what it imports.`,
+  keptAlive: (id) => `Runner ${id} is alive, and its inactivity clock has been reset.`,
+  launchFailed: (id, error) => `Launching runner ${id} failed. ${error}`,
+  launchLost: (id, error) => `Launching runner ${id} failed. ${error}. The request may still have reached QA Wolf and started a runner, so relaunch the same id with qawolf runner launch --id ${id} to attach to it rather than start a second one, or stop it with qawolf runner stop --runner ${id}.`,
+  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.`,
+  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}`,
+  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.`,
+  runSubmitted: (runId) => `Submitted run ${runId}.`,
+  runnerHasNoScreen: "This runner does not run a browser on a virtual desktop, so there is nothing about it to see or drive. Retrying will never help: launch a node20WithPlaywright runner instead.",
+  runnerHasNoScreenToEvaluate: "The runner could not evaluate the snippet. This covers a runner that is still starting or busy, and also one with no live page to evaluate against: a freshly launched runner has no page until a run opens one, so run a flow on it with qawolf runner run first. If it is not a runner that runs a browser at all, this will never clear. It is not proof the snippet did not run, so do not resubmit one that mutates the page without reading qawolf runner events console first.",
+  runnerUnreachable: "The runner could not be reached. It may still be starting, or it may have terminated after inactivity. Retry, or launch it again.",
+  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.",
+  screenshotUnwritable: (path, detail) => `The screen was captured but could not be written to "${path}": ${detail}. Give --out a path this process can write to.`,
+  screenshotWritten: (path) => `Wrote the runner's screen to ${path}.`,
+  skippedEntries: (stream, count) => `${pluralize(count, "entry", "entries")} of ${stream} were dropped before this read: the runner keeps a bounded history and this follow has been overtaken.`,
+  snippetEmpty: (path) => `"${path}" holds no code to evaluate.`,
+  snippetErrored: (errorMessage2) => errorMessage2 === undefined ? "The snippet threw and reported no message." : `The snippet threw: ${errorMessage2}`,
+  snippetFileUnreadable: (path) => `Could not read "${path}". Name a readable file, or "-" to read the snippet from stdin.`,
+  snippetRan: "The snippet ran. Its value is not returned: read anything it printed with qawolf runner events console.",
+  snippetStopped: "The snippet was interrupted before it finished. Anything it printed first is in qawolf runner events console.",
+  stdinEmptyAction: 'Nothing arrived on stdin. Pipe the action in, or name the action type instead of "-".',
+  stdinEmptySnippet: 'Nothing arrived on stdin. Pipe the snippet in, or name a file instead of "-".',
+  stopped: (id) => `Stopped runner ${id}.`,
+  requestTooLarge: (byteLength, maxByteLength) => `The run request encodes to ${String(byteLength)} bytes, over the ${String(maxByteLength)} a runner accepts. Escaping inflates file content, so a set of files inside the content cap can still encode to more than this. Run from a directory holding only the flow and what it imports.`,
+  unknownStream: (stream, known) => `"${stream}" is not a stream QA Wolf writes, so this read has nothing to return. QA Wolf writes ${known.join(", ")}.`,
+  unsearchedHistory: (stream) => `This read of ${stream} stopped before searching all of the runner's history, so older entries may exist that it did not look at. Page forwards with --since to reach them.`,
+  submitMayHaveStarted: "The runner did not answer, which does not mean the run did not start. Read qawolf runner events run-status before running the flow again, and use the newest run id there if one appeared.",
+  targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`
+};
 // src/core/messages/runner.ts
 var runnerMessages = {
   playwrightLoadFailed: (envDir, detail) => packageLoadFailed("Playwright", envDir, detail),
@@ -156543,7 +156597,8 @@ var exitCodes = {
   invalidArgs: 2,
   auth: 3,
   network: 4,
-  config: 5
+  config: 5,
+  timeout: 6
 };
 function exit(code, message, proc = process) {
   if (message !== undefined && message.length > 0) {
@@ -171279,7 +171334,12 @@ async function requestWithRetry(args) {
     const backoff = args.backoffMs[attempt];
     const retryable = result.error.kind === "network" || result.error.kind === "timeout";
     if (backoff === undefined || !retryable) {
-      return { ok: false, ...args.describe(result.error) };
+      const mayHaveArrived = result.error.kind !== "http";
+      return {
+        ok: false,
+        ...args.describe(result.error),
+        ...mayHaveArrived ? { mayHaveArrived } : {}
+      };
     }
     await sleep2(backoff);
   }
@@ -172427,7 +172487,6 @@ var browserActionSchema = exports_external.discriminatedUnion("type", [
     type: exports_external.literal("type")
   })
 ]);
-
 // node_modules/@qawolf/api-contracts/dist/v1/runner/environment.js
 var reservedRunEnvironmentVariablePrefix = "QAWOLF_";
 function refusalForRunEnvironmentVariableName(name) {
@@ -172488,7 +172547,6 @@ var runFilePathSchema = exports_external.string().refine(isShippableRunFilePath,
   error: runFilePathRefusal
 });
 var runPackageJsonPath = "package.json";
-
 // node_modules/@qawolf/api-contracts/dist/v1/runner/identity.js
 var runnerNameSchema = exports_external.enum([
   "node20Basic",
@@ -172502,7 +172560,6 @@ var makeRunnerSchema = () => exports_external.object({
   id: runnerIdSchema.describe("The runner's id, as supplied when launching it."),
   runnerName: runnerNameSchema.describe("The image requested when the runner was launched. QA Wolf may place it on faster hardware, reported in gpuAccelerated.")
 });
-
 // node_modules/@qawolf/api-contracts/dist/v1/runner/journal.js
 var journalEntrySchema = exports_external.object({
   payload: exports_external.unknown(),
@@ -172537,7 +172594,6 @@ var readJournalResponseSchema = exports_external.object({
   nextSequence: exports_external.number().int().nonnegative(),
   oldestAvailableSequence: exports_external.number().int().nonnegative()
 });
-
 // node_modules/@qawolf/api-contracts/dist/v1/runner/payloadSize.js
 var maxRunFilesByteLength = 4 * 1024 * 1024;
 var maxRunnerRequestEncodedByteLength = 9 * 1024 * 1024;
@@ -172560,7 +172616,6 @@ var runFilesSchema = exports_external.record(exports_external.string(), exports_
 }).refine((files) => runFilesByteLength(files) <= maxRunFilesByteLength, {
   error: `The files in one request may carry at most ${maxRunFilesByteLength} bytes in total.`
 });
-
 // node_modules/@qawolf/api-contracts/dist/v1/runner/screen.js
 var runnerScreenNotReadySchema = exports_external.object({
   outcome: exports_external.literal("screen-not-ready")
@@ -172666,6 +172721,7 @@ var makeEnvironmentResourceSchema = (ids) => resource({
     })
   ]).optional().describe("The environment's flow code branch and its git reconciliation state, if it has one."),
   id: ids.environment,
+  isDefault: exports_external.boolean().describe("Whether this is the workspace's default environment."),
   kind: exports_external.enum(["static", "preview"]).describe("Whether the environment is static or a preview."),
   name: exports_external.string(),
   runConcurrencyLimit: exports_external.string().describe('Maximum number of concurrent runs: a whole number, "unlimited", or a concurrency expression.'),
@@ -172681,6 +172737,7 @@ var makeFindEnvironmentsContract = (ids) => {
     ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 100 })
   });
   const output = exports_external.object({
+    defaultEnvironmentId: ids.environment.describe("The id of the workspace's default environment."),
     environments: exports_external.array(makeEnvironmentResourceSchema(ids)).describe("The team's environments, newest first."),
     nextCursor: nextCursorSchema
   });
@@ -172754,7 +172811,7 @@ var makeSetEnvironmentVariableContract = (ids) => {
     name: exports_external.string().describe("The stored variable name after whitespace is replaced with underscores and letters are uppercased.")
   });
   return {
-    description: 'Create or replace an environment variable. If the user asks to create one for "my email" without naming it, use DEFAULT_ENVIRONMENT_EMAIL. The value is never returned.',
+    description: 'Create or replace an environment variable. If the user asks to create one for "my email" without naming it, use DEFAULT_EMAIL. The value is never returned.',
     input,
     kind: "write",
     name: "environment.setVariable",
@@ -173056,8 +173113,50 @@ var makeGetRunContract = (ids) => {
   const input = exports_external.object({
     runId: ids.run
   });
+  const artifactUrls = {
+    logsUrl: exports_external.url().optional().describe("Signed URL for the attempt's execution logs."),
+    traceUrl: exports_external.url().optional().describe("Signed URL for the attempt's Playwright trace (a trace.zip; open it with `npx playwright show-trace`)."),
+    videoUrl: exports_external.url().optional().describe("Signed URL for the attempt's screen recording.")
+  };
+  const automatedKind = exports_external.literal("automated").describe("The attempt ran on a QA Wolf runner.");
+  const automatedAttempt = exports_external.discriminatedUnion("status", [
+    exports_external.object({
+      ...artifactUrls,
+      completedAt: exports_external.iso.datetime(),
+      kind: automatedKind,
+      startedAt: exports_external.iso.datetime(),
+      status: exports_external.literal("passed")
+    }),
+    exports_external.object({
+      ...artifactUrls,
+      completedAt: exports_external.iso.datetime(),
+      kind: automatedKind,
+      startedAt: exports_external.iso.datetime().optional().describe("Absent when the attempt failed before it could start."),
+      status: exports_external.literal("failed")
+    }),
+    exports_external.object({
+      completedAt: exports_external.iso.datetime().optional(),
+      kind: automatedKind,
+      startedAt: exports_external.iso.datetime().optional(),
+      status: exports_external.literal("canceled").describe("The attempt was terminated without reaching a verdict.")
+    })
+  ]);
+  const manualAttempt = exports_external.object({
+    completedAt: exports_external.iso.datetime(),
+    kind: exports_external.literal("manual").describe("The attempt ran by hand in the Wolf Browser."),
+    startedAt: exports_external.iso.datetime(),
+    status: exports_external.literal("passed")
+  });
+  const attempt = exports_external.union([automatedAttempt, manualAttempt]);
+  const attempts = exports_external.array(attempt).optional().describe("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.");
+  const diagnosis = exports_external.object({
+    issueId: ids.issue,
+    type: exports_external.enum(["bug", "maintenance"])
+  }).optional().describe("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.");
   const failedFlow = exports_external.object({
+    attempts,
     failure: exports_external.object({
+      diagnosis,
       error: exports_external.string()
     }),
     flowId: ids.flow,
@@ -173065,6 +173164,7 @@ var makeGetRunContract = (ids) => {
     status: exports_external.literal("failed")
   });
   const nonFailedFlow = exports_external.object({
+    attempts,
     flowId: ids.flow,
     name: exports_external.string(),
     status: exports_external.enum(["queued", "running", "passed", "canceled"])
@@ -175510,6 +175610,8 @@ function createAgentRenderers() {
       writeStderrLine(humanMessage);
     },
     gap: () => writeStderrLine(""),
+    stream: (_data, line) => writeStdoutRaw(`${line}
+`),
     write: (text) => writeStderrRaw(text),
     withProgress: async (steps, done) => {
       const results = [];
@@ -175545,6 +175647,8 @@ ${body}` : ""));
     },
     output: (_data, humanMessage) => clack.log.info(humanMessage),
     gap: () => process.stderr.write(`
+`),
+    stream: (_data, line) => writeStdoutRaw(`${line}
 `),
     write: (text) => writeStdoutRaw(text),
     withProgress: async (steps, done) => {
@@ -175618,6 +175722,7 @@ function createJsonRenderers() {
     error: (title, body) => writeJsonDiagnostic({ type: "error", title, body }),
     output: (data, _humanMessage) => writeJsonLine(data),
     gap: () => {},
+    stream: (data, _line) => writeJsonLine(data),
     write: () => {},
     withProgress: async (steps, done) => {
       const results = [];
@@ -175804,7 +175909,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.8.1",
+  version: "1.9.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -175864,7 +175969,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.24.0",
+    "@qawolf/api-contracts": "0.25.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -185988,16 +186093,29 @@ async function handlePublicApiCommand(ctx, spec, options) {
   return;
 }
 
+// src/domains/publicApi/skippedContracts.ts
+var handWrittenContractNames = new Set([
+  "flow.list",
+  "runner.evaluateSnippet",
+  "runner.launch",
+  "runner.performAction",
+  "runner.readJournal",
+  "runner.runFlow",
+  "runner.stop",
+  "runner.takeScreenshot"
+]);
+var unexpressibleContractNames = new Set([
+  "issue.update"
+]);
+var skippedContractNames = new Set([
+  ...handWrittenContractNames,
+  ...unexpressibleContractNames
+]);
+
 // src/commands/publicApi/index.ts
 var groupDescriptions = {
   run: "Trigger and manage QA Wolf runs on the platform"
 };
-var handWrittenContractNames = new Set(["flow.list"]);
-var skippedContractNames = new Set([
-  ...handWrittenContractNames,
-  "issue.update",
-  "runner.performAction"
-]);
 var optionEnvironmentVariables = new Map([
   ["environmentId", "QAWOLF_ENVIRONMENT"],
   ["public.run.create.aiTaskId", "QAWOLF_AI_TASK_ID"]
@@ -186044,6 +186162,1016 @@ function registerPublicApiCommands(program2, signals, options = {}) {
   }
 }
 
+// src/core/interactiveRunner/runFiles.ts
+import { isAbsolute as isAbsolute5, relative as relative8, resolve as resolve11, sep as sep5 } from "node:path";
+function toCollectedPath(cwd, path9) {
+  const absolute = isAbsolute5(path9) ? path9 : resolve11(cwd, path9);
+  return relative8(cwd, absolute).split(sep5).join("/");
+}
+var namedLargestFileCount = 3;
+function largestFiles(files) {
+  return Object.entries(files).map(([path9, content]) => ({
+    byteLength: runFilesByteLength({ [path9]: content }),
+    path: path9
+  })).sort((a3, b4) => b4.byteLength - a3.byteLength).slice(0, namedLargestFileCount);
+}
+function checkPresenceAndSize(files, requiredPath) {
+  if (!Object.hasOwn(files, requiredPath)) {
+    return { path: requiredPath, type: "missing-file" };
+  }
+  const byteLength = runFilesByteLength(files);
+  if (byteLength > maxRunFilesByteLength) {
+    return {
+      byteLength,
+      largest: largestFiles(files),
+      maxByteLength: maxRunFilesByteLength,
+      type: "too-large"
+    };
+  }
+  const encodedByteLength = Buffer.byteLength(JSON.stringify({ files, path: requiredPath }), "utf8");
+  if (encodedByteLength > maxRunnerRequestEncodedByteLength) {
+    return {
+      byteLength: encodedByteLength,
+      maxByteLength: maxRunnerRequestEncodedByteLength,
+      type: "request-too-large"
+    };
+  }
+  return { type: "ok" };
+}
+function checkRunFiles(files, entryPointPath) {
+  const present = checkPresenceAndSize(files, entryPointPath);
+  if (present.type !== "ok")
+    return present;
+  if (!Object.hasOwn(files, runPackageJsonPath)) {
+    return { type: "missing-package-json" };
+  }
+  return { type: "ok" };
+}
+function checkSnippetFiles(files, contextFilePath) {
+  return checkPresenceAndSize(files, contextFilePath);
+}
+function describeRunFilesCheck(check2) {
+  switch (check2.type) {
+    case "missing-file":
+      return interactiveRunnerMessages.fileNotCollected(check2.path);
+    case "missing-package-json":
+      return interactiveRunnerMessages.missingPackageJson;
+    case "too-large":
+      return interactiveRunnerMessages.filesTooLarge(check2.byteLength, check2.maxByteLength, check2.largest);
+    case "request-too-large":
+      return interactiveRunnerMessages.requestTooLarge(check2.byteLength, check2.maxByteLength);
+  }
+}
+
+// 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
+async function launchRunner(ctx, options) {
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.launch, {
+    id: options.id,
+    ...options.runnerName ? { runnerName: options.runnerName } : {}
+  });
+  if (!result.ok) {
+    return {
+      error: result.error,
+      exitCode: exitCodes.network,
+      mayHaveArrived: result.mayHaveArrived ?? false,
+      ok: false
+    };
+  }
+  return { ok: true, value: result.value };
+}
+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(() => {
+    ctx.ui.warn(interactiveRunnerMessages.defaultNotRemembered(options.id));
+    return false;
+  });
+  const launched = await launchRunner(ctx, options);
+  if (launched.ok)
+    return launched;
+  if (remembered && !launched.mayHaveArrived) {
+    await (priorDefault === undefined ? deps.store.clearDefaultRunnerId() : deps.store.writeDefaultRunnerId(priorDefault)).catch(() => {
+      return;
+    });
+  }
+  return {
+    error: launched.mayHaveArrived ? interactiveRunnerMessages.launchLost(options.id, launched.error) : interactiveRunnerMessages.launchFailed(options.id, launched.error),
+    exitCode: launched.exitCode,
+    mayHaveArrived: launched.mayHaveArrived,
+    ok: false
+  };
+}
+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 { error: launched.error, exitCode: launched.exitCode };
+  }
+  ctx.ui.output(launched.value, launched.value.outcome === "launched" ? interactiveRunnerMessages.launched(launched.value.id) : interactiveRunnerMessages.alreadyRunning(launched.value.id));
+  return;
+}
+
+// src/domains/interactiveRunner/resolveRunner.ts
+var runnerIdEnvironmentVariable = "QAWOLF_RUNNER_ID";
+async function chooseRunnerId(runner, deps) {
+  if (runner !== undefined)
+    return runner;
+  const fromEnvironment = deps.env[runnerIdEnvironmentVariable]?.trim();
+  if (fromEnvironment)
+    return fromEnvironment;
+  return deps.store.readDefaultRunnerId();
+}
+async function resolveRunner(ctx, options, deps) {
+  const chosen = await chooseRunnerId(options.runner, deps);
+  if (chosen !== undefined) {
+    const parsed = parseRunnerId(chosen);
+    return parsed.ok ? { runnerId: parsed.id, type: "resolved" } : {
+      error: parsed.error,
+      exitCode: exitCodes.invalidArgs,
+      type: "failed"
+    };
+  }
+  if (!options.autoLaunch) {
+    return {
+      error: options.noRunnerIdMessage ?? interactiveRunnerMessages.noRunnerId,
+      exitCode: exitCodes.invalidArgs,
+      type: "failed"
+    };
+  }
+  const launched = await launchAndRemember(ctx, { id: deps.makeRunnerId(), runnerName: undefined }, deps);
+  if (!launched.ok) {
+    return {
+      error: launched.error,
+      exitCode: launched.exitCode,
+      type: "failed"
+    };
+  }
+  return { runnerId: launched.value.id, type: "launched" };
+}
+function announceRunner(ctx, resolved) {
+  if (resolved.type === "launched") {
+    ctx.ui.info(interactiveRunnerMessages.launchedForCommand(resolved.runnerId));
+  }
+}
+
+// src/domains/interactiveRunner/evaluateSnippet.ts
+var stdinArgument = "-";
+async function resolveScope(contextFile, deps) {
+  if (contextFile === undefined) {
+    return { filePath: undefined, files: undefined, ok: true };
+  }
+  const filePath = toCollectedPath(deps.cwd, contextFile);
+  const files = await deps.collectRunFiles();
+  const check2 = checkSnippetFiles(files, filePath);
+  if (check2.type !== "ok") {
+    return { error: describeRunFilesCheck(check2), ok: false };
+  }
+  return { filePath, files, ok: true };
+}
+async function readCode(source, deps) {
+  const code = source === stdinArgument ? await deps.readStdin() : await deps.readFile(source).catch(() => {
+    return;
+  });
+  if (code === undefined) {
+    return {
+      error: interactiveRunnerMessages.snippetFileUnreadable(source),
+      ok: false
+    };
+  }
+  if (code.trim() === "") {
+    return source === stdinArgument ? { error: interactiveRunnerMessages.stdinEmptySnippet, ok: false } : { error: interactiveRunnerMessages.snippetEmpty(source), ok: false };
+  }
+  return { code, ok: true };
+}
+async function handleRunnerExec(ctx, options, deps) {
+  const code = await readCode(options.source, deps);
+  if (!code.ok)
+    return { error: code.error, exitCode: exitCodes.invalidArgs };
+  const scope = await resolveScope(options.contextFile, deps);
+  if (!scope.ok)
+    return { error: scope.error, exitCode: exitCodes.invalidArgs };
+  const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
+  if (resolved.type === "failed") {
+    return { error: resolved.error, exitCode: resolved.exitCode };
+  }
+  announceRunner(ctx, resolved);
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.evaluateSnippet, {
+    code: code.code,
+    id: resolved.runnerId,
+    ...scope.filePath === undefined ? {} : { filePath: scope.filePath },
+    ...scope.files === undefined ? {} : { files: scope.files }
+  });
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  if (result.value.outcome === "runner-unreachable") {
+    return {
+      error: interactiveRunnerMessages.runnerHasNoScreenToEvaluate,
+      exitCode: exitCodes.network
+    };
+  }
+  switch (result.value.result) {
+    case "success":
+      ctx.ui.output({ outcome: "evaluated", result: "success" }, interactiveRunnerMessages.snippetRan);
+      return;
+    case "stopped":
+      return {
+        error: interactiveRunnerMessages.snippetStopped,
+        exitCode: exitCodes.testFailure
+      };
+    case "error":
+      return {
+        error: interactiveRunnerMessages.snippetErrored(result.value.errorMessage),
+        exitCode: exitCodes.testFailure
+      };
+  }
+}
+
+// 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/performAction.ts
+var stdinArgument2 = "-";
+async function readAction(type, flags, deps) {
+  if (type !== stdinArgument2)
+    return buildBrowserAction(type, flags);
+  if (Object.values(flags).some((value) => value !== undefined)) {
+    return { error: interactiveRunnerMessages.actionFlagsWithStdin, ok: false };
+  }
+  const piped = (await deps.readStdin()).trim();
+  if (piped === "") {
+    return { error: interactiveRunnerMessages.stdinEmptyAction, ok: false };
+  }
+  try {
+    return parseBrowserAction(JSON.parse(piped));
+  } catch {
+    return { error: interactiveRunnerMessages.actionNotJson, ok: false };
+  }
+}
+async function handleRunnerAct(ctx, options, deps) {
+  const built = await readAction(options.type, options.flags, deps);
+  if (!built.ok)
+    return { error: built.error, exitCode: exitCodes.invalidArgs };
+  const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
+  if (resolved.type === "failed") {
+    return { error: resolved.error, exitCode: resolved.exitCode };
+  }
+  announceRunner(ctx, resolved);
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.performAction, { action: built.action, id: resolved.runnerId });
+  if (!result.ok) {
+    const fields = failureFields(result);
+    return {
+      ...fields,
+      ...result.mayHaveArrived ? {
+        error: `${fields.error} ${interactiveRunnerMessages.actionMayHaveHappened}`
+      } : {},
+      exitCode: exitCodes.network
+    };
+  }
+  switch (result.value.outcome) {
+    case "performed":
+      ctx.ui.output({ action: built.action, outcome: "performed" }, interactiveRunnerMessages.actionPerformed(built.action.type));
+      return;
+    case "action-failed":
+      return {
+        error: interactiveRunnerMessages.actionFailed(result.value.errorMessage),
+        exitCode: exitCodes.testFailure
+      };
+    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-has-no-screen":
+      return {
+        error: interactiveRunnerMessages.runnerHasNoScreen,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.actionMayHaveHappened,
+        exitCode: exitCodes.network
+      };
+  }
+}
+
+// src/domains/interactiveRunner/takeScreenshot.ts
+async function handleRunnerScreenshot(ctx, options, deps) {
+  const resolved = await resolveRunner(ctx, {
+    autoLaunch: false,
+    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForScreenshot,
+    runner: options.runner
+  }, deps);
+  if (resolved.type === "failed") {
+    return { error: resolved.error, exitCode: resolved.exitCode };
+  }
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.takeScreenshot, { id: resolved.runnerId });
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  switch (result.value.outcome) {
+    case "captured": {
+      const written = await deps.writeScreenshot({
+        imageJpegBase64: result.value.imageJpegBase64,
+        path: options.out
+      });
+      if (!written.ok) {
+        return written.reason === "not-a-jpeg" ? {
+          error: interactiveRunnerMessages.screenshotNotAnImage,
+          exitCode: exitCodes.network
+        } : {
+          error: interactiveRunnerMessages.screenshotUnwritable(options.out, written.detail),
+          exitCode: exitCodes.invalidArgs
+        };
+      }
+      ctx.ui.output({ outcome: "captured", path: options.out }, interactiveRunnerMessages.screenshotWritten(options.out));
+      return;
+    }
+    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-has-no-screen":
+      return {
+        error: interactiveRunnerMessages.runnerHasNoScreen,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.runnerUnreachable,
+        exitCode: exitCodes.network
+      };
+  }
+}
+
+// src/shell/interactiveRunner/collectRunFiles.ts
+import { join as join42 } from "node:path";
+async function collectRunFiles(options) {
+  const paths = await glob(shippableRunFileExtensions.map((extension) => `**/*${extension}`), {
+    cwd: options.cwd,
+    followSymbolicLinks: false,
+    ignore: ["**/node_modules/**"]
+  });
+  const shippable = paths.filter(isShippableRunFilePath).sort();
+  const files = {};
+  const read = batchMap(shippable, async (path9) => ({
+    content: await options.fs.readFile(join42(options.cwd, path9)),
+    path: path9
+  }), flowBatchSize);
+  for await (const file2 of read)
+    files[file2.path] = file2.content;
+  return files;
+}
+
+// src/shell/interactiveRunner/makeRunnerId.ts
+import { randomUUID } from "node:crypto";
+function makeRunnerId() {
+  return `cli-${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+}
+
+// src/shell/interactiveRunner/runnerStore.ts
+import { join as join43 } from "node:path";
+var storeFileName = "runner.json";
+var storeSchema = exports_external.object({ defaultRunnerId: exports_external.string().optional() });
+function parseJson(text3) {
+  try {
+    return JSON.parse(text3);
+  } catch {
+    return;
+  }
+}
+function makeRunnerStore(options) {
+  const directory = join43(options.cwd, qawolfDir);
+  const path9 = join43(directory, storeFileName);
+  let pendingWrites = 0;
+  const nextPendingPath = () => `${path9}.${process.pid}.${++pendingWrites}.tmp`;
+  return {
+    async clearDefaultRunnerId() {
+      await options.fs.rm(path9, { force: true });
+    },
+    async readDefaultRunnerId() {
+      const contents2 = await options.fs.readFile(path9).catch(() => {
+        return;
+      });
+      if (contents2 === undefined)
+        return;
+      const parsed = storeSchema.safeParse(parseJson(contents2));
+      return parsed.success ? parsed.data.defaultRunnerId : undefined;
+    },
+    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);
+    }
+  };
+}
+
+// src/shell/interactiveRunner/writeScreenshot.ts
+import { dirname as dirname14 } from "node:path";
+var jpegStartOfImage = [255, 216, 255];
+async function writeScreenshot(options) {
+  const bytes = Buffer.from(options.imageJpegBase64, "base64");
+  if (jpegStartOfImage.some((byte, index2) => bytes[index2] !== byte)) {
+    return { ok: false, reason: "not-a-jpeg" };
+  }
+  try {
+    await options.fs.mkdir(dirname14(options.path), { recursive: true });
+    await options.fs.writeFile(options.path, bytes);
+  } catch (error51) {
+    return { detail: errorMessage(error51), ok: false, reason: "unwritable" };
+  }
+  return { ok: true };
+}
+
+// src/shell/stdin.ts
+async function readStdin2() {
+  if (process.stdin.isTTY === true)
+    return "";
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// src/domains/interactiveRunner/deps.ts
+function makeInteractiveRunnerDeps(options) {
+  return {
+    collectRunFiles: () => collectRunFiles({ cwd: options.cwd, fs: options.fs }),
+    cwd: options.cwd,
+    env: options.env,
+    makeRunnerId,
+    readFile: (path9) => options.fs.readFile(path9),
+    readStdin: readStdin2,
+    sleep,
+    store: makeRunnerStore({ cwd: options.cwd, fs: options.fs }),
+    writeScreenshot: (screenshot) => writeScreenshot({ ...screenshot, fs: options.fs })
+  };
+}
+
+// src/commands/runner/context.ts
+var runnerFlagDescription = "Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner";
+function runnerDeps(ctx) {
+  return makeInteractiveRunnerDeps({
+    cwd: process.cwd(),
+    env: process.env,
+    fs: ctx.fs
+  });
+}
+
+// src/commands/runner/interact.register.ts
+var defaultScreenshotPath = "screenshot.jpg";
+var screenshotExamples = `
+Examples:
+  $ qawolf runner screenshot
+  $ qawolf runner screenshot --out screens/step-3.jpg`;
+var actExamples = `
+Examples:
+  $ qawolf runner act click --button left --x 480 --y 260
+  $ qawolf runner act type --text "hello@example.com"
+  $ qawolf runner act keypress --keys Control a
+  $ qawolf runner act navigate --url https://example.com
+  $ qawolf runner act drag --path '[{"x":10,"y":20},{"x":80,"y":90}]'
+  $ echo '{"type":"click","button":"left","x":1,"y":2}' | qawolf runner act -`;
+var execExamples = `
+Examples:
+  $ qawolf runner exec snippet.ts
+  $ echo 'console.log(await page.title())' | qawolf runner exec -
+  $ 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, {
+    flags: {
+      button: opts.button,
+      keys: opts.keys,
+      path: opts.path,
+      scrollX: opts.scrollX,
+      scrollY: opts.scrollY,
+      text: opts.text,
+      url: opts.url,
+      x: opts.x,
+      y: opts.y
+    },
+    runner: opts.runner,
+    type: action2
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).action((file2, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file2 }, runnerDeps(ctx)))(opts, command));
+}
+
+// src/domains/interactiveRunner/readJournal.ts
+function journalReadFailure(failed) {
+  const { type: _type, ...failure } = failed;
+  return failure;
+}
+var unreachableFailure = {
+  error: interactiveRunnerMessages.runnerUnreachable,
+  exitCode: exitCodes.network
+};
+async function readJournal(ctx, runnerId, request) {
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.readJournal, {
+    id: runnerId,
+    stream: request.stream,
+    ...request.runId === undefined ? {} : { runId: request.runId },
+    ...request.sinceSequence === undefined ? {} : { sinceSequence: request.sinceSequence },
+    ...request.tail === undefined ? {} : { tail: request.tail }
+  });
+  if (!result.ok) {
+    return {
+      ...failureFields(result),
+      exitCode: exitCodes.network,
+      type: "failed"
+    };
+  }
+  if (result.value.outcome === "runner-unreachable") {
+    return { type: "unreachable" };
+  }
+  return { type: "read", value: result.value };
+}
+
+// src/domains/interactiveRunner/keepalive.ts
+async function handleRunnerKeepalive(ctx, options, deps) {
+  const resolved = await resolveRunner(ctx, { autoLaunch: false, runner: options.runner }, deps);
+  if (resolved.type === "failed") {
+    return { error: resolved.error, exitCode: resolved.exitCode };
+  }
+  const window2 = await readJournal(ctx, resolved.runnerId, {
+    stream: "run-status",
+    tail: 1
+  });
+  if (window2.type === "unreachable")
+    return { ...unreachableFailure };
+  if (window2.type === "failed")
+    return window2;
+  ctx.ui.output({ id: resolved.runnerId, outcome: "alive" }, interactiveRunnerMessages.keptAlive(resolved.runnerId));
+  return;
+}
+
+// src/domains/interactiveRunner/stop.ts
+async function handleRunnerStop(ctx, options, deps) {
+  const resolved = await resolveRunner(ctx, { autoLaunch: false, runner: options.runner }, deps);
+  if (resolved.type === "failed") {
+    return { error: resolved.error, exitCode: resolved.exitCode };
+  }
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.stop, {
+    id: resolved.runnerId
+  });
+  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(() => {
+    ctx.ui.warn(interactiveRunnerMessages.defaultNotForgotten(resolved.runnerId));
+  });
+  ctx.ui.output(result.value, result.value.outcome === "stopped" ? interactiveRunnerMessages.stopped(result.value.id) : interactiveRunnerMessages.notRunning(result.value.id));
+  return;
+}
+
+// src/commands/runner/lifecycle.register.ts
+var launchExamples = `
+Examples:
+  $ qawolf runner launch
+  $ qawolf runner launch --name node20WithAndroid
+  $ qawolf runner launch --id ci`;
+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 <image>", "Runner image to run, e.g. node20WithPlaywright").addHelpText("after", launchExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("stop"), "write").description("Stop an interactive runner").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerStop(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));
+}
+
+// src/core/interactiveRunner/followTimeout.ts
+var defaultFollowTimeoutSeconds = 3600;
+var followTimeoutSchema = exports_external.coerce.number().int().positive();
+function parseFollowTimeout(seconds) {
+  if (seconds === undefined) {
+    return { ok: true, seconds: defaultFollowTimeoutSeconds };
+  }
+  const parsed = followTimeoutSchema.safeParse(seconds);
+  if (!parsed.success)
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  return { ok: true, seconds: parsed.data };
+}
+
+// src/core/interactiveRunner/journal.ts
+function formatJournalLine(entry, options) {
+  const data2 = options.envelope ? entry : entry.payload;
+  return { data: data2, line: JSON.stringify(data2) };
+}
+function countSkippedEntries(cursor3, oldestAvailableSequence) {
+  if (oldestAvailableSequence <= cursor3 + 1)
+    return 0;
+  return oldestAvailableSequence - cursor3 - 1;
+}
+var runStatusPayloadSchema = exports_external.object({
+  errorMessage: exports_external.string().optional(),
+  runId: exports_external.string(),
+  status: exports_external.string()
+});
+function readRunSettlement(payload) {
+  const parsed = runStatusPayloadSchema.safeParse(payload);
+  if (!parsed.success)
+    return { type: "unreadable" };
+  if (parsed.data.status === "in-progress")
+    return { type: "in-progress" };
+  return {
+    errorMessage: parsed.data.errorMessage,
+    status: parsed.data.status,
+    type: "settled"
+  };
+}
+var runLogPayloadSchema = exports_external.object({ message: exports_external.string() });
+function formatRunLogLine(payload) {
+  const parsed = runLogPayloadSchema.safeParse(payload);
+  return parsed.success ? parsed.data.message : JSON.stringify(payload);
+}
+
+// src/domains/interactiveRunner/eventsOptions.ts
+var countSchema = exports_external.coerce.number().int().positive();
+var sequenceSchema = exports_external.coerce.number().int().nonnegative();
+function parseEventsOptions(options) {
+  const parsed = exports_external.object({
+    run: readJournalRequestSchema.shape.runId,
+    since: sequenceSchema.optional(),
+    stream: journalStreamSchema,
+    tail: countSchema.optional()
+  }).safeParse({
+    stream: options.stream,
+    ...options.run === undefined ? {} : { run: options.run },
+    ...options.since === undefined ? {} : { since: options.since },
+    ...options.tail === undefined ? {} : { tail: options.tail }
+  });
+  if (!parsed.success)
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  return {
+    ok: true,
+    value: {
+      runId: parsed.data.run,
+      sinceSequence: parsed.data.since,
+      stream: parsed.data.stream,
+      tail: parsed.data.tail
+    }
+  };
+}
+
+// src/domains/interactiveRunner/journalCursor.ts
+function createJournalCursor(ctx, runnerId, request) {
+  let sinceSequence = request.sinceSequence;
+  let tail = request.tail;
+  let warnedUnsearchedHistory = false;
+  return async function read() {
+    const window2 = await readJournal(ctx, runnerId, {
+      ...request,
+      sinceSequence,
+      tail
+    });
+    if (window2.type !== "read")
+      return window2;
+    if (sinceSequence !== undefined) {
+      const skipped = countSkippedEntries(sinceSequence, window2.value.oldestAvailableSequence);
+      if (skipped > 0) {
+        ctx.ui.warn(interactiveRunnerMessages.skippedEntries(request.stream, skipped));
+      }
+    }
+    if (window2.value.hasUnsearchedHistory && !warnedUnsearchedHistory) {
+      warnedUnsearchedHistory = true;
+      ctx.ui.warn(interactiveRunnerMessages.unsearchedHistory(request.stream));
+    }
+    tail = undefined;
+    sinceSequence = Math.max(sinceSequence ?? 0, window2.value.nextSequence);
+    return { entries: window2.value.entries, type: "entries" };
+  };
+}
+var unreachableGraceMs = 60000;
+function createUnreachableBudget(pollIntervalMs2) {
+  const limit = Math.ceil(unreachableGraceMs / pollIntervalMs2);
+  let consecutive = 0;
+  return {
+    exhausted: () => ++consecutive >= limit,
+    reset: () => {
+      consecutive = 0;
+    }
+  };
+}
+
+// src/domains/interactiveRunner/events.ts
+var pollIntervalMs2 = 1000;
+async function handleRunnerEvents(ctx, options, deps) {
+  const parsed = parseEventsOptions(options);
+  if (!parsed.ok)
+    return { error: parsed.error, exitCode: exitCodes.invalidArgs };
+  const timeout = parseFollowTimeout(options.timeout);
+  if (!timeout.ok) {
+    return { error: timeout.error, exitCode: exitCodes.invalidArgs };
+  }
+  const resolved = await resolveRunner(ctx, { autoLaunch: false, runner: options.runner }, deps);
+  if (resolved.type === "failed") {
+    return { error: resolved.error, exitCode: resolved.exitCode };
+  }
+  const known = knownJournalStreams;
+  if (!known.includes(parsed.value.stream)) {
+    ctx.ui.warn(interactiveRunnerMessages.unknownStream(parsed.value.stream, known));
+  }
+  const read = createJournalCursor(ctx, resolved.runnerId, parsed.value);
+  const unreachable = createUnreachableBudget(pollIntervalMs2);
+  const maxPolls = Math.max(1, Math.ceil(timeout.seconds * 1000 / pollIntervalMs2));
+  for (let poll = 1;; poll++) {
+    const window2 = await read();
+    if (window2.type === "failed")
+      return journalReadFailure(window2);
+    if (window2.type === "unreachable") {
+      if (!options.follow || unreachable.exhausted()) {
+        return { ...unreachableFailure };
+      }
+    } else {
+      unreachable.reset();
+      for (const entry of window2.entries) {
+        const { data: data2, line } = formatJournalLine(entry, {
+          envelope: options.envelope
+        });
+        ctx.ui.stream(data2, line);
+      }
+      if (!options.follow)
+        return;
+    }
+    if (poll >= maxPolls) {
+      return {
+        error: interactiveRunnerMessages.followEventsTimedOut(parsed.value.stream, timeout.seconds),
+        exitCode: exitCodes.timeout
+      };
+    }
+    await deps.sleep(pollIntervalMs2);
+  }
+}
+
+// src/domains/interactiveRunner/collectFiles.ts
+async function collectRunFiles2(deps) {
+  try {
+    return { files: await deps.collectRunFiles(), ok: true };
+  } catch (error51) {
+    const path9 = readErrorPath(error51);
+    return {
+      error: path9 === undefined ? interactiveRunnerMessages.filesUnreadable(errorMessage(error51)) : interactiveRunnerMessages.fileUnreadable(path9, errorMessage(error51)),
+      ok: false
+    };
+  }
+}
+function readErrorPath(error51) {
+  if (typeof error51 !== "object" || error51 === null)
+    return;
+  const path9 = error51.path;
+  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" };
+    }
+    return { status: settlement.status, type: "unrecognized" };
+  }
+  return;
+}
+function reportSettlement(ctx, settlement) {
+  if (settlement.type === "passed") {
+    ctx.ui.success(interactiveRunnerMessages.runPassed);
+    return;
+  }
+  return {
+    error: settlement.type === "failed" ? interactiveRunnerMessages.runFailed(settlement.errorMessage) : interactiveRunnerMessages.runSettledUnknown(settlement.status),
+    exitCode: exitCodes.testFailure
+  };
+}
+async function followRun(ctx, options, deps) {
+  const readLogs = createJournalCursor(ctx, options.runnerId, {
+    runId: options.runId,
+    stream: "run-logs"
+  });
+  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));
+    }
+    return logs;
+  };
+  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();
+    if (status.type === "failed")
+      return journalReadFailure(status);
+    if (logs.type === "unreachable" || status.type === "unreachable") {
+      if (unreachable.exhausted())
+        return { ...unreachableFailure };
+    } else {
+      unreachable.reset();
+      const settlement = findSettlement(status.entries);
+      if (settlement !== undefined) {
+        await printLogs();
+        return reportSettlement(ctx, settlement);
+      }
+    }
+    if (poll >= maxPolls) {
+      return {
+        error: interactiveRunnerMessages.followTimedOut(options.runId, options.runnerId, options.timeoutSeconds),
+        exitCode: exitCodes.timeout
+      };
+    }
+    await deps.sleep(pollIntervalMs3);
+  }
+}
+
+// src/domains/interactiveRunner/runFlow.ts
+async function handleRunnerRun(ctx, options, deps) {
+  const timeout = parseFollowTimeout(options.timeout);
+  if (!timeout.ok) {
+    return { error: timeout.error, exitCode: exitCodes.invalidArgs };
+  }
+  const entryPointPath = toCollectedPath(deps.cwd, options.entryPoint);
+  const collected = await collectRunFiles2(deps);
+  if (!collected.ok) {
+    return { error: collected.error, exitCode: exitCodes.config };
+  }
+  const files = collected.files;
+  const check2 = checkRunFiles(files, entryPointPath);
+  if (check2.type !== "ok") {
+    return {
+      error: describeRunFilesCheck(check2),
+      exitCode: exitCodes.invalidArgs
+    };
+  }
+  const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
+  if (resolved.type === "failed") {
+    return { error: resolved.error, exitCode: resolved.exitCode };
+  }
+  announceRunner(ctx, resolved);
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.runFlow, { entryPointPath, files, id: resolved.runnerId });
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  switch (result.value.outcome) {
+    case "runner-target-mismatch":
+      return {
+        error: interactiveRunnerMessages.targetMismatch(result.value.runnerName, result.value.requiredRunnerName),
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.submitMayHaveStarted,
+        exitCode: exitCodes.network
+      };
+    case "submitted": {
+      const runId = result.value.runId;
+      if (!options.follow) {
+        ctx.ui.output({ runId, runnerId: resolved.runnerId }, interactiveRunnerMessages.runSubmitted(runId));
+        return;
+      }
+      ctx.ui.info(interactiveRunnerMessages.runSubmitted(runId));
+      return followRun(ctx, {
+        runId,
+        runnerId: resolved.runnerId,
+        timeoutSeconds: timeout.seconds
+      }, deps);
+    }
+    default: {
+      result.value;
+      return {
+        error: interactiveRunnerMessages.runSubmitAnsweredUnknown(String(result.value.outcome)),
+        exitCode: exitCodes.network
+      };
+    }
+  }
+}
+
+// src/commands/runner/run.register.ts
+var runExamples2 = `
+Examples:
+  $ qawolf runner run flows/checkout.flow.ts
+  $ qawolf runner run flows/checkout.flow.ts --follow`;
+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, {
+    entryPoint: file2,
+    follow: opts.follow,
+    runner: opts.runner,
+    timeout: opts.timeout
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("events <stream>"), "read").description(`Print a runner's journal, one entry per line. QA Wolf writes ${knownJournalStreams.join(", ")}`).option("--follow", "Keep reading as new entries arrive. Reading counts as activity, so a follow left open keeps the runner alive and billing", false).option("--run <id>", "Restrict run-scoped streams to one run").option("--runner <id>", runnerFlagDescription).option("--since <sequence>", "Read entries after this sequence").option("--tail <count>", "Read only the newest <count> entries").option("--timeout <seconds>", "Give up following after this long. Reading keeps the runner alive, so a follow left open would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", eventsExamples).action((stream, opts, command) => withAuthContext(signals, (ctx) => handleRunnerEvents(ctx, {
+    envelope: Boolean(command.optsWithGlobals().json),
+    follow: opts.follow,
+    run: opts.run,
+    runner: opts.runner,
+    since: opts.since,
+    stream,
+    tail: opts.tail,
+    timeout: opts.timeout
+  }, runnerDeps(ctx)))(opts, command));
+}
+
+// src/commands/runner/index.ts
+function registerRunnerCommand(program2, signals) {
+  const runner = program2.command("runner").description("Drive an interactive runner on the QA Wolf platform");
+  registerRunnerLifecycleCommands(runner, signals);
+  registerRunnerRunCommands(runner, signals);
+  registerRunnerInteractCommands(runner, signals);
+}
+
 // src/commands/program.ts
 function createProgram({
   signals
@@ -186056,6 +187184,7 @@ function createProgram({
   registerFlowsCommand(program2, signals);
   registerInitCommand(program2, signals);
   registerInstallCommand(program2, signals);
+  registerRunnerCommand(program2, signals);
   registerPublicApiCommands(program2, signals);
   return program2;
 }
@@ -186079,4 +187208,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=45F0ABBEFD04330664756E2164756E21
+//# debugId=B4115D163429543264756E2164756E21