ccqa 1.31.0 → 1.31.1

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

package/dist/hub-client/index.d.mts

@@ -481,8 +481,8 @@ declare const ReportSpecResultSchema: z.ZodObject<{
   title: z.ZodNullable<z.ZodString>;
   target: z.ZodOptional<z.ZodString>;
   mode: z.ZodOptional<z.ZodEnum<{
-    live: "live";
     deterministic: "deterministic";
+    live: "live";
   }>>;
   status: z.ZodEnum<{
     passed: "passed";
@@ -665,8 +665,8 @@ declare const RunReportDataSchema: z.ZodObject<{
     title: z.ZodNullable<z.ZodString>;
     target: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<{
-      live: "live";
       deterministic: "deterministic";
+      live: "live";
     }>>;
     status: z.ZodEnum<{
       passed: "passed";

package/dist/package.json

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