@qawolf/cli 1.30.0 → 1.32.0

package/dist/runner-sdk.js

@@ -9485,7 +9485,14 @@ var authErrorMessages = {
     rejected401: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 401). Check your API key.`,
     rejected402: (noun) => `QA Wolf API refused the${noun ? ` ${noun}` : ""} request (HTTP 402): billing prevented it.`,
     rejected403: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
-    notFound404: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
+    notFound404Environment: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
+    notFound404Runner: (runnerId) => runnerId === undefined ? "That runner is not running (HTTP 404)." : `Runner ${runnerId} is not running (HTTP 404).`,
+    runnerIsGone: "It was never launched, or it has since been terminated or idled out.",
+    launchTheRunner: (runnerId) => runnerId === undefined ? "Launch one with qawolf runner launch --id <id>, or name a running one with --runner." : `Launch it with qawolf runner launch --id ${runnerId}, or send this to a different runner with --runner.`,
+    notFound404Run: (runId) => `QA Wolf has no run ${runId ?? "by that id"} on this team (HTTP 404).`,
+    runIdMayBeRunnerLocal: (runId) => `A run id printed by qawolf runner run belongs to that runner rather than to the platform, so this command cannot resolve it. Read that run with qawolf runner events run-status --run ${runId ?? "<id>"}.`,
+    notFound404Record: (noun, id) => `QA Wolf has no ${noun} ${id} (HTTP 404).`,
+    notFound404: (noun) => noun === undefined ? "QA Wolf found nothing matching the request (HTTP 404)." : `QA Wolf found nothing matching the ${noun} request (HTTP 404).`,
     failedWithStatus: (status, noun) => `QA Wolf API${noun ? ` ${noun}` : ""} request failed (HTTP ${status}).`,
     networkUnreachable: (baseUrl, noun) => `Could not reach the QA Wolf API at ${baseUrl}${noun ? ` to fetch ${noun}` : ""}. Check your network connection and QAWOLF_HOST_URL.`,
     timedOut: (timeoutMs, noun) => `The QA Wolf API${noun ? ` ${noun}` : ""} request timed out after ${formatSeconds(timeoutMs)}. The work may still be finishing on the platform.`,
@@ -9836,7 +9843,14 @@ var lifecycleMessages = {
   terminated: (id) => `Terminated runner ${id}.`,
   runStopped: (id) => `Stopped the run on runner ${id}. The runner is still up, on whatever page the run reached.`,
   nothingToStop: (id) => `Runner ${id} had nothing to stop. The run had already finished, or none had been submitted.`,
-  runnerUnreachable: "The runner could not be reached. It may still be starting, or it may have terminated after inactivity. Retry, or launch it again."
+  runnerUnreachable: "The runner could not be reached. It may still be starting, or it may have terminated after inactivity. Retry, or launch it again.",
+  runnerIdCameFrom: (id, source) => ({
+    environment: `The id ${id} came from QAWOLF_RUNNER_ID.`,
+    flag: `The id ${id} came from --runner.`,
+    given: `The id ${id} is the one this call named.`,
+    launched: `Runner ${id} was launched for this command.`,
+    stored: `The id ${id} came from the runner this directory last launched, recorded in .qawolf.`
+  })[source]
 };
 
 // src/core/messages/interactiveRunner/list.ts
@@ -9935,7 +9949,9 @@ ${dir}`,
   ].join(`
 `),
   outerHopCarriedOver: (names) => `Carried over ${pluralize(names.length, "undeclared package")} from the project node_modules: ${listNames(names)}. Declare them in package.json "dependencies".`,
-  moduleNotFoundHint: (pkg, projectDir) => projectDir === undefined ? `Hint: '${pkg}' could not be resolved. Run from within your flows project so its dependencies can be found.` : `Hint: '${pkg}' could not be resolved. Ensure it is declared in ${projectDir}/package.json "dependencies" and run npm install in that project.`
+  moduleNotFoundHint: (pkg, projectDir) => projectDir === undefined ? `Hint: '${pkg}' could not be resolved. Run from within your flows project so its dependencies can be found.` : `Hint: '${pkg}' could not be resolved. Ensure it is declared in ${projectDir}/package.json "dependencies" and run npm install in that project.`,
+  tsconfigUnparsedNotice: (projectDir) => `Not resolving path aliases: ${projectDir}/tsconfig.json is not valid JSON. Comments and trailing commas are not supported, here or on the platform. Remove them so "compilerOptions.paths" can be read.`,
+  pathAliasNotFoundHint: (specifier, projectDir) => projectDir === undefined ? `Hint: '${specifier}' looks like a tsconfig path alias. Run from within your flows project so its tsconfig.json can be found.` : `Hint: '${specifier}' looks like a tsconfig path alias. Ensure "compilerOptions.paths" in ${projectDir}/tsconfig.json maps it to a file that exists.`
 };
 // src/shell/exit.ts
 var exitCodes = {
@@ -9946,7 +9962,8 @@ var exitCodes = {
   network: 4,
   config: 5,
   timeout: 6,
-  payment: 7
+  payment: 7,
+  notFound: 8
 };
 
 // src/core/sleep.ts
@@ -10894,41 +10911,70 @@ function isPathAlias(importPath, paths) {
 // src/core/interactiveRunner/resolveImportPath.ts
 import { dirname as dirname2, join, normalize as normalize2 } from "node:path/posix";
 
-// src/core/interactiveRunner/tsconfigPaths.ts
+// src/core/aliasImports/tsconfigPaths.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
 function isTsconfigPaths(value) {
   return isRecord(value) && Object.values(value).every((targets) => Array.isArray(targets) && targets.every((target) => typeof target === "string"));
 }
-function parseTsconfigPaths(tsconfigContent) {
+function parseTsconfigContent(tsconfigContent) {
   let parsed;
   try {
     parsed = JSON.parse(tsconfigContent);
   } catch {
-    return;
+    return { type: "unparseable" };
   }
   if (!isRecord(parsed))
-    return;
+    return { paths: undefined, type: "parsed" };
   const compilerOptions = parsed["compilerOptions"];
   if (!isRecord(compilerOptions))
-    return;
+    return { paths: undefined, type: "parsed" };
   const paths = compilerOptions["paths"];
-  return isTsconfigPaths(paths) ? paths : undefined;
+  return {
+    paths: isTsconfigPaths(paths) ? paths : undefined,
+    type: "parsed"
+  };
+}
+function parseTsconfigPaths(tsconfigContent) {
+  const parsed = parseTsconfigContent(tsconfigContent);
+  return parsed.type === "parsed" ? parsed.paths : undefined;
+}
+function parseWildcardPattern(pattern) {
+  const wildcard = pattern.indexOf("*");
+  if (wildcard === -1 || wildcard !== pattern.lastIndexOf("*"))
+    return;
+  return {
+    prefix: pattern.slice(0, wildcard),
+    suffix: pattern.slice(wildcard + 1)
+  };
+}
+function matchesWildcard(importPath, { prefix, suffix }) {
+  return importPath.length >= prefix.length + suffix.length && importPath.startsWith(prefix) && importPath.endsWith(suffix);
+}
+function longestPrefixMatch(importPath, paths) {
+  return Object.entries(paths).flatMap(([pattern, targets]) => {
+    const parsed = parseWildcardPattern(pattern);
+    if (parsed === undefined || !matchesWildcard(importPath, parsed)) {
+      return [];
+    }
+    return [{ pattern: parsed, targets }];
+  }).reduce((best, candidate) => best === undefined || candidate.pattern.prefix.length > best.pattern.prefix.length ? candidate : best, undefined);
 }
 function resolvePathAlias(importPath, paths) {
   if (paths === undefined)
     return;
-  for (const [pattern, targets] of Object.entries(paths)) {
-    const prefix = pattern.replace("*", "");
-    if (!importPath.startsWith(prefix))
-      continue;
-    const [target] = targets;
-    if (target !== undefined) {
-      return target.replace("*", importPath.slice(prefix.length));
-    }
-  }
-  return;
+  const [exactTarget] = paths[importPath] ?? [];
+  if (exactTarget !== undefined)
+    return exactTarget;
+  const match = longestPrefixMatch(importPath, paths);
+  if (match === undefined)
+    return;
+  const [target] = match.targets;
+  if (target === undefined)
+    return;
+  const substituted = importPath.slice(match.pattern.prefix.length, importPath.length - match.pattern.suffix.length);
+  return target.replace("*", substituted);
 }
 
 // src/core/interactiveRunner/resolveImportPath.ts
@@ -11366,6 +11412,47 @@ function makeDefaultFs() {
   };
 }
 
+// src/core/publicApi/notFoundSubject.ts
+var runnerRoutesThatNameNoRunner = new Set([
+  "runner.launch",
+  "runner.list"
+]);
+var runRoutesThatResolveOneRun = new Set([
+  "run.diagnose",
+  "run.get",
+  "run.reattempt",
+  "run.stop"
+]);
+var recordFieldNouns = [
+  ["sessionId", "session"],
+  ["triggerId", "trigger"],
+  ["issueId", "issue"],
+  ["flowId", "flow"],
+  ["filePath", "file"]
+];
+function field(input, name) {
+  if (typeof input !== "object" || input === null)
+    return;
+  const value = input[name];
+  return typeof value === "string" ? value : undefined;
+}
+function notFoundSubject(contractName, input) {
+  if (contractName.startsWith("runner.") && !runnerRoutesThatNameNoRunner.has(contractName)) {
+    return { kind: "runner", runnerId: field(input, "id") };
+  }
+  if (runRoutesThatResolveOneRun.has(contractName)) {
+    return { kind: "run", runId: field(input, "runId") };
+  }
+  for (const [name, noun] of recordFieldNouns) {
+    const id = field(input, name);
+    if (id !== undefined)
+      return { id, kind: "record", noun };
+  }
+  if (field(input, "environmentId") !== undefined)
+    return { kind: "environment" };
+  return { kind: "other" };
+}
+
 // src/core/publicApi/flagKind.ts
 function flagKind(schema) {
   if (schema.type === "string")
@@ -11536,6 +11623,42 @@ function applyWorkspaceId(inputSchema, input, workspaceId) {
   return { ...input, workspaceId };
 }
 
+// src/shell/platform/describeNotFound.ts
+var m = authMessages.errors.request;
+var saysNothingMore = (reason) => /^(\w+ )*not ?found\.?$/i.test(reason.trim());
+function describeNotFound(subject, noun, reason) {
+  const explained = reason && !saysNothingMore(reason) ? reason : undefined;
+  const say = (own) => {
+    const body = [explained ? undefined : own.guess, own.guidance].filter((line) => line);
+    return {
+      error: explained ? `${explained} (HTTP 404)` : own.statement,
+      exitCode: exitCodes.notFound,
+      ...body.length > 0 ? { errorBody: body.join(`
+`) } : {}
+    };
+  };
+  switch (subject?.kind) {
+    case "runner":
+      return say({
+        guess: m.runnerIsGone,
+        guidance: m.launchTheRunner(subject.runnerId),
+        statement: m.notFound404Runner(subject.runnerId)
+      });
+    case "run":
+      return say({
+        guess: m.runIdMayBeRunnerLocal(subject.runId),
+        statement: m.notFound404Run(subject.runId)
+      });
+    case "record":
+      return say({ statement: m.notFound404Record(subject.noun, subject.id) });
+    case "other":
+      return say({ statement: m.notFound404(noun) });
+    case "environment":
+    case undefined:
+      return say({ statement: m.notFound404Environment(noun) });
+  }
+}
+
 // src/shell/platform/parseErrorBody.ts
 var defaultMaxLength = 1024;
 function asRecord(value) {
@@ -11578,69 +11701,69 @@ function clip(message, maxLength) {
 }
 
 // src/shell/platform/describeErrors.ts
-var m = authMessages.errors;
+var m2 = authMessages.errors;
 var inlineReasonMaxLength = 200;
 function describeIdentityError(err) {
   if (err.kind === "http") {
     if (err.status === 401 || err.status === 403) {
       return {
-        error: m.identity.invalidOrUnauthorized,
+        error: m2.identity.invalidOrUnauthorized,
         ...err.status === 401 ? { exitCode: exitCodes.auth } : {}
       };
     }
     return {
-      error: m.identity.couldNotVerify(parseErrorBody(err.body, inlineReasonMaxLength), err.status)
+      error: m2.identity.couldNotVerify(parseErrorBody(err.body, inlineReasonMaxLength), err.status)
     };
   }
   if (err.kind === "network") {
-    return { error: m.identity.couldNotVerifyNetwork(err.cause.message) };
+    return { error: m2.identity.couldNotVerifyNetwork(err.cause.message) };
   }
   if (err.kind === "timeout") {
-    return { error: m.identity.timedOut(err.timeoutMs) };
+    return { error: m2.identity.timedOut(err.timeoutMs) };
   }
-  return { error: m.identity.unexpectedFormat };
+  return { error: m2.identity.unexpectedFormat };
 }
-function describeRequestError(err, baseUrl, noun) {
+function describeRequestError(err, baseUrl, noun, notFound) {
   if (err.kind === "http") {
     const reason = parseErrorBody(err.body);
     const body = reason ? { errorBody: reason } : {};
     if (err.status === 401)
       return {
-        error: m.request.rejected401(noun),
+        error: m2.request.rejected401(noun),
         exitCode: exitCodes.auth,
         ...body
       };
     if (err.status === 402)
       return {
-        error: m.request.rejected402(noun),
+        error: m2.request.rejected402(noun),
         exitCode: exitCodes.payment,
         ...body
       };
     if (err.status === 403)
-      return { error: m.request.rejected403(noun), ...body };
+      return { error: m2.request.rejected403(noun), ...body };
     if (err.status === 404)
-      return { error: m.request.notFound404(noun), ...body };
-    return { error: m.request.failedWithStatus(err.status, noun), ...body };
+      return describeNotFound(notFound, noun, reason);
+    return { error: m2.request.failedWithStatus(err.status, noun), ...body };
   }
   if (err.kind === "network") {
-    return { error: m.request.networkUnreachable(baseUrl, noun) };
+    return { error: m2.request.networkUnreachable(baseUrl, noun) };
   }
   if (err.kind === "timeout") {
-    return { error: m.request.timedOut(err.timeoutMs, noun) };
+    return { error: m2.request.timedOut(err.timeoutMs, noun) };
   }
-  return { error: m.request.unexpectedResponse(noun) };
+  return { error: m2.request.unexpectedResponse(noun) };
 }
 function describeBundleDownloadError(err) {
   if (err.kind === "http") {
     if (err.status === 401 || err.status === 403)
-      return m.bundle.linkExpired;
-    return m.bundle.failedWithStatus(err.status);
+      return m2.bundle.linkExpired;
+    return m2.bundle.failedWithStatus(err.status);
   }
   if (err.kind === "network")
-    return m.bundle.networkUnreachable;
+    return m2.bundle.networkUnreachable;
   if (err.kind === "timeout")
-    return m.bundle.timedOut(err.timeoutMs);
-  return m.bundle.malformed;
+    return m2.bundle.timedOut(err.timeoutMs);
+  return m2.bundle.malformed;
 }
 function describeTeamStorageDownloadError(path, err) {
   if (err.kind === "http") {
@@ -11667,12 +11790,16 @@ function callPublicApi(trpc, contract, input, options) {
   return trpc.mutation(path, input, contract.output, options);
 }
 function makeCallPublicApiMethod(trpc, deps, readBackoffMs) {
-  return async (contract, input, options) => requestWithRetry({
-    call: () => callPublicApi(trpc, contract, applyWorkspaceId(contract.input, input, deps.workspaceId), options),
-    backoffMs: contract.kind === "read" ? readBackoffMs : [],
-    describe: (err) => describeRequestError(err, deps.baseUrl, contract.name),
-    sleep: deps.sleep
-  });
+  return async (contract, input, options) => {
+    const sent = applyWorkspaceId(contract.input, input, deps.workspaceId);
+    const subject = notFoundSubject(contract.name, sent);
+    return requestWithRetry({
+      call: () => callPublicApi(trpc, contract, sent, options),
+      backoffMs: contract.kind === "read" ? readBackoffMs : [],
+      describe: (err) => describeRequestError(err, deps.baseUrl, contract.name, subject),
+      sleep: deps.sleep
+    });
+  };
 }
 
 // node_modules/superjson/dist/double-indexed-kv.js
@@ -13161,25 +13288,36 @@ function createSdkContext(options) {
   };
 }
 
+// src/domains/interactiveRunner/runnerRequestFailure.ts
+function runnerRequestFailure(failure, runner) {
+  const fields = failureFields(failure);
+  if (failure.exitCode !== exitCodes.notFound) {
+    return { ...fields, exitCode: failure.exitCode ?? exitCodes.network };
+  }
+  const cameFrom = interactiveRunnerMessages.runnerIdCameFrom(runner.runnerId, runner.source);
+  return {
+    ...fields,
+    errorBody: fields.errorBody ? `${fields.errorBody}
+${cameFrom}` : cameFrom,
+    exitCode: exitCodes.notFound
+  };
+}
+
 // src/domains/interactiveRunner/readJournal.ts
 var unreachableFailure = {
   error: interactiveRunnerMessages.runnerUnreachable,
   exitCode: exitCodes.network
 };
-async function readJournal(ctx, runnerId, request) {
+async function readJournal(ctx, runner, request) {
   const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.readJournal, {
-    id: runnerId,
+    id: runner.runnerId,
     stream: request.stream,
     ...request.runId === undefined ? {} : { runId: request.runId },
     ...request.sinceSequence === undefined ? {} : { sinceSequence: request.sinceSequence },
     ...request.tail === undefined ? {} : { tail: request.tail }
   }, runnerCallOptions);
   if (!result.ok) {
-    return {
-      ...failureFields(result),
-      exitCode: exitCodes.network,
-      type: "failed"
-    };
+    return { ...runnerRequestFailure(result, runner), type: "failed" };
   }
   if (result.value.outcome === "failure") {
     result.value.failureReason;
@@ -13188,9 +13326,24 @@ async function readJournal(ctx, runnerId, request) {
   return { type: "read", value: result.value };
 }
 
+// src/runnerSdk/givenRunner.ts
+var givenRunner = (runnerId) => ({
+  runnerId,
+  source: "given"
+});
+
+// src/runnerSdk/toSdkFailure.ts
+function toSdkFailure(failure) {
+  return {
+    error: failure.error,
+    ...failure.errorBody ? { errorDetail: failure.errorBody } : {},
+    ok: false
+  };
+}
+
 // src/runnerSdk/toSdkResult.ts
 function toSdkResult(result) {
-  return result.ok ? { ok: true, value: result.value } : { error: result.error, ok: false };
+  return result.ok ? { ok: true, value: result.value } : toSdkFailure(result);
 }
 
 // src/runnerSdk/lifecycleVerbs.ts
@@ -13201,16 +13354,13 @@ function createLifecycleVerbs({ platformClient }) {
     async keepalive({
       runnerId
     }) {
-      const read = await readJournal(ctx, runnerId, {
+      const read = await readJournal(ctx, givenRunner(runnerId), {
         stream: "run-status",
         tail: 1
       });
       if (read.type === "read")
         return { ok: true, value: { id: runnerId } };
-      return {
-        error: read.type === "unreachable" ? "The runner could not be reached." : read.error,
-        ok: false
-      };
+      return read.type === "unreachable" ? { error: "The runner could not be reached.", ok: false } : toSdkFailure(read);
     },
     async launch({
       id,
@@ -13692,10 +13842,7 @@ async function sendRunFlowRequest(ctx, options, delta) {
   }, runnerCallOptions);
   if (!result.ok) {
     return {
-      failure: {
-        ...failureFields(result),
-        exitCode: result.exitCode ?? exitCodes.network
-      },
+      failure: runnerRequestFailure(result, options.resolved),
       type: "failed"
     };
   }
@@ -13784,17 +13931,14 @@ function createRunVerbs({ deps, platformClient }) {
       stream,
       window
     }) {
-      const read = await readJournal(ctx, runnerId, {
+      const read = await readJournal(ctx, givenRunner(runnerId), {
         stream,
         ...runFilter === "all-runs" ? {} : { runId: runFilter.runId },
         ...window === "newest" ? {} : ("tail" in window) ? { tail: window.tail } : { sinceSequence: window.sinceSequence }
       });
       if (read.type === "read")
         return { ok: true, value: read.value };
-      return {
-        error: read.type === "unreachable" ? "The runner could not be reached." : read.error,
-        ok: false
-      };
+      return read.type === "unreachable" ? { error: "The runner could not be reached.", ok: false } : toSdkFailure(read);
     },
     async run({
       entryPointPath,
@@ -13816,11 +13960,11 @@ function createRunVerbs({ deps, platformClient }) {
         environment: prepared.environment,
         environmentId: prepared.environmentId,
         files: prepared.files,
-        resolved: { runnerId, type: "resolved" },
+        resolved: { ...givenRunner(runnerId), type: "resolved" },
         selection: prepared.selection
       }, deps);
       if (!submitted.ok)
-        return { error: submitted.error, ok: false };
+        return toSdkFailure(submitted);
       return {
         ok: true,
         value: {
@@ -13851,4 +13995,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=395E9F8ECC554DB664756E2164756E21
+//# debugId=C50E262AB8A599ED64756E2164756E21

package/dist/types/runnerSdk/types.d.ts

@@ -11,6 +11,12 @@ export type RunnerSdkOptions = {
 };
 export type SdkResult<Value> = {
     error: string;
+    /**
+     * What the platform said beyond the headline, and what to do about it:
+     * the reason a runner is gone, which of `--runner`, `QAWOLF_RUNNER_ID` or
+     * the stored default named it, the command that brings one back.
+     */
+    errorDetail?: string;
     ok: false;
 } | {
     ok: true;

package/package.json

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

package/skills/qawolf-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qawolf-cli
-description: Manage QA Wolf through the qawolf CLI. Use when asked to create, update, or list coverage requests, bug reports, or maintenance reports; start a run of flows or tags on the QA Wolf platform or read a run's results; list, set, or delete environment variables; manage environments, flows, or tags; request automation of draft flows; run or list flows locally; authenticate; install the local runtime; or drive a live cloud browser (launch a runner, screenshot it, click and type on it, read its recorder) from a shell.
+description: Manage QA Wolf through the qawolf CLI. Use when asked to create, update, or list coverage requests, bug reports, or maintenance reports; start a run of flows or tags on the QA Wolf platform or read a run's results; list, set, or delete environment variables; manage environments, flows, or tags; run or list flows locally; authenticate; install the local runtime; or drive a live cloud browser (launch a runner, screenshot it, click and type on it, read its recorder) from a shell.
 license: Apache-2.0
 compatibility: Requires the qawolf CLI on PATH. Install it from @qawolf/cli or use a standalone binary from GitHub Releases.
 ---
@@ -131,7 +131,6 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf auth logout` | local | Remove stored credentials |
 | `qawolf auth switch` | local | Choose which workspace to work in |
 | `qawolf auth whoami` | read | Show authentication status |
-| `qawolf automate` | write | Request automation for draft flows. First create a named local .flow.ts draft for every requested journey that does not already have a matching draft; never reuse a generic starter or placeholder. Each new draft must start with a JSDoc Goal: description, import flow from @qawolf/flows/web, and use export default flow(...); a comment-only file or direct test(...) call is not a valid draft. Commit and push all changes with Git to publish them, then list remote drafts to resolve every selected ID. Do not use patch to create or rename a selected flow. Finally make one automation request containing all requested flow IDs. |
 | `qawolf doctor` | local | Diagnose problems running flows locally |
 | `qawolf email find` | read | List the workspace's inbox, or its sent mail, newest first. Read a message body with email.get. |
 | `qawolf email get` | read | Read one email of the workspace, with its plain text and HTML bodies. Use it to pull a sign-in code or a verification link out of a message. |

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

@@ -25,6 +25,14 @@ run
 `runId` in the response is canonical and can differ from the id you asked for.
 Use the returned value for follow-up calls.
 
+`run get` resolves platform runs only. A run id printed by `qawolf runner run`
+belongs to that runner, so `run get` answers exit `8` and no such run on this
+team. Read one of those with `qawolf runner events run-status --run <id>`.
+
+A run that has been requested but not yet created answers exit `8` too, and
+says it is still being created. That one clears on its own, so read the message
+rather than the code before deciding whether to poll.
+
 Poll `status` until it reaches `passed`, `failed` or `canceled`. The other
 values mean the run is still going.
 

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

@@ -30,8 +30,8 @@ then launched without `--id` ends up with a pod it is not addressing. Pass
 And a runner id that is set is treated as found, whether or not anything is
 running under it. So exporting `QAWOLF_RUNNER_ID=agent-1` turns off the
 auto-launch described next: instead of starting `agent-1`, commands try to reach
-it and fail with exit code `4`, which reads as "retry" and never succeeds.
-Launch that id once yourself and the rest follows.
+it and fail with exit code `8`, naming the id and saying the variable is what
+chose it. Launch that id once yourself and the rest follows.
 
 And launching an id that differs from `QAWOLF_RUNNER_ID` prints a warning on
 stderr naming both ids: the variable still outranks the directory default, so
@@ -119,11 +119,14 @@ and says so on stderr. Everything else on this page waits for a run.
 
 Retry on the exit code, not on the message text:
 
-- `4` is usually transient. The screen is up but cannot serve this instant:
-  restarting after a display-size change, or busy with another request. Retry in
-  a second or two — but bound the retries, because `4` also covers a runner that
-  was reaped after inactivity, which no amount of retrying brings back. If `4`
-  persists past a few tries, relaunch the id.
+- `4` is transient. The screen is up but cannot serve this instant: restarting
+  after a display-size change, or busy with another request. Retry in a second
+  or two, and bound the retries.
+- `8` means there is no such runner. It was never launched, or it was
+  terminated, or it idled out. Retrying never brings one back, so stop and
+  launch the id or name one that is running. The message says which runner was
+  meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored
+  default chose it — read that line before you pick an id to launch.
 - `2` will not clear on its own. Either nothing has run on this runner yet, so
   run a flow, or the runner has no browser at all, so launch with
   `--name playwright` instead. The message says which.
@@ -224,7 +227,8 @@ what the page shows.
 One failure covers three causes, because a runner cannot tell them apart: no
 live page, no element matching the selector, no variable under that name. All
 three exit `2` and none clears by waiting, so read the message, which carries
-whatever the runner said. An unreachable runner exits `4` and is worth retrying.
+whatever the runner said. An unreachable runner exits `4` and is worth retrying;
+a runner that is not running at all exits `8` and is not.
 
 Use `inspect` before reaching for `exec`. Reading a value through a snippet
 means printing it and then fishing it back out of the `console` stream, which is