@cohortapp/agent-sdk 2.3.0

package/lib/setup/sections/org.mjs

@@ -0,0 +1,475 @@
+/**
+ * sections/org.mjs — org enrollment (Cohort knowledge plane, order 75).
+ *
+ * Cross-workstream seam (design §3.2): registered by dropping this file into
+ * sections/ (no core dispatcher edit — runner.mjs globs sections/). This is the
+ * step that makes an agent JOIN the org: it captures the Cohort server URL plus
+ * an admin-issued org API key (Bearer; hq's documented COHORT_API_KEY),
+ * and writes them to config/org.yaml under the canonical
+ * `org.cohort.{enabled,base,orgId,token,trustedSignersPem?}` shape that
+ * lib/org/client.mjs (isEnabled/configFromAgent) already reads. Once enrolled,
+ * the daemon's prompt-builder can consult lib/org/knowledge.recall() so the
+ * agent's replies are informed by what the fleet already knows.
+ *
+ * Order 75 (between recovery-adjacent 70-band and the WS4 recovery/85 + verify/90)
+ * so org wiring lands after identity/company/model/comms/tools but is verified
+ * before the final verify gate.
+ *
+ * Every hook is non-blocking under --headless: detect/apply/verify NEVER read the
+ * TTY (so doctor/CI/--headless can call them directly); only prompt() touches the
+ * TTY and it honours io's headless resolution. apply() is idempotent — it never
+ * clobbers an operator-customised config/org.yaml, and verify() is best-effort
+ * (a disabled or unreachable server WARNs, it does not hard-fail setup).
+ *
+ * @module lib/setup/sections/org
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import * as io from "../io.mjs";
+import { isEnabled, configFromAgent, read, fetchSelfProfile, pairRequest } from "../../org/client.mjs";
+import { ensureDeviceKey } from "../../org/keys.mjs";
+import { mergeAgentJson, readAgentJson } from "../sot.mjs";
+import { cohortPullEnv, pullAndPlan } from "../enroll-from-cohort.mjs";
+import { bootstrapAndPersist } from "../../org/bootstrap-context.mjs";
+import { runGenerator } from "../run-generator.mjs";
+
+const CONFIG_REL = join("config", "org.yaml");
+
+/** The header comment prepended to every config/org.yaml we write. */
+const ORG_YAML_HEADER =
+  "# config/org.yaml — Org enrollment (Cohort shared knowledge plane).\n" +
+  "# Written by `maestro setup` (section org). The bearer token authorises\n" +
+  "# org-wide recall/remember; the SERVER enforces ACL — this file only points\n" +
+  "# the agent at the endpoint. enabled flips true once base + token are set.\n";
+
+/** Lazily load js-yaml (a maestro dep) the same way the lib/org modules do. */
+async function loadYaml() {
+  const m = await import("js-yaml");
+  return m && m.default ? m.default : m;
+}
+
+/**
+ * Read config/org.yaml into a plain object. Returns {} when the file is absent or
+ * unreadable so callers can null-check uniformly. Never throws.
+ * @param {string} agentRoot
+ * @returns {Promise<object>}
+ */
+export async function readOrgConfig(agentRoot) {
+  const p = join(agentRoot, CONFIG_REL);
+  if (!existsSync(p)) return {};
+  try {
+    const yaml = await loadYaml();
+    const doc = yaml.load(readFileSync(p, "utf8"));
+    return doc && typeof doc === "object" ? doc : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Build the `org.cohort` config block from the supplied answers, merged over any
+ * existing config so we never drop operator-set fields (e.g. trustedSignersPem).
+ * `enabled` is true only when we have both a base URL and a credential (the org
+ * API key / bearer token).
+ *
+ * @param {object} existing the existing parsed config/org.yaml ({} when none)
+ * @param {{base?:string, orgId?:string, token?:string}} ans
+ * @returns {object} the merged config object to serialise
+ */
+export function buildOrgConfig(existing, ans = {}) {
+  const prev = (existing && existing.org && existing.org.cohort) || {};
+  const base = (ans.base != null && String(ans.base).trim()) || prev.base || "";
+  const orgId = (ans.orgId != null && String(ans.orgId).trim()) || prev.orgId || "";
+  const token = (ans.token != null && String(ans.token).trim()) || prev.token || "";
+  const cohort = { ...prev };
+
+  if (base) cohort.base = base.replace(/\/+$/, ""); else delete cohort.base;
+  if (orgId) cohort.orgId = orgId; else if (!cohort.orgId) delete cohort.orgId;
+  if (token) cohort.token = token; else if (!cohort.token) delete cohort.token;
+
+  // The integration is only live once we have an endpoint AND a credential (the
+  // bearer token is what makes recall() authoritative). Fail-closed on the
+  // credential, fail-open on the network.
+  cohort.enabled = !!(cohort.base && (cohort.token || prev.enabled));
+
+  // Preserve any pinned snapshot signer PEMs the operator configured.
+  if (Array.isArray(prev.trustedSignersPem) && prev.trustedSignersPem.length) {
+    cohort.trustedSignersPem = prev.trustedSignersPem;
+  }
+
+  return { ...(existing || {}), org: { ...((existing && existing.org) || {}), cohort } };
+}
+
+/**
+ * Pull this agent's record from Cohort and merge it into config/agent.json when
+ * the COHORT_* pull env is present. Fail-open + non-blocking: a missing var or an
+ * unreachable server is a no-op (the wizard falls back to the manual prompts).
+ * Returns the pull plan ({pulled, patch, changes, ...}) so callers can report it.
+ * Shared by this section's apply() and `maestro sync`.
+ *
+ * @param {string} agentRoot
+ * @param {{env?:object, force?:boolean, fetchSelfProfileImpl?:Function}} [opts]
+ * @returns {Promise<object>} the pullAndPlan result
+ */
+export async function pullProfileIntoAgentConfig(agentRoot, opts = {}) {
+  const plan = await pullAndPlan({
+    agentRoot,
+    env: opts.env || process.env,
+    force: !!opts.force,
+    fetchSelfProfileImpl: opts.fetchSelfProfileImpl || fetchSelfProfile,
+  });
+  if (plan.pulled && plan.patch && Object.keys(plan.patch).length) {
+    mergeAgentJson(agentRoot, plan.patch);
+  }
+  return plan;
+}
+
+/**
+ * Fetch the agent's full authoritative org context from Cohort (self profile,
+ * org chart, relationships, strategy, hierarchy, adopted decisions, policy,
+ * board) and persist it to `config/org-context.json` so the running agent
+ * consumes the org as its source of truth (lib/org/awareness.mjs reads it).
+ *
+ * Resolves the endpoint + credential from the COHORT_* pull env first (the
+ * org-data API path), falling back to the persisted config/org.yaml. Fail-open +
+ * non-blocking: when the endpoint/credential/org id are absent it returns
+ * `{ skipped:true }`; an unreachable server yields a context full of nulls and a
+ * best-effort cache — it NEVER throws. Shared by this section's apply() and the
+ * `maestro sync` path.
+ *
+ * @param {string} agentRoot
+ * @param {{env?:object, fetchImpl?:Function}} [opts]
+ * @returns {Promise<{ctx:object|null, path:string|null, skipped?:boolean}>}
+ */
+export async function bootstrapOrgContextInto(agentRoot, opts = {}) {
+  const env = opts.env || process.env;
+  const e = cohortPullEnv(env);
+  const cfg = await readOrgConfig(agentRoot);
+  const c = configFromAgent(cfg);
+  // The org-data DTO reads + /v1 reads share the OrgApiKey; prefer the explicit
+  // pull env (the canonical provisioning vars), then the persisted org.yaml.
+  const base = e.base || c.base || "";
+  const apiKey = e.apiKey || c.token || "";
+  const orgId = e.orgId || c.orgId || "";
+  if (!base || !apiKey || !orgId) return { ctx: null, path: null, skipped: true };
+  try {
+    return await bootstrapAndPersist(agentRoot, {
+      base,
+      apiKey,
+      orgId,
+      agentId: e.agentId || undefined,
+      emailHint: String(env.COHORT_AGENT_EMAIL || "").trim() || undefined,
+      fetchImpl: opts.fetchImpl,
+    });
+  } catch {
+    return { ctx: null, path: null, skipped: false };
+  }
+}
+
+/**
+ * Would the bootstrapped org context actually SHAPE the backlog? True when it
+ * carries strategy streams OR a non-empty ready board — the two inputs
+ * `lib/backlog.orgContextStreams` distils into leading WBS streams. A context
+ * with neither would only re-write the identical archetype skeleton, so we skip
+ * the generate-backlog re-run in that case. Pure; tolerant of a null/partial ctx.
+ * @param {object|null} orgCtx the bootstrapContext result
+ * @returns {boolean}
+ */
+export function orgContextShapesBacklog(orgCtx) {
+  if (!orgCtx || typeof orgCtx !== "object") return false;
+  const strategy = orgCtx.strategy && typeof orgCtx.strategy === "object" ? orgCtx.strategy : {};
+  const hasStreams = Array.isArray(strategy.streams) && strategy.streams.length > 0;
+  const hasBoard = Array.isArray(orgCtx.board) && orgCtx.board.length > 0;
+  return hasStreams || hasBoard;
+}
+
+/** Slugify a free-text value into a stable, wire-safe agent id. Pure. */
+function slugId(v) {
+  const s = String(v || "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return s;
+}
+
+/**
+ * Derive this agent's `{ agentId, displayName }` for the pairing handshake from
+ * config/agent.json (falling back to the answers bag / COHORT_AGENT_ID). The id
+ * is a slug of the explicit agent id, else the email local-part, else the name;
+ * the display name is the agent's full name. Pure over its inputs (reads disk via
+ * readAgentJson which is itself fail-open). Never throws.
+ * @param {string} agentRoot
+ * @param {object} [ans] the resolved answers bag (may carry agentId)
+ * @returns {{agentId:string, displayName:string}}
+ */
+export function deriveAgentIdentity(agentRoot, ans = {}) {
+  const id = readAgentJson(agentRoot) || {};
+  const explicit = (ans.agentId != null && String(ans.agentId).trim()) || process.env.COHORT_AGENT_ID || "";
+  const emailLocal = String(id.email || "").split("@")[0];
+  const nameFallback = String(id.fullName || [id.firstName, id.lastName].filter(Boolean).join(" ")).trim();
+  const agentId = slugId(explicit || emailLocal || nameFallback) || "agent";
+  const displayName = (nameFallback || agentId).trim();
+  return { agentId, displayName };
+}
+
+/**
+ * Run the pre-auth pairing handshake for this agent, then persist the pairing
+ * intent into config/org.yaml under `org.cohort.pairing`.
+ *
+ * Steps: ensure the Ed25519 device keypair (the PUBLIC key is presented in the
+ * handshake), derive `{agentId, displayName}` from config/agent.json, POST
+ * `pairing.request { code, agentId, displayName, pubkey }` with NO bearer (this
+ * is the genuine UNAUTHENTICATED half — the server carves `pairing.request` out
+ * of auth), and record `{ code, agentId, status, requestedAt }` so detect()/
+ * verify() surface the outstanding handshake and a later re-run knows about it.
+ *
+ * The config stays DISABLED (no token yet) — enablement waits on an org admin
+ * running pairing.approve and minting/handing back a Bearer key. Fail-open: a
+ * missing base/short code or an unreachable server returns `{ok:false,error}`
+ * and NEVER throws, so it can never block setup.
+ *
+ * @param {string} agentRoot
+ * @param {{base:string, code:string, orgId?:string, answers?:object, fetchImpl?:Function}} opts
+ * @returns {Promise<{ok:boolean, frame?:object, agentId?:string, code?:string, status?:string, error?:string}>}
+ */
+export async function requestPairing(agentRoot, opts = {}) {
+  const base = opts.base ? String(opts.base).replace(/\/+$/, "") : "";
+  const code = opts.code != null ? String(opts.code).trim() : "";
+  if (!base) return { ok: false, error: "missing base" };
+  if (code.length < 4) return { ok: false, error: "pairing code must be at least 4 characters" };
+
+  const { agentId, displayName } = deriveAgentIdentity(agentRoot, opts.answers || {});
+  let pubkey = "";
+  try { pubkey = ensureDeviceKey(agentRoot).publicKeyPem; } catch { /* device key unavailable */ }
+  if (!pubkey) return { ok: false, agentId, code, error: "could not materialise the device key" };
+
+  const frame = await pairRequest({ base, agentId, displayName, pubkey, code, fetchImpl: opts.fetchImpl });
+  const ok = !!(frame && frame.ok);
+  const status = (ok && frame.result && frame.result.status) || (ok ? "pending" : "error");
+
+  // Persist the pairing intent (survives buildOrgConfig's prev-spread merge, so a
+  // subsequent apply keeps it). Best-effort — a write failure is non-fatal.
+  try {
+    const existing = await readOrgConfig(agentRoot);
+    const nextOrg = { ...((existing && existing.org) || {}) };
+    const cohort = { ...((nextOrg && nextOrg.cohort) || {}) };
+    if (base && !cohort.base) cohort.base = base;
+    if (opts.orgId && !cohort.orgId) cohort.orgId = String(opts.orgId);
+    cohort.pairing = { code, agentId, status, requestedAt: new Date().toISOString() };
+    nextOrg.cohort = cohort;
+    const next = { ...(existing || {}), org: nextOrg };
+    mkdirSync(join(agentRoot, "config"), { recursive: true });
+    const yaml = await loadYaml();
+    writeFileSync(join(agentRoot, CONFIG_REL), ORG_YAML_HEADER + yaml.dump(next, { lineWidth: 120, sortKeys: false }));
+  } catch { /* best-effort persistence */ }
+
+  if (!ok) {
+    const error = (frame && frame.error && frame.error.message) || "pairing request failed";
+    return { ok: false, agentId, code, error };
+  }
+  return { ok: true, frame, agentId, code, status };
+}
+
+/** Resolve the answers bag for this section (answers → env, via io defaults). */
+function resolvedAnswers(ctx) {
+  const a = (ctx && ctx.answers) || {};
+  return {
+    base: a.orgBase != null ? a.orgBase : (process.env.COHORT_BASE || ""),
+    orgId: a.orgId != null ? a.orgId : (process.env.COHORT_ORG_ID || ""),
+    // Token precedence mirrors configFromAgent / cohortPullEnv: hq's DOCUMENTED
+    // agent var is COHORT_API_KEY (README: `Authorization: Bearer <COHORT_API_KEY>`),
+    // so the single documented key must enable the plane. The older
+    // COHORT_API_TOKEN / COHORT_TOKEN are still accepted for back-compat.
+    token: a.orgToken != null
+      ? a.orgToken
+      : (process.env.COHORT_API_TOKEN || process.env.COHORT_TOKEN || process.env.COHORT_API_KEY || ""),
+    // Pairing lane: an operator-chosen handshake code (COHORT_PAIRING_CODE env
+    // for headless provisioning) + the chosen auth method (apikey|pairing).
+    pairingCode: a.orgPairingCode != null ? a.orgPairingCode : (process.env.COHORT_PAIRING_CODE || ""),
+    authMethod: a.orgAuthMethod != null ? a.orgAuthMethod : (process.env.COHORT_AUTH_METHOD || ""),
+  };
+}
+
+export default {
+  id: "org",
+  label: "Org enrollment (shared knowledge)",
+  order: 75,
+
+  async detect(ctx) {
+    const cfg = await readOrgConfig(ctx.agentRoot);
+    if (!existsSync(join(ctx.agentRoot, CONFIG_REL))) {
+      return { status: "unconfigured", missing: ["config/org.yaml"] };
+    }
+    if (isEnabled(cfg)) return { status: "complete", summary: "enrolled in org knowledge plane" };
+    const n = (cfg.org && cfg.org.cohort) || {};
+    // An outstanding pairing handshake: surface it honestly (awaiting the admin's
+    // pairing.approve + an issued Bearer key) rather than as a bare missing token.
+    if (n.pairing && n.pairing.code) {
+      return {
+        status: "partial",
+        summary: `pairing ${n.pairing.status || "requested"} (code ${n.pairing.code}) — awaiting admin approval + org key`,
+        missing: ["cohort token (approve the pairing, then set org.cohort.token)"],
+      };
+    }
+    const missing = [];
+    if (!(n.base || (n.apiUrl && n.orgId))) missing.push("cohort endpoint (base/apiUrl)");
+    if (!n.token) missing.push("cohort token (or admin-approved pairing)");
+    return { status: "partial", summary: "config/org.yaml present but not enabled", missing };
+  },
+
+  async prompt(ctx) {
+    io.note("Enroll this agent in the org's shared knowledge plane (Cohort). Leave blank to skip.", { dim: true });
+    const base = await io.text(ctx, {
+      message: "Cohort server URL (e.g. https://cohort.internal)",
+      key: "orgBase",
+      env: "COHORT_BASE",
+      default: "",
+    });
+    ctx.answers.orgBase = base;
+    if (!base) return;
+    ctx.answers.orgId = await io.text(ctx, { message: "Org id / slug (optional)", key: "orgId", env: "COHORT_ORG_ID", default: "" });
+
+    // Two honest credential lanes (hq now ships pairing.request/approve):
+    //   apikey  — an admin mints an org API key (Bearer) which you paste here.
+    //   pairing — you pick a code, the agent opens a pre-auth handshake, and an
+    //             org admin approves it (pairing.approve); the admin then issues
+    //             the Bearer key that finishes enabling the plane.
+    const method = await io.select(ctx, {
+      message: "How should this agent authenticate to the org?",
+      key: "orgAuthMethod",
+      env: "COHORT_AUTH_METHOD",
+      default: "apikey",
+      choices: [
+        { label: "Org API key (admin-minted Bearer)", value: "apikey" },
+        { label: "Pairing code (an org admin approves a handshake)", value: "pairing" },
+      ],
+    });
+    ctx.answers.orgAuthMethod = method;
+
+    if (method === "pairing") {
+      io.note("Pick a pairing code and share it with an org admin — they approve it in Cohort (pairing.approve).", { dim: true });
+      ctx.answers.orgPairingCode = await io.text(ctx, { message: "Pairing code (4+ chars)", key: "orgPairingCode", env: "COHORT_PAIRING_CODE", default: "" });
+      // An admin may hand back the Bearer key immediately after approving; take it
+      // if offered so the plane can enable in one pass. Otherwise pair-then-enable.
+      ctx.answers.orgToken = await io.secret(ctx, { message: "Org API key if already issued (optional — leave blank to pair first)", key: "orgToken", env: "COHORT_API_KEY" });
+    } else {
+      ctx.answers.orgToken = await io.secret(ctx, { message: "Org API key (Bearer — mint in Cohort admin)", key: "orgToken", env: "COHORT_API_KEY" });
+    }
+  },
+
+  async apply(ctx) {
+    const ans = resolvedAnswers(ctx);
+    const existing = await readOrgConfig(ctx.agentRoot);
+    const next = buildOrgConfig(existing, ans);
+
+    // Idempotent: if nothing meaningful was supplied and no file exists yet, write
+    // a disabled stub so detect/verify have a stable artefact to read. If a file
+    // already exists we merge over it (never dropping operator fields).
+    mkdirSync(join(ctx.agentRoot, "config"), { recursive: true });
+    const yaml = await loadYaml();
+    writeFileSync(join(ctx.agentRoot, CONFIG_REL), ORG_YAML_HEADER + yaml.dump(next, { lineWidth: 120, sortKeys: false }));
+
+    // Pairing lane (hq ships pairing.request/approve): when the operator chose a
+    // pairing code and no Bearer token is available yet, open the pre-auth
+    // handshake so an org admin can approve it (pairing.approve). Fail-open +
+    // non-blocking: an unreachable server records the intent and moves on; the
+    // plane stays DISABLED until a token lands (fail-closed on the credential).
+    if (ans.pairingCode && !ans.token) {
+      try {
+        const res = await requestPairing(ctx.agentRoot, {
+          base: ans.base,
+          code: ans.pairingCode,
+          orgId: ans.orgId,
+          answers: (ctx && ctx.answers) || {},
+          fetchImpl: ctx && ctx.pairFetchImpl,
+        });
+        if (ctx && ctx.answers) ctx.answers.pairingRequested = !!res.ok;
+        if (res.ok) {
+          io.note(`Pairing requested (code ${res.code}, agent ${res.agentId}, status ${res.status}). Ask an org admin to approve it (pairing.approve), then set org.cohort.token to the issued key.`, { dim: true });
+        } else {
+          io.note(`Pairing request not completed (${res.error}). Re-run \`maestro pair ${ans.pairingCode}\` once the server is reachable.`, { dim: true });
+        }
+      } catch { /* fail-open — the manual API-key path stands */ }
+    }
+
+    // Cohort-driven setup: when COHORT_API_KEY + COHORT_ORG_ID (and optionally
+    // COHORT_AGENT_ID) are present, PULL this agent's record from the org-data API
+    // and auto-populate config/agent.json — the identity section then CONFIRMS the
+    // pulled values rather than prompting from scratch. Fail-open + non-blocking:
+    // a missing var / unreachable server is a no-op and the manual prompts stand.
+    try {
+      const plan = await pullProfileIntoAgentConfig(ctx.agentRoot, {});
+      if (plan && plan.pulled) {
+        if (ctx && ctx.answers) ctx.answers.cohortPulled = true;
+        const n = plan.changes ? plan.changes.length : 0;
+        io.note(`Pulled ${n} field${n === 1 ? "" : "s"} from Cohort into config/agent.json.`, { dim: true });
+      }
+    } catch { /* fail-open — manual prompts stand */ }
+
+    // Bootstrap the agent's authoritative org context (chart/relationships/
+    // strategy/hierarchy/decisions/policy/board) into config/org-context.json so
+    // the running agent consults the org as its source of truth. Fail-open +
+    // non-blocking: a missing endpoint/credential or unreachable server is a
+    // no-op (the agent runs on its local model).
+    try {
+      const res = await bootstrapOrgContextInto(ctx.agentRoot, {});
+      if (res && res.path) io.note("Cached org context → config/org-context.json (chart, strategy, decisions, policy).", { dim: true });
+
+      // The operating-model section (order 60) already seeded the backlog from the
+      // ARCHETYPE alone — but it ran BEFORE this section wrote config/org-context.json
+      // (order 75), so that first backlog could not yet be shaped by the org. Now
+      // that the org context is cached, RE-RUN generate-backlog so the fetched org
+      // strategy streams + ready-board frontier actually shape the backlog (closes
+      // the audit gap "fetched org context shapes nothing: backlog"). Only when the
+      // context carries strategy streams or a ready board — otherwise it's a no-op
+      // re-write of the identical skeleton. Fail-open + non-blocking.
+      if (orgContextShapesBacklog(res && res.ctx)) {
+        const g = runGenerator("generate-backlog.mjs", ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+        if (g.ok) io.note("Re-materialised the backlog with org context (strategy streams + ready board lead).", { dim: true });
+        else if (ctx.flags && ctx.flags.verbose) io.note(`generate-backlog re-run: ${(g.stderr || "").trim().slice(0, 200)}`, { dim: true });
+      }
+    } catch { /* fail-open — local model stands */ }
+  },
+
+  async verify(ctx) {
+    const checks = [];
+    const cfgPresent = existsSync(join(ctx.agentRoot, CONFIG_REL));
+    checks.push({ name: "config/org.yaml present", ok: cfgPresent, remedy: cfgPresent ? undefined : "run `maestro setup --only org`" });
+
+    const cfg = await readOrgConfig(ctx.agentRoot);
+    const enabled = isEnabled(cfg);
+    if (!enabled) {
+      // Org enrollment is OPTIONAL — a not-yet-enrolled agent WARNs (remedy shown)
+      // but does not hard-fail setup. ok=true so the agent can run standalone.
+      checks.push({ name: "org knowledge plane (not enrolled — optional)", ok: true, remedy: "set org.cohort.base + token in config/org.yaml, or pair with the org admin" });
+      return { ok: true, checks };
+    }
+
+    // Best-effort, NON-BLOCKING reachability probe. A GET /v1/snapshot round-trips
+    // the configured endpoint; the client is fail-open (transport error → ok:false
+    // frame, never a throw). A timeout/unreachable server WARNs, it never blocks
+    // setup — the daemon's recall() is itself fail-open at runtime.
+    let reachable = false;
+    let detail = "no fetch / unreachable";
+    try {
+      const c = configFromAgent(cfg);
+      const r = await read("snapshot", { base: c.base, token: c.token, timeoutMs: 4000 });
+      reachable = !!(r && r.ok);
+      if (!reachable && r && r.status) detail = `server returned ${r.status}`;
+    } catch {
+      reachable = false;
+    }
+    checks.push({
+      name: reachable ? "Cohort reachable (snapshot read)" : "Cohort reachability (best-effort)",
+      ok: true, // never hard-fail on reachability — recall() is fail-open at runtime
+      remedy: reachable ? undefined : `could not reach the org server (${detail}) — recall() will fail open until it is up`,
+    });
+
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};