ccqa 1.31.0 → 1.31.2

package/dist/bin/ccqa.mjs

@@ -15523,7 +15523,7 @@ const VALIDATION_MODES = ["lenient", "strict"];
 const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--instruction <text>", "Extra guidance for the recording agent — e.g. the drift audit's finding when re-recording a drifted spec.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
 	throw new Error(`--trace-validation must be one of ${VALIDATION_MODES.join(" | ")}`);
-}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").option("--report-to-hub", "Leave a run (kind: record) on the hub saying this spec was recorded and what the recording spent on Claude, so a budget summed over the hub's runs sees it. It advances no ledger: a recording verifies nothing.").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--timeout <seconds>", "Abort the recording after this many seconds, wherever it is (trace, generate, auto-fix): reap the browser session, seal the open hub run (--report-to-hub) with a 'timed out' note, and exit 124. Prefer this over wrapping the command in an external `timeout`, whose SIGTERM may never reach this process.", parseTimeoutSeconds).option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").option("--report-to-hub", "Leave a run (kind: record) on the hub saying this spec was recorded and what the recording spent on Claude, so a budget summed over the hub's runs sees it. It advances no ledger: a recording verifies nothing.").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("record", () => runRecord(specPath, opts));
 }));
 async function runRecord(specPath, opts) {
@@ -15578,21 +15578,29 @@ async function runRecord(specPath, opts) {
 	let recorded = false;
 	let sealed = true;
 	let tracingStep;
-	let killedBy;
+	let abortCause;
 	const teardown = createRunTeardown();
 	teardown.onFinalize(async () => {
 		if (!push) return;
-		const note = killedBy ? `terminated by signal (${killedBy})${tracingStep ? ` during ${tracingStep}` : ""}` : void 0;
-		sealed = await sealRecordPush(push, featureName, specName, recorded, note);
+		sealed = await sealRecordPush(push, featureName, specName, recorded, abortCause !== void 0 ? abortNote(abortCause, tracingStep) : void 0);
 	});
 	const disposeSignalHandlers = installTeardownSignalHandlers(teardown, (sig) => {
-		killedBy = sig;
+		abortCause = `terminated by signal (${sig})`;
 	});
+	let deadline;
+	if (opts.timeout !== void 0) {
+		const seconds = opts.timeout;
+		deadline = setTimeout(() => {
+			abortCause = `timed out after ${seconds}s`;
+			error(`--timeout: ${abortNote(abortCause, tracingStep)}`);
+			teardown.run().finally(() => process.exit(124));
+		}, seconds * 1e3);
+		deadline.unref();
+	}
 	try {
-		let traceResult = null;
 		let generated = true;
 		try {
-			traceResult = await runTrace(featureName, specName, opts.model, opts.traceValidation ?? "lenient", language, {
+			const traceResult = await runTrace(featureName, specName, opts.model, opts.traceValidation ?? "lenient", language, {
 				cwd: cwdForProfile,
 				hubContext,
 				...opts.instruction ? { instruction: opts.instruction } : {},
@@ -15602,6 +15610,15 @@ async function runRecord(specPath, opts) {
 			});
 			tracingStep = void 0;
 			blank();
+			await learnFromTrace({
+				enabled: opts.learnHubTracePrompt === true,
+				featureName,
+				specName,
+				traceResult,
+				hubContext,
+				...opts.model ? { model: opts.model } : {},
+				...language ? { language } : {}
+			});
 			if (!opts.traceOnly) generated = (await runGenerate(featureName, specName, {
 				maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
 				fixMode: toFixMode(opts.autoFix ?? "interactive"),
@@ -15616,25 +15633,52 @@ async function runRecord(specPath, opts) {
 		} finally {
 			await releaseLock();
 		}
-		if (opts.learnHubTracePrompt && traceResult !== null) {
-			blank();
-			await updateAgentPrompt({
-				kind: "record",
-				flag: "--learn-hub-trace-prompt",
-				runSummary: buildRecordRunSummary(featureName, specName, traceResult),
-				hubContext,
-				...opts.model ? { model: opts.model } : {},
-				...language ? { language } : {}
-			});
-		}
 		recorded = generated;
 	} finally {
+		if (deadline !== void 0) clearTimeout(deadline);
 		await teardown.run();
 		disposeSignalHandlers();
 	}
 	if (!sealed) process.exit(2);
 	if (!recorded) process.exit(1);
 }
+/** `--timeout <seconds>`: a positive whole number of seconds. */
+function parseTimeoutSeconds(raw) {
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n <= 0 || Math.floor(n) !== n) throw new Error(`--timeout must be a positive integer number of seconds, got "${raw}"`);
+	return n;
+}
+/**
+* The one line an aborted recording leaves on its hub row: what ended it
+* ("terminated by signal (SIGTERM)", "timed out after 900s") plus the spec
+* step that was tracing, when one was in flight. The signal handlers and the
+* --timeout deadline both seal through this, so every abort dies with the
+* same shape of reason.
+*/
+function abortNote(cause, tracingStep) {
+	return `${cause}${tracingStep !== void 0 ? ` during ${tracingStep}` : ""}`;
+}
+/**
+* The rule for `--learn-hub-trace-prompt`: a browser trace ran → learn from
+* it; no trace → stay silent. `runRecord` calls this immediately after the
+* trace, before generate — sequencing it after the generate/auto-fix half
+* (as record once did) let any death there discard a completed trace's
+* learnings. Returns whether the refresh fired, and takes the updater as a
+* seam so the rule is testable without a browser.
+*/
+async function learnFromTrace(args, update = updateAgentPrompt) {
+	if (!args.enabled || args.traceResult === null) return false;
+	blank();
+	await update({
+		kind: "record",
+		flag: "--learn-hub-trace-prompt",
+		runSummary: buildRecordRunSummary(args.featureName, args.specName, args.traceResult),
+		hubContext: args.hubContext,
+		...args.model !== void 0 ? { model: args.model } : {},
+		...args.language !== void 0 ? { language: args.language } : {}
+	});
+	return true;
+}
 /**
 * Close the record run with the one row this command produced, answering
 * whether it closed. One spec is recorded per invocation, so one row is the
@@ -16443,19 +16487,42 @@ async function fetchAuditNeed(ctx, profile) {
 		throw new RunUsageError(`${FLAG}: could not ask the hub which specs need auditing: ${errMessage(err)}`);
 	}
 }
+/**
+* Specs whose drift-ledger entry is still open. The hub's audit-need answer is
+* deploy-based, and a merged fix changes only the spec tree — no deploy lands
+* on the spec, so the hub would never call it due again and the entry would
+* stay open forever. A drifted spec is due until the audit itself clears it.
+* Unreadable ledger degrades to the deploy-based answer alone: the sweep must
+* not die over the supplementary question.
+*/
+async function fetchStillDrifted(ctx) {
+	try {
+		const ledger = await ctx.hub.getDriftLedger(ctx.project);
+		return new Set(Object.entries(ledger.specs ?? {}).filter(([, entry]) => entry.label != null).map(([key]) => key));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
 /** Worst-known-first, so the line leads with what has never been looked at. */
 const SUMMARY_ORDER = rankedOrder({
 	neverAudited: 0,
-	cannotTell: 1,
-	deployReached: 2,
-	held: 3,
-	current: 4
+	stillDrifted: 1,
+	cannotTell: 2,
+	deployReached: 3,
+	held: 4,
+	current: 5
 });
-function selectSpecsNeedingAudit(targets, report) {
+function selectSpecsNeedingAudit(targets, report, stillDrifted = /* @__PURE__ */ new Set()) {
 	const counts = /* @__PURE__ */ new Map();
 	const selected = [];
 	for (const target of targets) {
-		const need = report.specs[specKey(target)] ?? { because: "neverAudited" };
+		const key = specKey(target);
+		if (stillDrifted.has(key)) {
+			counts.set("stillDrifted", (counts.get("stillDrifted") ?? 0) + 1);
+			selected.push(target);
+			continue;
+		}
+		const need = report.specs[key] ?? { because: "neverAudited" };
 		counts.set(need.because, (counts.get(need.because) ?? 0) + 1);
 		if (needsAudit(need)) selected.push(target);
 	}
@@ -16467,7 +16534,7 @@ function selectSpecsNeedingAudit(targets, report) {
 //#endregion
 //#region src/cli/audit.ts
 const DEFAULT_CONCURRENCY = 3;
-const auditCommand = addProfileOption(addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").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. Costs one model call; specs it cannot decide are audited rather than skipped.").option("--only-hub-audit-needed", "Only specs the hub says a deploy has landed on since the audit last read them. A spec that was never audited is always included, and one the hub cannot answer for is audited rather than skipped. No git diff involved. Requires a hub connection and --hub-profile.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger. A spec it finds drifted answers `needsRepair` to `ccqa run --only-hub-rerun-needed`, and is not run until a person repairs it.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption))).action(withUsageErrors(async (specPath, opts) => {
+const auditCommand = addProfileOption(addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").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. Costs one model call; specs it cannot decide are audited rather than skipped.").option("--only-hub-audit-needed", "Only specs the hub says a deploy has landed on since the audit last read them. A spec that was never audited is always included, one the hub cannot answer for is audited rather than skipped, and one whose drift entry is still open is always re-audited — a merged fix changes only the spec tree, which no deploy answer covers. No git diff involved. Requires a hub connection and --hub-profile.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger. A spec it finds drifted answers `needsRepair` to `ccqa run --only-hub-rerun-needed`, and is not run until a person repairs it.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("audit", () => runAudit(specPath, opts));
 }));
 async function runAudit(specPath, opts) {
@@ -16511,11 +16578,12 @@ async function runAudit(specPath, opts) {
 	}
 	if (opts.onlyHubAuditNeeded) {
 		const total = targets.length;
-		const report = await fetchAuditNeed({
+		const ctx = {
 			hub,
 			project: hubProject
-		}, opts.hubProfile);
-		const selection = selectSpecsNeedingAudit(targets, report);
+		};
+		const [report, stillDrifted] = await Promise.all([fetchAuditNeed(ctx, opts.hubProfile), fetchStillDrifted(ctx)]);
+		const selection = selectSpecsNeedingAudit(targets, report, stillDrifted);
 		targets = selection.selected;
 		if (format === "text") {
 			meta("hub", selection.summary);

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.31.0",
+  "version": "1.31.2",
   "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.31.0",
+  "version": "1.31.2",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {