ccqa-tools 1.37.1 → 1.38.0

package/README.md

@@ -52,8 +52,9 @@ application pays nothing at all.
 | Variable | Meaning |
 | --- | --- |
 | `CCQA_COVERAGE` | `1` to enable. Any other value is a `<runId>.<specId>` and becomes the ambient spec for a process with no inbound request to read — a worker started per spec. |
-| `CCQA_COVERAGE_ENDPOINT` | Where to push. Unset collects in memory and reports nothing. |
-| `CCQA_COVERAGE_TOKEN` | Sent as a bearer token, but the current `ccqa` sink does not check it. For a relay in front of it, or a future endpoint that does. |
+| `CCQA_COVERAGE_ENDPOINT` | Where to push. Defaults to `http://127.0.0.1:4757`, the loopback sink a local `ccqa run --coverage` binds; a deployed application sets its own. |
+| `CCQA_COVERAGE_TOKEN` | Sent as a bearer token. The hub's coverage inbox verifies it; the loopback sink a local run binds does not check it, as before. |
+| `CCQA_COVERAGE_HEADER` | One extra `name:value` header sent with every push, for a load balancer that gates the endpoint on a header. |
 | `CCQA_COVERAGE_ROOT` | Root that file ids are relative to. Defaults to `process.cwd()`. In a workspace, point it at a directory containing the sibling packages too, and give `ccqa` the same one through `coverage.projectRoot`. |
 | `CCQA_COVERAGE_INCLUDE` | Comma-separated directories to instrument, relative to the root. Defaults to `src`. |
 | `CCQA_COVERAGE_DEBUG` | `1` for diagnostics on stderr. |

package/dist/coverage/collector.cjs

@@ -26,6 +26,17 @@ function closeActorBucket(runtime, key) {
 function armGate(runtime) {
 	runtime.active = runtime.buckets.size + runtime.actors.size;
 }
+/**
+* Sent as a bearer token. The hub's coverage inbox verifies it; the loopback
+* sink a local run binds does not check it, as before — there it is carried
+* for a relay in front of the sink.
+*/
+const ENV_TOKEN = "CCQA_COVERAGE_TOKEN";
+/**
+* One extra `name:value` header sent with every push, for a load balancer
+* that gates the endpoint on a header.
+*/
+const ENV_HEADER = "CCQA_COVERAGE_HEADER";
 //#endregion
 //#region src/coverage/runtime-env.ts
 /**
@@ -48,6 +59,42 @@ function debugLog(config, message) {
 * that commutative, associative and idempotent, so the sink never has to know
 * how many replicas there were.
 */
+/** The loopback inbox a local `ccqa run --coverage` binds — its default too. */
+const DEFAULT_ENDPOINT = "http://127.0.0.1:4757";
+/**
+* Env → options, at register time. The endpoint defaults to the run's
+* loopback inbox, so a local stack needs no endpoint configuration at all;
+* only a deployed environment writes one.
+*/
+function collectorOptionsFromEnv(env, config) {
+	const endpoint = env["CCQA_COVERAGE_ENDPOINT"] || "http://127.0.0.1:4757";
+	if (config && !env["CCQA_COVERAGE_ENDPOINT"]) debugLog(config, `endpoint defaulted to ${DEFAULT_ENDPOINT}`);
+	return {
+		endpoint,
+		token: env[ENV_TOKEN],
+		header: parseHeader(env[ENV_HEADER])
+	};
+}
+/**
+* `name:value` for the one extra push header, split on the first colon so the
+* value may contain more. Malformed input is warned about rather than silently
+* dropped: the header exists to pass a gateway, and a push missing it fails
+* looking exactly like an unreachable sink. The value may be a gateway secret,
+* so the warning names the variable and never echoes its content.
+*/
+function parseHeader(raw) {
+	if (!raw) return void 0;
+	const colon = raw.indexOf(":");
+	const name = colon < 0 ? "" : raw.slice(0, colon).trim();
+	if (name === "") {
+		process.stderr.write(`[ccqa-tools] ignoring ${ENV_HEADER}: expected "name:value"\n`);
+		return;
+	}
+	return {
+		name,
+		value: raw.slice(colon + 1).trim()
+	};
+}
 const DEFAULT_INTERVAL_MS = 1e3;
 const DEFAULT_IDLE_TTL_MS = 12e4;
 /**
@@ -113,7 +160,7 @@ function startCollector(options, config) {
 			state.droppedPushes++;
 			consecutiveFailures++;
 			if (config) debugLog(config, `push failed: ${String(error)}`);
-			if (consecutiveFailures === 1 || consecutiveFailures % 10 === 0) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
+			if (shouldWarnPushFailure(consecutiveFailures)) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
 		}).finally(() => {
 			inFlight = false;
 		});
@@ -133,6 +180,15 @@ function startCollector(options, config) {
 	};
 }
 /**
+* Which consecutive-failure counts warn: 1, 10, 100, then every 1000th.
+* Backing off rather than a fixed every-10: the endpoint now has a default,
+* so a deployed process whose endpoint was never configured fails every tick
+* for its whole life — a permanent once-per-ten-seconds drone, not a burst.
+*/
+function shouldWarnPushFailure(consecutiveFailures) {
+	return consecutiveFailures === 1 || consecutiveFailures === 10 || consecutiveFailures === 100 || consecutiveFailures % 1e3 === 0;
+}
+/**
 * `acked` is always a subset of `reached`, and neither ever shrinks, so equal
 * sizes mean nothing new — skip the copy-then-filter and check that first.
 */
@@ -213,6 +269,7 @@ function dropQuiet(entries, sent, state, cutoff, now, close) {
 async function post(options, payload) {
 	const headers = { "content-type": "application/json" };
 	if (options.token) headers.authorization = `Bearer ${options.token}`;
+	if (options.header) headers[options.header.name] = options.header.value;
 	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
 	const response = await fetch(options.endpoint, {
 		method: "POST",
@@ -223,7 +280,11 @@ async function post(options, payload) {
 	if (!response.ok) throw new Error(`sink returned ${response.status}`);
 }
 //#endregion
+exports.DEFAULT_ENDPOINT = DEFAULT_ENDPOINT;
+exports.collectorOptionsFromEnv = collectorOptionsFromEnv;
 exports.createCollectorState = createCollectorState;
 exports.diff = diff;
 exports.evict = evict;
+exports.parseHeader = parseHeader;
+exports.shouldWarnPushFailure = shouldWarnPushFailure;
 exports.startCollector = startCollector;

package/dist/coverage/collector.d.cts

@@ -117,10 +117,34 @@ interface CoverageConfig {
 interface CollectorOptions {
   endpoint: string;
   token?: string | undefined;
+  /** One extra header on every push, for a gateway in front of the endpoint. */
+  header?: {
+    name: string;
+    value: string;
+  } | undefined;
   intervalMs?: number;
   /** Drops a spec's bucket this long after its last change and last flush. */
   idleTtlMs?: number;
 }
+/** The loopback inbox a local `ccqa run --coverage` binds — its default too. */
+declare const DEFAULT_ENDPOINT = "http://127.0.0.1:4757";
+/**
+ * Env → options, at register time. The endpoint defaults to the run's
+ * loopback inbox, so a local stack needs no endpoint configuration at all;
+ * only a deployed environment writes one.
+ */
+declare function collectorOptionsFromEnv(env: NodeJS.ProcessEnv, config?: CoverageConfig): CollectorOptions;
+/**
+ * `name:value` for the one extra push header, split on the first colon so the
+ * value may contain more. Malformed input is warned about rather than silently
+ * dropped: the header exists to pass a gateway, and a push missing it fails
+ * looking exactly like an unreachable sink. The value may be a gateway secret,
+ * so the warning names the variable and never echoes its content.
+ */
+declare function parseHeader(raw: string | undefined): {
+  name: string;
+  value: string;
+} | undefined;
 interface CoveragePush {
   protocol: 1;
   pid: number;
@@ -171,6 +195,13 @@ interface CollectorState {
 }
 declare function createCollectorState(): CollectorState;
 declare function startCollector(options: CollectorOptions, config?: CoverageConfig): () => void;
+/**
+ * Which consecutive-failure counts warn: 1, 10, 100, then every 1000th.
+ * Backing off rather than a fixed every-10: the endpoint now has a default,
+ * so a deployed process whose endpoint was never configured fails every tick
+ * for its whole life — a permanent once-per-ten-seconds drone, not a burst.
+ */
+declare function shouldWarnPushFailure(consecutiveFailures: number): boolean;
 /** Exported for tests: the sink's HTTP round trip is the only real-I/O part. */
 declare function diff(runtime: CoverageRuntime, state: CollectorState): CoveragePush | undefined;
 /**
@@ -180,4 +211,4 @@ declare function diff(runtime: CoverageRuntime, state: CollectorState): Coverage
  */
 declare function evict(runtime: CoverageRuntime, state: CollectorState, idleTtlMs: number): void;
 //#endregion
-export { CollectorOptions, CollectorState, CoveragePush, createCollectorState, diff, evict, startCollector };
+export { CollectorOptions, CollectorState, CoveragePush, DEFAULT_ENDPOINT, collectorOptionsFromEnv, createCollectorState, diff, evict, parseHeader, shouldWarnPushFailure, startCollector };

package/dist/coverage/collector.d.ts

@@ -117,10 +117,34 @@ interface CoverageConfig {
 interface CollectorOptions {
   endpoint: string;
   token?: string | undefined;
+  /** One extra header on every push, for a gateway in front of the endpoint. */
+  header?: {
+    name: string;
+    value: string;
+  } | undefined;
   intervalMs?: number;
   /** Drops a spec's bucket this long after its last change and last flush. */
   idleTtlMs?: number;
 }
+/** The loopback inbox a local `ccqa run --coverage` binds — its default too. */
+declare const DEFAULT_ENDPOINT = "http://127.0.0.1:4757";
+/**
+ * Env → options, at register time. The endpoint defaults to the run's
+ * loopback inbox, so a local stack needs no endpoint configuration at all;
+ * only a deployed environment writes one.
+ */
+declare function collectorOptionsFromEnv(env: NodeJS.ProcessEnv, config?: CoverageConfig): CollectorOptions;
+/**
+ * `name:value` for the one extra push header, split on the first colon so the
+ * value may contain more. Malformed input is warned about rather than silently
+ * dropped: the header exists to pass a gateway, and a push missing it fails
+ * looking exactly like an unreachable sink. The value may be a gateway secret,
+ * so the warning names the variable and never echoes its content.
+ */
+declare function parseHeader(raw: string | undefined): {
+  name: string;
+  value: string;
+} | undefined;
 interface CoveragePush {
   protocol: 1;
   pid: number;
@@ -171,6 +195,13 @@ interface CollectorState {
 }
 declare function createCollectorState(): CollectorState;
 declare function startCollector(options: CollectorOptions, config?: CoverageConfig): () => void;
+/**
+ * Which consecutive-failure counts warn: 1, 10, 100, then every 1000th.
+ * Backing off rather than a fixed every-10: the endpoint now has a default,
+ * so a deployed process whose endpoint was never configured fails every tick
+ * for its whole life — a permanent once-per-ten-seconds drone, not a burst.
+ */
+declare function shouldWarnPushFailure(consecutiveFailures: number): boolean;
 /** Exported for tests: the sink's HTTP round trip is the only real-I/O part. */
 declare function diff(runtime: CoverageRuntime, state: CollectorState): CoveragePush | undefined;
 /**
@@ -180,4 +211,4 @@ declare function diff(runtime: CoverageRuntime, state: CollectorState): Coverage
  */
 declare function evict(runtime: CoverageRuntime, state: CollectorState, idleTtlMs: number): void;
 //#endregion
-export { CollectorOptions, CollectorState, CoveragePush, createCollectorState, diff, evict, startCollector };
+export { CollectorOptions, CollectorState, CoveragePush, DEFAULT_ENDPOINT, collectorOptionsFromEnv, createCollectorState, diff, evict, parseHeader, shouldWarnPushFailure, startCollector };

package/dist/coverage/collector.js

@@ -25,6 +25,17 @@ function closeActorBucket(runtime, key) {
 function armGate(runtime) {
 	runtime.active = runtime.buckets.size + runtime.actors.size;
 }
+/**
+* Sent as a bearer token. The hub's coverage inbox verifies it; the loopback
+* sink a local run binds does not check it, as before — there it is carried
+* for a relay in front of the sink.
+*/
+const ENV_TOKEN = "CCQA_COVERAGE_TOKEN";
+/**
+* One extra `name:value` header sent with every push, for a load balancer
+* that gates the endpoint on a header.
+*/
+const ENV_HEADER = "CCQA_COVERAGE_HEADER";
 //#endregion
 //#region src/coverage/runtime-env.ts
 /**
@@ -47,6 +58,42 @@ function debugLog(config, message) {
 * that commutative, associative and idempotent, so the sink never has to know
 * how many replicas there were.
 */
+/** The loopback inbox a local `ccqa run --coverage` binds — its default too. */
+const DEFAULT_ENDPOINT = "http://127.0.0.1:4757";
+/**
+* Env → options, at register time. The endpoint defaults to the run's
+* loopback inbox, so a local stack needs no endpoint configuration at all;
+* only a deployed environment writes one.
+*/
+function collectorOptionsFromEnv(env, config) {
+	const endpoint = env["CCQA_COVERAGE_ENDPOINT"] || "http://127.0.0.1:4757";
+	if (config && !env["CCQA_COVERAGE_ENDPOINT"]) debugLog(config, `endpoint defaulted to ${DEFAULT_ENDPOINT}`);
+	return {
+		endpoint,
+		token: env[ENV_TOKEN],
+		header: parseHeader(env[ENV_HEADER])
+	};
+}
+/**
+* `name:value` for the one extra push header, split on the first colon so the
+* value may contain more. Malformed input is warned about rather than silently
+* dropped: the header exists to pass a gateway, and a push missing it fails
+* looking exactly like an unreachable sink. The value may be a gateway secret,
+* so the warning names the variable and never echoes its content.
+*/
+function parseHeader(raw) {
+	if (!raw) return void 0;
+	const colon = raw.indexOf(":");
+	const name = colon < 0 ? "" : raw.slice(0, colon).trim();
+	if (name === "") {
+		process.stderr.write(`[ccqa-tools] ignoring ${ENV_HEADER}: expected "name:value"\n`);
+		return;
+	}
+	return {
+		name,
+		value: raw.slice(colon + 1).trim()
+	};
+}
 const DEFAULT_INTERVAL_MS = 1e3;
 const DEFAULT_IDLE_TTL_MS = 12e4;
 /**
@@ -112,7 +159,7 @@ function startCollector(options, config) {
 			state.droppedPushes++;
 			consecutiveFailures++;
 			if (config) debugLog(config, `push failed: ${String(error)}`);
-			if (consecutiveFailures === 1 || consecutiveFailures % 10 === 0) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
+			if (shouldWarnPushFailure(consecutiveFailures)) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
 		}).finally(() => {
 			inFlight = false;
 		});
@@ -132,6 +179,15 @@ function startCollector(options, config) {
 	};
 }
 /**
+* Which consecutive-failure counts warn: 1, 10, 100, then every 1000th.
+* Backing off rather than a fixed every-10: the endpoint now has a default,
+* so a deployed process whose endpoint was never configured fails every tick
+* for its whole life — a permanent once-per-ten-seconds drone, not a burst.
+*/
+function shouldWarnPushFailure(consecutiveFailures) {
+	return consecutiveFailures === 1 || consecutiveFailures === 10 || consecutiveFailures === 100 || consecutiveFailures % 1e3 === 0;
+}
+/**
 * `acked` is always a subset of `reached`, and neither ever shrinks, so equal
 * sizes mean nothing new — skip the copy-then-filter and check that first.
 */
@@ -212,6 +268,7 @@ function dropQuiet(entries, sent, state, cutoff, now, close) {
 async function post(options, payload) {
 	const headers = { "content-type": "application/json" };
 	if (options.token) headers.authorization = `Bearer ${options.token}`;
+	if (options.header) headers[options.header.name] = options.header.value;
 	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
 	const response = await fetch(options.endpoint, {
 		method: "POST",
@@ -222,4 +279,4 @@ async function post(options, payload) {
 	if (!response.ok) throw new Error(`sink returned ${response.status}`);
 }
 //#endregion
-export { createCollectorState, diff, evict, startCollector };
+export { DEFAULT_ENDPOINT, collectorOptionsFromEnv, createCollectorState, diff, evict, parseHeader, shouldWarnPushFailure, startCollector };

package/dist/coverage/register.cjs

@@ -156,10 +156,17 @@ const BAGGAGE_KEY = "ccqa.coverage";
 * inbound request to read, such as a worker started per spec.
 */
 const ENV_NAME = "CCQA_COVERAGE";
-/** Where the collector pushes to. Unset means collect in memory only. */
-const ENV_ENDPOINT = "CCQA_COVERAGE_ENDPOINT";
-/** The current ccqa sink does not check this. Carried for a relay in front of it, or a future endpoint that does. */
+/**
+* Sent as a bearer token. The hub's coverage inbox verifies it; the loopback
+* sink a local run binds does not check it, as before — there it is carried
+* for a relay in front of the sink.
+*/
 const ENV_TOKEN = "CCQA_COVERAGE_TOKEN";
+/**
+* One extra `name:value` header sent with every push, for a load balancer
+* that gates the endpoint on a header.
+*/
+const ENV_HEADER = "CCQA_COVERAGE_HEADER";
 const SPEC_ID = /^[A-Za-z0-9._\-/]{1,200}$/;
 /**
 * Accepts a carrier value only if it looks like an id we wrote.
@@ -236,6 +243,42 @@ function debugLog(config, message) {
 * that commutative, associative and idempotent, so the sink never has to know
 * how many replicas there were.
 */
+/** The loopback inbox a local `ccqa run --coverage` binds — its default too. */
+const DEFAULT_ENDPOINT = "http://127.0.0.1:4757";
+/**
+* Env → options, at register time. The endpoint defaults to the run's
+* loopback inbox, so a local stack needs no endpoint configuration at all;
+* only a deployed environment writes one.
+*/
+function collectorOptionsFromEnv(env, config) {
+	const endpoint = env["CCQA_COVERAGE_ENDPOINT"] || "http://127.0.0.1:4757";
+	if (config && !env["CCQA_COVERAGE_ENDPOINT"]) debugLog(config, `endpoint defaulted to ${DEFAULT_ENDPOINT}`);
+	return {
+		endpoint,
+		token: env[ENV_TOKEN],
+		header: parseHeader(env[ENV_HEADER])
+	};
+}
+/**
+* `name:value` for the one extra push header, split on the first colon so the
+* value may contain more. Malformed input is warned about rather than silently
+* dropped: the header exists to pass a gateway, and a push missing it fails
+* looking exactly like an unreachable sink. The value may be a gateway secret,
+* so the warning names the variable and never echoes its content.
+*/
+function parseHeader(raw) {
+	if (!raw) return void 0;
+	const colon = raw.indexOf(":");
+	const name = colon < 0 ? "" : raw.slice(0, colon).trim();
+	if (name === "") {
+		process.stderr.write(`[ccqa-tools] ignoring ${ENV_HEADER}: expected "name:value"\n`);
+		return;
+	}
+	return {
+		name,
+		value: raw.slice(colon + 1).trim()
+	};
+}
 const DEFAULT_INTERVAL_MS = 1e3;
 const DEFAULT_IDLE_TTL_MS = 12e4;
 /**
@@ -301,7 +344,7 @@ function startCollector(options, config) {
 			state.droppedPushes++;
 			consecutiveFailures++;
 			if (config) debugLog(config, `push failed: ${String(error)}`);
-			if (consecutiveFailures === 1 || consecutiveFailures % 10 === 0) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
+			if (shouldWarnPushFailure(consecutiveFailures)) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
 		}).finally(() => {
 			inFlight = false;
 		});
@@ -321,6 +364,15 @@ function startCollector(options, config) {
 	};
 }
 /**
+* Which consecutive-failure counts warn: 1, 10, 100, then every 1000th.
+* Backing off rather than a fixed every-10: the endpoint now has a default,
+* so a deployed process whose endpoint was never configured fails every tick
+* for its whole life — a permanent once-per-ten-seconds drone, not a burst.
+*/
+function shouldWarnPushFailure(consecutiveFailures) {
+	return consecutiveFailures === 1 || consecutiveFailures === 10 || consecutiveFailures === 100 || consecutiveFailures % 1e3 === 0;
+}
+/**
 * `acked` is always a subset of `reached`, and neither ever shrinks, so equal
 * sizes mean nothing new — skip the copy-then-filter and check that first.
 */
@@ -401,6 +453,7 @@ function dropQuiet(entries, sent, state, cutoff, now, close) {
 async function post(options, payload) {
 	const headers = { "content-type": "application/json" };
 	if (options.token) headers.authorization = `Bearer ${options.token}`;
+	if (options.header) headers[options.header.name] = options.header.value;
 	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
 	const response = await fetch(options.endpoint, {
 		method: "POST",
@@ -707,12 +760,7 @@ if (config.enabled) {
 			files
 		});
 	}
-	const endpoint = process.env[ENV_ENDPOINT];
-	if (endpoint) startCollector({
-		endpoint,
-		token: process.env[ENV_TOKEN]
-	}, config);
-	else process.stderr.write(`[ccqa-tools] collection is enabled but ${ENV_ENDPOINT} is not set; results will be discarded\n`);
+	startCollector(collectorOptionsFromEnv(process.env, config), config);
 	debugLog(config, `armed in pid ${process.pid}`);
 }
 /**

package/dist/coverage/register.js

@@ -131,10 +131,17 @@ const BAGGAGE_KEY = "ccqa.coverage";
 * inbound request to read, such as a worker started per spec.
 */
 const ENV_NAME = "CCQA_COVERAGE";
-/** Where the collector pushes to. Unset means collect in memory only. */
-const ENV_ENDPOINT = "CCQA_COVERAGE_ENDPOINT";
-/** The current ccqa sink does not check this. Carried for a relay in front of it, or a future endpoint that does. */
+/**
+* Sent as a bearer token. The hub's coverage inbox verifies it; the loopback
+* sink a local run binds does not check it, as before — there it is carried
+* for a relay in front of the sink.
+*/
 const ENV_TOKEN = "CCQA_COVERAGE_TOKEN";
+/**
+* One extra `name:value` header sent with every push, for a load balancer
+* that gates the endpoint on a header.
+*/
+const ENV_HEADER = "CCQA_COVERAGE_HEADER";
 const SPEC_ID = /^[A-Za-z0-9._\-/]{1,200}$/;
 /**
 * Accepts a carrier value only if it looks like an id we wrote.
@@ -211,6 +218,42 @@ function debugLog(config, message) {
 * that commutative, associative and idempotent, so the sink never has to know
 * how many replicas there were.
 */
+/** The loopback inbox a local `ccqa run --coverage` binds — its default too. */
+const DEFAULT_ENDPOINT = "http://127.0.0.1:4757";
+/**
+* Env → options, at register time. The endpoint defaults to the run's
+* loopback inbox, so a local stack needs no endpoint configuration at all;
+* only a deployed environment writes one.
+*/
+function collectorOptionsFromEnv(env, config) {
+	const endpoint = env["CCQA_COVERAGE_ENDPOINT"] || "http://127.0.0.1:4757";
+	if (config && !env["CCQA_COVERAGE_ENDPOINT"]) debugLog(config, `endpoint defaulted to ${DEFAULT_ENDPOINT}`);
+	return {
+		endpoint,
+		token: env[ENV_TOKEN],
+		header: parseHeader(env[ENV_HEADER])
+	};
+}
+/**
+* `name:value` for the one extra push header, split on the first colon so the
+* value may contain more. Malformed input is warned about rather than silently
+* dropped: the header exists to pass a gateway, and a push missing it fails
+* looking exactly like an unreachable sink. The value may be a gateway secret,
+* so the warning names the variable and never echoes its content.
+*/
+function parseHeader(raw) {
+	if (!raw) return void 0;
+	const colon = raw.indexOf(":");
+	const name = colon < 0 ? "" : raw.slice(0, colon).trim();
+	if (name === "") {
+		process.stderr.write(`[ccqa-tools] ignoring ${ENV_HEADER}: expected "name:value"\n`);
+		return;
+	}
+	return {
+		name,
+		value: raw.slice(colon + 1).trim()
+	};
+}
 const DEFAULT_INTERVAL_MS = 1e3;
 const DEFAULT_IDLE_TTL_MS = 12e4;
 /**
@@ -276,7 +319,7 @@ function startCollector(options, config) {
 			state.droppedPushes++;
 			consecutiveFailures++;
 			if (config) debugLog(config, `push failed: ${String(error)}`);
-			if (consecutiveFailures === 1 || consecutiveFailures % 10 === 0) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
+			if (shouldWarnPushFailure(consecutiveFailures)) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
 		}).finally(() => {
 			inFlight = false;
 		});
@@ -296,6 +339,15 @@ function startCollector(options, config) {
 	};
 }
 /**
+* Which consecutive-failure counts warn: 1, 10, 100, then every 1000th.
+* Backing off rather than a fixed every-10: the endpoint now has a default,
+* so a deployed process whose endpoint was never configured fails every tick
+* for its whole life — a permanent once-per-ten-seconds drone, not a burst.
+*/
+function shouldWarnPushFailure(consecutiveFailures) {
+	return consecutiveFailures === 1 || consecutiveFailures === 10 || consecutiveFailures === 100 || consecutiveFailures % 1e3 === 0;
+}
+/**
 * `acked` is always a subset of `reached`, and neither ever shrinks, so equal
 * sizes mean nothing new — skip the copy-then-filter and check that first.
 */
@@ -376,6 +428,7 @@ function dropQuiet(entries, sent, state, cutoff, now, close) {
 async function post(options, payload) {
 	const headers = { "content-type": "application/json" };
 	if (options.token) headers.authorization = `Bearer ${options.token}`;
+	if (options.header) headers[options.header.name] = options.header.value;
 	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
 	const response = await fetch(options.endpoint, {
 		method: "POST",
@@ -682,12 +735,7 @@ if (config.enabled) {
 			files
 		});
 	}
-	const endpoint = process.env[ENV_ENDPOINT];
-	if (endpoint) startCollector({
-		endpoint,
-		token: process.env[ENV_TOKEN]
-	}, config);
-	else process.stderr.write(`[ccqa-tools] collection is enabled but ${ENV_ENDPOINT} is not set; results will be discarded\n`);
+	startCollector(collectorOptionsFromEnv(process.env, config), config);
 	debugLog(config, `armed in pid ${process.pid}`);
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa-tools",
-  "version": "1.37.1",
+  "version": "1.38.0",
   "type": "module",
   "description": "Instrumentation the application under test installs, for ccqa. Currently: per-spec reach coverage.",
   "repository": {