@sdods/cli 0.8.0 → 0.10.0

package/dist/commands/baselines.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function register(program: Command): void;
+//# sourceMappingURL=baselines.d.ts.map

package/dist/commands/baselines.js

@@ -0,0 +1,111 @@
+import { relative, resolve as resolvePath } from 'node:path';
+import pc from 'picocolors';
+import { DEFAULT_ARTIFACTS_DIR, SdodsError, acceptVisualFailures, listVisualFailures, selectVisualFailures, } from '@sdods/core';
+import { createContext } from '../context.js';
+import { heading, json, ok, out, table } from '../ui.js';
+import { listRuns } from './trace.js';
+function artifactsDirOf(ctx, flag) {
+    return resolvePath(ctx.rootDir, flag ?? process.env.SDODS_ARTIFACTS_DIR ?? DEFAULT_ARTIFACTS_DIR);
+}
+function findRun(ctx, opts) {
+    const artifactsDir = artifactsDirOf(ctx, opts.artifactsDir);
+    const runs = listRuns(artifactsDir);
+    const run = opts.run ? runs.find((r) => r.runId === opts.run) : runs[0];
+    if (!run)
+        throw new SdodsError('CONFIG_NOT_FOUND', opts.run
+            ? `Run ${opts.run} not found under ${artifactsDir}.`
+            : `No runs under ${artifactsDir}.`, {
+            hint: 'Run `sdods run -t @visual …` first, or download the CI run into .sdods/runs/<id>.',
+            exitCode: 2,
+        });
+    return run;
+}
+const pct = (r) => (r === undefined ? '' : `${(r * 100).toFixed(2)}%`);
+export function register(program) {
+    const baselines = program
+        .command('baselines')
+        .description('Review failed visual baseline checks of a run and accept the new screenshots');
+    baselines
+        .command('diff')
+        .description('List the visual checks that failed in a run: expected, actual and diff images')
+        .option('--run <id>', 'run id (default: the most recent run)')
+        .option('--artifacts-dir <dir>', `artifacts directory (default: ${DEFAULT_ARTIFACTS_DIR})`)
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        const run = findRun(ctx, opts);
+        const failures = listVisualFailures(run.dir);
+        const abs = (p) => (p ? resolvePath(run.dir, p) : undefined);
+        if (ctx.opts.json)
+            return json({
+                runId: run.runId,
+                failures: failures.map((f) => ({
+                    ...f,
+                    actual: abs(f.actual),
+                    expected: abs(f.expected),
+                    diff: abs(f.diff),
+                })),
+            });
+        if (!failures.length) {
+            ok(`No failed visual checks in run ${run.runId}.`);
+            return;
+        }
+        heading(`${failures.length} failed visual check(s) in run ${run.runId}`);
+        const rel = (p) => (p ? relative(ctx.rootDir, p) : '—');
+        for (const f of failures) {
+            out('');
+            out(`${pc.bold(`${f.runnerProject}/${f.name}`)}  ${pc.dim(f.platform)}  ${reasonLabel(f)}`);
+            out(`  scenario  ${f.scenarioName} ${pc.dim(`(${f.featureUri})`)}`);
+            out(`  baseline  ${f.baseline}`);
+            table([
+                { image: 'expected', path: rel(abs(f.expected)) },
+                { image: 'actual', path: rel(abs(f.actual)) },
+                { image: 'diff', path: rel(abs(f.diff)) },
+            ]);
+        }
+        out('');
+        out(pc.dim(`Accept after reviewing the diff: sdods baselines accept <name…> --run ${run.runId}  (or --all)`));
+    });
+    baselines
+        .command('accept [names...]')
+        .description('Copy the actual screenshot of failed visual checks over their baselines (writes to the project tree)')
+        .requiredOption('--run <id>', 'run id the screenshots come from (required)')
+        .option('--all', 'accept every failed visual check of the run')
+        .option('--artifacts-dir <dir>', `artifacts directory (default: ${DEFAULT_ARTIFACTS_DIR})`)
+        .action(async (names, opts, cmd) => {
+        const ctx = createContext(cmd);
+        if (opts.all && names.length)
+            throw new SdodsError('CONFIG_INVALID', 'Pass baseline names or --all, not both.', {
+                exitCode: 2,
+            });
+        const run = findRun(ctx, opts);
+        const failures = listVisualFailures(run.dir);
+        if (!failures.length)
+            throw new SdodsError('CONFIG_NOT_FOUND', `No failed visual checks in run ${run.runId}.`, {
+                hint: 'Nothing to accept. `sdods baselines diff --run <id>` lists what failed.',
+                exitCode: 2,
+            });
+        const picked = selectVisualFailures(failures, { names, all: opts.all });
+        const accepted = acceptVisualFailures({
+            runDir: run.dir,
+            failures: picked,
+            projectRoot: (slug) => ctx.registry.rootOf(slug),
+        });
+        if (ctx.opts.json)
+            return json({ runId: run.runId, accepted });
+        for (const a of accepted) {
+            ok(`${a.created ? 'created' : 'updated'} ${relative(ctx.rootDir, a.to)}  ${pc.dim(`${a.runnerProject}/${a.name} · ${a.platform} · ${reasonLabel(a)}`)}`);
+            out(pc.dim(`  from ${relative(ctx.rootDir, a.from)}`));
+            if (a.diff)
+                out(pc.dim(`  diff ${relative(ctx.rootDir, a.diff)}`));
+        }
+        out(pc.dim('Review the PNGs with `git diff --stat` and commit them with the change that moved the pixels.'));
+    });
+}
+function reasonLabel(f) {
+    if (f.reason === 'missing')
+        return pc.cyan('new baseline');
+    if (f.reason === 'size')
+        return pc.yellow('size changed');
+    return pc.yellow(`changed ${pct(f.diffRatio)}`.trim());
+}
+//# sourceMappingURL=baselines.js.map

package/dist/commands/browsers.js

@@ -75,7 +75,7 @@ export async function browserStatuses(names = DOWNLOADED_BROWSERS) {
     return names.map((name) => {
         const engine = ENGINE_OF[name] ?? 'chromium';
         const channel = CHANNEL_OF[name] ?? null;
-        let executable = null;
+        let executable;
         try {
             executable = channel ? channelExecutable(channel) : pw[engine].executablePath();
         }

package/dist/commands/doctor.js

@@ -2,17 +2,18 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
-import { collectVarRefs, loadDotEnvLayer, loadEnvFile } from '@sdods/core';
+import { collectVarRefs, describeWorkers, effectiveWorkers, loadDotEnvLayer, loadEnvFile, poolAccountsByEnv, } from '@sdods/core';
 import { createContext } from '../context.js';
 import { browserStatuses } from './browsers.js';
 import { MIN_PLAYWRIGHT_FOR_STEP_RESULTS, installedPlaywrightVersion, stepResultsWarning, } from '../runner-compat.js';
-import { json, out } from '../ui.js';
+import { json, out, parseIntFlag } from '../ui.js';
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
         .description('Check Node, Bun, browsers, projects, env vars and database reachability')
         .option('-p, --project <slug>', 'limit env-var checks to one project')
         .option('--fix', 'install missing browsers')
+        .option('-w, --workers <n>', 'worker count to check user pools against (default: SDODS_WORKERS, else Playwright default)', parseIntFlag('workers'))
         .action(async (opts, cmd) => {
         const ctx = createContext(cmd);
         const checks = [];
@@ -45,6 +46,8 @@ export function registerDoctorCommand(program) {
                 cwd: ctx.rootDir,
             }).catch(() => undefined);
         }
+        const envWorkers = Number(process.env.SDODS_WORKERS);
+        const workers = opts.workers ?? (Number.isInteger(envWorkers) && envWorkers > 0 ? envWorkers : undefined);
         const entries = opts.project
             ? [ctx.registry.entry(opts.project)]
             : ctx.registry.entriesList();
@@ -80,6 +83,9 @@ export function registerDoctorCommand(program) {
                         ? `Add ${missing.join(', ')} to ${join(e.root, `.env.${envName}`)}`
                         : undefined,
                 });
+                const pool = poolCheck(e.slug, envName, { ...e.config, root: e.root }, envCfg.users.poolSize, workers);
+                if (pool)
+                    checks.push(pool);
             }
         }
         const driver = process.env.DB_DRIVER ?? 'sqlite';
@@ -121,6 +127,42 @@ export function registerDoctorCommand(program) {
             process.exitCode = 1;
     });
 }
+/**
+ * #153: accounts per role in an exclusive, worker-held pool against the worker count. Advisory —
+ * doctor does not know which roles a run will select; `sdods run` makes the real decision and
+ * fails with USER_POOL_TOO_SMALL. Undefined when there is nothing to compare.
+ */
+function poolCheck(slug, envName, project, poolSize, workers) {
+    const pool = project.data.userPool;
+    if (!pool)
+        return undefined;
+    const name = `${slug}/${envName} user pool`;
+    if (pool.mode === 'shared' || pool.leaseScope === 'scenario') {
+        return {
+            name,
+            ok: true,
+            detail: pool.mode === 'shared' ? 'mode: shared (no leases)' : 'leaseScope: scenario (queues)',
+        };
+    }
+    const accounts = poolAccountsByEnv(project, {
+        envs: [envName],
+        poolSize: () => poolSize,
+    })?.get(envName);
+    if (!accounts)
+        return undefined; // not file-backed
+    const n = effectiveWorkers(workers);
+    const short = [...accounts].filter(([, count]) => count < n);
+    return {
+        name,
+        ok: short.length === 0,
+        optional: true,
+        detail: `${[...accounts].map(([role, count]) => `${role} ${count}`).join(', ') || 'no accounts'} ` +
+            `vs ${describeWorkers(workers)}`,
+        fix: short.length
+            ? `fewer accounts than workers for ${short.map(([r]) => r).join(', ')}: sdods run stops with USER_POOL_TOO_SMALL when more of their @user: scenarios could run at once than there are accounts. Set data.userPool.leaseScope: scenario, add accounts, or lower --workers.`
+            : undefined,
+    };
+}
 /**
  * The token matrix. "one-of" rows form a group: agents need ANY one of them.
  * Platform features never need an external token.

package/dist/commands/init.js

@@ -140,12 +140,12 @@ export async function initWorkspace(target, flags) {
             // 1.63 is the floor, not a preference: below it an npm-installed workspace records every
             // Gherkin step SKIPPED in messages.ndjson (see runner-compat.ts).
             '@playwright/test': flags.link && flags.pm === 'bun' ? 'link:@playwright/test' : '^1.63.0',
-            'playwright-bdd': flags.link && flags.pm === 'bun' ? 'link:playwright-bdd' : '^9.2.0',
+            'playwright-bdd': flags.link && flags.pm === 'bun' ? 'link:playwright-bdd' : '^9.2.1',
         },
         devDependencies: {
-            '@types/node': '^22.15.0',
-            typescript: '~5.9.3',
-            tsx: '^4.23.0',
+            '@types/node': '^22.20.2',
+            typescript: '~6.0.3',
+            tsx: '^4.23.13',
         },
         trustedDependencies: [
             '@playwright/test',

package/dist/commands/report.js

@@ -1,10 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, extname, join, resolve } from 'node:path';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
-import { runFiles } from '@sdods/contracts';
-import { SdodsError } from '@sdods/core';
+import { legacyRunFiles, runFiles, } from '@sdods/contracts';
+import { SdodsError, collectGateEvidence, evaluateGates, gateReportsFromRunnerJson, gateTotalsFromRunnerStats, hasGates, ingestGateJudge, } from '@sdods/core';
 import { createContext } from '../context.js';
+import { gateFailedError, printGates } from '../gates.js';
 import { json, ok, out, table, warn } from '../ui.js';
 function artifactsRoot(rootDir) {
     return resolve(rootDir, process.env.SDODS_ARTIFACTS_DIR ?? '.sdods/runs');
@@ -35,6 +37,82 @@ async function openPath(p) {
     const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
     await execa(cmd, [p], { shell: process.platform === 'win32' }).catch(() => undefined);
 }
+/**
+ * The process `report merge` judges: `--process` (with `-p`, or the project in a run.json), or the
+ * process a run.json names when it declares gates. `undefined` when there is nothing to judge.
+ */
+function resolveMergeProcess(ctx, input) {
+    const manifest = input.manifestDirs
+        .map((d) => readJsonFile(join(d, runFiles.manifest)))
+        .find(Boolean);
+    const name = input.process ?? manifest?.process;
+    if (!name)
+        return undefined;
+    const slug = input.project ?? manifest?.projectSlug;
+    if (!slug)
+        throw new SdodsError('CONFIG_INVALID', `--process ${name} needs the project that defines it, and no run.json names one.`, {
+            hint: `Pass -p <slug>: sdods report merge --process ${name} -p <slug> <dirs...>`,
+            exitCode: 2,
+        });
+    let proc;
+    try {
+        proc = ctx.registry.processOf(slug, name);
+    }
+    catch (e) {
+        // Named explicitly, an unknown process is an error. Inferred from a run.json this checkout
+        // cannot resolve, it only means there is nothing here to judge it by; the merge still runs.
+        if (input.process)
+            throw e;
+        warn(`run.json names process "${name}" of ${slug}, which this checkout does not define: gates not judged.`);
+        return undefined;
+    }
+    if (!hasGates(proc.gates)) {
+        // Named explicitly, a process without gates is a mistake worth saying; inferred, it is not.
+        if (input.process)
+            warn(`process "${name}" of ${slug} declares no gates, so there is nothing to judge.`);
+        return undefined;
+    }
+    return { slug, process: proc };
+}
+/**
+ * A merge workspace for `playwright merge-reports`: the blob reports of every directory copied into
+ * one (it reads exactly one directory; prefixed, because two runs' shard 1 carry the same file
+ * name), and a merge config that pins the root the report paths are relative to. Blobs recorded
+ * under different checkouts, such as CI's Playwright container (`/__w/…`) and its bare runner
+ * (`/home/runner/work/…`), otherwise refuse to merge ("recorded with different test directories").
+ */
+function mergeWorkspace(dirs, rootDir) {
+    const dir = mkdtempSync(join(tmpdir(), 'sdods-merge-'));
+    const reports = join(dir, 'reports');
+    mkdirSync(reports);
+    dirs.forEach((from, i) => {
+        for (const name of readdirSync(from))
+            if (name.endsWith('.zip'))
+                copyFileSync(join(from, name), join(reports, `${i + 1}-${name}`));
+    });
+    const config = join(dir, 'merge.config.mjs');
+    writeFileSync(config, `export default ${JSON.stringify({ testDir: rootDir })};\n`);
+    return { reports, config, dir };
+}
+/** The error Playwright printed, rather than the last lines of its stack. */
+function mergeFailureHint(stderr) {
+    const lines = (stderr ?? '').split('\n');
+    const at = lines.findIndex((l) => /^\s*Error\b/.test(l));
+    const picked = at >= 0 ? lines.slice(at, at + 12).filter((l) => !/^\s+at /.test(l)) : lines.slice(-3);
+    return picked.join(' ').replace(/\s+/g, ' ').trim() || undefined;
+}
+/** Writes the merged verdict where `sdods run --process` writes one, so ingest records it the same way. */
+function recordMergedGates(runDir, gates) {
+    writeFileSync(join(runDir, runFiles.gates), JSON.stringify(gates, null, 2));
+    const manifestFile = join(runDir, runFiles.manifest);
+    const manifest = readJsonFile(manifestFile);
+    if (manifest)
+        writeFileSync(manifestFile, JSON.stringify({ ...manifest, gatesPassed: gates.passed }, null, 2));
+    const summaryFile = join(runDir, runFiles.summary);
+    const summary = readJsonFile(summaryFile);
+    if (summary)
+        writeFileSync(summaryFile, JSON.stringify({ ...summary, gates }, null, 2));
+}
 export function register(program) {
     const report = program
         .command('report')
@@ -172,12 +250,25 @@ export function register(program) {
                 artifactsRoot: root,
                 replace: Boolean(opts.replace),
                 env: opts.env,
+                // A run with no gates.json whose process declares gates is judged here, as the run would have been.
+                gates: ingestGateJudge({
+                    manifest: manifest ?? m.readManifest(join(root, opts.runId)),
+                    runDir: join(root, opts.runId),
+                    processOf: (slug, name) => ctx.registry.processOf(slug, name),
+                }),
             });
             if (ctx.opts.json)
                 return json(res);
             ok(`Ingested run ${res.runId} (${res.projectSlug}): ${res.scenarios} scenario(s), ${res.attempts} attempt(s), ${res.steps} step(s), ${res.artifacts} artifact(s), ${res.healEvents} heal event(s)`);
             const t = res.totals;
             out(`${pc.green(`${t.passed} passed`)}  ${pc.red(`${t.failed} failed`)}  ${pc.yellow(`${t.flaky} flaky`)}  ${pc.dim(`${t.skipped} skipped`)}  → ${res.status}`);
+            if (res.gates)
+                out(`gates · process ${res.gates.process}: ${res.gates.passed
+                    ? pc.green('passed')
+                    : pc.red(`FAILED (${res.gates.rows
+                        .filter((r) => !r.passed)
+                        .map((r) => r.gate)
+                        .join(', ')})`)}`);
             if (res.filesSkipped.length)
                 out(pc.dim(`skipped (already ingested): ${res.filesSkipped.join(', ')}`));
             if (res.parseErrors)
@@ -189,9 +280,11 @@ export function register(program) {
     });
     report
         .command('merge <dirs...>')
-        .description('Merge sharded run reports into one HTML report and JUnit file')
+        .description('Merge sharded run reports into one HTML report and JUnit file, and judge process gates on the whole run')
         .option('--run <id>', 'run id to write the merged report into (default: latest)')
         .option('--reporter <list>', 'reporters for the merged output', 'html,junit')
+        .option('--process <name>', "evaluate this process's gates over the merged shards; exit 1 when one is not met (default: the process in run.json, when it declares gates)")
+        .option('-p, --project <slug>', 'project that defines --process (default: from run.json)')
         .action(async (dirs, opts, cmd) => {
         const ctx = createContext(cmd);
         const root = artifactsRoot(ctx.rootDir);
@@ -212,28 +305,82 @@ export function register(program) {
                 exitCode: 2,
             });
         }
+        const shardDirs = dirs.map((d) => resolve(ctx.rootDir, d));
+        // The run directory each shard report sits in (`<run>/shard-reports`) holds that shard's
+        // @a11y and @perf scenario reports, which is the gate evidence the merged report lacks.
+        const shardRunDirs = shardDirs
+            .filter((d) => [runFiles.shardReports, legacyRunFiles.shardReports].includes(basename(d)))
+            .map((d) => dirname(d));
+        const gated = resolveMergeProcess(ctx, {
+            process: opts.process,
+            project: opts.project,
+            manifestDirs: [runDir, ...shardRunDirs],
+        });
+        const reporters = String(opts.reporter)
+            .split(',')
+            .map((r) => r.trim())
+            .filter(Boolean);
+        const mergedJson = join(runDir, runFiles.mergedResults);
+        if (gated && !reporters.includes('json'))
+            reporters.push('json');
+        if (gated)
+            mkdirSync(runDir, { recursive: true });
         // Shard reports are produced by `sdods run --reporter blob --shard i/n`; merging them
         // rebuilds one HTML report and JUnit file for the whole matrix.
+        const workspace = mergeWorkspace(shardDirs, ctx.rootDir);
         const args = [
             'playwright',
             'merge-reports',
+            '--config',
+            workspace.config,
             '--reporter',
-            opts.reporter,
-            ...dirs.map((d) => resolve(ctx.rootDir, d)),
+            reporters.join(','),
+            workspace.reports,
         ];
         const res = await execa('npx', args, {
             cwd: ctx.rootDir,
             reject: false,
-            env: { ...process.env, PLAYWRIGHT_HTML_OUTPUT_DIR: join(runDir, runFiles.htmlReport) },
+            env: {
+                ...process.env,
+                PLAYWRIGHT_HTML_OUTPUT_DIR: join(runDir, runFiles.htmlReport),
+                ...(gated ? { PLAYWRIGHT_JSON_OUTPUT_FILE: mergedJson } : {}),
+            },
         });
-        if (res.exitCode !== 0) {
-            throw new SdodsError('RUN_FAILED', `Merging shard reports failed (exit ${res.exitCode}).`, {
-                hint: res.stderr?.split('\n').slice(-3).join(' ') || undefined,
-            });
+        let gates;
+        try {
+            if (res.exitCode !== 0) {
+                throw new SdodsError('RUN_FAILED', `Merging shard reports failed (exit ${res.exitCode}).`, { hint: mergeFailureHint(res.stderr) });
+            }
+            if (gated) {
+                const merged = readJsonFile(mergedJson);
+                gates = evaluateGates({
+                    process: gated.process.name,
+                    gates: gated.process.gates,
+                    totals: gateTotalsFromRunnerStats(merged?.stats),
+                    // The shards' run directories, and the reports attached in the blobs themselves: a
+                    // download of the shard reports alone still carries its evidence.
+                    evidence: collectGateEvidence([runDir, ...shardRunDirs], gateReportsFromRunnerJson(merged)),
+                });
+                recordMergedGates(runDir, gates);
+            }
+        }
+        finally {
+            rmSync(workspace.dir, { recursive: true, force: true });
         }
         if (ctx.opts.json)
-            return json({ runId, merged: dirs.length, htmlReport: join(runDir, runFiles.htmlReport) });
-        ok(`Merged ${dirs.length} shard report dir(s) into ${join(runDir, runFiles.htmlReport)}`);
+            json({
+                runId,
+                merged: dirs.length,
+                htmlReport: join(runDir, runFiles.htmlReport),
+                ...(gates ? { gates } : {}),
+            });
+        else {
+            ok(`Merged ${dirs.length} shard report dir(s) into ${join(runDir, runFiles.htmlReport)}`);
+            if (gates)
+                printGates(gates);
+        }
+        if (gates && !gates.passed)
+            throw gateFailedError(gates, join(runDir, runFiles.gates));
     });
     report
         .command('traceability')

package/dist/commands/run.d.ts

@@ -40,6 +40,7 @@ export interface RunFlags {
     trigger?: string;
     allowEmpty?: boolean;
     notify?: boolean;
+    allowPoolContention?: boolean;
 }
 export declare function register(program: Command): void;
 export declare function runCommand(flags: RunFlags, cmd: Command): Promise<number>;

package/dist/commands/run.js

@@ -3,13 +3,14 @@ import { isAbsolute, join, relative, resolve as resolvePath } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
 import { RecordingModeSchema, newRunId, runFiles, } from '@sdods/contracts';
-import { SdodsError, CLI_OVERRIDES_ENV, VERSION, formatFindings, lintProject, listGeneratedProjects, moduleByName, moduleDir, normalizeTagExpr, parseTagExpr, redactRunTraces, serializeCliOverrides, setupTierOf, } from '@sdods/core';
+import { SdodsError, CLI_OVERRIDES_ENV, VERSION, checkPoolCapacity, collectGateEvidence, effectiveWorkers, evaluateGates, formatFindings, hasGates, lintProject, listGeneratedProjects, moduleByName, moduleDir, normalizeTagExpr, parseTagExpr, poolAccountsFor, poolDemandByRole, poolTooSmallError, redactRunTraces, serializeCliOverrides, setupTierOf, } from '@sdods/core';
 import { analyzeChangeImpact } from '@sdods/mcp';
 import { createContext } from '../context.js';
 import { browserStatuses } from './browsers.js';
+import { gateFailedError, printGates } from '../gates.js';
 import { maybeNotify, notifyRun } from '../notify.js';
 import { installedPlaywrightVersion, stepResultsWarning } from '../runner-compat.js';
-import { collect, json, out, parseIntFlag, table, warn } from '../ui.js';
+import { collect, json, out, parseIntFlag, renderError, table, warn } from '../ui.js';
 const RECORDING_MODES = RecordingModeSchema.options.join(' | ');
 /** `--trace`/`--video` take Playwright's modes; refuse anything else before specs are generated. */
 function recordingMode(flag, value) {
@@ -37,6 +38,7 @@ function addRunOptions(cmd) {
         .option('--device <name>', 'device name for mobile emulation, e.g. "iPhone 15"')
         .option('--headed', 'run headed')
         .option('-w, --workers <n>', 'parallel workers', parseIntFlag('workers'))
+        .option('--allow-pool-contention', 'run even when a @user: role has fewer pool accounts than the workers that need it')
         .option('--shard <i/n>', 'shard, e.g. 1/3')
         .option('--retries <n>', 'retries per test', parseIntFlag('retries'))
         .option('--trace <mode>', `Playwright trace: ${RECORDING_MODES} (default: evidence.trace)`)
@@ -54,7 +56,7 @@ function addRunOptions(cmd) {
         .option('--har-update', 'record/refresh HAR files for @har scenarios')
         .option('--har-replay', 'replay HAR files for @har scenarios')
         .option('--strict', 'with --har-replay: abort on any request not in the HAR (offline)')
-        .option('--update-snapshots', 'update visual baselines')
+        .option('--update-snapshots', 'overwrite visual baselines without review (prefer `sdods baselines diff` / `accept`)')
         .option('--ui', 'interactive UI mode')
         .option('--debug', 'step debugger')
         .option('--list', 'list the run targets and tests that would run')
@@ -150,6 +152,9 @@ export async function runCommand(flags, cmd) {
     if (stepResults)
         warn(stepResults);
     const runId = flags.runId ?? newRunId();
+    if (flags.updateSnapshots)
+        warn('--update-snapshots overwrites every compared baseline without showing the diff. ' +
+            `Prefer a normal run, then \`sdods baselines diff --run ${runId}\` and \`sdods baselines accept <name> --run ${runId}\`.`);
     const cli = {
         env: envName,
         headed: flags.headed,
@@ -206,6 +211,59 @@ export async function runCommand(flags, cmd) {
         if (result.warnings.length && ctx.opts.verbose)
             process.stderr.write(formatFindings(result) + '\n');
     }
+    // --since selects features by git range; resolved here so the pool check counts the same selection.
+    const impact = flags.since
+        ? analyzeChangeImpact(cfg.project.root, ctx.rootDir, flags.since)
+        : undefined;
+    // #153: refuse, before generating anything, a run whose user pool cannot cover its workers.
+    // Listing runs nothing, and --ui / --debug run one scenario at a time by hand.
+    if (!flags.list && !flags.ui && !flags.debug) {
+        const poolCfg = cfg.project.data.userPool;
+        const accounts = poolCfg && poolCfg.mode !== 'shared' && poolCfg.leaseScope !== 'scenario'
+            ? poolAccountsFor(cfg)
+            : undefined;
+        if (accounts) {
+            const moduleRels = modules.map((m) => relative(cfg.project.root, moduleDir(cfg.project.root, moduleByName(projectCfg, m)))
+                .replace(/\\/g, '/')
+                .concat('/'));
+            const impactedRels = impact ? new Set(impact.impacted.map((r) => r.feature)) : undefined;
+            const grep = flags.grep ? safeRegExp(flags.grep) : undefined;
+            const features = cfg.env.vars?.features;
+            const demand = poolDemandByRole(cfg.project, cfg.env.name, {
+                layers: layers.length ? layers : projectCfg.layers,
+                browsers: browsers.length ? browsers : projectCfg.browsers,
+                tags,
+                setupTags: setup?.tags,
+                flags: typeof features === 'string'
+                    ? features
+                        .split(',')
+                        .map((f) => f.trim())
+                        .filter(Boolean)
+                    : undefined,
+                quarantine: process.env.SDODS_QUARANTINE === 'run' ? 'run' : 'skip',
+                fullyParallel: proc?.fullyParallel ?? projectCfg.fullyParallel,
+                includeFeature: (rel) => (!featureRel || rel === featureRel) &&
+                    (!moduleRels.length || moduleRels.some((m) => rel.startsWith(m))) &&
+                    (!impactedRels || impactedRels.has(rel)),
+                includeScenario: (name) => (!flags.scenario || name.includes(flags.scenario)) &&
+                    (!flags.grep || (grep?.test(name) ?? false)),
+                repeatEach: flags.repeatEach,
+                shardTotal: cfg.runtime.shard?.total,
+            });
+            const shortfalls = checkPoolCapacity({
+                pool: poolCfg,
+                accounts,
+                demand,
+                workers: effectiveWorkers(cfg.runtime.workers),
+            });
+            if (shortfalls.length) {
+                const error = poolTooSmallError(cfg, shortfalls, cfg.runtime.workers);
+                if (!flags.allowPoolContention)
+                    throw error;
+                warn(`${error.message} Running anyway (--allow-pool-contention).`);
+            }
+        }
+    }
     const selection = {
         project: entry.slug,
         env: cfg.env.name,
@@ -318,8 +376,7 @@ export async function runCommand(flags, cmd) {
     // `analyzeChangeImpact` has existed for a while and was reachable only
     // through MCP, so it could advise a human and could not select a run. This is
     // the seam that was missing; the mapping itself is unchanged.
-    if (flags.since) {
-        const impact = analyzeChangeImpact(cfg.project.root, ctx.rootDir, flags.since);
+    if (flags.since && impact) {
         if (impact.impacted.length === 0) {
             // Deliberately NOT "run everything" and deliberately not a silent empty
             // run. A run that registered zero scenarios exits 0 and looks identical
@@ -389,6 +446,30 @@ export async function runCommand(flags, cmd) {
             warn(`trace redaction failed for ${relative(ctx.rootDir, e.file)}: ${e.error}`);
     }
     const summary = readSummary(runDir, runId, exitCode, Date.now() - started);
+    // Process gates are judged here, from the run that just finished, before anything publishes it.
+    // One shard of several holds only part of the run, so its pass rate and its a11y/perf evidence
+    // are not the run's; a sharded process is gated where the shards are merged
+    // (`sdods report merge --process`), not per shard.
+    const shardTotal = cfg.runtime.shard?.total ?? 1;
+    let gates;
+    if (proc && hasGates(proc.gates) && exitCode !== 130) {
+        if (shardTotal > 1) {
+            warn(`process "${proc.name}" gates are not evaluated on shard ${cfg.runtime.shard?.current}/${shardTotal}: one shard is not the whole run. Judge them on the merged shards with \`sdods report merge --process ${proc.name}\`.`);
+        }
+        else {
+            gates = evaluateGates({
+                process: proc.name,
+                gates: proc.gates,
+                totals: summary?.totals,
+                evidence: collectGateEvidence(runDir),
+            });
+            writeFileSync(join(runDir, runFiles.gates), JSON.stringify(gates, null, 2));
+            if (summary)
+                summary.gates = gates;
+            manifest.gatesPassed = gates.passed;
+            writeManifest();
+        }
+    }
     if (summary)
         writeFileSync(join(runDir, runFiles.summary), JSON.stringify(summary, null, 2));
     const dbConfigured = process.env.DB_DRIVER === 'postgres'
@@ -428,6 +509,13 @@ export async function runCommand(flags, cmd) {
             writeManifest();
         }
     }
+    // A breached gate fails a run whose scenarios passed. Exit 1, as the exit-code reference says:
+    // a gate not met is a failure, not a configuration error.
+    if (gates && !gates.passed && finalExit === 0) {
+        finalExit = 1;
+        manifest.exitCode = finalExit;
+        writeManifest();
+    }
     // Enabled integrations (check runs, PR comment, issues) act on the run here, the same way
     // `sdods integrations notify --run-id` does. Failures are reported and never change the exit code.
     const notify = await maybeNotify({
@@ -461,9 +549,11 @@ export async function runCommand(flags, cmd) {
         out(pc.dim(`integrations: not notified (${notify.reason})`));
     }
     if (ctx.opts.json) {
-        json({ runId, runDir, exitCode: finalExit, summary, manifest, notify });
+        json({ runId, runDir, exitCode: finalExit, summary, manifest, notify, gates });
     }
     else {
+        if (gates)
+            printGates(gates);
         const t = summary?.totals;
         out('');
         out(`${finalExit === 0 ? pc.green('✔ passed') : finalExit === 130 ? pc.yellow('■ cancelled') : finalExit === 2 ? pc.yellow('■ nothing ran') : pc.red('✖ failed')}  ${t ? `${t.passed} passed, ${t.failed} failed, ${t.skipped} skipped, ${t.flaky} flaky` : ''}  ${pc.dim(`(${Math.round((Date.now() - started) / 1000)}s)`)}`);
@@ -471,6 +561,8 @@ export async function runCommand(flags, cmd) {
         out(pc.dim(`html report: ${join(runDir, runFiles.htmlReport, 'index.html')}`));
         out(pc.dim(`dashboard:   ${join(runDir, runFiles.dashboard, 'index.html')}`));
     }
+    if (gates && !gates.passed)
+        renderError(gateFailedError(gates, join(runDir, runFiles.gates)), Boolean(ctx.opts.json));
     return finalExit;
 }
 /**
@@ -496,6 +588,15 @@ function projectFeaturePath(projectRoot, repoRoot, input) {
         });
     return rel;
 }
+/** `--grep` as the pool check reads it; a pattern Playwright would reject matches no scenario. */
+function safeRegExp(pattern) {
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        return undefined;
+    }
+}
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }