@qawolf/cli 1.17.0 → 1.18.0

package/dist/cli.js

@@ -326161,6 +326161,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 +326205,7 @@ var runMessages = {
 // src/core/messages/interactiveRunner/index.ts
 var interactiveRunnerMessages = {
   ...lifecycleMessages,
+  ...listMessages,
   ...runMessages,
   ...interactMessages
 };
@@ -343242,6 +343250,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 +343590,7 @@ var makeContractsV1 = (ids) => {
     },
     runner: {
       evaluateSnippet: makeEvaluateSnippetOnRunnerContract(),
+      get: makeGetRunnerContract(),
       highlightSelector: makeHighlightSelectorOnRunnerContract(),
       importPackage: makeImportPackageOnRunnerContract(),
       inspect: makeInspectOnRunnerContract(),
@@ -346098,7 +346126,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.17.0",
+  version: "1.18.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -346158,7 +346186,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 +348618,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 +348707,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 +356628,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 +356697,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 +356717,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 +357112,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 +357127,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);
     }
   };
 }
@@ -357795,6 +357888,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 +358007,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 +358020,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));
@@ -358305,13 +358485,15 @@ var refused = (error51, exitCode) => ({
   ok: false
 });
 async function prepareRun(options, deps) {
-  const environmentId = options.envId?.trim();
-  if (environmentId !== undefined && options.envFile !== undefined) {
+  const explicitEnvId = options.envId?.trim();
+  if (explicitEnvId !== undefined && options.envFile !== undefined) {
     return refused(interactiveRunnerMessages.envIdWithEnvFile, exitCodes.invalidArgs);
   }
-  if (environmentId === "") {
+  if (explicitEnvId === "") {
     return refused(interactiveRunnerMessages.envIdBlank, exitCodes.invalidArgs);
   }
+  const fromEnvVar = deps.env["QAWOLF_ENVIRONMENT"]?.trim();
+  const environmentId = explicitEnvId ?? (options.envFile === undefined && fromEnvVar ? fromEnvVar : undefined);
   const linesFilePath = options.linesFile === undefined ? undefined : toCollectedPath(deps.cwd, options.linesFile);
   const roots = linesFilePath === undefined || linesFilePath === options.entryPointPath ? [options.entryPointPath] : [options.entryPointPath, linesFilePath];
   const collected = await collectRunFiles2(deps, roots);
@@ -358522,6 +358704,9 @@ async function handleRunnerRun(ctx, options, deps) {
   if (!prepared.ok) {
     return { error: prepared.error, exitCode: prepared.exitCode };
   }
+  if (options.envId === undefined && prepared.environmentId !== undefined) {
+    ctx.ui.info(environmentsMessages.usingFromEnvVar(prepared.environmentId));
+  }
   const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
   if (resolved.type === "failed") {
     return { ...failureFields(resolved), exitCode: resolved.exitCode };
@@ -358579,7 +358764,7 @@ Examples:
   $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
   $ qawolf runner run flows/checkout.flow.ts --env-id staging`;
 function registerRunCommand(runner, signals) {
-  declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").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("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").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((flowFile, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
+  declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").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("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").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((flowFile, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
     entryPoint: flowFile,
     envFile: opts.envFile,
     envId: opts.envId,
@@ -358643,4 +358828,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=408E9965E881500264756E2164756E21
+//# debugId=B6D9FB052BE12D6D64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.17.0",
+  "version": "1.18.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

@@ -38,7 +38,9 @@ is set; otherwise select an id or alias from
 `qawolf --json environment find` and reuse it. Shell invocations may not share
 exported variables, so pass the selected environment explicitly instead of
 rediscovering it. Check the command's help for its environment flag: variable
-commands use `--environment-id`; `qawolf flows run` uses `--env`.
+commands use `--environment-id`; `qawolf flows run` uses `--env`; and
+`qawolf runner run` uses `--env-id`, which falls back to `QAWOLF_ENVIRONMENT`
+when neither it nor `--env-file` is passed.
 
 If multiple environments are returned and the task context does not identify
 the target, ask instead of guessing. Do not default to the newest environment.
@@ -103,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 -->
@@ -152,6 +165,7 @@ current branch.
 | `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,32 @@ 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.
 
+## 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
@@ -312,6 +338,18 @@ qawolf runner run flows/checkout.flow.ts --env-id staging
 qawolf runner run flows/checkout.flow.ts --env-file .env
 ```
 
+**A run with neither flag falls back to `QAWOLF_ENVIRONMENT`**, the same
+variable `qawolf flows` reads, so one export covers both. The run says on
+stderr which environment it picked up, because those variables reach your flow's
+code and a run should never be given an environment silently. `--env-id` wins
+over it, and `--env-file` suppresses it, so a run reading a dotenv file is not
+handed a second environment on top.
+
+```sh
+export QAWOLF_ENVIRONMENT=staging
+qawolf runner run flows/checkout.flow.ts     # runs against staging
+```
+
 **Prefer `--env-id`.** QA Wolf reads and decrypts the environment itself, so the
 values never leave the server, nothing has to be pulled to disk first, and no
 size limit applies to them. It is the only way to run a flow whose environment