@skyramp/mcp 0.4.4 → 0.5.0-rc.10

package/build/tools/generate-tests/generateUILoadRestTool.js

@@ -1,9 +1,12 @@
 import { SkyrampClient } from "@skyramp/skyramp";
 import { z } from "zod";
-import { existsSync, readFileSync } from "fs";
+import semver from "semver";
+import { appendFileSync, copyFileSync, existsSync, readFileSync } from "fs";
+import * as path from "path";
 import { ProgrammingLanguage } from "../../types/TestTypes.js";
 import { toolError, validatePath } from "../../utils/utils.js";
 import { logger } from "../../utils/logger.js";
+import { SKYRAMP_SDK_VERSION } from "../../utils/skyrampSdkVersion.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { generatedFilesFrom } from "../../services/TestGenerationService.js";
 import { getTestsRepoDir } from "../../utils/AnalysisStateManager.js";
@@ -12,6 +15,7 @@ import { resolveOutputDir, stageGeneratedPaths, } from "../../utils/gitStaging.j
 import { normalizeLanguageParams } from "../../utils/normalizeParams.js";
 import { getEntryPoint } from "../../utils/telemetry.js";
 import { checkTraceReuse, recordTraceOutput } from "./trace-reuse-guard.js";
+import { limitConfirmationToken, readFleetFileLimits, } from "../../services/fleetLimitConfirmation.js";
 const TOOL_NAME = "skyramp_ui_load_test_generation";
 /**
  * Language and framework in the spelling the generator takes. Done in the SCHEMA rather than
@@ -83,8 +87,9 @@ export const uiLoadTestSchema = {
             .string()
             .default("")
             .describe("Remote Docker Engine where the worker for this host is deployed, e.g. " +
-            '"tcp://10.0.1.11:2376". Empty means the local/default Docker context, which ' +
-            "skyramp_execute_fleet cannot run: run such a fleet on the host instead."),
+            '"tcp://10.0.1.11:2376". Empty means the local Docker daemon: the worker is ' +
+            "deployed on this machine and no certificates are needed, which is how to try a " +
+            "fleet before pointing it at regions."),
         tls: z
             .string()
             .default("")
@@ -122,6 +127,14 @@ export const uiLoadTestSchema = {
             .default("")
             .describe("Tag for workerImage. Empty uses the library's default. skyramp_execute_fleet " +
             "refuses a fleet that sets it: run such a fleet on the host."),
+        browserSessions: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Browser sessions this host runs, fixed. 0 (the default) sizes it from the host's " +
+            "CPU cores (see coresPerBrowser). Java, python, typescript and javascript. Set it when the user names a browser " +
+            'count per host ("4 browsers on each host").'),
     }))
         .min(1)
         // The fleet runner's own rules (pkg/fleet/runner.go validate), applied here so a host
@@ -161,17 +174,6 @@ export const uiLoadTestSchema = {
         .describe("The load-generating hosts to fan the journey across, one entry per VM or region. " +
         "Each becomes an inline Host(...) in the generated fleet manager. Ask the user which " +
         "regions they want to drive load from; at least one is required."),
-    browserCoverage: z
-        .number()
-        // Strictly inside 0..1, not inclusive: ui-load always emits BOTH halves, and the fleet
-        // refuses a run carrying both unless the virtual users actually divide between them. 0
-        // gives each half the full count; 1 leaves the protocol half none.
-        .gt(0)
-        .lt(1)
-        .default(0.1)
-        .describe("Fraction of the run executed in REAL browsers, strictly between 0 and 1; the rest " +
-        "runs as the cheaper protocol load. Default 0.1. Raise toward 1 for browser " +
-        "fidelity, lower for mostly protocol load. Do NOT assume a non-default value."),
     loadDuration: z
         .number()
         .int()
@@ -185,9 +187,11 @@ export const uiLoadTestSchema = {
         .positive()
         // 2, not 1: both halves always ship, so the smallest honest run is one user in each.
         .default(2)
-        .describe("Total virtual users (default 2), split between the browser and protocol halves by " +
-        "browserCoverage and then across the hosts. Must be large enough to give every " +
-        "host at least one user in each half; a smaller count is refused with the minimum."),
+        .describe('Total user sessions (default 2), the number the user asks for ("100 users"). The ' +
+        "fleet splits them by host capacity: each host runs as many real-browser sessions " +
+        "as it can carry and protocol users for the rest of its share, so the run provisions " +
+        "exactly this many. Capacity follows pacing: one browser per CPU core when " +
+        "loadTargetRPS is set, a quarter of the cores when it is not. At least one per host."),
     loadCount: z
         .number()
         .int()
@@ -199,7 +203,18 @@ export const uiLoadTestSchema = {
         .int()
         .nonnegative()
         .default(0)
-        .describe("Target requests per second. 0 means as fast as the virtual users go."),
+        .describe("Pace for the protocol users, in scenario iterations per second for the whole run " +
+        "(one iteration replays every recorded request once). 0 means as fast as the " +
+        "application answers, which takes most of each host's CPU and leaves the browsers " +
+        "one per four cores. Set it when the user asks for a rate or wants browser timings " +
+        "that describe the application rather than the test machine."),
+    coresPerBrowser: z
+        .number()
+        .positive()
+        .optional()
+        .describe("CPU cores given to each browser session when the fleet sizes a host's browser " +
+        "capacity, e.g. 1 for one browser per core or 0.5 for two. Omit it and capacity " +
+        "follows pacing (1 when loadTargetRPS is set, 4 when not). Java, python, typescript and javascript."),
     loadRampupDuration: z
         .number()
         .int()
@@ -212,6 +227,44 @@ export const uiLoadTestSchema = {
         .nonnegative()
         .default(0)
         .describe("Seconds between ramp-up steps."),
+    limits: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Performance pass conditions, validated by the native KPI parser. Read " +
+        "skyramp_kpi_catalog first for native names, units, scopes and site defaults. " +
+        "Syntax: '<kpi>[{scope}] [<agg>] <op> <value> [fail|warn] [for <duration>] [stop]'; " +
+        "'for' holds a breach for that long during the run before it trips, 'stop' ends the " +
+        "run when a fail limit trips. Examples: 'backend_latency p95 < 1500ms fail', " +
+        "'backend_latency p95 < 1200ms warn for 60s', 'error_rate < 5% fail for 30s stop', " +
+        "'lcp{region:eu-west} p90 < 2500ms fail'. " +
+        "KPIs: 'the slowest 5% of API calls', 'p95', '95th percentile' -> backend_latency p95; " +
+        "'API calls', 'requests', 'the backend' (latency) -> backend_latency; " +
+        "'pages render/load in', 'page load' -> lcp p90; 'responsiveness', 'interaction' -> " +
+        "inp p90; 'layout shift', 'jumpy' -> cls p90; 'errors', 'error rate', 'failed " +
+        "requests' -> error_rate; 'journeys don't finish', 'complete', 'success' -> " +
+        "journey_success (a minimum rate, >=). ttfb is not a catalogue entry: ASK, offering " +
+        "backend_latency or lcp, rather than substitute silently. " +
+        "PASS condition: 'go over/exceed/more than X' -> <= X (fail is strictly > X); " +
+        "'within X' -> <= X (inclusive); 'under/less than X' -> < X (exclusive); " +
+        "'at least X%' -> >= X%. Units: '1.5 seconds' -> 1500ms, 'two seconds' -> 2000ms, " +
+        "'2%' -> 2% (0.02), '99%' -> 99% (0.99). " +
+        "Severity: 'fail', 'fail the build', 'the run must' -> fail (the default); 'warn', " +
+        "'tell me', 'flag', 'let me know', 'heading there' -> warn ('flag' always means warn). " +
+        "Holds: 'for more than a minute' -> for 60s; 'for half a minute' -> for 30s; a bare " +
+        "'warn if X hits Y' uses a 60s warning hold (echo it explicitly); 'a single bad spike " +
+        "is fine' needs a for: ASK for the duration if none is given. " +
+        "Stop: 'end the run when'/'stop when' -> append stop, with a 30s hold when none is " +
+        "given (echo it). Only fail limits can stop: if the user asks to warn AND stop, ASK " +
+        "whether they mean fail+stop instead. 'don't stop the run' never gets stop. " +
+        "Scopes: 'in the UK' -> {region:uk}; a host by name -> {host:name}; the region or " +
+        "host must exist in the run, ASK if it does not. " +
+        "ASK, do not guess, when a unit is ambiguous or limits on one KPI/scope contradict " +
+        "(e.g. < 1000ms and > 2000ms). " +
+        "Translate to pass conditions; do not invent units, durations or unknown scopes. " +
+        "Omit when the user states none: no default limits are added — site defaults are " +
+        "'suggested, NOT applied', offer them but add only if asked. Echo the normalized " +
+        "limits this tool returns (scope, severity, hold) and WAIT for user confirmation " +
+        "before passing confirmationToken to skyramp_start_fleet or skyramp_execute_fleet."),
     thresholds: z
         .string()
         .default("")
@@ -241,6 +294,13 @@ export const uiLoadTestSchema = {
         .string()
         .min(1)
         .describe("Absolute path to the directory the three files are written to."),
+    credentialsFile: z
+        .string()
+        .optional()
+        .describe("Absolute path to the credential pool (CSV with a `token` column, or `username,password`) " +
+        "the fleet hands its virtual users. Copied next to the generated files as " +
+        "credentials.csv, where the generated fleet reads it. Default: a credentials.csv " +
+        "beside playwrightStoragePath."),
     allowTraceReuse: z
         .boolean()
         .default(false)
@@ -255,29 +315,95 @@ export const uiLoadTestSchema = {
         .describe("Overwrite existing files with the same names (default true). Set false to keep " +
         "files that are already there."),
 };
+/**
+ * The first @skyramp/skyramp release whose native fleet runner sizes `browserCoverage: 0`
+ * by host capacity and reads a `{hosts, coresPerBrowser}` envelope. Both changed meaning
+ * from the released sizing model (0 used to mean "give each half the full count", and
+ * hosts was always an array), entirely on the native side: the JS wrapper forwards either
+ * shape unchanged, so unlike playwrightStorage there is no source text to detect the
+ * capability from, only the version this code was written against.
+ */
+const MIN_SIZING_SDK_VERSION = "1.3.50";
 /** The line the generator prints for each file it writes. */
 const GENERATED_FILES_LINE = /Successfully generated\/updated tests? files?:/i;
+/** The generated fleet manager, named as skyramp_execute_fleet discovers it. */
+const FLEET_MANAGER_FILE = /(FleetTest\.java|_fleet\.(py|ts|js))$/;
 /**
- * The smallest virtual-user count, at or above `threads`, that gives every host at least
- * one user in each half -- or null when `threads` already does.
- *
- * Mirrors the fleet (pkg/fleet/runner.go): browserShare splits the total between the halves,
- * rounding the browser slice to nearest and flooring it at 1, and splitShare then divides
- * each half across the hosts, which this tool always weights equally. The worker runs a
- * share of zero as ONE session, so a count too small to divide does not fail: it quietly
- * runs more users than the generated file names.
+ * Legacy threshold keys in the limit form the fleet core maps them to (D7): inclusive
+ * bounds, evaluated per region and overall, CPU per host. For the echo only; the
+ * thresholds themselves still reach the generator unchanged.
  */
-function minimumThreads(threads, hosts, coverage) {
-    const divides = (total) => {
-        const browser = Math.min(Math.max(Math.round(total * coverage), 1), total);
-        return browser >= hosts && total - browser >= hosts;
-    };
-    if (divides(threads))
-        return null;
-    let total = threads + 1;
-    while (!divides(total))
-        total++;
-    return total;
+export function legacyThresholdLimits(thresholds) {
+    const lines = [];
+    for (const pair of thresholds.split(",")) {
+        const [key, value] = pair.split("=").map((p) => p?.trim() ?? "");
+        if (!key)
+            continue;
+        const line = {
+            lcp_ms: `lcp p90 <= ${value}ms fail`,
+            inp_ms: `inp p90 <= ${value}ms fail`,
+            cls: `cls p90 <= ${value} fail`,
+            journey_success_rate: `journey_success >= ${value} fail`,
+            generator_cpu_pct: `generator_cpu p50 <= ${value}% fail`,
+        }[key];
+        if (line)
+            lines.push(line);
+        else if (key === "allowUnmeasured")
+            lines.push(`allowUnmeasured=${value} (an unmeasured threshold passes)`);
+        else
+            lines.push(`${key}=${value} (not a known threshold key)`);
+    }
+    return lines;
+}
+/**
+ * What the generation tells the agent to echo before any run. Explicit limits come with
+ * the confirmation token the runners require. Legacy thresholds are shown as the limits
+ * they map to. With neither the fleet gates on nothing, and the site defaults are only
+ * offered as suggestions (D5 does not apply them).
+ */
+function limitEcho(client, params, fileLimits, token) {
+    const parts = [];
+    if (fileLimits.length > 0) {
+        parts.push("Limits set (normalized):\n" +
+            fileLimits.map((l) => `- ${l}`).join("\n") +
+            `\nconfirmationToken: ${token}\n` +
+            "Echo these pass conditions to the user and WAIT for their confirmation. Only after " +
+            "they confirm, pass confirmationToken to skyramp_start_fleet (then poll " +
+            "skyramp_fleet_status and collect skyramp_fleet_result) or skyramp_execute_fleet; " +
+            "both refuse this fleet without it.");
+    }
+    if (params.thresholds) {
+        const mapped = legacyThresholdLimits(params.thresholds).map((line) => {
+            if (!client.normalizeFleetLimits || line.includes("("))
+                return line;
+            try {
+                return client.normalizeFleetLimits([line], params.hosts)[0] ?? line;
+            }
+            catch {
+                return line;
+            }
+        });
+        parts.push("Legacy thresholds set, enforced with their original behavior (per region and " +
+            "overall; generator CPU per host):\n" +
+            mapped.map((l) => `- ${l}`).join("\n") +
+            "\nEcho these to the user before running the fleet.");
+    }
+    if (parts.length === 0) {
+        let suggested = [];
+        try {
+            suggested = client.getFleetLimitCatalogue?.().defaults ?? [];
+        }
+        catch {
+            // An SDK without the catalogue has no suggestions to offer.
+        }
+        parts.push("No limits set: this fleet gates on no performance limit." +
+            (suggested.length > 0
+                ? "\nSuggested site defaults (suggested, NOT applied):\n" +
+                    suggested.map((l) => `- ${l}`).join("\n") +
+                    "\nOffer them to the user; regenerate with them as limits only if the user asks."
+                : ""));
+    }
+    return parts.join("\n\n");
 }
 /**
  * Every file the generator reports writing. ui-load prints one "Successfully generated"
@@ -357,6 +483,9 @@ export async function generateUILoadTest(params) {
     const outError = validatePath(params.outputDir, "outputDir");
     if (outError)
         return outError;
+    const credentialsError = validatePath(params.credentialsFile ?? "", "credentialsFile");
+    if (credentialsError)
+        return credentialsError;
     // The filesystem guards every other generator gets from TestGenerationService, which
     // this tool does not pass through because ui-load has its own FFI export.
     // In cross-repo mode the files belong in the tests repo clone, not the source repo.
@@ -366,17 +495,23 @@ export async function generateUILoadTest(params) {
     const badTarget = generationTargets(outputDir, params.output || undefined).find(isInsideExecutorWorkDir);
     if (badTarget)
         return toolError(executorWorkDirRefusal(badTarget));
-    const minimum = minimumThreads(params.loadNumThreads, params.hosts.length, params.browserCoverage);
-    if (minimum !== null) {
+    // The fleet refuses this too; refusing here says so before any file is written.
+    if (params.loadNumThreads < params.hosts.length) {
         return toolError(`Error: loadNumThreads ${params.loadNumThreads} cannot give each of the ` +
-            `${params.hosts.length} host(s) a virtual user in both halves at browserCoverage ` +
-            `${params.browserCoverage}. Use at least ${minimum}, or change browserCoverage.`);
+            `${params.hosts.length} host(s) a session. Use at least ${params.hosts.length}.`);
     }
     const client = new SkyrampClient();
     if (typeof client.generateUILoad !== "function") {
         return toolError("Error: the installed @skyramp/skyramp SDK does not expose generateUILoad. " +
             "Upgrade to an SDK that includes the ui-load generator.");
     }
+    // Sent on every call, not only when coresPerBrowser is set: an SDK below this floor reads
+    // browserCoverage 0 and an array-only hosts shape under the OLD sizing model, which
+    // silently doubles the provisioned users rather than failing loudly.
+    if (semver.lt(SKYRAMP_SDK_VERSION, MIN_SIZING_SDK_VERSION)) {
+        return toolError(`Error: the installed @skyramp/skyramp SDK (${SKYRAMP_SDK_VERSION}) predates host-capacity ` +
+            `sizing for ui-load. Upgrade to ${MIN_SIZING_SDK_VERSION} or later, which this generator requires.`);
+    }
     // The released SDK has generateUILoad but never reads playwrightStorage, so the session
     // would be dropped and every virtual user would run unauthenticated, with a success
     // message on top. The function's own source is the only signal the SDK offers: it has no
@@ -392,6 +527,22 @@ export async function generateUILoadTest(params) {
         hosts: params.hosts.length,
         outputDir,
     });
+    // Without limits the generation is the one older SDKs know: the limit functions are
+    // never needed, and no default limits are added (D5 defaults are only suggested).
+    let normalizedLimits = [];
+    if (params.limits && params.limits.length > 0) {
+        if (typeof client.normalizeFleetLimits !== "function") {
+            return toolError("Error: the installed @skyramp/skyramp SDK is too old for limits: it cannot " +
+                "validate them natively. Upgrade the SDK, or generate without limits.");
+        }
+        try {
+            normalizedLimits = client.normalizeFleetLimits(params.limits, params.hosts);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Error: ui-load generation failed: ${message}`);
+        }
+    }
     let result;
     try {
         result = await client.generateUILoad({
@@ -410,9 +561,12 @@ export async function generateUILoadTest(params) {
             loadRampupDuration: params.loadRampupDuration,
             loadRampupInterval: params.loadRampupInterval,
             loadTargetRPS: params.loadTargetRPS,
-            browserCoverage: params.browserCoverage,
+            browserCoverage: 0,
             thresholds: params.thresholds,
-            hosts: params.hosts,
+            ...(normalizedLimits.length > 0 ? { limits: normalizedLimits } : {}),
+            hosts: params.coresPerBrowser !== undefined
+                ? { hosts: params.hosts, coresPerBrowser: params.coresPerBrowser }
+                : params.hosts,
             deployWorker: params.deployWorker,
             entrypoint: getEntryPoint(),
         });
@@ -439,25 +593,137 @@ export async function generateUILoadTest(params) {
             "@skyramp/skyramp SDK ignored it, so the fleet cannot run as generated. Upgrade to " +
             "an SDK that supports per-host hostPort and tls.");
     }
-    // Stage so testbot includes the generated files in its output commit.
-    await stageGeneratedPaths(outputDir);
+    // The limits the fleet will actually run, read back from what was written: the token
+    // the runners require is computed from the same file.
+    const fleetFile = files.find((f) => FLEET_MANAGER_FILE.test(f));
+    let fileLimits = [];
+    let token;
+    if (normalizedLimits.length > 0) {
+        const fleetPath = fleetFile ? path.resolve(outputDir, fleetFile) : "";
+        try {
+            fileLimits =
+                fleetPath && existsSync(fleetPath)
+                    ? readFleetFileLimits(fleetPath)
+                    : [];
+        }
+        catch (error) {
+            return toolError(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // The generator writes the normalized lines verbatim, so any difference means the SDK
+        // dropped or changed a requested limit, and the token would confirm a different run.
+        const missing = normalizedLimits.filter((l) => !fileLimits.includes(l));
+        const unexpected = fileLimits.filter((l) => !normalizedLimits.includes(l));
+        if (missing.length > 0 || unexpected.length > 0) {
+            return toolError("Error: the generated fleet file does not carry exactly the requested limits." +
+                (missing.length > 0 ? ` Missing: ${missing.join("; ")}.` : "") +
+                (unexpected.length > 0
+                    ? ` Unexpected: ${unexpected.join("; ")}.`
+                    : "") +
+                " The installed @skyramp/skyramp SDK ignored or changed them; upgrade it to " +
+                "generate limits.");
+        }
+        token = limitConfirmationToken(fleetPath, fileLimits);
+    }
+    const poolNote = placeCredentialPool(files, outputDir, params);
+    // Stage an explicit allowlist, not outputDir itself: `git add <dir>` restages any path
+    // under it that's already tracked regardless of .gitignore, so bulk-staging could
+    // recommit the credential pool if this outputDir once had it tracked and deleted.
+    const gitignorePath = path.join(outputDir, ".gitignore");
+    const pathsToStage = existsSync(gitignorePath)
+        ? [...files, gitignorePath]
+        : files;
+    for (const generatedPath of pathsToStage) {
+        await stageGeneratedPaths(generatedPath);
+    }
     return {
         content: [
             { type: "text", text: result },
+            { type: "text", text: limitEcho(client, params, fileLimits, token) },
             {
                 type: "text",
                 text: `Generated three coordinated files in ${outputDir}:\n` +
                     `- the UI test, which replays the recorded journey in a real browser\n` +
                     `- the load file, whose function RETURNS the protocol scenario (static assets filtered out)\n` +
                     `- the fleet manager, which wires the hosts, the UI test and the scenario into one run\n\n` +
-                    `The fleet manager is the entry point. For python/typescript/javascript run it as a ` +
-                    `script; for java run it as a JUnit test. It builds the scenario, fans the journey ` +
-                    `across the hosts at browserCoverage ${params.browserCoverage}, and asserts the ` +
-                    `thresholds.`,
+                    `The fleet manager is the entry point; run it with skyramp_execute_fleet (java, ` +
+                    `python, typescript, javascript), which runs it in the executor container. It builds the scenario, runs ` +
+                    `${params.loadNumThreads} sessions across the hosts for ${params.loadDuration}s -- as ` +
+                    `many real browsers as each host can carry, protocol users for the rest -- and ` +
+                    `asserts the thresholds.` +
+                    (poolNote ? `\n\n${poolNote}` : ""),
             },
         ],
     };
 }
+/** The file the generated fleet reads its identities from (SKYRAMP_CREDENTIALS default). */
+const CREDENTIALS_FILENAME = "credentials.csv";
+/**
+ * Copy the credential pool (credentialsFile, else credentials.csv beside the recorded
+ * session) to credentials.csv beside the generated files, where the fleet reads it; an
+ * existing one is left alone. Returns a line for the tool's result, or "" when not needed.
+ */
+export function placeCredentialPool(files, outputDir, params) {
+    const note = copyCredentialPool(files, outputDir, params);
+    return note && note + ignoreCredentialPool(outputDir);
+}
+function copyCredentialPool(files, outputDir, params) {
+    const fleetFile = files.find((f) => FLEET_MANAGER_FILE.test(f));
+    if (!fleetFile)
+        return "";
+    let fleetSource = "";
+    try {
+        fleetSource = readFileSync(path.resolve(outputDir, fleetFile), "utf8");
+    }
+    catch {
+        return "";
+    }
+    if (!fleetSource.includes(CREDENTIALS_FILENAME))
+        return "";
+    const target = path.join(outputDir, CREDENTIALS_FILENAME);
+    if (existsSync(target)) {
+        return `Credential pool: the fleet reads ${target}, which is already there.`;
+    }
+    const candidates = [
+        params.credentialsFile,
+        params.playwrightStoragePath
+            ? path.join(path.dirname(params.playwrightStoragePath), CREDENTIALS_FILENAME)
+            : undefined,
+    ].filter((p) => !!p);
+    const source = candidates.find((p) => existsSync(p));
+    if (!source) {
+        return (`Credential pool: the fleet reads ${target}, and none was found ` +
+            `(looked for ${candidates.join(", ") || "credentialsFile"}). Put the pool there, or ` +
+            "pass credentialsFile, before running the fleet.");
+    }
+    try {
+        copyFileSync(source, target);
+    }
+    catch (error) {
+        return (`Credential pool: could not copy ${source} to ${target} ` +
+            `(${error instanceof Error ? error.message : String(error)}). Copy it there, or ` +
+            "pass credentialsFile, before running the fleet.");
+    }
+    return `Credential pool: copied ${source} to ${target}, where the fleet reads it.`;
+}
+/** Lists the pool in <outputDir>/.gitignore so testbot's staging never commits it. */
+function ignoreCredentialPool(outputDir) {
+    const ignoreFile = path.join(outputDir, ".gitignore");
+    try {
+        const existing = existsSync(ignoreFile)
+            ? readFileSync(ignoreFile, "utf8")
+            : "";
+        if (existing.split(/\r?\n/).some((l) => l.trim() === CREDENTIALS_FILENAME)) {
+            return "";
+        }
+        const separator = existing === "" || existing.endsWith("\n") ? "" : "\n";
+        appendFileSync(ignoreFile, `${separator}${CREDENTIALS_FILENAME}\n`);
+        return "";
+    }
+    catch (error) {
+        return (` Warning: could not add ${CREDENTIALS_FILENAME} to ${ignoreFile} ` +
+            `(${error instanceof Error ? error.message : String(error)}); keep the pool out of git.`);
+    }
+}
 /**
  * The tool's entry point: the trace-reuse guard and the usage event around the generation,
  * as skyramp_ui_test_generation has them.
@@ -494,7 +760,7 @@ Emits THREE coordinated files:
 
 **Inputs you must gather from the user, not guess:**
 - \`hosts\` — which VMs or regions should generate load. At least one is required; each becomes an inline Host(...) in the fleet manager. A host on a remote Docker Engine (\`dockerHost\`) also needs \`tls\` — the directory holding its client certificates — because that connection is mTLS.
-- \`browserCoverage\` — how much of the run is real browsers. Strictly between 0 and 1. Do NOT assume a non-default value.
+- \`loadNumThreads\` — how many user sessions to run ("100 users"). The fleet splits them by host capacity: each host runs as many real-browser sessions as it can carry and protocol users for the rest, and fails the run when it cannot provision them. Capacity defaults to one browser per CPU core when \`loadTargetRPS\` is set, a quarter of the cores otherwise; set \`coresPerBrowser\` to change that ratio, or a host's \`browserSessions\` to fix its browser count directly ("4 browsers on each host").
 
 **Exclude third-party hosts.** A trace from a real site carries CDN, analytics and ad traffic. \`exclude\` matches the EXACT host, so enumerate every one — excluding "example.com" does not drop "cdn.example.com". Without this the protocol half load-tests other people's infrastructure.