ccqa 1.29.0 → 1.31.0

package/dist/bin/ccqa.mjs

@@ -871,10 +871,12 @@ function cloudProviderEnabled() {
 /**
 * Probe whether the host has any credential the Anthropic SDK can pick up:
 *   1. ANTHROPIC_API_KEY env var (CI / scripted use)
-*   2. CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX (cloud-provider
+*   2. CLAUDE_CODE_OAUTH_TOKEN env var (a long-lived subscription token from
+*      `claude setup-token`, the headless-CI counterpart of a login)
+*   3. CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX (cloud-provider
 *      endpoints authenticated by the cloud SDK's credential chain)
-*   3. ~/.claude/.credentials.json (Claude Code login, file-based platforms)
-*   4. macOS Keychain item "Claude Code-credentials" (Claude Code login on
+*   4. ~/.claude/.credentials.json (Claude Code login, file-based platforms)
+*   5. macOS Keychain item "Claude Code-credentials" (Claude Code login on
 *      darwin stores the OAuth credentials in the Keychain, not on disk)
 *
 * Claude-driven hooks are opt-in, so the caller only consults this after the
@@ -882,14 +884,16 @@ function cloudProviderEnabled() {
 * that surfaces as "analysis skipped".
 */
 function driftAuthAvailable() {
-	const key = process.env["ANTHROPIC_API_KEY"];
-	if (typeof key === "string" && key.length > 0) return { ok: true };
+	for (const key of ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"]) {
+		const value = process.env[key];
+		if (typeof value === "string" && value.length > 0) return { ok: true };
+	}
 	if (cloudProviderEnabled()) return { ok: true };
 	if (existsSync(join(homedir(), ".claude", ".credentials.json"))) return { ok: true };
 	if (process.platform === "darwin" && keychainHasClaudeCredentials()) return { ok: true };
 	return {
 		ok: false,
-		reason: "no ANTHROPIC_API_KEY / Bedrock or Vertex env / claude login"
+		reason: "no ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN / Bedrock or Vertex env / claude login"
 	};
 }
 /**
@@ -1509,18 +1513,27 @@ function resolveModel(explicit) {
 * - `ANTHROPIC_AUTH_TOKEN`    — sent as `Authorization: Bearer <token>`.
 * - `ANTHROPIC_API_KEY`       — API key, when used instead of a token.
 * - `ANTHROPIC_CUSTOM_HEADERS` — extra request headers.
+* - `CLAUDE_CODE_OAUTH_TOKEN` — long-lived subscription token from
+*   `claude setup-token`, the headless-CI counterpart of a login.
 */
 const ENDPOINT_ENV_KEYS = [
 	"ANTHROPIC_BASE_URL",
 	"ANTHROPIC_AUTH_TOKEN",
 	"ANTHROPIC_API_KEY",
-	"ANTHROPIC_CUSTOM_HEADERS"
+	"ANTHROPIC_CUSTOM_HEADERS",
+	"CLAUDE_CODE_OAUTH_TOKEN"
 ];
 /**
 * Collects the endpoint/auth variables set in the current process environment
 * so they can be forwarded, verbatim, to every Claude Code invocation. Returns
 * only the keys that are actually set (non-empty), so unset variables never
 * override the SDK's own defaults.
+*
+* When both credentials are present the OAuth token wins and the API key is
+* not forwarded. Left to the CLI the API key would win, which makes "switch a
+* CI job to the subscription token" require unwiring the key everywhere; with
+* the precedence here, adding the one variable is the whole switch, and
+* removing it is the whole rollback.
 */
 function resolveEndpointEnv() {
 	const endpointEnv = {};
@@ -1528,6 +1541,7 @@ function resolveEndpointEnv() {
 		const value = process.env[key];
 		if (value && value.length > 0) endpointEnv[key] = value;
 	}
+	if (endpointEnv["CLAUDE_CODE_OAUTH_TOKEN"]) delete endpointEnv["ANTHROPIC_API_KEY"];
 	return endpointEnv;
 }
 /**
@@ -7523,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(),
@@ -13830,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;
@@ -13840,6 +13859,7 @@ function installTeardownSignalHandlers(teardown) {
 			return;
 		}
 		handling = true;
+		onSignal?.(sig);
 		teardown.run().finally(() => process.exit(code));
 	};
 	const onInt = () => handler("SIGINT");
@@ -14004,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");
@@ -14391,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.
 
@@ -14867,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(" + "));
@@ -14878,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 ? {
@@ -15220,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;
 		}
 	};
@@ -15486,7 +15520,7 @@ 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) => {
@@ -15543,19 +15577,30 @@ async function runRecord(specPath, opts) {
 	if (push) info(`hub: record run opened (${push.runId})`);
 	let recorded = false;
 	let sealed = true;
+	let tracingStep;
+	let killedBy;
 	const teardown = createRunTeardown();
 	teardown.onFinalize(async () => {
-		if (push) sealed = await sealRecordPush(push, featureName, specName, recorded);
+		if (!push) return;
+		const note = killedBy ? `terminated by signal (${killedBy})${tracingStep ? ` during ${tracingStep}` : ""}` : void 0;
+		sealed = await sealRecordPush(push, featureName, specName, recorded, note);
+	});
+	const disposeSignalHandlers = installTeardownSignalHandlers(teardown, (sig) => {
+		killedBy = sig;
 	});
-	const disposeSignalHandlers = installTeardownSignalHandlers(teardown);
 	try {
 		let traceResult = null;
 		let generated = true;
 		try {
 			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();
 			if (!opts.traceOnly) generated = (await runGenerate(featureName, specName, {
 				maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
@@ -15594,15 +15639,23 @@ async function runRecord(specPath, opts) {
 * 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,
@@ -17443,6 +17496,7 @@ function gradedDriftEntry(ledger, key, runId, label) {
 	};
 	if (label === null) {
 		delete graded.surface;
+		delete graded.subDiagnosis;
 		delete graded.headline;
 		delete graded.confidence;
 	}
@@ -17807,9 +17861,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

@@ -35,9 +35,9 @@ declare const RunSchema: z.ZodObject<{
     running: "running";
   }>;
   kind: z.ZodDefault<z.ZodEnum<{
-    record: "record";
     run: "run";
     drift: "drift";
+    record: "record";
   }>>;
   drift: z.ZodDefault<z.ZodNullable<z.ZodObject<{
     specs: z.ZodNumber;
@@ -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";
@@ -621,9 +626,9 @@ type ReportSpecResult = z.infer<typeof ReportSpecResultSchema>;
 declare const RunReportDataSchema: z.ZodObject<{
   schemaVersion: z.ZodLiteral<1>;
   kind: z.ZodDefault<z.ZodEnum<{
-    record: "record";
     run: "run";
     drift: "drift";
+    record: "record";
   }>>;
   createdAt: z.ZodString;
   runId: z.ZodNullable<z.ZodString>;

package/dist/package.json

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