@qawolf/cli 1.34.0 → 1.35.0

package/dist/cli.js

@@ -16635,7 +16635,7 @@ var agentSessionStatuses = [
   "failed",
   "cancelled"
 ];
-var agentSessionStatusSchema = _enum(agentSessionStatuses).describe('Where the work stands. "working" means the AI is still on it. "waiting-for-you" means it asked a question and cannot continue until agent.send answers it. "completed", "failed" and "cancelled" are settled and will not change.');
+var agentSessionStatusSchema = _enum(agentSessionStatuses).describe('Where the work stands. "working" means the AI is still on it. "waiting-for-you" means it asked a question and cannot continue until agent.send answers it. "completed" means it finished what it was asked, and a new agent.send continues it. "failed" and "cancelled" are settled and will not change.');
 var agentReplySchema = object({
   askedAt: exports_iso.datetime().describe("When the AI wrote this, as an ISO 8601 timestamp."),
   choices: array(string2()).optional().describe("The answers the AI offered, when the reply is a question with a fixed set of them. Answer by sending one of these back through agent.send."),
@@ -16814,7 +16814,7 @@ var defaultIdSchemas = {
   trigger: string2().min(1).describe("The id of the trigger."),
   workspace: string2().min(1).describe("The id of the workspace.")
 };
-var workspaceForEnvironmentRef = (workspace) => workspace.optional().describe("The workspace the environment belongs to. Required to reference the environment by alias when authenticating with an organization or user API key.");
+var workspaceForEnvironmentRef = (workspace) => workspace.optional().describe("The workspace the environment belongs to, which an alias resolves in. Read it from whoami.");
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/flowSelection.js
 var makeFlowSelectionSchema = (ids) => object({
@@ -16988,7 +16988,7 @@ var runnerNameSchema = _enum([
   "android",
   "ios"
 ]);
-var runnerWorkspaceRequirement = "Required when the credential is not bound to a single workspace, such as a user API key or an OAuth connection whose organization owns several.";
+var runnerWorkspaceRequirement = "Read it from whoami.";
 var runnerWorkspaceIdDescription = `The workspace the runner belongs to. ${runnerWorkspaceRequirement}`;
 var runnerIdSchema = string2().min(1).max(63).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "A runner id may contain only lowercase letters, digits and dashes, and must start and end with a letter or digit.");
 var runnerWatchUrlSchema = url().describe("A QA Wolf page showing what the runner is doing right now, where the person who launched it can watch and take over with their own mouse and keyboard. Opening it requires being signed in to QA Wolf. This link belongs to the user: put it in a normal message as soon as the runner is launched, so they can follow along while the browser is being driven. It is theirs to open, never a page for the caller to fetch or navigate to. The page ends when the runner is terminated, so share it while the runner is alive and report what you found at the end instead of repeating a dead link.");
@@ -17569,23 +17569,28 @@ var makeTriggerActionSchema = (ids) => object({
   instructions: string2().min(1).optional().describe("Guidance for QA Wolf. Applies to generativeSuite only."),
   investigateFailures: boolean2().optional().describe("Whether QA Wolf investigates failures in the resulting runs. Defaults to true."),
   kind: triggerActionKindSchema.default("createSuite"),
+  runConcurrencyLimit: string2().trim().min(1).max(255).optional().describe(`How many runs of the resulting suite may execute at once: a whole number from 1 to 1000, "unlimited", or a concurrency expression, which the server validates. It replaces the environment's limit rather than capping below it. Omit it to leave the environment's limit in charge.`),
   tagNames: array(string2().min(1)).default([]).describe("Tags naming the flows to run. Combined with flowIds.")
 }).describe("What the trigger runs when it fires.");
 var makeTriggerScheduleFields = (ids) => ({
   action: makeTriggerActionSchema(ids),
   cadence: triggerCadenceSchema,
   dayOfWeek: triggerDayOfWeekSchema.optional().describe("The day a weekly schedule fires on, read in timezoneId. Required when cadence is weekly."),
+  daysOfWeek: array(triggerDayOfWeekSchema).min(1).refine((daysOfWeek) => new Set(daysOfWeek).size === daysOfWeek.length, {
+    message: "Expected each day to be named at most once."
+  }).optional().describe("The only days an hourly or daily schedule fires on, read in timezoneId. Name each day at most once. Omitting it fires on every day."),
   environmentId: ids.environmentId.describe("The environment the scheduled runs happen in."),
   minuteOfHour: number2().int().min(0).max(59).optional().describe("Minutes past the hour an hourly schedule fires. Defaults to 0."),
   timeOfDay: string2().regex(/^([01]\d|2[0-3]):[0-5]\d$/).optional().describe('The wall clock time a daily or weekly schedule fires, as "HH:mm". Required when cadence is daily or weekly.'),
-  timezoneId: string2().min(1).refine(isTimezone, "Expected an IANA timezone, such as America/New_York.").optional().describe("The IANA timezone that timeOfDay is read in, such as America/New_York. Required when cadence is daily or weekly.")
+  timezoneId: string2().min(1).refine(isTimezone, "Expected an IANA timezone, such as America/New_York.").optional().describe("The IANA timezone the schedule is read in, such as America/New_York. Required when cadence is daily or weekly, and when an hourly schedule names daysOfWeek, whose day boundaries it sets. An hourly schedule firing on every day needs none, and is read in America/Los_Angeles.")
 });
 var makeTriggerDeploymentFields = (ids) => ({
   action: makeTriggerActionSchema(ids),
   branchPattern: string2().min(1).optional().describe("Only fire for deployments of a branch matching this pattern."),
-  deployTargetPattern: string2().min(1).optional().describe("Only fire for deployments of an app matching this pattern. A deploy target names one app within an environment."),
+  deployTargetPattern: string2().min(1).optional().describe("Only fire for deployments whose deploy target matches this pattern. A deploy target is the URL or label the deploy reported, which many deployments do not carry."),
   environmentIds: array(ids.environment).default([]).describe("Only fire for deployments to these environments. Mutually exclusive with environmentPattern."),
-  environmentPattern: string2().min(1).optional().describe("Only fire for deployments to environments matching this pattern. Mutually exclusive with environmentIds.")
+  environmentPattern: string2().min(1).optional().describe("Only fire for deployments to environments matching this pattern. Mutually exclusive with environmentIds."),
+  servicePattern: string2().min(1).optional().describe("Only fire for deployments whose service matches this pattern. A deployment that names no service never matches it.")
 });
 
 // node_modules/@qawolf/api-contracts/dist/v1/trigger/configurationRules.js
@@ -17621,20 +17626,28 @@ var requiredScheduleFields = {
   hourly: [],
   weekly: ["dayOfWeek", "timeOfDay", "timezoneId"]
 };
+var optionalScheduleFields = {
+  daily: ["daysOfWeek"],
+  hourly: ["daysOfWeek", "minuteOfHour", "timezoneId"],
+  weekly: []
+};
 var cadencesUsingField = {
   dayOfWeek: "a weekly cadence",
+  daysOfWeek: "an hourly or daily cadence",
   minuteOfHour: "an hourly cadence",
   timeOfDay: "a daily or weekly cadence",
-  timezoneId: "a daily or weekly cadence"
+  timezoneId: "an hourly, daily or weekly cadence"
 };
 var scheduleFields = [
   "dayOfWeek",
+  "daysOfWeek",
   "minuteOfHour",
   "timeOfDay",
   "timezoneId"
 ];
 var checkScheduleFields = (value, ctx) => {
   const required = requiredScheduleFields[value.cadence];
+  const optional = optionalScheduleFields[value.cadence];
   for (const field of scheduleFields) {
     const isSupplied = value[field] !== undefined;
     if (required.includes(field)) {
@@ -17647,7 +17660,7 @@ var checkScheduleFields = (value, ctx) => {
       }
       continue;
     }
-    if (isSupplied && !(value.cadence === "hourly" && field === "minuteOfHour")) {
+    if (isSupplied && !optional.includes(field)) {
       ctx.addIssue({
         code: "custom",
         message: `${field} applies to ${cadencesUsingField[field]} only.`,
@@ -17656,8 +17669,18 @@ var checkScheduleFields = (value, ctx) => {
     }
   }
 };
+var checkHourlyZone = (value, ctx) => {
+  if (value.cadence !== "hourly" || value.daysOfWeek === undefined || value.timezoneId !== undefined)
+    return;
+  ctx.addIssue({
+    code: "custom",
+    message: "timezoneId is required when an hourly cadence names daysOfWeek.",
+    path: ["timezoneId"]
+  });
+};
 var checkSchedule = (value, ctx) => {
   checkScheduleFields(value, ctx);
+  checkHourlyZone(value, ctx);
   if (value.action.kind === "generativeSuite") {
     ctx.addIssue({
       code: "custom",
@@ -18023,12 +18046,14 @@ var makeDeploymentResourceSchema = (ids) => resource({
   commitAuthorName: string2().optional().describe("The author of the deployed commit."),
   commitMessage: string2().optional().describe("The message of the deployed commit."),
   commitSha: string2().optional().describe("The sha of the deployed commit."),
+  commitUrl: string2().optional().describe("A link to the deployed commit, as declared by the deployment report."),
   deployedAt: exports_iso.datetime().describe("When QA Wolf first received the deployment."),
   deployTarget: string2().optional().describe("Identifies the deployed app within the environment: the URL it serves, or the build path of a mobile build. A trigger's deployTargetPattern matches against it."),
   environmentId: ids.environment.describe("The QA Wolf environment the deployment reported into."),
   environmentName: string2().optional().describe("The environment's name. Absent when the environment has since been deleted."),
   id: ids.deployment,
   provider: _enum(["github", "gitlab", "api"]).optional().describe("How QA Wolf received the deployment: a GitHub webhook, a GitLab webhook, or the deployment.reportStatus API."),
+  service: string2().optional().describe("Which application was deployed, as the deployer named it. Absent when the deployer named none."),
   status: _enum(["pending", "success", "failure", "inactive"]).optional().describe("The deployment's lifecycle status, in the vocabulary deployment.reportStatus accepts. Absent when no status was ever reported.")
 }, {
   urlFieldDescription: "Absolute URL of the workspace's deployments page."
@@ -18058,8 +18083,55 @@ var makeFindDeploymentsContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/deployment/didNotRunReason.js
+var didNotRunReasonSchema = _enum([
+  "billing-prevented",
+  "branch-still-syncing",
+  "deployment-no-longer-live",
+  "duplicate-run",
+  "environment-not-linked-to-branch",
+  "environment-not-ready",
+  "environment-terminated",
+  "internal-error",
+  "low-risk-change",
+  "no-flows-to-run",
+  "no-matching-trigger",
+  "no-pull-request",
+  "no-relevant-flows",
+  "rate-limited",
+  "run-not-created",
+  "skipped",
+  "test-configuration-error",
+  "trigger-not-found",
+  "workspace-inactive",
+  "workspace-not-ready"
+]).describe([
+  "Why the matched trigger created no run, as a stable value safe to branch on in a CI pipeline. The accompanying `message` is the wording for a person to read and may be reworded at any time; this value will not be.",
+  "billing-prevented: a billing restriction on the workspace stopped the run.",
+  "branch-still-syncing: the environment was still syncing its flows.",
+  "deployment-no-longer-live: the deployment was torn down or replaced by a newer one before the run started.",
+  "duplicate-run: another run already covered this same deployment.",
+  "environment-not-linked-to-branch: the environment has no branch to take flows from yet.",
+  "environment-not-ready: the environment was still being prepared; retrying later can succeed.",
+  "environment-terminated: the environment for the run is terminated.",
+  "internal-error: QA Wolf could not start the run and the cause is on our side.",
+  "low-risk-change: adaptive flow selection assessed the change as low risk, so nothing needed to run.",
+  "no-flows-to-run: no flow was eligible, because the trigger's flows are in maintenance, still drafts, or missing on this branch.",
+  "no-matching-trigger: no deployment trigger matched.",
+  "no-pull-request: the trigger uses adaptive flow selection, which needs an open pull request, and this deployment had none.",
+  "no-relevant-flows: adaptive flow selection found no existing flow covering this change.",
+  "rate-limited: too many runs were requested at once; retrying later can succeed.",
+  "run-not-created: the run never reached a decision.",
+  "skipped: the run was skipped for a reason with no more specific value.",
+  "test-configuration-error: the workspace's flows or dependency rules need fixing before this can run.",
+  "trigger-not-found: the trigger no longer exists.",
+  "workspace-inactive: the workspace is not active.",
+  "workspace-not-ready: the workspace has not finished setting up."
+].join(`
+`));
+
 // node_modules/@qawolf/api-contracts/dist/v1/deployment/listTriggerEvaluations.js
-var conditionKindSchema = _enum(["environment", "deployTarget", "branch"]).describe("What the condition checks on the deployment: the environment it reported into, the deploy target identifying the deployed app, or the git branch of the deployed commit.");
+var conditionKindSchema = _enum(["environment", "deployTarget", "branch", "service"]).describe("What the condition checks on the deployment: the environment it reported into, the deploy target it serves, the git branch of the deployed commit, or the service it deployed.");
 var conditionVerdictSchema = discriminatedUnion("outcome", [
   object({
     kind: conditionKindSchema,
@@ -18082,12 +18154,13 @@ var makeRunOutcomeSchema = (ids) => discriminatedUnion("status", [
   }),
   object({ status: literal("starting") }),
   object({
-    reason: string2().describe("Why the matched trigger created no run, in plain language."),
+    message: string2().describe("Why the matched trigger created no run, in plain language."),
+    reason: didNotRunReasonSchema,
     status: literal("did-not-run"),
     supersededByRunId: ids.run.optional().describe("The run that covered this deployment instead, when an earlier delivery of the same deployment had already created one.")
   }),
   object({ status: literal("unknown") })
-]).describe("What became of the match. Matching is not running: a matched trigger can still be stopped from creating a run, and did-not-run carries the reason. starting means run creation is still in progress; unknown means QA Wolf has no record of what followed the match.");
+]).describe("What became of the match. Matching is not running: a matched trigger can still be stopped from creating a run, and did-not-run carries the reason. starting means run creation is still in progress; unknown means QA Wolf has no record of what followed the match. did-not-run also carries a stable reason to branch on, beside the message for a person to read.");
 var makeVerdictSchema = (ids) => discriminatedUnion("outcome", [
   object({
     conditionSets: conditionSetsField,
@@ -18136,6 +18209,7 @@ var deploymentReportMetadata = strictObject({
   commitAuthorName: string2().trim().min(1).max(255).describe("The display name of the person who authored the deployed commit.").optional(),
   commitMessage: string2().trim().min(1).max(2048).describe("The message of the deployed commit. The deployments list shows its first line.").optional(),
   commitSha: string2().trim().min(1).max(255).describe("The commit sha of the deployed application revision.").optional(),
+  commitUrl: httpUrl().max(2048).describe("A link to the deployed commit in your code host. Send this when QA Wolf cannot resolve the commit itself, for example when the QA Wolf GitHub App is not installed.").optional(),
   pullRequestNumber: number2().int().positive().describe("The number of the pull request the deployment belongs to. Requires repository.").optional(),
   ref: string2().trim().min(1).max(255).describe("The branch or ref that was deployed.").optional(),
   repository: string2().trim().min(1).max(255).describe('The owner/name of the repository, e.g. "acme/web".').optional()
@@ -18170,6 +18244,7 @@ var makeReportDeploymentStatusContract = (ids) => {
     environmentVariables: record(string2(), string2()).describe("Environment variable overrides for the runs this deployment requests. A report that omits this field keeps the stored values. A report that sends it replaces them.").optional(),
     metadata: deploymentReportMetadata.describe("Details the deployer declares about the deployed revision; a code host integration's own record of the same commit is shown in preference to the message and author declared here.").optional(),
     providerDeploymentId: string2().trim().min(1).max(255).describe('Your identifier for the deployment, e.g. "vercel_dpl_123". Reports with the same providerDeploymentId update one deployment within this workspace.'),
+    service: string2().trim().min(1).max(255).describe('Which application was deployed, e.g. "checkout-api", when several services deploy into one environment. A report that omits it keeps the stored value.').optional(),
     status: deploymentStatusSchema.describe("The deployment lifecycle status. A deployment's first success report evaluates global triggers asynchronously, and it is the only report that does. The response does not include the resulting runs."),
     workspaceId: ids.workspace.describe("The workspace to report the deployment status into. A team API key must name its own workspace.")
   }).superRefine((value, context) => {
@@ -18840,6 +18915,70 @@ var makeGetIssueContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/investigation/finding.js
+var investigationFindingStateDescription = 'What the investigation concluded about the cause. Known values: "investigating", "fixed", "fix-proposed", "reported", "report-proposed", "flake", "question" and "dismissed". New values can appear.';
+var makeInvestigationFindingSchema = (ids) => object({
+  actual: string2().optional(),
+  commitHash: string2().optional(),
+  decidedBy: _enum(["agent", "user"]).optional().describe("Who decided: the AI on its own, or a person who approved or dismissed it. Absent until someone decides."),
+  disputeReason: string2().optional().describe("Why a person disputed what the AI did. Present on a proposal the AI made again after that dispute."),
+  expected: string2().optional(),
+  findingId: string2(),
+  flowIds: array(ids.flow),
+  headline: string2().optional(),
+  issueId: ids.issue.optional(),
+  kind: string2().describe('What the failure is. Known values: "maintenance", "bug", "flake" and "unknown". New values can appear.'),
+  matchReason: string2().optional(),
+  priority: issuePrioritySchema.optional(),
+  question: object({
+    answers: array(object({
+      description: string2().optional(),
+      title: string2(),
+      value: string2().describe('What choosing this answer means. Known values: "apply", "dismiss", "report", "maintenance" and "bug". New values can appear.')
+    })),
+    text: string2()
+  }).optional().describe("The question waiting for a person, with the answers offered."),
+  response: object({
+    answer: string2().optional(),
+    at: exports_iso.datetime(),
+    reason: string2().optional(),
+    type: string2().describe('Known values: "answer" and "dispute". New values can appear.')
+  }).optional().describe("A person's answer or dispute that the investigation hasn't acted on yet."),
+  state: string2().describe(investigationFindingStateDescription),
+  steps: array(string2()).optional(),
+  subSessionIds: array(ids.chatSession),
+  summary: string2().optional(),
+  updatedAt: exports_iso.datetime()
+});
+
+// node_modules/@qawolf/api-contracts/dist/v1/investigation/get.js
+var makeGetInvestigationContract = (ids) => {
+  const input = object({ runId: ids.run });
+  const output = resource({
+    findings: array(makeInvestigationFindingSchema(ids)),
+    runId: ids.run,
+    sessionId: ids.chatSession.optional().describe("The investigation session. Absent when the run has none."),
+    status: _enum(["investigating", "finished", "not-investigated"]).describe('Whether the investigation session is still working. "not-investigated" when the run has no investigation.')
+  }, { urlFieldDescription: "The run in the QA Wolf app." });
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: "Read what the QA Wolf AI investigating a run has concluded: one finding per cause of its failures, " + "with the question waiting for a person and any answer or dispute the investigation hasn't acted on yet.",
+    input,
+    kind: "read",
+    name: "investigation.get",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/investigation/index.js
+var makeInvestigationContracts = (ids) => ({
+  get: makeGetInvestigationContract(ids)
+});
+
 // node_modules/@qawolf/api-contracts/dist/v1/issue/addFlows.js
 var makeAddFlowsToIssueContract = (ids) => {
   const input = object({
@@ -19097,6 +19236,13 @@ var makeDiagnoseRunContract = (ids) => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/summary.js
+var publicRunStatusValues = [
+  "queued",
+  "running",
+  "passed",
+  "failed",
+  "canceled"
+];
 var makeRunSummaryFields = (ids) => ({
   completedAt: exports_iso.datetime().optional().describe("When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped)."),
   createdAt: exports_iso.datetime(),
@@ -19107,7 +19253,7 @@ var makeRunSummaryFields = (ids) => ({
     commitUrl: string2().optional().describe("Link to the commit on the code host.")
   }).describe("The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create."),
   runId: ids.run,
-  status: _enum(["queued", "running", "passed", "failed", "canceled"]).describe("Whole-run status. Terminal statuses are passed, failed, and canceled; poll until one is reached.")
+  status: _enum(publicRunStatusValues).describe("Whole-run status, and the value to gate a pipeline on. Terminal statuses are passed, failed, and canceled; poll until one is reached. `failed` means the run found a bug that is still open and serious enough to block — a lower-priority bug, or one since resolved, reads `passed`, and the per-flow diagnoses are still in `flows`. The run stays `running` while any investigation is unresolved, including one that carried over to a later run, so a terminal status always means a settled answer.")
 });
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/find.js
@@ -19140,7 +19286,9 @@ var makeFindRunsContract = (ids) => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/get.js
 var makeGetRunContract = (ids) => {
+  const flowStatus = _enum(publicRunStatusValues);
   const input = object({
+    flowStatuses: array(flowStatus).min(1).optional().describe("Return only the flows whose status is one of these. A suite run can " + "hold hundreds of flows, so start an investigation with failed " + "alone. A flow that passed after a retry reads passed, so add " + "passed when a flaky flow is missing from the answer. Omit to " + "return every flow. The run-level fields are unaffected."),
     runId: ids.run
   });
   const artifactUrls = {
@@ -19197,11 +19345,12 @@ var makeGetRunContract = (ids) => {
     attempts,
     flowId: ids.flow,
     name: string2(),
-    status: _enum(["queued", "running", "passed", "canceled"])
+    status: flowStatus.exclude(["failed"])
   });
-  const flows = array(discriminatedUnion("status", [failedFlow, nonFailedFlow])).describe("The run's flows, ordered alphabetically by name.");
+  const flows = array(discriminatedUnion("status", [failedFlow, nonFailedFlow])).describe("The run's flows, ordered alphabetically by name. Only the flows " + "matching flowStatuses when the request set it.");
   const output = resource({
     ...makeRunSummaryFields(ids),
+    blockingBugCount: number2().int().nonnegative().describe("How many bugs this run found are blocking: still open, and priority urgent, high, or unprioritized — unprioritized counts because nobody has ruled it out yet. This is what `failed` is derived from, so it explains a failure rather than adding a second verdict: gate on `status`, then read this to say how many bugs are holding the build. It counts a bug filed against a later run by an investigation that carried over from this one, and it drops a bug once that bug is resolved."),
     flows,
     runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.")
   }, { urlFieldDescription: "Absolute URL of the run page." });
@@ -19211,7 +19360,7 @@ var makeGetRunContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: true
     },
-    description: "Get a run's status, per-flow results, and links.",
+    description: "Get a run's status, per-flow results, links, and how many of its bugs are blocking.",
     input,
     kind: "read",
     name: "run.get",
@@ -19463,8 +19612,12 @@ var makeImportPackageOnRunnerContract = (ids) => {
 var makeLaunchRunnerContract = (ids) => {
   const input = object({
     id: runnerIdSchema.describe("Id to launch the runner under, chosen by the caller. Launching the same id again returns the runner already running under it."),
+    initialUrl: navigableUrlSchema.optional().describe("The page to open as the browser starts, so the first screenshot already shows the application rather than a blank page."),
     runnerName: runnerNameSchema.optional().describe("The runner family to launch. Defaults to the standard web family, playwright."),
     workspaceId: ids.workspace.optional().describe(`The workspace to launch the runner in. ${runnerWorkspaceRequirement}`)
+  }).refine((request) => request.initialUrl === undefined || (request.runnerName ?? "playwright") === "playwright", {
+    message: "initialUrl opens a page in the runner's browser, so only the playwright runner takes it.",
+    path: ["initialUrl"]
   });
   const output = makeRunnerSchema().extend({
     alreadyRunning: boolean2().describe("True when a runner was already running under this id and was returned unchanged, so no second runner was started and nothing new is billed. Not an error either way."),
@@ -19476,7 +19629,7 @@ var makeLaunchRunnerContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: false
     },
-    description: "Launch an interactive runner on the caller's team under an id the caller chooses. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner — so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running — launching the same id again attaches to it. After a successful launch, put the exact returned `url` in a normal user-visible assistant message so they can watch while the browser is driven. Tool output and internal reasoning do not count as sharing the link. When `alreadyRunning` is true the `url` is the same page, so share it again instead of assuming the caller still has it.",
+    description: "Launch an interactive runner on the caller's team under an id the caller chooses. Send `initialUrl` so its browser comes up on the page the work starts from, which saves a separate navigation and the browser's cold start. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner, so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running, and launching the same id again attaches to it.",
     input,
     kind: "write",
     name: "runner.launch",
@@ -19522,7 +19675,7 @@ var makeListRunnersContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: true
     },
-    description: "List the runners running on the caller's team right now. A team API key already names the team and sends nothing; a credential bound to no single workspace names one in `workspaceId`. A runner that was terminated, or that terminated on its own after inactivity, is not listed, because the run system keeps no record of a runner once it is gone. 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. It is how to find a runner launched from another machine or in an earlier session, when the id it was launched under is no longer at hand.",
+    description: "List the runners running on the caller's team right now. A listed runner may be driven by another machine or session, so sending it work can collide with theirs. A runner that was terminated, or that terminated on its own after inactivity, is not listed, because the run system keeps no record of a runner once it is gone. 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. It is how to find a runner launched from another machine or in an earlier session, when the id it was launched under is no longer at hand.",
     input,
     kind: "read",
     name: "runner.list",
@@ -19607,6 +19760,7 @@ var makeRunFlowOnRunnerContract = (ids) => {
     env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run."),
     environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. Send this or `env`, not both."),
     files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
+    flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omit it when the flow is not in QA Wolf yet, and the run has no `QAWOLF_WORKFLOW_ID`."),
     id: runnerIdSchema.describe("Id of the runner to run the flow on."),
     selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
     unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
@@ -19858,6 +20012,7 @@ var makeContractsV1 = (ids) => {
       removeTag: makeRemoveTagFromFlowsContract(resolvedIds),
       update: makeUpdateFlowContract(resolvedIds)
     },
+    investigation: makeInvestigationContracts(resolvedIds),
     issue: {
       addFlows: makeAddFlowsToIssueContract(resolvedIds),
       create: makeCreateIssueContract(resolvedIds),
@@ -22390,7 +22545,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.34.0",
+  version: "1.35.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -22461,7 +22616,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.64.0",
+    "@qawolf/api-contracts": "0.70.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -38665,4 +38820,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=5DFA383F9EE30BDB64756E2164756E21
+//# debugId=DB32E61082C9C27564756E2164756E21

package/dist/runner-sdk.js

@@ -6998,7 +6998,7 @@ var agentSessionStatuses = [
   "failed",
   "cancelled"
 ];
-var agentSessionStatusSchema = _enum(agentSessionStatuses).describe('Where the work stands. "working" means the AI is still on it. "waiting-for-you" means it asked a question and cannot continue until agent.send answers it. "completed", "failed" and "cancelled" are settled and will not change.');
+var agentSessionStatusSchema = _enum(agentSessionStatuses).describe('Where the work stands. "working" means the AI is still on it. "waiting-for-you" means it asked a question and cannot continue until agent.send answers it. "completed" means it finished what it was asked, and a new agent.send continues it. "failed" and "cancelled" are settled and will not change.');
 var agentReplySchema = object({
   askedAt: exports_iso.datetime().describe("When the AI wrote this, as an ISO 8601 timestamp."),
   choices: array(string2()).optional().describe("The answers the AI offered, when the reply is a question with a fixed set of them. Answer by sending one of these back through agent.send."),
@@ -7177,7 +7177,7 @@ var defaultIdSchemas = {
   trigger: string2().min(1).describe("The id of the trigger."),
   workspace: string2().min(1).describe("The id of the workspace.")
 };
-var workspaceForEnvironmentRef = (workspace) => workspace.optional().describe("The workspace the environment belongs to. Required to reference the environment by alias when authenticating with an organization or user API key.");
+var workspaceForEnvironmentRef = (workspace) => workspace.optional().describe("The workspace the environment belongs to, which an alias resolves in. Read it from whoami.");
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/flowSelection.js
 var makeFlowSelectionSchema = (ids) => object({
@@ -7353,7 +7353,7 @@ var runnerNameSchema = _enum([
   "android",
   "ios"
 ]);
-var runnerWorkspaceRequirement = "Required when the credential is not bound to a single workspace, such as a user API key or an OAuth connection whose organization owns several.";
+var runnerWorkspaceRequirement = "Read it from whoami.";
 var runnerWorkspaceIdDescription = `The workspace the runner belongs to. ${runnerWorkspaceRequirement}`;
 var runnerIdSchema = string2().min(1).max(63).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "A runner id may contain only lowercase letters, digits and dashes, and must start and end with a letter or digit.");
 var runnerWatchUrlSchema = url().describe("A QA Wolf page showing what the runner is doing right now, where the person who launched it can watch and take over with their own mouse and keyboard. Opening it requires being signed in to QA Wolf. This link belongs to the user: put it in a normal message as soon as the runner is launched, so they can follow along while the browser is being driven. It is theirs to open, never a page for the caller to fetch or navigate to. The page ends when the runner is terminated, so share it while the runner is alive and report what you found at the end instead of repeating a dead link.");
@@ -7938,23 +7938,28 @@ var makeTriggerActionSchema = (ids) => object({
   instructions: string2().min(1).optional().describe("Guidance for QA Wolf. Applies to generativeSuite only."),
   investigateFailures: boolean2().optional().describe("Whether QA Wolf investigates failures in the resulting runs. Defaults to true."),
   kind: triggerActionKindSchema.default("createSuite"),
+  runConcurrencyLimit: string2().trim().min(1).max(255).optional().describe(`How many runs of the resulting suite may execute at once: a whole number from 1 to 1000, "unlimited", or a concurrency expression, which the server validates. It replaces the environment's limit rather than capping below it. Omit it to leave the environment's limit in charge.`),
   tagNames: array(string2().min(1)).default([]).describe("Tags naming the flows to run. Combined with flowIds.")
 }).describe("What the trigger runs when it fires.");
 var makeTriggerScheduleFields = (ids) => ({
   action: makeTriggerActionSchema(ids),
   cadence: triggerCadenceSchema,
   dayOfWeek: triggerDayOfWeekSchema.optional().describe("The day a weekly schedule fires on, read in timezoneId. Required when cadence is weekly."),
+  daysOfWeek: array(triggerDayOfWeekSchema).min(1).refine((daysOfWeek) => new Set(daysOfWeek).size === daysOfWeek.length, {
+    message: "Expected each day to be named at most once."
+  }).optional().describe("The only days an hourly or daily schedule fires on, read in timezoneId. Name each day at most once. Omitting it fires on every day."),
   environmentId: ids.environmentId.describe("The environment the scheduled runs happen in."),
   minuteOfHour: number2().int().min(0).max(59).optional().describe("Minutes past the hour an hourly schedule fires. Defaults to 0."),
   timeOfDay: string2().regex(/^([01]\d|2[0-3]):[0-5]\d$/).optional().describe('The wall clock time a daily or weekly schedule fires, as "HH:mm". Required when cadence is daily or weekly.'),
-  timezoneId: string2().min(1).refine(isTimezone, "Expected an IANA timezone, such as America/New_York.").optional().describe("The IANA timezone that timeOfDay is read in, such as America/New_York. Required when cadence is daily or weekly.")
+  timezoneId: string2().min(1).refine(isTimezone, "Expected an IANA timezone, such as America/New_York.").optional().describe("The IANA timezone the schedule is read in, such as America/New_York. Required when cadence is daily or weekly, and when an hourly schedule names daysOfWeek, whose day boundaries it sets. An hourly schedule firing on every day needs none, and is read in America/Los_Angeles.")
 });
 var makeTriggerDeploymentFields = (ids) => ({
   action: makeTriggerActionSchema(ids),
   branchPattern: string2().min(1).optional().describe("Only fire for deployments of a branch matching this pattern."),
-  deployTargetPattern: string2().min(1).optional().describe("Only fire for deployments of an app matching this pattern. A deploy target names one app within an environment."),
+  deployTargetPattern: string2().min(1).optional().describe("Only fire for deployments whose deploy target matches this pattern. A deploy target is the URL or label the deploy reported, which many deployments do not carry."),
   environmentIds: array(ids.environment).default([]).describe("Only fire for deployments to these environments. Mutually exclusive with environmentPattern."),
-  environmentPattern: string2().min(1).optional().describe("Only fire for deployments to environments matching this pattern. Mutually exclusive with environmentIds.")
+  environmentPattern: string2().min(1).optional().describe("Only fire for deployments to environments matching this pattern. Mutually exclusive with environmentIds."),
+  servicePattern: string2().min(1).optional().describe("Only fire for deployments whose service matches this pattern. A deployment that names no service never matches it.")
 });
 
 // node_modules/@qawolf/api-contracts/dist/v1/trigger/configurationRules.js
@@ -7990,20 +7995,28 @@ var requiredScheduleFields = {
   hourly: [],
   weekly: ["dayOfWeek", "timeOfDay", "timezoneId"]
 };
+var optionalScheduleFields = {
+  daily: ["daysOfWeek"],
+  hourly: ["daysOfWeek", "minuteOfHour", "timezoneId"],
+  weekly: []
+};
 var cadencesUsingField = {
   dayOfWeek: "a weekly cadence",
+  daysOfWeek: "an hourly or daily cadence",
   minuteOfHour: "an hourly cadence",
   timeOfDay: "a daily or weekly cadence",
-  timezoneId: "a daily or weekly cadence"
+  timezoneId: "an hourly, daily or weekly cadence"
 };
 var scheduleFields = [
   "dayOfWeek",
+  "daysOfWeek",
   "minuteOfHour",
   "timeOfDay",
   "timezoneId"
 ];
 var checkScheduleFields = (value, ctx) => {
   const required = requiredScheduleFields[value.cadence];
+  const optional = optionalScheduleFields[value.cadence];
   for (const field of scheduleFields) {
     const isSupplied = value[field] !== undefined;
     if (required.includes(field)) {
@@ -8016,7 +8029,7 @@ var checkScheduleFields = (value, ctx) => {
       }
       continue;
     }
-    if (isSupplied && !(value.cadence === "hourly" && field === "minuteOfHour")) {
+    if (isSupplied && !optional.includes(field)) {
       ctx.addIssue({
         code: "custom",
         message: `${field} applies to ${cadencesUsingField[field]} only.`,
@@ -8025,8 +8038,18 @@ var checkScheduleFields = (value, ctx) => {
     }
   }
 };
+var checkHourlyZone = (value, ctx) => {
+  if (value.cadence !== "hourly" || value.daysOfWeek === undefined || value.timezoneId !== undefined)
+    return;
+  ctx.addIssue({
+    code: "custom",
+    message: "timezoneId is required when an hourly cadence names daysOfWeek.",
+    path: ["timezoneId"]
+  });
+};
 var checkSchedule = (value, ctx) => {
   checkScheduleFields(value, ctx);
+  checkHourlyZone(value, ctx);
   if (value.action.kind === "generativeSuite") {
     ctx.addIssue({
       code: "custom",
@@ -8392,12 +8415,14 @@ var makeDeploymentResourceSchema = (ids) => resource({
   commitAuthorName: string2().optional().describe("The author of the deployed commit."),
   commitMessage: string2().optional().describe("The message of the deployed commit."),
   commitSha: string2().optional().describe("The sha of the deployed commit."),
+  commitUrl: string2().optional().describe("A link to the deployed commit, as declared by the deployment report."),
   deployedAt: exports_iso.datetime().describe("When QA Wolf first received the deployment."),
   deployTarget: string2().optional().describe("Identifies the deployed app within the environment: the URL it serves, or the build path of a mobile build. A trigger's deployTargetPattern matches against it."),
   environmentId: ids.environment.describe("The QA Wolf environment the deployment reported into."),
   environmentName: string2().optional().describe("The environment's name. Absent when the environment has since been deleted."),
   id: ids.deployment,
   provider: _enum(["github", "gitlab", "api"]).optional().describe("How QA Wolf received the deployment: a GitHub webhook, a GitLab webhook, or the deployment.reportStatus API."),
+  service: string2().optional().describe("Which application was deployed, as the deployer named it. Absent when the deployer named none."),
   status: _enum(["pending", "success", "failure", "inactive"]).optional().describe("The deployment's lifecycle status, in the vocabulary deployment.reportStatus accepts. Absent when no status was ever reported.")
 }, {
   urlFieldDescription: "Absolute URL of the workspace's deployments page."
@@ -8427,8 +8452,55 @@ var makeFindDeploymentsContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/deployment/didNotRunReason.js
+var didNotRunReasonSchema = _enum([
+  "billing-prevented",
+  "branch-still-syncing",
+  "deployment-no-longer-live",
+  "duplicate-run",
+  "environment-not-linked-to-branch",
+  "environment-not-ready",
+  "environment-terminated",
+  "internal-error",
+  "low-risk-change",
+  "no-flows-to-run",
+  "no-matching-trigger",
+  "no-pull-request",
+  "no-relevant-flows",
+  "rate-limited",
+  "run-not-created",
+  "skipped",
+  "test-configuration-error",
+  "trigger-not-found",
+  "workspace-inactive",
+  "workspace-not-ready"
+]).describe([
+  "Why the matched trigger created no run, as a stable value safe to branch on in a CI pipeline. The accompanying `message` is the wording for a person to read and may be reworded at any time; this value will not be.",
+  "billing-prevented: a billing restriction on the workspace stopped the run.",
+  "branch-still-syncing: the environment was still syncing its flows.",
+  "deployment-no-longer-live: the deployment was torn down or replaced by a newer one before the run started.",
+  "duplicate-run: another run already covered this same deployment.",
+  "environment-not-linked-to-branch: the environment has no branch to take flows from yet.",
+  "environment-not-ready: the environment was still being prepared; retrying later can succeed.",
+  "environment-terminated: the environment for the run is terminated.",
+  "internal-error: QA Wolf could not start the run and the cause is on our side.",
+  "low-risk-change: adaptive flow selection assessed the change as low risk, so nothing needed to run.",
+  "no-flows-to-run: no flow was eligible, because the trigger's flows are in maintenance, still drafts, or missing on this branch.",
+  "no-matching-trigger: no deployment trigger matched.",
+  "no-pull-request: the trigger uses adaptive flow selection, which needs an open pull request, and this deployment had none.",
+  "no-relevant-flows: adaptive flow selection found no existing flow covering this change.",
+  "rate-limited: too many runs were requested at once; retrying later can succeed.",
+  "run-not-created: the run never reached a decision.",
+  "skipped: the run was skipped for a reason with no more specific value.",
+  "test-configuration-error: the workspace's flows or dependency rules need fixing before this can run.",
+  "trigger-not-found: the trigger no longer exists.",
+  "workspace-inactive: the workspace is not active.",
+  "workspace-not-ready: the workspace has not finished setting up."
+].join(`
+`));
+
 // node_modules/@qawolf/api-contracts/dist/v1/deployment/listTriggerEvaluations.js
-var conditionKindSchema = _enum(["environment", "deployTarget", "branch"]).describe("What the condition checks on the deployment: the environment it reported into, the deploy target identifying the deployed app, or the git branch of the deployed commit.");
+var conditionKindSchema = _enum(["environment", "deployTarget", "branch", "service"]).describe("What the condition checks on the deployment: the environment it reported into, the deploy target it serves, the git branch of the deployed commit, or the service it deployed.");
 var conditionVerdictSchema = discriminatedUnion("outcome", [
   object({
     kind: conditionKindSchema,
@@ -8451,12 +8523,13 @@ var makeRunOutcomeSchema = (ids) => discriminatedUnion("status", [
   }),
   object({ status: literal("starting") }),
   object({
-    reason: string2().describe("Why the matched trigger created no run, in plain language."),
+    message: string2().describe("Why the matched trigger created no run, in plain language."),
+    reason: didNotRunReasonSchema,
     status: literal("did-not-run"),
     supersededByRunId: ids.run.optional().describe("The run that covered this deployment instead, when an earlier delivery of the same deployment had already created one.")
   }),
   object({ status: literal("unknown") })
-]).describe("What became of the match. Matching is not running: a matched trigger can still be stopped from creating a run, and did-not-run carries the reason. starting means run creation is still in progress; unknown means QA Wolf has no record of what followed the match.");
+]).describe("What became of the match. Matching is not running: a matched trigger can still be stopped from creating a run, and did-not-run carries the reason. starting means run creation is still in progress; unknown means QA Wolf has no record of what followed the match. did-not-run also carries a stable reason to branch on, beside the message for a person to read.");
 var makeVerdictSchema = (ids) => discriminatedUnion("outcome", [
   object({
     conditionSets: conditionSetsField,
@@ -8505,6 +8578,7 @@ var deploymentReportMetadata = strictObject({
   commitAuthorName: string2().trim().min(1).max(255).describe("The display name of the person who authored the deployed commit.").optional(),
   commitMessage: string2().trim().min(1).max(2048).describe("The message of the deployed commit. The deployments list shows its first line.").optional(),
   commitSha: string2().trim().min(1).max(255).describe("The commit sha of the deployed application revision.").optional(),
+  commitUrl: httpUrl().max(2048).describe("A link to the deployed commit in your code host. Send this when QA Wolf cannot resolve the commit itself, for example when the QA Wolf GitHub App is not installed.").optional(),
   pullRequestNumber: number2().int().positive().describe("The number of the pull request the deployment belongs to. Requires repository.").optional(),
   ref: string2().trim().min(1).max(255).describe("The branch or ref that was deployed.").optional(),
   repository: string2().trim().min(1).max(255).describe('The owner/name of the repository, e.g. "acme/web".').optional()
@@ -8539,6 +8613,7 @@ var makeReportDeploymentStatusContract = (ids) => {
     environmentVariables: record(string2(), string2()).describe("Environment variable overrides for the runs this deployment requests. A report that omits this field keeps the stored values. A report that sends it replaces them.").optional(),
     metadata: deploymentReportMetadata.describe("Details the deployer declares about the deployed revision; a code host integration's own record of the same commit is shown in preference to the message and author declared here.").optional(),
     providerDeploymentId: string2().trim().min(1).max(255).describe('Your identifier for the deployment, e.g. "vercel_dpl_123". Reports with the same providerDeploymentId update one deployment within this workspace.'),
+    service: string2().trim().min(1).max(255).describe('Which application was deployed, e.g. "checkout-api", when several services deploy into one environment. A report that omits it keeps the stored value.').optional(),
     status: deploymentStatusSchema.describe("The deployment lifecycle status. A deployment's first success report evaluates global triggers asynchronously, and it is the only report that does. The response does not include the resulting runs."),
     workspaceId: ids.workspace.describe("The workspace to report the deployment status into. A team API key must name its own workspace.")
   }).superRefine((value, context) => {
@@ -9209,6 +9284,70 @@ var makeGetIssueContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/investigation/finding.js
+var investigationFindingStateDescription = 'What the investigation concluded about the cause. Known values: "investigating", "fixed", "fix-proposed", "reported", "report-proposed", "flake", "question" and "dismissed". New values can appear.';
+var makeInvestigationFindingSchema = (ids) => object({
+  actual: string2().optional(),
+  commitHash: string2().optional(),
+  decidedBy: _enum(["agent", "user"]).optional().describe("Who decided: the AI on its own, or a person who approved or dismissed it. Absent until someone decides."),
+  disputeReason: string2().optional().describe("Why a person disputed what the AI did. Present on a proposal the AI made again after that dispute."),
+  expected: string2().optional(),
+  findingId: string2(),
+  flowIds: array(ids.flow),
+  headline: string2().optional(),
+  issueId: ids.issue.optional(),
+  kind: string2().describe('What the failure is. Known values: "maintenance", "bug", "flake" and "unknown". New values can appear.'),
+  matchReason: string2().optional(),
+  priority: issuePrioritySchema.optional(),
+  question: object({
+    answers: array(object({
+      description: string2().optional(),
+      title: string2(),
+      value: string2().describe('What choosing this answer means. Known values: "apply", "dismiss", "report", "maintenance" and "bug". New values can appear.')
+    })),
+    text: string2()
+  }).optional().describe("The question waiting for a person, with the answers offered."),
+  response: object({
+    answer: string2().optional(),
+    at: exports_iso.datetime(),
+    reason: string2().optional(),
+    type: string2().describe('Known values: "answer" and "dispute". New values can appear.')
+  }).optional().describe("A person's answer or dispute that the investigation hasn't acted on yet."),
+  state: string2().describe(investigationFindingStateDescription),
+  steps: array(string2()).optional(),
+  subSessionIds: array(ids.chatSession),
+  summary: string2().optional(),
+  updatedAt: exports_iso.datetime()
+});
+
+// node_modules/@qawolf/api-contracts/dist/v1/investigation/get.js
+var makeGetInvestigationContract = (ids) => {
+  const input = object({ runId: ids.run });
+  const output = resource({
+    findings: array(makeInvestigationFindingSchema(ids)),
+    runId: ids.run,
+    sessionId: ids.chatSession.optional().describe("The investigation session. Absent when the run has none."),
+    status: _enum(["investigating", "finished", "not-investigated"]).describe('Whether the investigation session is still working. "not-investigated" when the run has no investigation.')
+  }, { urlFieldDescription: "The run in the QA Wolf app." });
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: "Read what the QA Wolf AI investigating a run has concluded: one finding per cause of its failures, " + "with the question waiting for a person and any answer or dispute the investigation hasn't acted on yet.",
+    input,
+    kind: "read",
+    name: "investigation.get",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/investigation/index.js
+var makeInvestigationContracts = (ids) => ({
+  get: makeGetInvestigationContract(ids)
+});
+
 // node_modules/@qawolf/api-contracts/dist/v1/issue/addFlows.js
 var makeAddFlowsToIssueContract = (ids) => {
   const input = object({
@@ -9466,6 +9605,13 @@ var makeDiagnoseRunContract = (ids) => {
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/summary.js
+var publicRunStatusValues = [
+  "queued",
+  "running",
+  "passed",
+  "failed",
+  "canceled"
+];
 var makeRunSummaryFields = (ids) => ({
   completedAt: exports_iso.datetime().optional().describe("When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped)."),
   createdAt: exports_iso.datetime(),
@@ -9476,7 +9622,7 @@ var makeRunSummaryFields = (ids) => ({
     commitUrl: string2().optional().describe("Link to the commit on the code host.")
   }).describe("The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create."),
   runId: ids.run,
-  status: _enum(["queued", "running", "passed", "failed", "canceled"]).describe("Whole-run status. Terminal statuses are passed, failed, and canceled; poll until one is reached.")
+  status: _enum(publicRunStatusValues).describe("Whole-run status, and the value to gate a pipeline on. Terminal statuses are passed, failed, and canceled; poll until one is reached. `failed` means the run found a bug that is still open and serious enough to block — a lower-priority bug, or one since resolved, reads `passed`, and the per-flow diagnoses are still in `flows`. The run stays `running` while any investigation is unresolved, including one that carried over to a later run, so a terminal status always means a settled answer.")
 });
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/find.js
@@ -9509,7 +9655,9 @@ var makeFindRunsContract = (ids) => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/run/get.js
 var makeGetRunContract = (ids) => {
+  const flowStatus = _enum(publicRunStatusValues);
   const input = object({
+    flowStatuses: array(flowStatus).min(1).optional().describe("Return only the flows whose status is one of these. A suite run can " + "hold hundreds of flows, so start an investigation with failed " + "alone. A flow that passed after a retry reads passed, so add " + "passed when a flaky flow is missing from the answer. Omit to " + "return every flow. The run-level fields are unaffected."),
     runId: ids.run
   });
   const artifactUrls = {
@@ -9566,11 +9714,12 @@ var makeGetRunContract = (ids) => {
     attempts,
     flowId: ids.flow,
     name: string2(),
-    status: _enum(["queued", "running", "passed", "canceled"])
+    status: flowStatus.exclude(["failed"])
   });
-  const flows = array(discriminatedUnion("status", [failedFlow, nonFailedFlow])).describe("The run's flows, ordered alphabetically by name.");
+  const flows = array(discriminatedUnion("status", [failedFlow, nonFailedFlow])).describe("The run's flows, ordered alphabetically by name. Only the flows " + "matching flowStatuses when the request set it.");
   const output = resource({
     ...makeRunSummaryFields(ids),
+    blockingBugCount: number2().int().nonnegative().describe("How many bugs this run found are blocking: still open, and priority urgent, high, or unprioritized — unprioritized counts because nobody has ruled it out yet. This is what `failed` is derived from, so it explains a failure rather than adding a second verdict: gate on `status`, then read this to say how many bugs are holding the build. It counts a bug filed against a later run by an investigation that carried over from this one, and it drops a bug once that bug is resolved."),
     flows,
     runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.")
   }, { urlFieldDescription: "Absolute URL of the run page." });
@@ -9580,7 +9729,7 @@ var makeGetRunContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: true
     },
-    description: "Get a run's status, per-flow results, and links.",
+    description: "Get a run's status, per-flow results, links, and how many of its bugs are blocking.",
     input,
     kind: "read",
     name: "run.get",
@@ -9832,8 +9981,12 @@ var makeImportPackageOnRunnerContract = (ids) => {
 var makeLaunchRunnerContract = (ids) => {
   const input = object({
     id: runnerIdSchema.describe("Id to launch the runner under, chosen by the caller. Launching the same id again returns the runner already running under it."),
+    initialUrl: navigableUrlSchema.optional().describe("The page to open as the browser starts, so the first screenshot already shows the application rather than a blank page."),
     runnerName: runnerNameSchema.optional().describe("The runner family to launch. Defaults to the standard web family, playwright."),
     workspaceId: ids.workspace.optional().describe(`The workspace to launch the runner in. ${runnerWorkspaceRequirement}`)
+  }).refine((request) => request.initialUrl === undefined || (request.runnerName ?? "playwright") === "playwright", {
+    message: "initialUrl opens a page in the runner's browser, so only the playwright runner takes it.",
+    path: ["initialUrl"]
   });
   const output = makeRunnerSchema().extend({
     alreadyRunning: boolean2().describe("True when a runner was already running under this id and was returned unchanged, so no second runner was started and nothing new is billed. Not an error either way."),
@@ -9845,7 +9998,7 @@ var makeLaunchRunnerContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: false
     },
-    description: "Launch an interactive runner on the caller's team under an id the caller chooses. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner — so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running — launching the same id again attaches to it. After a successful launch, put the exact returned `url` in a normal user-visible assistant message so they can watch while the browser is driven. Tool output and internal reasoning do not count as sharing the link. When `alreadyRunning` is true the `url` is the same page, so share it again instead of assuming the caller still has it.",
+    description: "Launch an interactive runner on the caller's team under an id the caller chooses. Send `initialUrl` so its browser comes up on the page the work starts from, which saves a separate navigation and the browser's cold start. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner, so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running, and launching the same id again attaches to it.",
     input,
     kind: "write",
     name: "runner.launch",
@@ -9891,7 +10044,7 @@ var makeListRunnersContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: true
     },
-    description: "List the runners running on the caller's team right now. A team API key already names the team and sends nothing; a credential bound to no single workspace names one in `workspaceId`. A runner that was terminated, or that terminated on its own after inactivity, is not listed, because the run system keeps no record of a runner once it is gone. 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. It is how to find a runner launched from another machine or in an earlier session, when the id it was launched under is no longer at hand.",
+    description: "List the runners running on the caller's team right now. A listed runner may be driven by another machine or session, so sending it work can collide with theirs. A runner that was terminated, or that terminated on its own after inactivity, is not listed, because the run system keeps no record of a runner once it is gone. 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. It is how to find a runner launched from another machine or in an earlier session, when the id it was launched under is no longer at hand.",
     input,
     kind: "read",
     name: "runner.list",
@@ -9976,6 +10129,7 @@ var makeRunFlowOnRunnerContract = (ids) => {
     env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run."),
     environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. Send this or `env`, not both."),
     files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
+    flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omit it when the flow is not in QA Wolf yet, and the run has no `QAWOLF_WORKFLOW_ID`."),
     id: runnerIdSchema.describe("Id of the runner to run the flow on."),
     selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
     unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
@@ -10227,6 +10381,7 @@ var makeContractsV1 = (ids) => {
       removeTag: makeRemoveTagFromFlowsContract(resolvedIds),
       update: makeUpdateFlowContract(resolvedIds)
     },
+    investigation: makeInvestigationContracts(resolvedIds),
     issue: {
       addFlows: makeAddFlowsToIssueContract(resolvedIds),
       create: makeCreateIssueContract(resolvedIds),
@@ -14876,4 +15031,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=A7A37F8150999CFE64756E2164756E21
+//# debugId=CF6139275CB5B8DC64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -71,7 +71,7 @@
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.64.0",
+    "@qawolf/api-contracts": "0.70.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -76,7 +76,9 @@ sequence, omit it when you want the payloads themselves.
 
 A `--json` response shows you most of its own shape, so read it first.
 
-`qawolf run get` is the exception worth reading about before you use it. Its
+`qawolf run get` is the exception worth reading about before you use it. A
+suite run can hold hundreds of flows, so start with
+`--flow-statuses failed` and widen only if you need the rest. Its
 artifact URLs expire, its failure fields are absent from a passing run, and its
 `traceUrl` downloads a Playwright trace that you can read as JSON without
 opening the trace viewer. **Read
@@ -164,6 +166,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf install android` | local | Install Android system images, AVDs, and the Appium driver used by the project's Android flows |
 | `qawolf install browsers` | local | Install Playwright browsers used by the project's web flows |
 | `qawolf install clear` | local | Remove the managed runtime cache (all installed runtime versions) |
+| `qawolf investigation get` | read | Read what the QA Wolf AI investigating a run has concluded: one finding per cause of its failures, with the question waiting for a person and any answer or dispute the investigation hasn't acted on yet. |
 | `qawolf issue addFlows` | write | Add flows to a coverage request owned by the caller's team. Flows already covered stay covered. Bug and maintenance reports link to flows through the runs that reproduce them; use run.diagnose to record one. |
 | `qawolf issue create` | write | Create a bug or coverage request issue for the caller's team. Maintenance issues cannot be created through the public API. |
 | `qawolf issue find` | read | List the team's bug reports, maintenance reports, or coverage requests, newest first. |
@@ -176,7 +179,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf run create` | write | Create a run for the selected flows and/or tags in an environment. |
 | `qawolf run diagnose` | write | Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. The issue's type selects the diagnosis. Each flow must have failed in the run. A flow that is already diagnosed moves to this issue. The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead. |
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
-| `qawolf run get` | read | Get a run's status, per-flow results, and links. |
+| `qawolf run get` | read | Get a run's status, per-flow results, links, and how many of its bugs are blocking. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
 | `qawolf run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous and can update run-status messages and commit statuses in connected integrations. Repeated requests are safe, and finished runs keep their results. A run that is still being created returns not found; retry once run.get returns the run. If run.get returns a different runId, use that ID. Poll run.get for results. |
 | `qawolf run triage` | read | Prototype. Ask Jev, a TypeSafe System One model, whether a flow failure in a run is a bug in the product or a test that needs maintenance. Compares the failing attempt with the flow's last passing run in the same environment. Records nothing. |

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

@@ -8,6 +8,32 @@ this file for the parts a single response cannot show you: fields that appear
 only when something fails, rules about the artifact URLs, and how to read a
 trace without opening the trace viewer.
 
+## Start with the failed flows
+
+A run of a whole suite can hold hundreds of flows, and the full response then
+runs to hundreds of kilobytes: more than a shell shows you, and more than any
+investigation needs. The interesting part is a handful of failed flows, so ask
+for those first:
+
+```bash
+qawolf run get --run-id "$RUN_ID" --flow-statuses failed --json
+```
+
+`--flow-statuses` takes one or more of `queued`, `running`, `passed`, `failed`
+and `canceled`, separated by spaces (`--flow-statuses failed canceled`), and
+keeps only the flows whose status matches. The run-level fields (`status`,
+`blockingBugCount`, `git`, `url`) still describe the whole run, so a filtered
+read tells you both how the run went and which flows to look at. Widen the
+filter, or drop it, only when you need the other flows too.
+
+A flow that failed and then passed on a retry has status `passed`, so a
+`failed`-only read leaves it out. If the flow you were asked about passed on a
+retry, add `passed` to the filter and read its earlier attempts. For a flow
+that is still queued, running or was canceled, widen the filter or drop it.
+
+Do not save the full response to a file and script over it to find the failed
+flows. The filter answers that in one call.
+
 ## The shape
 
 A run holds flows, a flow holds attempts, and artifacts hang off an attempt:
@@ -63,7 +89,7 @@ recording) and `traceUrl` (a Playwright `trace.zip`).
    authentication header is needed and no QA Wolf credentials are involved.
 
 ```bash
-qawolf run get --run-id "$RUN_ID" --json \
+qawolf run get --run-id "$RUN_ID" --flow-statuses failed --json \
   | jq -r '.flows[].attempts[-1].traceUrl // empty' \
   | head -1 \
   | xargs -r curl -sS -o trace.zip
@@ -159,7 +185,8 @@ Every documented field of the `run.get` response. `[]` marks an array, so
 - `git.commitUrl` — Link to the commit on the code host.
 - `runId` — The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.
 - `status` — One of: queued, running, passed, failed, canceled
-- `flows` — The run's flows, ordered alphabetically by name.
+- `blockingBugCount` — How many bugs this run found are blocking: still open, and priority urgent, high, or unprioritized — unprioritized counts because nobody has ruled it out yet. This is what `failed` is derived from, so it explains a failure rather than adding a second verdict: gate on `status`, then read this to say how many bugs are holding the build. It counts a bug filed against a later run by an investigation that carried over from this one, and it drops a bug once that bug is resolved.
+- `flows` — The run's flows, ordered alphabetically by name. Only the flows matching flowStatuses when the request set it.
 - `flows[].attempts` — The flow's finished execution attempts, oldest first, including manual Wolf Browser attempts. Present once at least one attempt has finished, so a flow that passed after retries also lists its failed attempts. Artifact URLs appear only on automated attempts that reached a verdict, stay valid for at least a day (call run.get again for fresh ones), and can return 404 when the attempt did not produce that artifact.
 - `flows[].attempts[].logsUrl` — Signed URL for the attempt's execution logs.
 - `flows[].attempts[].traceUrl` — Signed URL for the attempt's Playwright trace (a trace.zip; open it with `npx playwright show-trace`).