@qawolf/cli 1.17.1 → 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.1",
+  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));
@@ -358648,4 +358828,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=C71E3AC48D2D260064756E2164756E21
+//# debugId=B6D9FB052BE12D6D64756E2164756E21

package/package.json

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

@@ -105,6 +105,17 @@ Inspect `git status` before publishing. Stage and commit only files changed for
 the current task, preserve unrelated worktree changes, then push the task's
 current branch.
 
+The platform reads flows from the environment's flow code branch, not from your
+task branch. `qawolf --json environment get` reports it as `flowCodeBranch`
+(`name`, `syncStatus`, `lastSyncedCommitHash`). A flow has a platform page, an
+id, and a place in `qawolf flows list --remote` only once it is on that branch
+and the environment has reconciled the commit. To link or run a new flow on the
+platform: integrate the flow code branch into your work, push the flow to that
+branch, poll `environment get` until `lastSyncedCommitHash` includes your
+commit, then read the flow's `flowId` and `url` from
+`qawolf --json flows list --remote --env <environment> --include-drafts`. Send
+that `url`; never guess a route and never send a repository link in its place.
+
 ## Commands
 
 <!-- commands-table:start — generated by `bun run generate`, do not edit -->
@@ -154,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