@sagentix-inc/evidence-collector 0.2.1 → 0.3.0

package/collector/src/cli.js

@@ -2,19 +2,22 @@
 // Sagentix evidence collector. Reads the customer's systems read-only, runs checks, signs the result
 // with an Ed25519 key and pushes it OUT to sos-app. `run` never listens for connections (only the one-time
 // `google-login` takes one redirect on 127.0.0.1), and sos-app never holds the customer's credentials.
+// Every run also checks in (a signed update may be named) and sends a run report; a source that fails
+// becomes skipped results and the run goes on (apps/sos-app/docs/COLLECTOR_CHANNEL.md).
 //
 //   collector keygen [--out <path>]
 //   collector run --config collector.config.json [any option below, which overrides the file]
+//   collector agent --config collector.config.json   stays connected (outbound WebSocket); runs when sos-app asks
 //   collector config-schema                  prints the JSON schema of the config file
 //   collector google-login --client <client JSON> [--token <file>]   one-time Google Workspace sign-in
 //   collector run --endpoint <url> --key-id <id> [--key <pem> | env SAGENTIX_COLLECTOR_KEY]
 //                 --source cloudflare[,...] [source options] [--catalog <dir>] [--dry-run] [--out <file>]
 //                 [--fedramp-target <id> [--class A|B|C|D]]
 //
-// Exit codes: 0 sent (or dry run), 1 error (bad key, network), 2 usage, 3 nothing to send,
-// 4 sos-app refused the push (its message is printed).
+// Exit codes: 0 sent (or dry run), 1 error (bad key, network, a source that failed), 2 usage, 3 nothing to send,
+// 4 sos-app refused the push (its message is printed); `agent` only: 75 a signed update was written, restart me.
 import { readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { DEFAULT_CATALOG_DIR, loadCatalog } from "./catalog.js";
@@ -25,9 +28,13 @@ import { CONFIG_SCHEMA, loadConfig } from "./config.js";
 import { googleLogin } from "./google_login.js";
 import { V1_COLLECT_PATH, v1Payload } from "./v1/index.js";
 import { CLASSES } from "./v1/rules.js";
+import { EXIT_UPDATE, checkin, detectRunner, modeOf } from "./channel.js";
+import { RunRecorder, buildReport, deliverReport } from "./report.js";
+import { agent } from "./agent.js";
 export const COLLECT_PATH = "/api/collect";
 export const KEY_ENV = "SAGENTIX_COLLECTOR_KEY";
-export const EXIT = { ok: 0, error: 1, usage: 2, nothing: 3, refused: 4 };
+/** `update` (75) is the agent's only: it wrote a signed update and exits so it is restarted on it. */
+export const EXIT = { ok: 0, error: 1, usage: 2, nothing: 3, refused: 4, update: EXIT_UPDATE };
 export function defaultDeps() {
     return {
         fetch: globalThis.fetch,
@@ -57,6 +64,7 @@ function usage(sources) {
     return `usage:
   collector keygen [--out sagentix-collector.pem]
   collector run --config collector.config.json [options that override the file]
+  collector agent --config collector.config.json   (stays connected to sos-app; runs when it asks)
   collector config-schema
   collector google-login --client <Desktop app client JSON> [--token sagentix-google-token.json] [--port <n>] [--login-hint <email>] [--no-browser]
   collector run --endpoint <url> --key-id <id> [--key <pem file>] --source ${sources.map((s) => s.name).join("|")}[,...]
@@ -65,7 +73,12 @@ function usage(sources) {
   The private key may come from ${KEY_ENV} (PEM text) instead of --key.
   Source options:
 ${opts.join("\n")}
-  Exit codes: 0 sent or dry run, 1 error, 2 usage, 3 nothing to send, 4 sos-app refused the push.`;
+  Every run checks in first (an update sos-app names is taken only with a valid Sagentix release signature, and only
+  as sagentix-collector.ref or .image beside the config, read on the next start) and ends by writing
+  sagentix-run-report.json beside the config and sending it (a dry run writes it only).
+  A source that fails gives skipped results; the run goes on, pushes the rest and exits 1.
+  Exit codes: 0 sent or dry run, 1 error (or a source failed), 2 usage, 3 nothing to send, 4 sos-app refused the push;
+  agent only: 75 a signed update was written (after any run in progress ended), so restart it on the new code.`;
 }
 /** https, or http on localhost; a bare origin gets the collect path appended. */
 export function collectUrl(endpoint, path = COLLECT_PATH) {
@@ -103,6 +116,9 @@ function serverMessage(text) {
     }
 }
 export async function run(argv, deps) {
+    // Every line the run writes to stderr also goes into its report (scrubbed there).
+    const rec = new RunRecorder(deps.now);
+    deps = { ...deps, err: rec.tee(deps.err) };
     const sourceOptions = {};
     for (const s of deps.sources) {
         for (const [n, o] of Object.entries(s.options)) {
@@ -119,6 +135,7 @@ export async function run(argv, deps) {
         deps.err(`${e.message}\n${usage(deps.sources)}`);
         return EXIT.usage;
     }
+    const configPath = typeof values.config === "string" ? values.config : undefined;
     if (typeof values.config === "string") {
         const c = loadConfig(values.config, deps.sources);
         if ("problems" in c) {
@@ -192,99 +209,149 @@ export async function run(argv, deps) {
         return EXIT.usage;
     }
     const catalog = loadCatalog(typeof values.catalog === "string" ? values.catalog : DEFAULT_CATALOG_DIR);
-    // Run every chosen source, then keep only what the server will accept.
-    const now = deps.now();
-    const raw = [];
-    for (const s of chosen) {
-        const got = await s.run({ opts: values, env: deps.env, clients: deps.clients, now, warn: deps.err });
-        const stray = got.filter((r) => !s.emits.includes(r.check)).map((r) => r.check);
-        if (stray.length)
-            deps.err(`warning: source ${s.name} emitted checks it does not declare: ${[...new Set(stray)].join(", ")}`);
-        raw.push(...got);
+    // From here on every run ends with a report; the check-in comes first, before any source reads.
+    const runner = detectRunner(deps.env), mode = modeOf(deps.env);
+    const dir = configPath ? dirname(resolve(configPath)) : (deps.cwd ?? process.cwd());
+    const channel = pem && keyId
+        ? { origin: new URL(url).origin, keyId, pem, fetch: deps.channel ?? deps.fetch, dir, runner, mode, env: deps.env, now: deps.now }
+        : undefined;
+    if (channel)
+        rec.note("checkin", (await checkin(channel, { write: !dry, log: deps.err })).warnings);
+    else
+        deps.err("check-in skipped: a dry run without a key cannot sign one.");
+    let code;
+    try {
+        code = await collect();
     }
-    const vetted = vet(raw, catalog);
-    if (vetted.unknown.length)
-        deps.err(`refused (not in the catalogue at ${typeof values.catalog === "string" ? values.catalog : DEFAULT_CATALOG_DIR}): ${vetted.unknown.join(", ")}`);
-    if (vetted.duplicates.length)
-        deps.err(`dropped duplicate results: ${vetted.duplicates.slice(0, 10).join(", ")}`);
-    const results = vetted.results;
-    const skipped = results.filter((r) => r.result === "skipped");
-    if (v1Target && results.length > MAX_RESULTS) {
-        deps.err(`${results.length} results; the v1 push takes at most ${MAX_RESULTS}. Narrow the run (e.g. --zone).`);
-        return EXIT.error;
+    catch (e) {
+        deps.err(`collector error: ${String(e?.message ?? e)}`);
+        code = EXIT.error;
     }
-    const issuedAt = now.toISOString();
-    // One push, or several when the results exceed what sos-app takes at once (5,000 results, 4 MB). Each is signed alone.
-    const pushes = [];
-    if (v1Target) {
-        const cpoUri = typeof values["cpo-uri"] === "string" ? values["cpo-uri"] : new URL(`/api/fedramp/targets/${encodeURIComponent(v1Target)}/export/cpo`, url).toString();
-        const v1 = v1Payload(results, catalog, { targetId: v1Target, cls, issuedAt, cpoUri });
-        if (v1.problems.length) {
-            deps.err(`The SDR is not valid against FedRAMP's schema:\n  ${v1.problems.join("\n  ")}`);
+    await deliverReport(buildReport(rec, { now: deps.now(), exitCode: code, runner, mode, env: deps.env }), { dry, channel, dir, log: deps.err });
+    return code;
+    async function collect() {
+        // Run every chosen source inside a guard, then keep only what the server will accept. A source that throws gives
+        // one skipped result per check it declares, and the run goes on (section 1 of COLLECTOR_CHANNEL.md).
+        const now = deps.now();
+        const raw = [];
+        const failed = [];
+        for (const s of chosen) {
+            const { value, error, report } = await rec.source(s.name, () => s.run({ opts: values, env: deps.env, clients: deps.clients, now, warn: deps.err }));
+            let got;
+            if (error !== undefined || !Array.isArray(value)) {
+                const message = error !== undefined ? String(error?.message ?? error) : "the source returned no list of results";
+                if (!report.error)
+                    report.error = { message, stack: "" };
+                deps.err(`error in source ${s.name}: ${message}; its ${s.emits.length} checks are sent as skipped and the run goes on.`);
+                failed.push(s.name);
+                got = s.emits.map((check) => ({ check, resource: `the ${s.name} source`, result: "skipped", detail: `collector error in ${s.name}: ${message}` }));
+            }
+            else
+                got = value;
+            const stray = got.filter((r) => !s.emits.includes(r.check)).map((r) => r.check);
+            if (stray.length)
+                deps.err(`warning: source ${s.name} emitted checks it does not declare: ${[...new Set(stray)].join(", ")}`);
+            for (const r of got)
+                report[r.result === "pass" ? "pass" : r.result === "fail" ? "fail" : "skipped"]++;
+            raw.push(...got);
+        }
+        // A failed source makes the run exit 1 once everything else is done, as a failed engine run always has.
+        const done = (c) => (c === EXIT.ok || c === EXIT.nothing) && failed.length ? EXIT.error : c;
+        const vetted = vet(raw, catalog);
+        if (vetted.unknown.length)
+            deps.err(`refused (not in the catalogue at ${typeof values.catalog === "string" ? values.catalog : DEFAULT_CATALOG_DIR}): ${vetted.unknown.join(", ")}`);
+        if (vetted.duplicates.length)
+            deps.err(`dropped duplicate results: ${vetted.duplicates.slice(0, 10).join(", ")}`);
+        const results = vetted.results;
+        const skipped = results.filter((r) => r.result === "skipped");
+        if (v1Target && results.length > MAX_RESULTS) {
+            deps.err(`${results.length} results; the v1 push takes at most ${MAX_RESULTS}. Narrow the run (e.g. --zone).`);
             return EXIT.error;
         }
-        if (!dry && !v1.payload.results.length) {
-            deps.err("Nothing to send: no KSI had a check that passed or failed.");
-            return EXIT.nothing;
+        const issuedAt = now.toISOString();
+        // One push, or several when the results exceed what sos-app takes at once (5,000 results, 4 MB). Each is signed alone.
+        const pushes = [];
+        if (v1Target) {
+            const cpoUri = typeof values["cpo-uri"] === "string" ? values["cpo-uri"] : new URL(`/api/fedramp/targets/${encodeURIComponent(v1Target)}/export/cpo`, url).toString();
+            const v1 = v1Payload(results, catalog, { targetId: v1Target, cls, issuedAt, cpoUri });
+            if (v1.problems.length) {
+                deps.err(`The SDR is not valid against FedRAMP's schema:\n  ${v1.problems.join("\n  ")}`);
+                return EXIT.error;
+            }
+            if (!dry && !v1.payload.results.length) {
+                deps.err("Nothing to send: no KSI had a check that passed or failed.");
+                return done(EXIT.nothing);
+            }
+            const body = new TextEncoder().encode(JSON.stringify(v1.payload));
+            pushes.push({ body, bodyText: new TextDecoder().decode(body), summary: { ksis: v1.payload.results.map((r) => `${r.ksiId} ${r.status}`), omitted: v1.omitted } });
         }
-        const body = new TextEncoder().encode(JSON.stringify(v1.payload));
-        pushes.push({ body, bodyText: new TextDecoder().decode(body), summary: { ksis: v1.payload.results.map((r) => `${r.ksiId} ${r.status}`), omitted: v1.omitted } });
-    }
-    else {
-        const sources = chosen.map((s) => ({ source: s.name, scope: s.describe(values) }));
-        const parts = results.length ? splitResults(results) : [[]];
-        if (parts.length > 1)
-            deps.err(`${results.length} results go out as ${parts.length} signed pushes (sos-app takes at most ${MAX_RESULTS} results or 4 MB per push).`);
-        for (const part of parts) {
-            const body = new TextEncoder().encode(JSON.stringify(buildPayload({ issuedAt, results: part, sources })));
-            pushes.push({ body, bodyText: new TextDecoder().decode(body),
-                summary: { passed: part.filter((r) => r.result === "pass").length, failed: part.filter((r) => r.result === "fail").length, skipped: part.filter((r) => r.result === "skipped").length } });
+        else {
+            const sources = chosen.map((s) => ({ source: s.name, scope: s.describe(values) }));
+            const parts = results.length ? splitResults(results) : [[]];
+            if (parts.length > 1)
+                deps.err(`${results.length} results go out as ${parts.length} signed pushes (sos-app takes at most ${MAX_RESULTS} results or 4 MB per push).`);
+            for (const part of parts) {
+                const body = new TextEncoder().encode(JSON.stringify(buildPayload({ issuedAt, results: part, sources })));
+                pushes.push({ body, bodyText: new TextDecoder().decode(body),
+                    summary: { passed: part.filter((r) => r.result === "pass").length, failed: part.filter((r) => r.result === "fail").length, skipped: part.filter((r) => r.result === "skipped").length } });
+            }
         }
-    }
-    for (const p of pushes)
-        p.signature = pem ? signBody(pem, p.body) : undefined;
-    const publicKey = pem ? publicKeyFromPrivate(pem) : null;
-    if (typeof values.out === "string") {
-        // The customer's own copy: the exact bytes sent, and what verifies them (one entry per push when split).
-        const copy = pushes.length === 1
-            ? { endpoint: url, keyId: keyId ?? null, publicKey, signature: pushes[0].signature ?? null, body: pushes[0].bodyText }
-            : { endpoint: url, keyId: keyId ?? null, publicKey, pushes: pushes.map((p) => ({ signature: p.signature ?? null, body: p.bodyText })) };
-        writeFileSync(values.out, JSON.stringify(copy, null, 2) + "\n");
-        deps.err(`signed payload written to ${values.out}`);
-    }
-    if (dry) {
-        const head = (p) => ({ "x-sagentix-key-id": keyId ?? null, "x-sagentix-signature": p.signature ?? null });
-        deps.out(JSON.stringify(pushes.length === 1
-            ? { dryRun: true, endpoint: url, headers: head(pushes[0]), publicKey, summary: pushes[0].summary, payload: JSON.parse(pushes[0].bodyText) }
-            : { dryRun: true, endpoint: url, publicKey, pushes: pushes.map((p) => ({ headers: head(p), summary: p.summary, payload: JSON.parse(p.bodyText) })) }, null, 2));
-        return EXIT.ok;
-    }
-    if (!results.some((r) => r.result !== "skipped")) {
-        deps.err("Nothing to send: every check was skipped. Run with --dry-run to see why.");
-        for (const s of skipped.slice(0, 50))
-            deps.err(`  skipped ${s.check} [${s.resource}]: ${s.detail}`);
-        return EXIT.nothing;
-    }
-    for (const s of skipped)
-        deps.err(`skipped ${s.check} [${s.resource}]: ${s.detail}`);
-    for (const [i, p] of pushes.entries()) {
-        const which = pushes.length > 1 ? ` (push ${i + 1} of ${pushes.length}${i ? `; pushes 1 to ${i} were accepted` : ""})` : "";
-        let res;
-        try {
-            res = await deps.fetch(url, { method: "POST", headers: { "content-type": "application/json", "x-sagentix-key-id": keyId, "x-sagentix-signature": p.signature }, body: p.body });
+        for (const p of pushes)
+            p.signature = pem ? signBody(pem, p.body) : undefined;
+        const publicKey = pem ? publicKeyFromPrivate(pem) : null;
+        if (typeof values.out === "string") {
+            // The customer's own copy: the exact bytes sent, and what verifies them (one entry per push when split).
+            const copy = pushes.length === 1
+                ? { endpoint: url, keyId: keyId ?? null, publicKey, signature: pushes[0].signature ?? null, body: pushes[0].bodyText }
+                : { endpoint: url, keyId: keyId ?? null, publicKey, pushes: pushes.map((p) => ({ signature: p.signature ?? null, body: p.bodyText })) };
+            writeFileSync(values.out, JSON.stringify(copy, null, 2) + "\n");
+            deps.err(`signed payload written to ${values.out}`);
         }
-        catch (e) {
-            deps.err(`POST ${url} failed${which}: ${String(e)}`);
-            return EXIT.error;
+        if (dry) {
+            const head = (p) => ({ "x-sagentix-key-id": keyId ?? null, "x-sagentix-signature": p.signature ?? null });
+            deps.out(JSON.stringify(pushes.length === 1
+                ? { dryRun: true, endpoint: url, headers: head(pushes[0]), publicKey, summary: pushes[0].summary, payload: JSON.parse(pushes[0].bodyText) }
+                : { dryRun: true, endpoint: url, publicKey, pushes: pushes.map((p) => ({ headers: head(p), summary: p.summary, payload: JSON.parse(p.bodyText) })) }, null, 2));
+            return done(EXIT.ok);
+        }
+        if (!results.some((r) => r.result !== "skipped")) {
+            deps.err("Nothing to send: every check was skipped. Run with --dry-run to see why.");
+            for (const s of skipped.slice(0, 50))
+                deps.err(`  skipped ${s.check} [${s.resource}]: ${s.detail}`);
+            return done(EXIT.nothing);
         }
-        const text = await res.text();
-        if (!res.ok) {
-            deps.err(`sos-app refused the push${which} (HTTP ${res.status}): ${serverMessage(text)}`);
-            return EXIT.refused;
+        for (const s of skipped)
+            deps.err(`skipped ${s.check} [${s.resource}]: ${s.detail}`);
+        // A push that fails is recorded and ends the pushing (the later parts would fail the same way); the report still goes.
+        for (const [i, p] of pushes.entries()) {
+            const which = pushes.length > 1 ? ` (push ${i + 1} of ${pushes.length}${i ? `; pushes 1 to ${i} were accepted` : ""})` : "";
+            let res;
+            try {
+                res = await deps.fetch(url, { method: "POST", headers: { "content-type": "application/json", "x-sagentix-key-id": keyId, "x-sagentix-signature": p.signature }, body: p.body });
+            }
+            catch (e) {
+                deps.err(`POST ${url} failed${which}: ${String(e)}`);
+                rec.pushes.push({ status: 0, error: String(e?.message ?? e) });
+                return EXIT.error;
+            }
+            const text = await res.text();
+            if (!res.ok) {
+                deps.err(`sos-app refused the push${which} (HTTP ${res.status}): ${serverMessage(text)}`);
+                rec.pushes.push({ status: res.status, error: serverMessage(text).slice(0, 500) });
+                return EXIT.refused;
+            }
+            let runId;
+            try {
+                const j = JSON.parse(text);
+                if (typeof j?.runId === "string")
+                    runId = j.runId;
+            }
+            catch { /* not JSON */ }
+            rec.pushes.push({ status: res.status, ...(runId ? { runId } : {}) });
+            deps.out(text);
         }
-        deps.out(text);
+        return done(EXIT.ok);
     }
-    return EXIT.ok;
 }
 export async function main(argv, deps = defaultDeps()) {
     const [cmd, ...rest] = argv;
@@ -293,6 +360,8 @@ export async function main(argv, deps = defaultDeps()) {
             return keygen(rest, deps);
         if (cmd === "run")
             return await run(rest, deps);
+        if (cmd === "agent")
+            return await agent(rest, deps);
         if (cmd === "config-schema") {
             deps.out(JSON.stringify(CONFIG_SCHEMA, null, 2));
             return EXIT.ok;
@@ -315,5 +384,7 @@ catch {
     return resolve(p);
 } };
 if (process.argv[1] && invokedPath(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
-    main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+    // The agent exits for real (75 after an update) even should a closed socket's handle linger.
+    main(process.argv.slice(2)).then((code) => { process.exitCode = code; if (process.argv[2] === "agent")
+        process.exit(code); });
 }

package/collector/src/release_keys.js

@@ -0,0 +1,9 @@
+// The Sagentix release public keys a check-in `update` must verify against (apps/sos-app/docs/COLLECTOR_CHANNEL.md,
+// section 4). Raw 32-byte Ed25519 public keys, base64. A list, so a key can be rotated: add the new key, release,
+// then sign with it, then drop the old one in a later release.
+//
+// 2026-10-28: created on the release Mac; the private half lives only in its macOS Keychain (service
+// `sagentix-collector-release`), and apps/sos-app/scripts/collector-channel.mjs signs with it.
+export const RELEASE_PUBLIC_KEYS = [
+    "Puo1SstVhUheQhkyFbepFDyLL3RYwOS4mxeSIa9Y+4E=",
+];

package/collector/src/report.js

@@ -0,0 +1,300 @@
+// The run report (apps/sos-app/docs/COLLECTOR_CHANNEL.md, section 2): what every run did, source by source, so a bug,
+// a refused call or a mis-read shows up in sos-app without anyone asking the client for a log. It carries counts,
+// timings, the shape of each outbound call (method, host, templated path, status) and the stderr lines, scrubbed;
+// never a response body, a request header, a query string or a credential.
+//
+// Written beside the config as sagentix-run-report.json before it is sent, so the client can read exactly what
+// leaves. A send that fails leaves sagentix-pending-report.json, sent first ("late": true) by the next run.
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { REPORT_PATH, collectorInfo, osInfo, signedPost, writePrivate } from "./channel.js";
+export const REPORT_FORMAT = "sagentix-run-report/1";
+export const REPORT_FILE = "sagentix-run-report.json";
+export const PENDING_FILE = "sagentix-pending-report.json";
+export const MAX_REPORT_BYTES = 512 * 1024;
+export const MAX_LOG_LINES = 1000;
+export const MAX_LINE = 500;
+export const MAX_WARNINGS = 50;
+// ── Scrubbing ─────────────────────────────────────────────────────────────────────────────────────
+const SECRET_ENV = /(_TOKEN|_SECRET|_KEY|_PASSWORD|_KEY_JSON)$/;
+const PEM = /-----BEGIN [A-Z0-9 ]+-----[\s\S]*?(-----END [A-Z0-9 ]+-----|$)/g;
+const JWT = /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]*/g;
+const AUTH = /\b(Bearer|Basic|SSWS)\s+[A-Za-z0-9._~+/=-]{6,}/gi;
+const AWS_KEY_ID = /\b(AKIA|ASIA)[A-Z0-9]{16}\b/g;
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/g;
+/** The values of the environment's secrets (section 2): names ending _TOKEN, _SECRET, _KEY, _PASSWORD, _KEY_JSON, or SAGENTIX_COLLECTOR_KEY. */
+export function envSecrets(env) {
+    return Object.entries(env)
+        .filter(([k, v]) => typeof v === "string" && v.length >= 6 && (SECRET_ENV.test(k) || k === "SAGENTIX_COLLECTOR_KEY"))
+        .map(([, v]) => v)
+        .sort((a, b) => b.length - a.length); // the longest first, so a secret containing another is cut whole
+}
+/** Text with every secret value, token shape and email address replaced. */
+export function scrubText(text, secrets) {
+    let t = text;
+    for (const s of secrets)
+        t = t.split(s).join("<secret>");
+    return t.replace(PEM, "<secret>").replace(JWT, "<secret>").replace(AUTH, (_m, scheme) => `${scheme} <secret>`)
+        .replace(AWS_KEY_ID, "<secret>").replace(EMAIL, "<email>");
+}
+/** Every string in a value scrubbed (keys are the report's own field names and stay). */
+function scrubDeep(v, secrets) {
+    if (typeof v === "string")
+        return scrubText(v, secrets);
+    if (Array.isArray(v))
+        return v.map((x) => scrubDeep(x, secrets));
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, scrubDeep(x, secrets)]));
+    return v;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX20 = /^[0-9a-f]{20,}$/i;
+// Base64 or base64url of 20 or more characters with a digit and a letter in it: an id, not a word like
+// "deviceManagementConfigurations".
+const B64_20 = /^(?=.*\d)(?=.*[A-Za-z])[A-Za-z0-9+/=_-]{20,}$/;
+/** A URL path with its ids replaced by `:id` (numbers, UUIDs, 12-digit account ids, long hex or base64, emails). */
+export function templatePath(path) {
+    return path.split("?")[0].split("#")[0].split("/").map((seg) => {
+        if (!seg)
+            return seg;
+        let d = seg;
+        try {
+            d = decodeURIComponent(seg);
+        }
+        catch { /* keep it */ }
+        return /^\d+$/.test(d) || UUID.test(d) || HEX20.test(d) || B64_20.test(d) || /@/.test(d) ? ":id" : seg;
+    }).join("/");
+}
+// ── Recording ─────────────────────────────────────────────────────────────────────────────────────
+/** Everything one run does that goes into its report. */
+export class RunRecorder {
+    startedAt;
+    sources = [];
+    pushes = [];
+    log = [];
+    calls = new Map();
+    current;
+    clock;
+    constructor(now, clock = () => performance.now()) {
+        this.startedAt = now();
+        this.clock = clock;
+    }
+    /** An err() that also records each line (and, while a source runs, counts it as that source's warning). */
+    tee(err) {
+        return (s) => {
+            for (const line of String(s).split("\n")) {
+                this.log.push(line);
+                if (this.current && this.current.warnings.length < MAX_WARNINGS)
+                    this.current.warnings.push(line);
+            }
+            err(s);
+        };
+    }
+    /** Runs one source's work with its outbound HTTP counted, and its time and warnings recorded. */
+    async source(name, work) {
+        const report = { name, ms: 0, pass: 0, fail: 0, skipped: 0, error: null, warnings: [] };
+        this.sources.push(report);
+        this.current = report;
+        const t0 = this.clock();
+        const restore = this.instrumentFetch(name);
+        try {
+            return { value: await work(), report };
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            report.error = { message: err.message, stack: err.stack ?? "" };
+            return { error: e, report };
+        }
+        finally {
+            restore();
+            report.ms = Math.round(this.clock() - t0);
+            this.current = undefined;
+        }
+    }
+    /** Warnings that belong to no source (the check-in's), as their own entry. */
+    note(name, warnings) {
+        if (warnings.length)
+            this.sources.push({ name, ms: 0, pass: 0, fail: 0, skipped: 0, error: null, warnings: warnings.slice(0, MAX_WARNINGS) });
+    }
+    /** One outbound call, by its shape only. */
+    call(source, method, url, status, ms, headers) {
+        let host = "", path = "";
+        try {
+            const u = new URL(url);
+            host = u.host;
+            path = templatePath(u.pathname);
+        }
+        catch {
+            host = "(not a URL)";
+        }
+        const key = `${source}\n${method}\n${host}\n${path}\n${status}`;
+        const c = this.calls.get(key) ?? { source, method, host, path, status, count: 0, ms: 0 };
+        c.count++;
+        c.ms += Math.round(ms);
+        // Dates or "true", never more: a header value is the provider's, but it is cut short all the same.
+        const dep = headers?.get("deprecation"), sun = headers?.get("sunset");
+        if (dep)
+            c.deprecation = dep.slice(0, 64);
+        if (sun)
+            c.sunset = sun.slice(0, 64);
+        this.calls.set(key, c);
+    }
+    callList() { return [...this.calls.values()]; }
+    /** A warning in the source's own list, once per endpoint: the provider retires (410) or plans to retire it. */
+    deprecated(source, method, url, status, sunset) {
+        let where = url;
+        try {
+            const u = new URL(url);
+            where = `${u.host}${templatePath(u.pathname)}`;
+        }
+        catch { /* the raw string, scrubbed later */ }
+        const text = status === 410 ? `provider endpoint gone (HTTP 410): ${method} ${where}`
+            : `provider marks this endpoint deprecated${sunset ? `, sunset ${sunset.slice(0, 64)}` : ""}: ${method} ${where}`;
+        const s = this.sources.find((x) => x.name === source);
+        // The source's entry exists from the moment it starts (source() pushes it first).
+        if (s && !s.warnings.includes(text) && s.warnings.length < MAX_WARNINGS)
+            s.warnings.push(text);
+    }
+    /**
+     * Every source reaches the network through the global fetch (the default `fetchFn` of each client, read when the
+     * client is built), so wrapping it while one source runs counts that source's calls, and only them.
+     */
+    instrumentFetch(source) {
+        const original = globalThis.fetch;
+        if (typeof original !== "function")
+            return () => { };
+        const rec = this;
+        const wrapped = async function (input, init) {
+            const url = input instanceof Request ? input.url : String(input);
+            const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+            const t0 = rec.clock();
+            try {
+                const res = await original(input, init);
+                rec.call(source, method, url, res.status, rec.clock() - t0, res.headers);
+                if (res.headers?.get("deprecation") || res.headers?.get("sunset") || res.status === 410) {
+                    rec.deprecated(source, method, url, res.status, res.headers?.get("sunset") ?? null);
+                }
+                return res;
+            }
+            catch (e) {
+                rec.call(source, method, url, 0, rec.clock() - t0);
+                throw e;
+            }
+        };
+        globalThis.fetch = wrapped;
+        return () => { if (globalThis.fetch === wrapped)
+            globalThis.fetch = original; };
+    }
+}
+// ── Building, trimming, sending ───────────────────────────────────────────────────────────────────
+export function buildReport(rec, o) {
+    const report = {
+        format: REPORT_FORMAT,
+        issuedAt: o.now.toISOString(),
+        late: false,
+        collector: collectorInfo(o.env),
+        runner: o.runner,
+        mode: o.mode,
+        os: osInfo(),
+        node: process.version,
+        startedAt: rec.startedAt.toISOString(), endedAt: o.now.toISOString(), exitCode: o.exitCode,
+        sources: rec.sources.map((s) => ({ ...s, warnings: s.warnings.slice(0, MAX_WARNINGS).map((w) => w.slice(0, MAX_LINE)) })),
+        calls: rec.callList(),
+        pushes: rec.pushes,
+        log: rec.log.slice(0, MAX_LOG_LINES).map((l) => l.slice(0, MAX_LINE)),
+    };
+    if (rec.log.length > MAX_LOG_LINES)
+        report.log[MAX_LOG_LINES - 1] = `(log cut: ${rec.log.length} lines, the first ${MAX_LOG_LINES - 1} kept)`;
+    return trimReport(scrubDeep(report, envSecrets(o.env)));
+}
+const bytes = (r) => Buffer.byteLength(JSON.stringify(r, null, 2));
+/** At most MAX_REPORT_BYTES: drops log lines first, then calls, then stacks, and says so in a last log line. */
+export function trimReport(r, max = MAX_REPORT_BYTES) {
+    if (bytes(r) <= max)
+        return r;
+    const out = { ...r, log: [...r.log], calls: [...r.calls], sources: r.sources.map((s) => ({ ...s, error: s.error && { ...s.error } })) };
+    const cut = [];
+    const note = () => `(report trimmed to ${max} bytes: ${cut.join(", ")})`;
+    const fits = () => bytes({ ...out, log: [...out.log, note()] }) <= max;
+    const logs = out.log.length;
+    while (out.log.length && !fits())
+        out.log.splice(Math.floor(out.log.length / 2));
+    if (out.log.length < logs)
+        cut.push(`log ${logs} to ${out.log.length} lines`);
+    if (!fits()) {
+        const calls = out.calls.length;
+        out.calls.sort((a, b) => b.count - a.count);
+        while (out.calls.length && !fits())
+            out.calls.splice(Math.floor(out.calls.length / 2));
+        cut.push(`calls ${calls} to ${out.calls.length}`);
+    }
+    if (!fits()) {
+        for (const s of out.sources)
+            if (s.error)
+                s.error.stack = "";
+        cut.push("stacks removed");
+    }
+    if (out.log.length >= MAX_LOG_LINES)
+        out.log.pop();
+    out.log.push(note());
+    return out;
+}
+/** The report's bytes, as written and as sent. */
+export const reportBytes = (r) => new TextEncoder().encode(JSON.stringify(r, null, 2) + "\n");
+/** HTTP answers that will never accept this body; a pending copy of it would be refused on every later run. */
+const PERMANENT = new Set([400, 413]);
+/**
+ * Writes the report beside the config, then (not on a dry run) sends any pending report first and this one after.
+ * Never throws; what happened goes to `log`.
+ */
+export async function deliverReport(r, o) {
+    const file = join(o.dir, REPORT_FILE), pending = join(o.dir, PENDING_FILE);
+    try {
+        writePrivate(file, new TextDecoder().decode(reportBytes(r)));
+    }
+    catch (e) {
+        o.log(`warning: cannot write ${file}: ${e.code ?? String(e)}`);
+    }
+    if (o.dry || !o.channel)
+        return;
+    const send = async (body) => {
+        try {
+            const res = await signedPost(o.channel, REPORT_PATH, body);
+            if (res.status >= 200 && res.status < 300)
+                return { ok: true, keep: false, why: "" };
+            return { ok: false, keep: !PERMANENT.has(res.status), why: `HTTP ${res.status}` };
+        }
+        catch (e) {
+            return { ok: false, keep: true, why: String(e?.message ?? e) };
+        }
+    };
+    if (existsSync(pending)) {
+        let body;
+        try {
+            body = new Uint8Array(readFileSync(pending));
+        }
+        catch { /* unreadable: leave it */ }
+        if (body) {
+            const s = await send(body);
+            if (s.ok || !s.keep) {
+                rmSync(pending, { force: true });
+                if (!s.ok)
+                    o.log(`warning: the report left from an earlier run was refused (${s.why}) and removed`);
+            }
+            else
+                o.log(`warning: the report left from an earlier run is still not sent (${s.why}); kept as ${pending}`);
+        }
+    }
+    const s = await send(reportBytes(r));
+    if (s.ok)
+        return;
+    if (!s.keep) {
+        o.log(`warning: sos-app refused the run report (${s.why}); a copy stays in ${file}`);
+        return;
+    }
+    try {
+        writePrivate(pending, new TextDecoder().decode(reportBytes({ ...r, late: true })));
+    }
+    catch { /* the report file is still there */ }
+    o.log(`warning: the run report was not sent (${s.why}); kept as ${pending}, sent first next run`);
+}