ccqa 1.17.0 → 1.18.0

package/README.md

@@ -125,6 +125,13 @@ run executes it claims its specs, so a cycle that starts before the last one
 finishes skips what is already running instead of driving the same flow
 twice.
 
+Specs that write to the same place outside your app — a chat channel, a
+shared inbox — join a
+[`serialGroups`](./docs/targets.md#serialgroups--specs-that-must-not-run-at-the-same-time)
+entry in `.ccqa/config.yaml`. The claim covers those groups too, so
+`--concurrency` shortens a run without letting two specs read each other's
+effects, in this run or the next one.
+
 When a clean spec still fails, `--on-fail-explain` labels whose problem
 it is: `TEST_DRIFT`, `SPEC_CHANGE`, `PRODUCT_BUG`, or `UNKNOWN`. You
 grade the calls on the hub, and it learns from your grades.

package/dist/bin/ccqa.mjs

@@ -180,27 +180,31 @@ const StepSchema = z.union([ActionStepSchema, IncludeStepSchema]);
 */
 const SpecModeSchema = z.enum(["deterministic", "live"]);
 /**
-* A session name: the identifier of a saved browser session (cookies +
-* localStorage) to restore before the spec runs. Resolved to
-* `.ccqa/sessions/<profile>/<name>.json` at run time. Restricted to a safe
-* slug so the name can't escape the sessions directory.
+* A name a spec chooses that ccqa resolves to a path or looks up in a
+* registry. Restricted to a slug so it cannot escape a directory.
 */
-const SessionNameSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "session name must be a slug (letters, digits, '.', '_', '-'; no path separators)");
+function slug(what) {
+	return z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, `${what} must be a slug (letters, digits, '.', '_', '-'; no path separators)`);
+}
+/**
+* A saved browser session (cookies + localStorage) to restore before the spec
+* runs, resolved to `.ccqa/sessions/<profile>/<name>.json` at run time.
+*/
+const SessionNameSchema = slug("session name");
 /**
-* Sessions to restore before a `mode: live` spec runs: a single name or a
-* list. Always normalized to an array. Each name maps to a saved
-* agent-browser state file; multiple names are merged (their cookies +
+* Sessions to restore before a `mode: live` spec runs: one name or a list,
+* always read back as a list. Multiple names are merged (their cookies +
 * localStorage are unioned) and restored together, so a spec can start
 * signed-in to several providers at once.
 */
 const SessionFieldSchema = z.union([SessionNameSchema, z.array(SessionNameSchema).min(1)]).transform((v) => Array.isArray(v) ? v : [v]);
 /**
 * A generation-target id: which plugin turns this spec into runnable tests
-* (e.g. "agent-browser", "playwright", "runn"). The schema only enforces a
-* safe slug — whether the id names a registered target is the registry's
-* responsibility, so new targets don't require a schema change.
+* (e.g. "agent-browser", "playwright", "runn"). Whether the id names a
+* registered target is the registry's responsibility, so new targets don't
+* require a schema change.
 */
-const TargetIdSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "target must be a slug (letters, digits, '.', '_', '-'; no path separators)");
+const TargetIdSchema = slug("target");
 /** The built-in recorder-backed target. `mode:` / `session:` only apply to it. */
 const AGENT_BROWSER_TARGET = "agent-browser";
 /**
@@ -794,23 +798,42 @@ function stepArtifactPaths(runDir, stepId) {
 }
 //#endregion
 //#region src/runtime/pool.ts
-/**
-* Run each item through `fn` with at most `concurrency` running at once.
-* Results preserve input order. A throwing `fn` rejects the whole pool
-* (callers that want per-item isolation should catch inside `fn`).
-*/
-async function runPool(items, concurrency, fn) {
+async function runPool(items, concurrency, fn, opts = {}) {
 	const results = new Array(items.length);
-	let cursor = 0;
-	const worker = async () => {
-		while (true) {
-			const idx = cursor++;
-			if (idx >= items.length) return;
-			results[idx] = await fn(items[idx], idx);
-		}
+	const needs = items.map((item) => opts.resources?.(item) ?? []);
+	const busy = /* @__PURE__ */ new Set();
+	const queued = new Set(items.map((_, i) => i));
+	const inFlight = /* @__PURE__ */ new Map();
+	const limit = Math.max(1, Math.min(concurrency, items.length));
+	const failures = [];
+	const start = (idx) => {
+		queued.delete(idx);
+		for (const name of needs[idx]) busy.add(name);
+		inFlight.set(idx, Promise.resolve().then(async () => {
+			try {
+				results[idx] = await fn(items[idx], idx);
+			} catch (err) {
+				failures.push(err);
+			} finally {
+				for (const name of needs[idx]) busy.delete(name);
+				inFlight.delete(idx);
+			}
+		}));
 	};
-	const n = Math.max(1, Math.min(concurrency, items.length));
-	await Promise.all(Array.from({ length: n }, () => worker()));
+	while (queued.size > 0 || inFlight.size > 0) {
+		if (failures.length === 0) {
+			for (const idx of queued) {
+				if (inFlight.size >= limit) break;
+				if (needs[idx].some((name) => busy.has(name))) continue;
+				start(idx);
+			}
+			if (inFlight.size === 0) throw new Error(`runPool: ${queued.size} item(s) unrunnable with nothing in flight`);
+		}
+		if (inFlight.size === 0) break;
+		await Promise.race(inFlight.values());
+	}
+	if (failures.length === 1) throw failures[0];
+	if (failures.length > 1) throw new AggregateError(failures, `${failures.length} items failed`);
 	return results;
 }
 //#endregion
@@ -2966,7 +2989,7 @@ const runCommandRunner = { async run(specs, opts) {
 			warn(`${key}: could not report row incrementally: ${err instanceof Error ? err.message : String(err)}`);
 		}
 		return row;
-	});
+	}, { resources: opts.resources });
 } };
 /** File `ccqa generate` writes into the spec directory for external targets. */
 const GENERATED_MANIFEST_FILE = "generated.json";
@@ -6711,27 +6734,57 @@ async function tryDeployHeadSha(hubCtx, profile) {
 * produced, and leaving them out would make the list look shorter than the
 * run's report will be.
 */
-function formatDryRunLines(agentBrowser, routed) {
+function formatDryRunLines(agentBrowser, routed, resources) {
 	const tagged = [
 		...agentBrowser.map((s) => ({
 			key: specKey(s),
-			tag: s.mode
+			tag: s.mode,
+			held: resources(s)
 		})),
 		...routed.external.flatMap((g) => g.specs.map((s) => ({
 			key: specKey(s),
-			tag: g.targetId
+			tag: g.targetId,
+			held: resources(s)
 		}))),
 		...routed.skipped.map((s) => ({
 			key: specKey(s),
-			tag: `skipped — ${s.reason}`
+			tag: `skipped — ${s.reason}`,
+			held: []
 		})),
 		...routed.unresolved.map((s) => ({
 			key: specKey(s),
-			tag: `unresolved — ${s.reason}`
+			tag: `unresolved — ${s.reason}`,
+			held: []
 		}))
 	];
 	const width = Math.max(0, ...tagged.map((t) => t.key.length));
-	return tagged.map((t) => `  ${t.key.padEnd(width)}  ${t.tag}`);
+	return tagged.map((t) => `  ${t.key.padEnd(width)}  ${t.tag}` + (t.held.length > 0 ? `  serial: ${t.held.join(", ")}` : ""));
+}
+//#endregion
+//#region src/run/serial-groups.ts
+const NO_GROUPS = () => [];
+/**
+* Invert `serialGroups` into a per-spec lookup, checking every member names a
+* spec that exists.
+*
+* The check is the point of putting the groups here: a member that resolves to
+* nothing is a typo, and left unchecked it would quietly shrink the group
+* instead of failing. Validated against every spec in the project, not the
+* selection, so a group whose members this run did not select is still read as
+* correct.
+*/
+async function resolveSerialGroups(groups, cwd) {
+	const names = Object.keys(groups);
+	if (names.length === 0) return NO_GROUPS;
+	const known = new Set((await listAllSpecsWithSpecFile(cwd)).map(specKey));
+	const bySpec = /* @__PURE__ */ new Map();
+	for (const name of names) for (const member of groups[name] ?? []) {
+		if (!known.has(member)) throw new RunUsageError(`serialGroups.${name} lists "${member}", which is not a spec in this project`);
+		const list = bySpec.get(member);
+		if (list) list.push(name);
+		else bySpec.set(member, [name]);
+	}
+	return (ref) => bySpec.get(specKey(ref)) ?? [];
 }
 //#endregion
 //#region src/hub/contract/schema.ts
@@ -6998,7 +7051,11 @@ const SpecLockSchema = z.object({
 	holder: z.string(),
 	expiresAt: z.string()
 });
-/** The per-(project, profile) lock document: "feature/spec" → who holds it. */
+/**
+* The per-(project, profile) lock document: key → who holds it. A key is a
+* spec ("feature/spec") or a shared resource ("resource:<name>", ADR-0015);
+* the separators keep the two apart.
+*/
 const SpecLocksSchema = z.object({ specs: z.record(z.string(), SpecLockSchema).default({}) });
 /** Body of `POST /projects/:project/locks?profile=`. */
 const AcquireLocksRequestSchema = z.object({
@@ -7281,26 +7338,34 @@ function emitGithubAnnotations(data) {
 	return lines;
 }
 //#endregion
-//#region src/cli/spec-mode.ts
-/**
-* Read each spec.yaml and resolve its execution mode. Spec-declared `mode:`
-* wins; otherwise `DEFAULT_SPEC_MODE`. Unreadable/unparseable YAML falls back
-* to the default so the per-mode runner surfaces the real error itself.
-*/
-async function resolveSpecsModes(specs, cwd) {
-	return Promise.all(specs.map(async (s) => ({
-		...s,
-		mode: await resolveOne(s, cwd)
-	})));
+//#region src/run/spec-catalog.ts
+async function readSpecs(refs, cwd) {
+	const entries = await Promise.all(refs.map(async (ref) => {
+		const yaml = await tryReadSpecFile(ref.featureName, ref.specName, cwd);
+		if (yaml === null) return [specKey(ref), {
+			spec: null,
+			error: null
+		}];
+		try {
+			return [specKey(ref), {
+				spec: parseTestSpec(yaml),
+				error: null
+			}];
+		} catch (err) {
+			return [specKey(ref), {
+				spec: null,
+				error: errMessage(err)
+			}];
+		}
+	}));
+	return new Map(entries);
 }
-async function resolveOne(spec, cwd) {
-	const yaml = await tryReadSpecFile(spec.featureName, spec.specName, cwd);
-	if (yaml === null) return DEFAULT_SPEC_MODE;
-	try {
-		return parseTestSpec(yaml).mode ?? "deterministic";
-	} catch {
-		return DEFAULT_SPEC_MODE;
-	}
+/** Spec-declared `mode:` wins; otherwise `DEFAULT_SPEC_MODE`. */
+function resolveSpecsModes(specs, catalog) {
+	return specs.map((s) => ({
+		...s,
+		mode: catalog.get(specKey(s))?.spec?.mode ?? "deterministic"
+	}));
 }
 //#endregion
 //#region src/cli/stale-blocks.ts
@@ -9695,7 +9760,7 @@ async function runLiveSpecs(specs, opts) {
 				row
 			};
 		});
-	});
+	}, { resources: opts.resources });
 	const runs = built.map((b) => b.outcome);
 	const failedCount = runs.filter((r) => r.kind === "error" || r.kind === "run" && r.result.status === "failed").length;
 	blank();
@@ -10083,13 +10148,26 @@ const TargetConfigSchema = z.object({
 	})
 }).strict();
 /**
+* Specs that must not run at the same time, grouped by the thing they share.
+*
+* The key names the shared thing (a chat channel, a seeded account, a tenant);
+* the list names the specs that write to it. `ccqa run` never runs two members
+* of one group concurrently, and specs sharing no group still run in parallel.
+*
+* Kept here rather than on each spec so there is one place to read the whole
+* picture, and so a mistyped member is a spec key that does not resolve —
+* caught — rather than a resource name that silently matches nothing.
+*/
+const SerialGroupsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i, "serial group name must be a slug (letters, digits, '.', '_', '-')"), z.array(z.string().min(1)).min(1));
+/**
 * Top-level `.ccqa/config.yaml` schema. `defaultTarget` is used by specs
 * with no `target:` of their own. Both defaults make a missing config file
 * equivalent to "agent-browser only, no extra settings".
 */
 const ProjectConfigSchema = z.object({
 	defaultTarget: TargetIdSchema.default(AGENT_BROWSER_TARGET),
-	targets: z.record(TargetIdSchema, TargetConfigSchema).default({})
+	targets: z.record(TargetIdSchema, TargetConfigSchema).default({}),
+	serialGroups: SerialGroupsSchema.default({})
 }).strict();
 /** Config file location, relative to the project root (`--cwd`). */
 const PROJECT_CONFIG_PATH = ".ccqa/config.yaml";
@@ -11635,20 +11713,30 @@ function resolveTargetFrom(spec, config, registry) {
 //#endregion
 //#region src/run/target-dispatch.ts
 /**
-* Read each spec.yaml, resolve its target, and group. A spec whose YAML is
-* missing or unparseable keeps today's behaviour: it falls through to the
-* agent-browser path, whose runner surfaces the real error itself. A spec
-* whose target resolution throws (unknown target, agent-browser-only fields
-* on another target) is recorded per-spec instead of stopping the run.
-* `resolve` is injectable so tests can supply a registry of fake targets.
+* Resolve each spec's target and group. A spec with no spec.yaml at all falls
+* through to the agent-browser path, whose runner surfaces the real error
+* itself. A spec whose file will not parse, or whose target resolution throws
+* (unknown target, agent-browser-only fields on another target), is recorded
+* per-spec instead of stopping the run. `resolve` is injectable so tests can
+* supply a registry of fake targets.
 */
-async function groupSpecsByTarget(specs, config, cwd, resolve = resolveTarget) {
+function groupSpecsByTarget(specs, catalog, config, resolve = resolveTarget) {
 	const agentBrowser = [];
 	const externalById = /* @__PURE__ */ new Map();
 	const skipped = [];
 	const unresolved = [];
 	for (const ref of specs) {
-		const spec = tryParseTestSpec(await tryReadSpecFile(ref.featureName, ref.specName, cwd));
+		const read = catalog.get(specKey(ref));
+		if (read?.error) {
+			unresolved.push({
+				...ref,
+				title: null,
+				reason: read.error,
+				targetId: null
+			});
+			continue;
+		}
+		const spec = read?.spec ?? null;
 		if (spec === null) {
 			agentBrowser.push(ref);
 			continue;
@@ -11756,6 +11844,7 @@ async function runExternalSpecs(dispatch, ctx) {
 				cwd: ctx.cwd,
 				reportDir: ctx.reportDir,
 				concurrency: ctx.concurrency,
+				resources: ctx.resources,
 				...ctx.model ? { model: ctx.model } : {},
 				...ctx.language ? { language: ctx.language } : {},
 				targetId: group.targetId,
@@ -12259,34 +12348,66 @@ function dedupeSpecs(specs) {
 */
 const LOCK_TTL_SECONDS = 10800;
 /**
-* Claim the specs this run is about to execute, and arrange for the claim to
-* be dropped. Best-effort against the hub: one too old to serve claims must
-* not stop a run that would otherwise work.
+* A serial group's name as a lock key. The `:` keeps it out of reach of spec
+* keys, which are always `feature/spec`.
 */
-async function holdSpecs(hubCtx, profile, specs, teardown) {
+function resourceKey(name) {
+	return `resource:${name}`;
+}
+/**
+* Claim what this run is about to execute, and arrange for the claim to be
+* dropped. Resources first, then only the specs that survived them: a spec
+* held but not run reads to every other job as covered when it is not.
+*
+* Best-effort against a hub too old to serve claims — but only when nothing
+* declares a resource. Running a declared spec unprotected trades a wrong
+* verdict for a completed run, which is the wrong way round.
+*/
+async function holdSpecs(hubCtx, profile, specs, needed, teardown) {
 	const holder = randomUUID();
-	let granted;
-	try {
+	const resources = [...new Set(specs.flatMap(needed))];
+	const take = async (keys) => {
 		const res = await hubCtx.hub.acquireLocks(hubCtx.project, { profile }, {
-			specs: specs.map(specKey),
+			specs: keys,
 			kind: "run",
 			holder,
 			ttlSeconds: LOCK_TTL_SECONDS
 		});
-		granted = new Set(res.granted);
-	} catch (err) {
-		warn(`could not claim specs on the hub, running without exclusion: ${errMessage(err)}`);
-		return specs;
-	}
+		return new Set(res.granted);
+	};
 	const release = async () => {
 		try {
 			await hubCtx.hub.releaseLocks(hubCtx.project, { profile }, holder);
 		} catch (err) {
-			warn(`could not release the spec claims: ${errMessage(err)}`);
+			warn(`could not release this run's claims: ${errMessage(err)} — they stay held for up to ${LOCK_TTL_SECONDS / 3600}h, so other jobs will skip these specs until then`);
 		}
 	};
 	teardown?.onFinalize(release);
-	return specs.filter((spec) => granted.has(specKey(spec)));
+	let runnable = specs;
+	let deniedResources = [];
+	try {
+		if (resources.length > 0) {
+			const granted = await take(resources.map(resourceKey));
+			deniedResources = resources.filter((name) => !granted.has(resourceKey(name)));
+			runnable = specs.filter((spec) => needed(spec).every((n) => !deniedResources.includes(n)));
+		}
+		if (runnable.length > 0) {
+			const granted = await take(runnable.map(specKey));
+			runnable = runnable.filter((spec) => granted.has(specKey(spec)));
+		}
+	} catch (err) {
+		if (resources.length > 0) throw new RunUsageError(`could not claim ${resources.join(", ")} on the hub: ${errMessage(err)} — these specs are in a \`serialGroups\` entry, so running without the claim risks two jobs writing to the same thing. Upgrade the hub, or drop the group to run them unprotected`);
+		warn(`could not claim specs on the hub, running without exclusion: ${errMessage(err)}`);
+		return {
+			specs,
+			deniedResources: []
+		};
+	}
+	if (deniedResources.length > 0) warn(`another job holds ${deniedResources.join(", ")}; the specs needing them wait`);
+	return {
+		specs: runnable,
+		deniedResources
+	};
 }
 /**
 * Run specs and (optionally) write a unified report. This is the library
@@ -12421,12 +12542,27 @@ async function executeRun(targets, opts) {
 			reportDir: null
 		};
 	}
+	const catalog = await readSpecs(specs, cwd);
+	const projectConfig = await loadProjectConfig(cwd);
+	const resources = await resolveSerialGroups(projectConfig.serialGroups, cwd);
+	const declared = [...new Set(specs.flatMap(resources))];
+	if (declared.length > 0) meta("serial groups", declared.join(", "));
+	let waitingOnGroup = [];
 	if (hubCtx && rerunProfile !== null) {
-		const held = await holdSpecs(hubCtx, rerunProfile, specs, opts.teardown);
-		if (held.length < specs.length) meta("held-elsewhere", `${specs.length - held.length} spec(s) another job is already running`);
-		specs = held;
+		const held = await holdSpecs(hubCtx, rerunProfile, specs, resources, opts.teardown);
+		waitingOnGroup = specs.flatMap((spec) => {
+			const groups = resources(spec).filter((n) => held.deniedResources.includes(n));
+			return groups.length > 0 ? [{
+				spec,
+				groups
+			}] : [];
+		});
+		const claimed = specs.length - held.specs.length - waitingOnGroup.length;
+		if (claimed > 0) warn(`${claimed} spec(s) another job is already running`);
+		specs = held.specs;
 		if (specs.length === 0) {
-			warn("every selected spec is already being run by another job");
+			if (held.deniedResources.length > 0) throw new RunUsageError(`every selected spec waits on a shared resource another job holds (${held.deniedResources.join(", ")}): exiting non-zero rather than reporting a green run that verified nothing`);
+			warn("every selected spec is claimed by another job");
 			return {
 				exitCode: 0,
 				report: null,
@@ -12436,11 +12572,17 @@ async function executeRun(targets, opts) {
 	}
 	let dispatch;
 	try {
-		dispatch = await groupSpecsByTarget(specs, await loadProjectConfig(cwd), cwd);
+		dispatch = groupSpecsByTarget(specs, catalog, projectConfig);
+		for (const { spec, groups } of waitingOnGroup) dispatch.skipped.push({
+			...spec,
+			title: catalog.get(specKey(spec))?.spec?.title ?? null,
+			reason: `waiting on ${groups.join(", ")}, held by another job`,
+			targetId: null
+		});
 	} catch (err) {
 		throw new RunUsageError(errMessage(err));
 	}
-	const withMode = await resolveSpecsModes(dispatch.agentBrowser, cwd);
+	const withMode = resolveSpecsModes(dispatch.agentBrowser, catalog);
 	const detSpecs = withMode.filter((s) => s.mode === "deterministic");
 	const liveSpecs = withMode.filter((s) => s.mode === "live");
 	meta("modes", `${detSpecs.length} deterministic / ${liveSpecs.length} live`);
@@ -12454,7 +12596,7 @@ async function executeRun(targets, opts) {
 	if (detSpecs.length === 0 && opts.replaySkipEvidence === true) warn("--no-evidence is ignored: it only applies to agent-browser 'mode: deterministic' specs, and this run has none");
 	blank();
 	if (opts.dryRun) {
-		for (const line of formatDryRunLines(withMode, dispatch)) emitRaw(line + "\n");
+		for (const line of formatDryRunLines(withMode, dispatch, resources)) emitRaw(line + "\n");
 		blank();
 		info("dry run: nothing was executed and no report was written");
 		return {
@@ -12463,7 +12605,7 @@ async function executeRun(targets, opts) {
 			reportDir: null
 		};
 	}
-	const det = await runDeterministicSpecs(detSpecs, opts, cwd, reportDir);
+	const det = await runDeterministicSpecs(detSpecs, opts, cwd, reportDir, resources);
 	let hubRunId = null;
 	let hubSink;
 	if (hubCtx != null && opts.reportToHub) try {
@@ -12522,6 +12664,7 @@ async function executeRun(targets, opts) {
 		cwd,
 		reportDir,
 		concurrency: opts.concurrency ?? 1,
+		resources,
 		...opts.model ? { model: opts.model } : {},
 		...opts.language ? { language: opts.language } : {},
 		report: incrementalReport
@@ -12534,6 +12677,7 @@ async function executeRun(targets, opts) {
 		reportDir,
 		...typeof opts.liveStepRetry === "number" ? { retry: opts.liveStepRetry } : {},
 		concurrency: opts.concurrency ?? 1,
+		resources,
 		...opts.hubProfile ? { profile: opts.hubProfile } : {},
 		diffProvider,
 		hubContext: hubCtx,
@@ -12679,7 +12823,7 @@ function oneLineSummary$1(s) {
 * Captures step-boundary evidence under `<reportDir>/evidence/<feature>/<spec>/`
 * when enabled.
 */
-async function runDeterministicSpecs(specs, opts, cwd, reportDirAbs) {
+async function runDeterministicSpecs(specs, opts, cwd, reportDirAbs, resources) {
 	if (specs.length === 0) return {
 		summaries: [],
 		exitCode: 0
@@ -12698,7 +12842,7 @@ async function runDeterministicSpecs(specs, opts, cwd, reportDirAbs) {
 		captureEvidence
 	};
 	try {
-		const summaries = (await runPool(specs, concurrency, (spec, i) => withBuffer(`${spec.featureName}/${spec.specName}`, concurrency > 1, () => runOneDeterministicSpec(spec, i, ctx)))).filter((s) => s !== null);
+		const summaries = (await runPool(specs, concurrency, (spec, i) => withBuffer(`${spec.featureName}/${spec.specName}`, concurrency > 1, () => runOneDeterministicSpec(spec, i, ctx)), { resources })).filter((s) => s !== null);
 		printSummary(summaries);
 		return {
 			summaries,
@@ -13138,7 +13282,7 @@ function installTeardownSignalHandlers(teardown) {
 }
 //#endregion
 //#region src/cli/run.ts
-const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-rerun-needed", "Only specs the hub answers `rerunNeeded` for: the audit cleared them, and their last result does not cover what is deployed. A spec whose audit has not caught up answers `inProgress`, and one the audit rejected or whose last run failed answers `needsRepair`; neither is taken, because running them races the audit or repairs nothing. No git diff involved. Requires a hub connection and --hub-profile.").option("--only-hub-rerun-needed-with-unknown", "With --only-hub-rerun-needed: also take specs the hub cannot answer for at all ('unanswerable' — a hole in the deploy log). Off by default: an unanswerable question is reported, not guessed.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
+const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-rerun-needed", "Only specs the hub answers `rerunNeeded` for: the audit cleared them, and their last result does not cover what is deployed. A spec whose audit has not caught up answers `inProgress`, and one the audit rejected or whose last run failed answers `needsRepair`; neither is taken, because running them races the audit or repairs nothing. No git diff involved. Requires a hub connection and --hub-profile.").option("--only-hub-rerun-needed-with-unknown", "With --only-hub-rerun-needed: also take specs the hub cannot answer for at all ('unanswerable' — a hole in the deploy log). Off by default: an unanswerable question is reported, not guessed.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Specs in the same `serialGroups` entry of .ccqa/config.yaml still take turns. Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
 	const n = Number(raw);
 	if (!Number.isFinite(n) || n < 0 || Math.floor(n) !== n) throw new Error(`--live-step-retry must be a non-negative integer, got "${raw}"`);
 	return n;
@@ -13174,23 +13318,22 @@ async function runCliAction(targets, opts) {
 	const cwd = resolveCwd(opts.cwd);
 	const teardown = createRunTeardown();
 	const disposeSignalHandlers = installTeardownSignalHandlers(teardown);
+	let exitCode;
 	try {
-		const result = await executeRun(targets, {
+		exitCode = (await executeRun(targets, {
 			...opts,
 			cwd,
 			teardown
-		});
-		await teardown.run();
-		process.exit(result.exitCode);
+		})).exitCode;
 	} catch (err) {
-		if (err instanceof RunUsageError) {
-			error(err.message);
-			process.exit(err.exitCode);
-		}
-		throw err;
+		if (!(err instanceof RunUsageError)) throw err;
+		error(err.message);
+		exitCode = err.exitCode;
 	} finally {
+		await teardown.run();
 		disposeSignalHandlers();
 	}
+	process.exit(exitCode);
 }
 //#endregion
 //#region src/store/spec-lock.ts

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {