@meffecta/agent 1.0.2 → 1.0.7

package/scripts/{setup-scheduler.sh → sync-triggers.sh}

@@ -32,12 +32,13 @@ set -euo pipefail
 # is restarted for them anyway. scripts/deploy.sh does it automatically.
 #
 # Usage:
-#   scripts/setup-scheduler.sh              # from the content repo (./deployment.env)
-#   scripts/setup-scheduler.sh --dry-run    # print what it would create, change nothing
+#   scripts/sync-triggers.sh              # from the content repo (./deployment.env)
+#   scripts/sync-triggers.sh --dry-run    # print what it would create, change nothing
 #
 # Which deployment: ./deployment.env, or --config <file>. See deployment.env.example.
 
 . "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+. "$(dirname "${BASH_SOURCE[0]}")/lib/tasks-queue.sh"
 
 DRY_RUN=false
 QUEUE_NAME=""
@@ -70,8 +71,8 @@ GC="gcloud --project=${PROJECT}"
 # arguments of the calls that create them — and gcloud echoes the arguments back when it
 # rejects one. Everything this script prints goes through here first.
 redact() {
-  if [ -n "${WEBHOOK_SECRET:-}" ]; then
-    printf '%s\n' "${1//${WEBHOOK_SECRET}/<secret>}"
+  if [ -n "${API_SECRET:-}" ]; then
+    printf '%s\n' "${1//${API_SECRET}/<secret>}"
   else
     printf '%s\n' "$1"
   fi
@@ -119,18 +120,24 @@ fi
 
 # The triggers authenticate with the same bearer token as everything else on this API, so
 # the secret has to be resolved — it is normally a Secret Manager reference on the service.
-SECRET_REF=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_WEBHOOK_SECRET)
-IFS=$'\t' read -r SECRET_KIND SECRET_A SECRET_B <<<"${SECRET_REF}"
-if [ "${SECRET_KIND}" = "value" ]; then
-  WEBHOOK_SECRET="${SECRET_A}"
-elif [ "${SECRET_KIND}" = "secret" ] && [ -n "${SECRET_A}" ]; then
-  WEBHOOK_SECRET=$(${GC} secrets versions access "${SECRET_B}" --secret="${SECRET_A}")
-else
-  echo "Could not resolve AGENT_WEBHOOK_SECRET from ${SERVICE} — is it set on the service?" >&2
-  echo "  scripts/set-secret.sh AGENT_WEBHOOK_SECRET --random" >&2
+# AGENT_WEBHOOK_SECRET is the old name, still read by the engine and still looked for here,
+# so a deployment part-way through the rename gets working triggers either way.
+API_SECRET=""
+for SECRET_VAR in AGENT_API_SECRET AGENT_WEBHOOK_SECRET; do
+  IFS=$'\t' read -r SECRET_KIND SECRET_A SECRET_B <<<"$(printf '%s' "${SERVICE_JSON}" | svc_field "${SECRET_VAR}")"
+  if [ "${SECRET_KIND}" = "value" ]; then
+    API_SECRET="${SECRET_A}"
+  elif [ "${SECRET_KIND}" = "secret" ] && [ -n "${SECRET_A}" ]; then
+    API_SECRET=$(${GC} secrets versions access "${SECRET_B}" --secret="${SECRET_A}")
+  fi
+  [ -n "${API_SECRET}" ] && break
+done
+if [ -z "${API_SECRET}" ]; then
+  echo "Could not resolve AGENT_API_SECRET (or the old AGENT_WEBHOOK_SECRET) from ${SERVICE}." >&2
+  echo "  $(cmd set-secret) AGENT_API_SECRET --random" >&2
+  echo "Refusing to create triggers that would 401 on every firing." >&2
   exit 1
 fi
-[ -n "${WEBHOOK_SECRET}" ] || { echo "AGENT_WEBHOOK_SECRET resolved empty — refusing to create triggers that would 401." >&2; exit 1; }
 
 echo "   url:     ${AGENT_URL}"
 echo "   runtime: ${RUNTIME_SA}"
@@ -142,25 +149,20 @@ if [ "${MIN_SCALE}" != "0" ] || [ "${CPU_THROTTLING}" = "false" ]; then
 ⚠️  ${SERVICE} still runs always-on (min-instances=${MIN_SCALE}, cpu-throttling=${CPU_THROTTLING}).
    External triggers work either way, but the saving does not arrive until the service
    scales to zero — and until then in-process timers and Cloud Scheduler would BOTH fire,
-   so every cron runs twice. The shape lives in deployment.env and deploy.sh asserts it:
+   so every cron runs twice. The shape lives in deployment.env, and is asserted on every
+   rollout:
 
      SCALING=scale-to-zero        # in deployment.env, then
-     scripts/deploy.sh            # rolls it out (--dry-run to see the shape first)
+     $(cmd deploy)            # rolls it out (--dry-run to see the shape first)
 
 EOF
 fi
 
+# Normally already there — setup-infrastructure.sh creates it with the deployment's other
+# static resources. Ensured here too for a deployment provisioned before that was true, and
+# because this script is also run on its own. See lib/tasks-queue.sh.
 echo "📥 Cloud Tasks queue ${QUEUE}..."
-if ! ${GC} tasks queues describe "${QUEUE}" --location="${REGION}" >/dev/null 2>&1; then
-  run ${GC} tasks queues create "${QUEUE}" --location="${REGION}" --quiet
-fi
-# max-concurrent-dispatches leaves room for several held attempts at once; the engine's own
-# queue is serial, so this bounds requests waiting, not jobs running.
-run ${GC} tasks queues update "${QUEUE}" --location="${REGION}" \
-  --max-attempts=4 --min-backoff=5s --max-backoff=30s --max-doublings=2 \
-  --max-concurrent-dispatches=8 --max-dispatches-per-second=2 --quiet
-run ${GC} tasks queues add-iam-policy-binding "${QUEUE}" --location="${REGION}" \
-  --member="serviceAccount:${RUNTIME_SA}" --role="roles/cloudtasks.enqueuer" --quiet
+ensure_tasks_queue "${QUEUE}"
 
 CURRENT_QUEUE=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_TASKS_QUEUE | cut -f2)
 CURRENT_URL=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_PUBLIC_URL | cut -f2)
@@ -171,7 +173,7 @@ if [ "${CURRENT_QUEUE}" != "${QUEUE_PATH}" ] || [ "${CURRENT_URL}" != "${AGENT_U
 fi
 
 echo "📋 Reading the job list from ${AGENT_URL}/jobs..."
-JOBS_JSON=$(curl -fsS --max-time 300 -H "Authorization: Bearer ${WEBHOOK_SECRET}" "${AGENT_URL}/jobs") || {
+JOBS_JSON=$(curl -fsS --max-time 300 -H "Authorization: Bearer ${API_SECRET}" "${AGENT_URL}/jobs") || {
   cat >&2 <<EOF
 Could not read ${AGENT_URL}/jobs.
 
@@ -179,7 +181,7 @@ The engine is the only thing that knows which jobs exist — it reads them from
 clone of the content repo. So the service has to be deployed and healthy first:
 
     curl -fsS ${AGENT_URL}/health
-    scripts/deploy.sh
+    $(cmd deploy)
 
 A first request after a scale-to-zero idle also has to wait out a cold start, which
 includes cloning the content repo.
@@ -193,7 +195,7 @@ EOF
 CRON_JOBS=$(printf '%s' "${JOBS_JSON}" | node "${READ_JSON}" crons)
 WATCHES_INBOX=$(printf '%s' "${JOBS_JSON}" | node "${READ_JSON}" watches-inbox)
 
-HEADERS="Content-Type=application/json,Authorization=Bearer ${WEBHOOK_SECRET}"
+HEADERS="Content-Type=application/json,Authorization=Bearer ${API_SECRET}"
 
 # `create http` takes --headers; `update http` insists on --update-headers for the same
 # thing. Everything else about the two calls is identical.

package/scripts/update-tooling.sh

@@ -30,6 +30,8 @@ set -euo pipefail
 # Artifact Registry). A deployment using an AR remote repository instead still needs it
 # here — once per engine version, rather than once per deploy.
 
+. "$(dirname "${BASH_SOURCE[0]}")/lib/cli-names.sh"
+
 GHCR_IMAGE="${GHCR_IMAGE:-ghcr.io/meffecta/agent}"
 TAG="latest"
 IMAGE=""
@@ -114,5 +116,5 @@ fi
 # This script is one of the files being overwritten, and bash reads a script as it runs it.
 # exec hands the process over so nothing further is read from the file underneath us.
 echo "✅ Updated. Review with \`git diff\`, then deploy the matching engine:"
-echo "     scripts/deploy.sh${TAG:+ --tag ${TAG}}"
+echo "     $(cmd deploy)${TAG:+ --tag ${TAG}}"
 exec cp -R "${TMP}/scripts/." "${DEST}/"

package/scripts/verify-credentials.mjs

@@ -8,6 +8,8 @@
 // Never prints a credential value. Exits 1 if anything configured actually fails.
 
 import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 const env = process.env;
 const results = [];
@@ -45,12 +47,21 @@ async function metadataToken(scopes) {
 
 async function checkGithub() {
   if (!env.GITHUB_TOKEN) {
-    return skip("GITHUB_TOKEN", "unset");
+    // Not a shrug: the service clones the content repo at boot, so unset is an outage.
+    return fail("GITHUB_TOKEN", "unset — the service cannot clone its content repo without it");
   }
-  // The content repo (from GIT_REPO_URL, when it's a GitHub URL), plus the working
-  // repos this deployment's jobs clone (deployment-specific — derive from jobs/ one day).
+  // The content repo (from GIT_REPO_URL, when it is a GitHub URL), plus any working repo
+  // this deployment names in a *_GIT_URL variable — its jobs clone those, so the token has
+  // to reach them. Nothing here may name a company: this script ships to every deployment.
   const contentRepo = env.GIT_REPO_URL?.match(/github\.com\/([^/]+\/[^/.]+)/)?.[1];
-  const repos = [...(contentRepo ? [contentRepo] : []), "meffecta/sweepos"];
+  const named = Object.entries(env)
+    .filter(([k]) => k.endsWith("_GIT_URL"))
+    .map(([, v]) => v?.match(/github\.com\/([^/]+\/[^/.]+)/)?.[1])
+    .filter(Boolean);
+  const repos = [...new Set([...(contentRepo ? [contentRepo] : []), ...named])];
+  if (repos.length === 0) {
+    return skip("GITHUB_TOKEN", "set, but no GitHub repo to check it against");
+  }
   const codes = await Promise.all(
     repos.map(
       async (r) =>
@@ -87,35 +98,38 @@ async function checkResend() {
     : fail("RESEND_API_KEY", `domains → ${status}`);
 }
 
-async function checkInternalApi() {
-  if (!env.SWEEPOS_API_URL || !env.INTERNAL_API_KEY) {
-    return skip("SWEEPOS internal API", "SWEEPOS_API_URL/INTERNAL_API_KEY not set");
-  }
-  const { status } = await http(`${env.SWEEPOS_API_URL}/v1/internal/leads?limit=1`, {
-    headers: { Authorization: `Bearer ${env.INTERNAL_API_KEY}` },
-  });
-  status === 200 ? ok("SWEEPOS internal API") : fail("SWEEPOS internal API", `leads → ${status}`);
-}
-
+/**
+ * Every read-only Postgres URL this deployment declares, by the documented convention
+ * <WORLD>_POSTGRES_URL_READONLY — the variable names belong to the deployment, so they are
+ * discovered rather than listed here.
+ */
+// There is deliberately no check for a deployment's own product API. Probing one means
+// knowing its path and its response shape — /v1/internal/leads was SweepOS's — and this
+// script ships to every deployment. A credential the engine's own skills use is fair game
+// here; a company's API is that company's tooling.
 function checkPostgres() {
-  return new Promise((resolve) => {
-    if (!env.SWEEPOS_POSTGRES_URL_READONLY) {
-      skip("SWEEPOS_POSTGRES_URL_READONLY", "unset");
-      return resolve();
-    }
-    execFile("psql", [env.SWEEPOS_POSTGRES_URL_READONLY, "-Atc", "SELECT 1"], { timeout: 10_000 }, (err, stdout) => {
-      if (err) {
-        err.code === "ENOENT"
-          ? skip("SWEEPOS_POSTGRES_URL_READONLY", "psql not installed here")
-          : fail("SWEEPOS_POSTGRES_URL_READONLY", err.message.split("\n")[0].slice(0, 120));
-      } else {
-        stdout.trim() === "1"
-          ? ok("SWEEPOS_POSTGRES_URL_READONLY")
-          : fail("SWEEPOS_POSTGRES_URL_READONLY", "unexpected result");
-      }
-      resolve();
-    });
-  });
+  const urls = Object.keys(env).filter((k) => k.endsWith("_POSTGRES_URL_READONLY") && env[k]);
+  if (urls.length === 0) {
+    skip("POSTGRES (read-only)", "no <WORLD>_POSTGRES_URL_READONLY set");
+    return Promise.resolve();
+  }
+  return Promise.all(
+    urls.map(
+      (name) =>
+        new Promise((resolve) => {
+          execFile("psql", [env[name], "-Atc", "SELECT 1"], { timeout: 10_000 }, (err, stdout) => {
+            if (err) {
+              err.code === "ENOENT"
+                ? skip(name, "psql not installed here")
+                : fail(name, err.message.split("\n")[0].slice(0, 120));
+            } else {
+              stdout.trim() === "1" ? ok(name) : fail(name, "unexpected result");
+            }
+            resolve();
+          });
+        }),
+    ),
+  );
 }
 
 async function checkPosthog() {
@@ -138,11 +152,13 @@ async function checkAhrefs() {
   if (!env.AHREFS_API_KEY) {
     return skip("AHREFS_API_KEY", "unset");
   }
-  const { status, json } = await http("https://api.ahrefs.com/v3/public/domain-rating-free?target=sweepos.app", {
+  // example.com rather than a domain belonging to any deployment: this only proves the key
+  // is accepted, and the answer for a real domain is a job's business, not a doctor's.
+  const { status, json } = await http("https://api.ahrefs.com/v3/public/domain-rating-free?target=example.com", {
     headers: { Authorization: `Bearer ${env.AHREFS_API_KEY}` },
   });
   status === 200
-    ? ok("AHREFS_API_KEY", `sweepos.app DR ${json?.domain_rating?.domain_rating ?? "?"}`)
+    ? ok("AHREFS_API_KEY", `example.com DR ${json?.domain_rating?.domain_rating ?? "?"}`)
     : fail("AHREFS_API_KEY", `domain-rating-free → ${status}`);
 }
 
@@ -164,6 +180,48 @@ async function checkSerper() {
   return fail("SERPER_API_KEY", json?.message ? `${json.message} (${status})` : `search → ${status}`);
 }
 
+async function checkHubspot() {
+  const token = env.HUBSPOT_TOKEN;
+  if (!token) {
+    return skip("HUBSPOT_TOKEN", "unset");
+  }
+  // limit=1 with no properties: the cheapest call that still proves the token and a scope.
+  const { status, json } = await http("https://api.hubapi.com/crm/v3/objects/contacts?limit=1", {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (status === 200) {
+    return ok("HUBSPOT_TOKEN", "CRM readable");
+  }
+  // 403 is a granted-scopes problem, not a bad token — different fix, so say which.
+  return fail(
+    "HUBSPOT_TOKEN",
+    status === 403 ? "token valid but missing CRM read scope (403)" : `contacts → ${status}`,
+  );
+}
+
+async function checkKleer() {
+  const token = env.KLEER_API_TOKEN;
+  if (!token) {
+    return skip("KLEER_API_TOKEN", "unset");
+  }
+  // The only POST in the read-only skill: it lists the companies this token can reach, and
+  // is the documented way to discover a company id. It changes nothing.
+  const { status, json } = await http("https://api.kleer.se/v1/access/authenticate", {
+    method: "POST",
+    headers: { "X-Token": token, "content-type": "application/json" },
+  });
+  if (status === 200) {
+    const companies = json?.["accessible-companies"];
+    const count = Array.isArray(companies)
+      ? companies.length
+      : Array.isArray(companies?.["accessible-companies"])
+        ? companies["accessible-companies"].length
+        : "?";
+    return ok("KLEER_API_TOKEN", `${count} companies reachable`);
+  }
+  return fail("KLEER_API_TOKEN", json?.message ? `${json.message} (${status})` : `authenticate → ${status}`);
+}
+
 async function checkCloudflare() {
   if (!env.CLOUDFLARE_API_KEY || !env.CLOUDFLARE_ACCOUNT_ID) {
     return skip("CLOUDFLARE", "CLOUDFLARE_API_KEY/ACCOUNT_ID not set");
@@ -466,8 +524,11 @@ async function checkGa4() {
 }
 
 async function checkGoogleAds() {
-  if (!env.GOOGLE_ADS_DEVELOPER_TOKEN || !env.SWEEPOS_GOOGLE_ADS_CUSTOMER_ID) {
-    return skip("GOOGLE ADS", "developer token / customer id not set");
+  // Any world's customer id proves the developer token and the manager link; which world
+  // is this deployment's business, so take the first one it declares.
+  const customerId = Object.entries(env).find(([k, v]) => k.endsWith("_GOOGLE_ADS_CUSTOMER_ID") && v)?.[1];
+  if (!env.GOOGLE_ADS_DEVELOPER_TOKEN || !customerId) {
+    return skip("GOOGLE ADS", "developer token / <WORLD>_GOOGLE_ADS_CUSTOMER_ID not set");
   }
   if (!onCloudRun) {
     return skip("GOOGLE ADS", "needs the metadata server — run on Cloud Run");
@@ -483,7 +544,7 @@ async function checkGoogleAds() {
       headers["login-customer-id"] = env.GOOGLE_ADS_LOGIN_CUSTOMER_ID;
     }
     const { status, json } = await http(
-      `https://googleads.googleapis.com/v25/customers/${env.SWEEPOS_GOOGLE_ADS_CUSTOMER_ID}/googleAds:searchStream`,
+      `https://googleads.googleapis.com/v25/customers/${customerId}/googleAds:searchStream`,
       { method: "POST", headers, body: JSON.stringify({ query: "SELECT customer.id FROM customer LIMIT 1" }) },
     );
     status === 200
@@ -512,9 +573,54 @@ async function checkDeploymentsContext() {
     : fail("Deployments context (run.viewer)", `list → ${status}`);
 }
 
+/**
+ * The handful of credentials without which there is no agent at all — as opposed to an
+ * integration being unavailable, which degrades one job. A deployment can be missing every
+ * other credential here and still work; missing one of these and it is simply down.
+ *
+ * These are also the ones a shipped script CAN test properly, because they are the
+ * engine's own and mean the same thing in every deployment.
+ */
+const ESSENTIAL = new Set(["AGENT_API_SECRET", "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN", "GIT_REPO_URL"]);
+
+/**
+ * Inside a run, three of the four are proven by the fact that this output exists at all —
+ * a stronger check than any probe could be. The run is happening, so the Claude credential
+ * works; the working directory is the content clone, so GIT_REPO_URL and the token that
+ * cloned it work; the request that started it was authenticated, so the API secret works.
+ */
+async function checkEssentials() {
+  const insideRun = Boolean(env.AGENT_SPAWN_TOKEN);
+  if (!env.GIT_REPO_URL) {
+    fail("GIT_REPO_URL", "unset — the service has no content repo to clone, and will not boot");
+  } else if (insideRun) {
+    ok("GIT_REPO_URL", "this run's own clone came from it");
+  } else {
+    ok("GIT_REPO_URL", "set (not verifiable from here)");
+  }
+}
+
 function checkPresence() {
-  for (const k of ["CLAUDE_CODE_OAUTH_TOKEN", "AGENT_WEBHOOK_SECRET"]) {
-    env[k] ? ok(k, "present (not remotely testable)") : skip(k, "unset");
+  // The token that authorises the whole deployment, and the one credential this check
+  // cannot see when it matters most. Run inside a job, `claude` strips its own credential
+  // from the environment of every subprocess it spawns — a run cannot read the token that
+  // started it, which is exactly right, and means "unset" here would be a lie: the run
+  // doing the reporting is itself the proof it is set. AGENT_SPAWN_TOKEN is how we know we
+  // are inside a run; the engine sets that one, so `claude` has no reason to strip it.
+  if (env.CLAUDE_CODE_OAUTH_TOKEN) {
+    ok("CLAUDE_CODE_OAUTH_TOKEN", "present (not remotely testable)");
+  } else if (env.AGENT_SPAWN_TOKEN) {
+    ok("CLAUDE_CODE_OAUTH_TOKEN", "in use by this very run — a run cannot read it, by design");
+  } else {
+    skip("CLAUDE_CODE_OAUTH_TOKEN", "unset");
+  }
+  // Either name satisfies the engine; say which one is actually in play.
+  if (env.AGENT_API_SECRET) {
+    ok("AGENT_API_SECRET", "present (not remotely testable)");
+  } else if (env.AGENT_WEBHOOK_SECRET) {
+    ok("AGENT_API_SECRET", "present under the old name AGENT_WEBHOOK_SECRET");
+  } else {
+    skip("AGENT_API_SECRET", "unset");
   }
 }
 
@@ -535,11 +641,12 @@ const CHECKS = [
   ["GITHUB_TOKEN", checkGithub],
   ["GRAFANA (Loki)", checkGrafana],
   ["RESEND_API_KEY", checkResend],
-  ["SWEEPOS internal API", checkInternalApi],
-  ["SWEEPOS_POSTGRES_URL_READONLY", checkPostgres],
+  ["POSTGRES (read-only)", checkPostgres],
   ["POSTHOG", checkPosthog],
   ["AHREFS_API_KEY", checkAhrefs],
   ["SERPER_API_KEY", checkSerper],
+  ["HUBSPOT_TOKEN", checkHubspot],
+  ["KLEER_API_TOKEN", checkKleer],
   ["CLOUDFLARE", checkCloudflare],
   ["ELEVENLABS_API_KEY", checkElevenlabs],
   ["GOOGLE_API_KEY (Places)", checkPlaces],
@@ -550,6 +657,7 @@ const CHECKS = [
   ["DWD drive+docs+slides", checkDwdDrive],
   ["DWD calendar (write scope)", checkDwdCalendar],
   ["SEARCH CONSOLE", checkSearchConsole],
+  ["Essentials", checkEssentials],
   ["GA4", checkGa4],
   ["GOOGLE ADS", checkGoogleAds],
   ["Deployments context (run.viewer)", checkDeploymentsContext],
@@ -561,16 +669,79 @@ await Promise.all(
 );
 
 results.sort((a, b) => a.name.localeCompare(b.name));
-const pad = Math.max(...results.map((r) => r.name.length)) + 2;
+
+// Configured surfaces get a line each. Unconfigured ones get a single line between them,
+// because this script ships to EVERY deployment and knows every integration the engine
+// supports — which is always more than any one deployment uses. Listing them individually
+// asks the operator "why is Kleer in my report?", and the honest answer is that it is not
+// theirs and never was. The deployment's own register of what it can reach is
+// ENVIRONMENT.md in its content repo; the catalogue of what it could add is `connect`.
+// Credentials this script has never heard of.
+//
+// A deployment adds its own systems, and their keys are just secrets bound to the service:
+// ACME_CRM_TOKEN means nothing to an engine that ships to everyone. Testing one needs its
+// endpoint, its auth header and a notion of what a good answer looks like — none of which
+// can be in here. Silence would be the wrong answer though, because "26 working" reads as
+// "everything works" while a set-but-never-exercised key sits beside it.
+//
+// So: name them, say plainly that nothing here can test them, and let the run that called
+// this reconcile them against ENVIRONMENT.md — the deployment's own register does know
+// what they are and which skill reaches them.
+//
+// Known-ness is decided from this file's own source, so the list maintains itself: if the
+// script mentions the variable, or the family it belongs to, it knows about it.
+// Comments stripped first: a variable named in a comment — including the example two
+// paragraphs up — is not a variable this script can test, and counting it as known is how
+// a real unknown gets silently swallowed.
+const selfSource = readFileSync(fileURLToPath(import.meta.url), "utf8")
+  .split("\n")
+  .filter((line) => !line.trim().startsWith("//"))
+  .join("\n");
+const CREDENTIAL_SHAPED = /_(TOKEN|KEY|SECRET|PASSWORD|CREDENTIALS)$/;
+const unknownCredentials = Object.keys(env)
+  .filter((name) => CREDENTIAL_SHAPED.test(name))
+  .filter((name) => !selfSource.includes(name) && !selfSource.includes(`${name.split("_")[0]}_`))
+  .sort();
+
+// An essential can never be "not set up here" — that is the whole point of the tier. Do
+// this BEFORE partitioning, or a promoted failure is counted and never printed.
+for (const missing of results.filter((r) => r.status === "skip" && ESSENTIAL.has(r.name))) {
+  missing.status = "FAIL";
+  missing.detail = `${missing.detail} — the agent cannot run without it`;
+}
+const configured = results.filter((r) => r.status !== "skip");
+const unconfigured = results.filter((r) => r.status === "skip");
+const pad = Math.max(...configured.map((r) => r.name.length), 1) + 2;
 console.log(
-  `\nCredential check — ${onCloudRun ? "Cloud Run (all surfaces)" : "local (metadata-server surfaces skipped)"}\n`,
+  `\nCredential check — ${onCloudRun ? "Cloud Run (all surfaces)" : "local (metadata-server surfaces skipped)"}`,
 );
-for (const r of results) {
-  const icon = r.status === "ok" ? "✅" : r.status === "FAIL" ? "❌" : "⏭️ ";
-  console.log(`${icon} ${r.name.padEnd(pad)} ${r.status === "ok" ? r.detail : r.detail && `— ${r.detail}`}`);
+const line = (r) => {
+  const icon = r.status === "ok" ? "✅" : "❌";
+  console.log(`  ${icon} ${r.name.padEnd(pad)} ${r.status === "ok" ? r.detail : r.detail && `— ${r.detail}`}`);
+};
+// Split, because a failure in the first group is an outage and a failure in the second is
+// one job doing less. Reading them in one list makes those look like the same news.
+const essential = configured.filter((r) => ESSENTIAL.has(r.name));
+const integrations = configured.filter((r) => !ESSENTIAL.has(r.name));
+if (essential.length) {
+  console.log("\nWithout these there is no agent at all");
+  essential.forEach(line);
+}
+if (integrations.length) {
+  console.log("\nWhat it can reach");
+  integrations.forEach(line);
 }
 const failures = results.filter((r) => r.status === "FAIL");
-console.log(
-  `\n${results.filter((r) => r.status === "ok").length} ok, ${failures.length} failed, ${results.filter((r) => r.status === "skip").length} skipped`,
-);
+console.log(`\n${configured.length - failures.length} working, ${failures.length} failing.`);
+if (unknownCredentials.length) {
+  // Names only. This script never prints a value, and that holds hardest for the ones it
+  // does not understand.
+  console.log(`\nSet, but nothing here knows how to test them (${unknownCredentials.length}):`);
+  console.log(`  ${unknownCredentials.join(", ")}`);
+  console.log("  Each should have a row in ENVIRONMENT.md saying which skill reaches it.");
+}
+if (unconfigured.length) {
+  console.log(`\nNot set up here (${unconfigured.length}): ${unconfigured.map((r) => r.name).join(", ")}.`);
+  console.log("The engine ships more integrations than any deployment uses — `connect` lists them.");
+}
 process.exit(failures.length ? 1 : 0);