ccqa 1.30.0 → 1.31.1

package/dist/bin/ccqa.mjs

@@ -7537,6 +7537,7 @@ z.object({
 const SpecDriftEntrySchema = z.object({
 	label: DriftLabelSchema.nullable(),
 	surface: DriftSurfaceSchema.optional(),
+	subDiagnosis: DriftSubDiagnosisSchema.optional(),
 	specChangeKind: SpecChangeKindSchema.optional(),
 	confidence: z.number().optional(),
 	headline: z.string().optional(),
@@ -13844,8 +13845,12 @@ function createRunTeardown() {
 * A command must install at most one: a second handler that also exits would
 * race this one and could terminate mid-finalizer. A second signal while
 * tearing down hard-exits immediately rather than waiting.
+*
+* `onSignal` runs synchronously before the teardown starts, so a finalizer
+* can already see which signal is ending the process (e.g. `ccqa record`
+* seals its hub run with a "terminated by signal" note).
 */
-function installTeardownSignalHandlers(teardown) {
+function installTeardownSignalHandlers(teardown, onSignal) {
 	let handling = false;
 	const handler = (sig) => {
 		const code = sig === "SIGINT" ? 130 : 143;
@@ -13854,6 +13859,7 @@ function installTeardownSignalHandlers(teardown) {
 			return;
 		}
 		handling = true;
+		onSignal?.(sig);
 		teardown.run().finally(() => process.exit(code));
 	};
 	const onInt = () => handler("SIGINT");
@@ -14018,6 +14024,16 @@ function generateSessionName() {
 */
 function buildTraceSystemPrompt(input) {
 	const sessionName = input.sessionName ?? generateSessionName();
+	const callerGuidance = input.instruction ? `## Caller Guidance
+
+The caller provided extra guidance for this recording — for example, a drift
+audit's finding about what a previous recording of this spec got wrong. Treat
+it as advice on what to avoid or verify while recording; the spec's steps
+above remain the contract for what to do.
+
+${input.instruction}
+
+` : "";
 	const stepsText = input.steps.map((step) => `### ${step.id} [${step.source}]
 - **Instruction**: ${step.instruction}
 - **Expected**: ${step.expected}`).join("\n\n");
@@ -14405,7 +14421,7 @@ RUN_COMPLETED|passed|<summary>
 RUN_COMPLETED|failed|<summary>
 \`\`\`
 
-## Start
+${callerGuidance}## Start
 
 Begin by clearing cookies, then proceed straight to the first step's instruction.
 
@@ -14881,7 +14897,8 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	const baseSystemPrompt = buildTraceSystemPrompt({
 		title: spec.title,
 		steps: expanded,
-		sessionName
+		sessionName,
+		...opts.instruction ? { instruction: opts.instruction } : {}
 	});
 	const promptBundle = await loadPromptBundleFromHub(opts.hubContext ?? null, "record");
 	if (promptBundle !== null) meta("prompt", promptBundle.loaded.join(" + "));
@@ -14892,7 +14909,7 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	const statusLines = [];
 	let overallStatus = "passed";
 	const traceActions = [];
-	const stepTracker = createStepTracker();
+	const stepTracker = createStepTracker(opts.onStep);
 	const withStepId = (action, stepId) => {
 		if (!action) return null;
 		return stepId ? {
@@ -15234,15 +15251,18 @@ function groupCountByStep(actions) {
 	}
 	return counts;
 }
-function createStepTracker() {
+function createStepTracker(onChange) {
 	let currentStepId;
+	const advance = (stepId) => {
+		if (stepId === currentStepId) return;
+		currentStepId = stepId;
+		onChange?.(stepId);
+	};
 	return {
 		current: () => currentStepId,
-		fromStepStartLine: (stepId) => {
-			currentStepId = stepId;
-		},
+		fromStepStartLine: advance,
 		fromCommand: (stepId) => {
-			if (stepId) currentStepId = stepId;
+			if (stepId) advance(stepId);
 			return currentStepId;
 		}
 	};
@@ -15500,10 +15520,10 @@ async function runGenerateCli(specPath, opts) {
 //#endregion
 //#region src/cli/record.ts
 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("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
+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) {
@@ -15557,20 +15577,48 @@ async function runRecord(specPath, opts) {
 	if (push) info(`hub: record run opened (${push.runId})`);
 	let recorded = false;
 	let sealed = true;
+	let tracingStep;
+	let abortCause;
 	const teardown = createRunTeardown();
 	teardown.onFinalize(async () => {
-		if (push) sealed = await sealRecordPush(push, featureName, specName, recorded);
+		if (!push) return;
+		sealed = await sealRecordPush(push, featureName, specName, recorded, abortCause !== void 0 ? abortNote(abortCause, tracingStep) : void 0);
 	});
-	const disposeSignalHandlers = installTeardownSignalHandlers(teardown);
+	const disposeSignalHandlers = installTeardownSignalHandlers(teardown, (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
+				hubContext,
+				...opts.instruction ? { instruction: opts.instruction } : {},
+				onStep: (stepId) => {
+					tracingStep = stepId;
+				}
 			});
+			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"),
@@ -15585,38 +15633,73 @@ 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
 * whole run — enough for the runs list to say what the money bought.
+*
+* `failureNote` (e.g. "terminated by signal (SIGTERM) during step-03") rides
+* in the row's `failureLogExcerpt` — the field a failed `ccqa run` row already
+* uses for its failure text — so the hub says why a recording died instead of
+* a bare status:"failed". Ignored on a successful recording.
 */
-async function sealRecordPush(push, featureName, specName, recorded) {
+async function sealRecordPush(push, featureName, specName, recorded, failureNote) {
 	return sealHubRun(push, {
-		rows: [emptySpecRow({
-			feature: featureName,
-			spec: specName,
-			title: null,
-			status: recorded ? "passed" : "failed"
-		})],
+		rows: [{
+			...emptySpecRow({
+				feature: featureName,
+				spec: specName,
+				title: null,
+				status: recorded ? "passed" : "failed"
+			}),
+			...!recorded && failureNote ? { failureLogExcerpt: failureNote } : {}
+		}],
 		reportMeta: {
 			git: {
 				head: push.gitHead,
@@ -17457,6 +17540,7 @@ function gradedDriftEntry(ledger, key, runId, label) {
 	};
 	if (label === null) {
 		delete graded.surface;
+		delete graded.subDiagnosis;
 		delete graded.headline;
 		delete graded.confidence;
 	}
@@ -17821,9 +17905,11 @@ async function updateDriftLedger(storage, run, results) {
 		if (row.status === "skipped") continue;
 		const key = `${row.feature}/${row.spec}`;
 		const diagnosis = row.analysis ? normalizeDiagnosis(row.analysis) : null;
+		const subDiagnosis = DriftSubDiagnosisSchema.safeParse(diagnosis?.subDiagnosis);
 		ledger.specs[key] = {
 			label: diagnosis ? diagnosis.label : null,
 			surface: diagnosis?.surface,
+			subDiagnosis: subDiagnosis.success ? subDiagnosis.data : void 0,
 			specChangeKind: diagnosis?.specChangeKind,
 			confidence: diagnosis?.confidence,
 			headline: diagnosis?.headline,

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

@@ -383,6 +383,11 @@ declare const DriftLedgerResponseSchema: z.ZodObject<{
       spec: "spec";
       generated: "generated";
     }>>;
+    subDiagnosis: z.ZodOptional<z.ZodEnum<{
+      OVER_ASSERTION: "OVER_ASSERTION";
+      SELECTOR_DRIFT: "SELECTOR_DRIFT";
+      NONE: "NONE";
+    }>>;
     specChangeKind: z.ZodOptional<z.ZodEnum<{
       FEATURE_REMOVED: "FEATURE_REMOVED";
       BEHAVIOUR_CHANGED: "BEHAVIOUR_CHANGED";
@@ -476,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";
@@ -660,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.30.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.30.0",
+  "version": "1.31.1",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {