@cohortapp/agent-sdk 2.3.0

package/lib/setup/sections/org.test.mjs

@@ -0,0 +1,313 @@
+/**
+ * org.test.mjs — org-enrollment setup section (order 75) tests.
+ * Run: node --test lib/setup/sections/org.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import yaml from "js-yaml";
+
+import org, { buildOrgConfig, readOrgConfig, pullProfileIntoAgentConfig, orgContextShapesBacklog, requestPairing, deriveAgentIdentity } from "./org.mjs";
+import { isEnabled } from "../../org/client.mjs";
+import { readAgentJson, writeAgentJson } from "../sot.mjs";
+import * as io from "../io.mjs";
+
+/**
+ * A deterministic fake fetch for the pairing handshake: records the calls and
+ * replies with a pending pairing frame (the shape hq's pairing.request returns).
+ * Never touches the network so the pairing tests stay hermetic + fast.
+ */
+function fakePairFetch(reply) {
+  const calls = [];
+  const fn = async (url, init) => {
+    calls.push({ url: String(url), init, body: init && init.body ? JSON.parse(init.body) : null });
+    const r = reply ? reply(url, init) : { ok: true, status: 200, body: { ok: true, result: { status: "pending", code: "PAIR-99" } } };
+    return { ok: r.ok !== false, status: r.status || 200, headers: { get: () => undefined }, json: async () => r.body };
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+function tmpRoot() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-orgsec-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function ctxFor(root, answers = {}) {
+  return { agentRoot: root, maestroRoot: MAESTRO_ROOT, flags: { headless: true }, answers, io };
+}
+function readCfg(root) {
+  return yaml.load(readFileSync(join(root, "config", "org.yaml"), "utf8"));
+}
+
+test("section shape: id/order=75/hooks", () => {
+  assert.equal(org.id, "org");
+  assert.equal(org.order, 75);
+  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof org[h], "function");
+});
+
+test("orgContextShapesBacklog: true iff strategy streams or a ready board are present", () => {
+  assert.equal(orgContextShapesBacklog(null), false);
+  assert.equal(orgContextShapesBacklog({}), false);
+  assert.equal(orgContextShapesBacklog({ strategy: {}, board: [] }), false);
+  assert.equal(orgContextShapesBacklog({ strategy: { streams: [{ code: "GTM" }] } }), true);
+  assert.equal(orgContextShapesBacklog({ board: [{ title: "do a thing" }] }), true);
+});
+
+test("detect: unconfigured before apply", async () => {
+  const root = tmpRoot();
+  const before = await org.detect(ctxFor(root));
+  assert.equal(before.status, "unconfigured");
+  assert.ok(before.missing.includes("config/org.yaml"));
+});
+
+test("apply with base + token writes a valid, ENABLED config/org.yaml", async () => {
+  const root = tmpRoot();
+  await org.apply(ctxFor(root, { orgBase: "https://cohort.example", orgId: "acme", orgToken: "tok-123" }));
+  assert.ok(existsSync(join(root, "config", "org.yaml")));
+  const cfg = readCfg(root);
+  assert.equal(cfg.org.cohort.base, "https://cohort.example");
+  assert.equal(cfg.org.cohort.orgId, "acme");
+  assert.equal(cfg.org.cohort.token, "tok-123");
+  assert.equal(cfg.org.cohort.enabled, true);
+  // The shape is exactly what lib/org/client.isEnabled() consumes.
+  assert.equal(isEnabled(cfg), true);
+});
+
+test("apply trims a trailing slash from the base URL", async () => {
+  const root = tmpRoot();
+  await org.apply(ctxFor(root, { orgBase: "https://cohort.example/", orgToken: "tok" }));
+  assert.equal(readCfg(root).org.cohort.base, "https://cohort.example");
+});
+
+test("apply with a pairing code but no token records intent but stays DISABLED", async () => {
+  const root = tmpRoot();
+  const f = fakePairFetch();
+  const ctx = { ...ctxFor(root, { orgBase: "https://cohort.example", orgPairingCode: "PAIR-99" }), pairFetchImpl: f };
+  await org.apply(ctx);
+  const cfg = readCfg(root);
+  assert.equal(cfg.org.cohort.base, "https://cohort.example");
+  assert.equal(cfg.org.cohort.enabled, false, "no token yet → fail-closed on the credential");
+  assert.equal(isEnabled(cfg), false);
+  // The handshake ran (pre-auth, no bearer) and the intent is persisted.
+  assert.equal(f.calls.length, 1);
+  assert.equal(f.calls[0].url, "https://cohort.example/api/v1/pairing.request");
+  assert.equal(f.calls[0].init.headers.authorization, undefined, "pairing.request is UNAUTHENTICATED");
+  assert.equal(f.calls[0].body.code, "PAIR-99");
+  assert.ok(f.calls[0].body.pubkey, "the device public key rides in the handshake");
+  assert.equal(cfg.org.cohort.pairing.code, "PAIR-99");
+  assert.equal(cfg.org.cohort.pairing.status, "pending");
+  assert.equal(ctx.answers.pairingRequested, true);
+});
+
+test("requestPairing: derives agentId from agent.json, persists pairing intent, stays disabled", async () => {
+  const root = tmpRoot();
+  writeAgentJson(root, { firstName: "Alex", lastName: "Rivera", email: "alex.rivera@acme.com", fullName: "Alex Rivera" });
+  const f = fakePairFetch();
+  const res = await requestPairing(root, { base: "https://cohort.example/", code: "TEAM-7", orgId: "acme", fetchImpl: f });
+  assert.equal(res.ok, true);
+  assert.equal(res.agentId, "alex-rivera");
+  assert.equal(res.status, "pending");
+  assert.equal(f.calls[0].body.agentId, "alex-rivera");
+  assert.equal(f.calls[0].body.displayName, "Alex Rivera");
+  const cfg = readCfg(root);
+  assert.equal(cfg.org.cohort.pairing.code, "TEAM-7");
+  assert.equal(cfg.org.cohort.orgId, "acme");
+  assert.equal(isEnabled(cfg), false, "pairing alone never enables the plane");
+  // A device key was materialised under state/org/.
+  assert.ok(existsSync(join(root, "state", "org", "device-key.pem")));
+});
+
+test("requestPairing: short/absent code → fail-open error, no fetch", async () => {
+  const root = tmpRoot();
+  const f = fakePairFetch();
+  assert.equal((await requestPairing(root, { base: "https://n", code: "ab", fetchImpl: f })).ok, false);
+  assert.equal((await requestPairing(root, { code: "abcd", fetchImpl: f })).ok, false, "missing base");
+  assert.equal(f.calls.length, 0);
+});
+
+test("requestPairing: unreachable server records intent + returns ok:false (fail-open)", async () => {
+  const root = tmpRoot();
+  const f = fakePairFetch(() => ({ ok: false, status: 0, body: null }));
+  const res = await requestPairing(root, { base: "https://cohort.example", code: "DOWN-1", fetchImpl: f });
+  assert.equal(res.ok, false);
+  // The intent is still persisted so a later `maestro pair` / setup knows about it.
+  const cfg = readCfg(root);
+  assert.equal(cfg.org.cohort.pairing.code, "DOWN-1");
+  assert.equal(cfg.org.cohort.pairing.status, "error");
+});
+
+test("deriveAgentIdentity: COHORT_AGENT_ID wins, else email local-part, else name", () => {
+  const root = tmpRoot();
+  writeAgentJson(root, { email: "robin.vega@x.io", fullName: "Robin Vega" });
+  assert.equal(deriveAgentIdentity(root).agentId, "robin-vega");
+  const saved = process.env.COHORT_AGENT_ID;
+  process.env.COHORT_AGENT_ID = "Robin The Bot";
+  try { assert.equal(deriveAgentIdentity(root).agentId, "robin-the-bot"); }
+  finally { if (saved === undefined) delete process.env.COHORT_AGENT_ID; else process.env.COHORT_AGENT_ID = saved; }
+});
+
+test("detect: surfaces a pending pairing handshake honestly", async () => {
+  const root = tmpRoot();
+  const f = fakePairFetch();
+  await org.apply({ ...ctxFor(root, { orgBase: "https://cohort.example", orgPairingCode: "SEE-ME" }), pairFetchImpl: f });
+  const d = await org.detect(ctxFor(root));
+  assert.equal(d.status, "partial");
+  assert.match(d.summary, /pairing pending \(code SEE-ME\)/);
+});
+
+test("apply with nothing supplied writes a disabled stub (idempotent artefact)", async () => {
+  const root = tmpRoot();
+  await org.apply(ctxFor(root, {}));
+  assert.ok(existsSync(join(root, "config", "org.yaml")));
+  const cfg = readCfg(root);
+  assert.equal(isEnabled(cfg), false);
+});
+
+test("apply is idempotent and preserves operator fields (trustedSignersPem)", async () => {
+  const root = tmpRoot();
+  // Operator pre-seeds pinned signer PEMs.
+  writeFileSync(
+    join(root, "config", "org.yaml"),
+    yaml.dump({ org: { cohort: { base: "https://old", token: "old-tok", trustedSignersPem: ["-----PEM-----"] } } })
+  );
+  await org.apply(ctxFor(root, { orgBase: "https://cohort.new", orgToken: "new-tok" }));
+  const cfg = readCfg(root);
+  assert.equal(cfg.org.cohort.base, "https://cohort.new");
+  assert.equal(cfg.org.cohort.token, "new-tok");
+  // The pinned signer PEMs survive the merge.
+  assert.deepEqual(cfg.org.cohort.trustedSignersPem, ["-----PEM-----"]);
+  // Re-applying with no answers must not clobber the now-enabled config.
+  await org.apply(ctxFor(root, {}));
+  const cfg2 = readCfg(root);
+  assert.equal(cfg2.org.cohort.base, "https://cohort.new");
+  assert.equal(cfg2.org.cohort.token, "new-tok");
+  assert.equal(isEnabled(cfg2), true);
+});
+
+test("buildOrgConfig: pure merge keeps existing cohort fields", () => {
+  const existing = { org: { cohort: { base: "https://a", token: "t", orgId: "x" } }, other: 1 };
+  const next = buildOrgConfig(existing, { orgId: undefined });
+  assert.equal(next.other, 1, "unrelated top-level keys preserved");
+  assert.equal(next.org.cohort.base, "https://a");
+  assert.equal(next.org.cohort.orgId, "x");
+});
+
+test("readOrgConfig returns {} when file absent (never throws)", async () => {
+  const root = tmpRoot();
+  assert.deepEqual(await readOrgConfig(root), {});
+});
+
+test("detect: complete after an enabled apply", async () => {
+  const root = tmpRoot();
+  await org.apply(ctxFor(root, { orgBase: "https://cohort.example", orgToken: "tok" }));
+  const d = await org.detect(ctxFor(root));
+  assert.equal(d.status, "complete");
+});
+
+test("detect: partial when file present but not enabled", async () => {
+  const root = tmpRoot();
+  // A too-short code never opens a handshake (requestPairing fail-opens before
+  // any fetch), so this exercises the plain not-enabled partial branch.
+  const f = fakePairFetch();
+  await org.apply({ ...ctxFor(root, { orgBase: "https://cohort.example", orgPairingCode: "P" }), pairFetchImpl: f });
+  assert.equal(f.calls.length, 0, "a <4-char code does not hit the network");
+  const d = await org.detect(ctxFor(root));
+  assert.equal(d.status, "partial");
+});
+
+test("verify is NON-BLOCKING and never hard-fails when not enrolled", async () => {
+  const root = tmpRoot();
+  await org.apply(ctxFor(root, {})); // disabled stub
+  const res = await org.verify(ctxFor(root));
+  assert.equal(res.ok, true, "an un-enrolled agent must not fail setup");
+  const byName = Object.fromEntries(res.checks.map((c) => [c.name, c.ok]));
+  assert.equal(byName["config/org.yaml present"], true);
+  // The optional-enrollment warn is present with a remedy.
+  const warn = res.checks.find((c) => /not enrolled/.test(c.name));
+  assert.ok(warn && warn.remedy);
+});
+
+// --- Cohort-driven setup pull (COHORT_API_KEY + COHORT_ORG_ID) ----------
+
+const PULL_PROFILE = {
+  slug: "robin", kind: "agent", displayName: "Robin Vega", firstName: "Robin", lastName: "Vega",
+  title: "VP Eng", team: "Platform", role: "engineering-lead", agentEmail: "robin@example.com",
+  supervisor: { displayName: "Layla Al-Masri", title: "CTO", email: "layla@example.com" },
+};
+
+function withCohortEnv(vars, fn) {
+  const keys = ["COHORT_API_KEY", "COHORT_ORG_ID", "COHORT_AGENT_ID", "COHORT_BASE"];
+  const saved = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+  for (const k of keys) delete process.env[k];
+  Object.assign(process.env, vars);
+  return Promise.resolve()
+    .then(fn)
+    .finally(() => { for (const k of keys) { if (saved[k] === undefined) delete process.env[k]; else process.env[k] = saved[k]; } });
+}
+
+test("pullProfileIntoAgentConfig: env + mocked profile populates config/agent.json", async () => {
+  const root = tmpRoot();
+  await withCohortEnv({ COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin", COHORT_BASE: "https://cohort.example" }, async () => {
+    const plan = await pullProfileIntoAgentConfig(root, { fetchSelfProfileImpl: async () => ({ ok: true, result: PULL_PROFILE }) });
+    assert.equal(plan.pulled, true);
+  });
+  const id = readAgentJson(root);
+  assert.equal(id.firstName, "Robin");
+  assert.equal(id.email, "robin@example.com");
+  assert.equal(id.function, "technical-leader");
+  assert.equal(id.principal.fullName, "Layla Al-Masri");
+});
+
+test("apply: with COHORT_* env present, pulls the profile into config/agent.json", async () => {
+  const root = tmpRoot();
+  // The real fetchSelfProfile is exercised via an injected global fetch.
+  const savedFetch = globalThis.fetch;
+  const calls = [];
+  globalThis.fetch = async (url) => {
+    calls.push(String(url));
+    return { ok: true, status: 200, headers: { get: () => undefined }, json: async () => PULL_PROFILE };
+  };
+  try {
+    await withCohortEnv({ COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin", COHORT_BASE: "https://cohort.example" }, async () => {
+      const ctx = ctxFor(root, { orgBase: "https://cohort.example", orgToken: "tok" });
+      await org.apply(ctx);
+      assert.equal(ctx.answers.cohortPulled, true, "apply records that a pull happened");
+    });
+  } finally {
+    globalThis.fetch = savedFetch;
+  }
+  assert.ok(calls.some((u) => u.includes("/api/v1/org/members/robin")), "hit the org-data members endpoint");
+  const id = readAgentJson(root);
+  assert.equal(id.firstName, "Robin");
+  assert.equal(id.title, "VP Eng");
+});
+
+test("apply: absent COHORT_* env → no pull, config/agent.json untouched (manual path)", async () => {
+  const root = tmpRoot();
+  await withCohortEnv({}, async () => {
+    const ctx = ctxFor(root, { orgBase: "https://cohort.example", orgToken: "tok" });
+    await org.apply(ctx);
+    assert.equal(ctx.answers.cohortPulled, undefined);
+  });
+  assert.equal(readAgentJson(root), null, "no agent.json written by the org section");
+});
+
+test("verify does NOT block / hard-fail on an unreachable enabled server (fail-open)", async () => {
+  const root = tmpRoot();
+  // Point at an unroutable endpoint; the client's fetch will fail fast.
+  await org.apply(ctxFor(root, { orgBase: "http://127.0.0.1:0", orgToken: "tok" }));
+  const res = await org.verify(ctxFor(root));
+  // Reachability is best-effort: ok stays true so setup never blocks on the network.
+  assert.equal(res.ok, true);
+  const reach = res.checks.find((c) => /reachab/i.test(c.name));
+  assert.ok(reach, "a reachability check is recorded");
+  assert.equal(reach.ok, true, "reachability must never hard-fail setup");
+});

package/lib/setup/sections/orgmail.mjs

@@ -0,0 +1,173 @@
+/**
+ * sections/orgmail.mjs — workspace email (Cohort-hosted mailbox) enablement
+ * (order 77).
+ *
+ * The wizard step that turns on the `orgmail` channel: the agent's REAL email
+ * address at the org's verified domain, transported entirely over org RPC (no
+ * IMAP, no app passwords — companion spec 2026-07-21). It is a thin follow-on
+ * to org (75) and messaging (76): it does NOT capture credentials (org.yaml is
+ * the enrollment SoT) — it confirms enrollment, surfaces the agent's mailbox
+ * address when one is discoverable (COHORT_AGENT_EMAIL hint or the pulled
+ * MemberProfileDTO's agentEmail in config/agent.json), and writes the gate
+ * file config/orgmail.yaml `{enabled, poll_seconds, mark_read}` that the
+ * daemon's platform loop keys on.
+ *
+ * Order 77 sits after org (75) + messaging (76) and before recovery (85) +
+ * verify (90), so the mailbox lands once the endpoint+token are known and is
+ * still verified before the final gate.
+ *
+ * Non-blocking by contract: detect/apply/verify NEVER read the TTY; only
+ * prompt() touches it. apply() is idempotent (re-writes the same gate file)
+ * and never destructive. verify() best-effort probes `email.inbox {limit:1}`
+ * and WARNs — never hard-fails — when the org has no verified domain or this
+ * agent has no mailbox yet (that is the admin's Settings → Email job).
+ *
+ * @module lib/setup/sections/orgmail
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import * as io from "../io.mjs";
+import { isEnabled, configFromAgent, loadOrgConfig } from "../../org/client.mjs";
+import { emailInbox } from "../../org/ui-parity.mjs";
+
+const GATE_REL = join("config", "orgmail.yaml");
+
+/** Lazily load js-yaml the same way the sibling sections do. */
+async function loadYaml() {
+  const m = await import("js-yaml");
+  return m && m.default ? m.default : m;
+}
+
+/** Parse config/orgmail.yaml → the inner {enabled, poll_seconds, mark_read} (or null). */
+export async function readOrgmailConfig(agentRoot) {
+  const p = join(agentRoot, GATE_REL);
+  if (!existsSync(p)) return null;
+  try {
+    const yaml = await loadYaml();
+    const doc = yaml.load(readFileSync(p, "utf8"));
+    if (!doc || typeof doc !== "object") return null;
+    return doc.orgmail && typeof doc.orgmail === "object" ? doc.orgmail : doc;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort mailbox-address hint: COHORT_AGENT_EMAIL env → config/agent.json
+ * `agentEmail`/`email` (the pull-enrollment writes the MemberProfileDTO there).
+ * Pure lookup, never throws.
+ */
+export function mailboxHint(agentRoot, env = process.env) {
+  if (env.COHORT_AGENT_EMAIL) return String(env.COHORT_AGENT_EMAIL);
+  try {
+    const p = join(agentRoot, "config", "agent.json");
+    if (!existsSync(p)) return "";
+    const doc = JSON.parse(readFileSync(p, "utf8"));
+    return String(doc.agentEmail || doc.email || "");
+  } catch {
+    return "";
+  }
+}
+
+export default {
+  id: "orgmail",
+  label: "Workspace email (Cohort mailbox)",
+  order: 77,
+
+  async detect(ctx) {
+    const orgCfg = loadOrgConfig(ctx.agentRoot);
+    if (!isEnabled(orgCfg)) {
+      return { status: "unconfigured", missing: ["org enrollment (run the org section first)"] };
+    }
+    const gate = await readOrgmailConfig(ctx.agentRoot);
+    if (gate && gate.enabled) {
+      return { status: "complete", summary: "workspace mailbox enabled (config/orgmail.yaml)" };
+    }
+    if (gate) {
+      return { status: "partial", summary: "config/orgmail.yaml present but not enabled", missing: ["orgmail.enabled: true"] };
+    }
+    return { status: "unconfigured", missing: ["config/orgmail.yaml (the channel gate file)"] };
+  },
+
+  async prompt(ctx) {
+    const hint = mailboxHint(ctx.agentRoot);
+    io.note(
+      "Workspace email gives this agent a real address at the org's verified domain " +
+        "(admin: Cohort → Settings → Email). Inbound + replies ride org RPC — no IMAP, no app passwords." +
+        (hint ? ` Detected mailbox hint: ${hint}` : ""),
+      { dim: true },
+    );
+    const enable = await io.confirm(ctx, {
+      message: "Enable the workspace mailbox channel (orgmail)?",
+      key: "orgmailEnabled",
+      env: "COHORT_ORGMAIL_ENABLED",
+      default: true,
+    });
+    ctx.answers.orgmailEnabled = !!enable;
+  },
+
+  async apply(ctx) {
+    const enabled = ctx.answers.orgmailEnabled !== false; // headless default: enable
+    const existing = (await readOrgmailConfig(ctx.agentRoot)) || {};
+    const next = {
+      orgmail: {
+        enabled,
+        poll_seconds: Number.isFinite(Number(existing.poll_seconds)) && Number(existing.poll_seconds) > 0 ? Number(existing.poll_seconds) : 45,
+        mark_read: existing.mark_read !== false,
+      },
+    };
+    mkdirSync(join(ctx.agentRoot, "config"), { recursive: true });
+    const yaml = await loadYaml();
+    const header =
+      "# config/orgmail.yaml — workspace email channel (Cohort-hosted mailbox).\n" +
+      "# GATE FILE: presence enables the daemon's orgmail channel; delete to disable.\n" +
+      "# Credentials come from config/org.yaml (org enrollment). mark_read advances\n" +
+      "# the SERVER-side cursor after a clean handoff — no local cursor file.\n";
+    writeFileSync(join(ctx.agentRoot, GATE_REL), header + yaml.dump(next, { lineWidth: 120, sortKeys: false }));
+  },
+
+  async verify(ctx) {
+    const checks = [];
+    const gate = await readOrgmailConfig(ctx.agentRoot);
+    const gateOk = !!(gate && gate.enabled);
+    checks.push({
+      name: "config/orgmail.yaml present + enabled",
+      ok: gateOk,
+      remedy: gateOk ? undefined : "run `maestro setup --only orgmail` (or copy scaffold/config/orgmail.yaml.example)",
+    });
+    if (!gateOk) return { ok: false, checks };
+
+    const orgCfg = configFromAgent(loadOrgConfig(ctx.agentRoot));
+    if (!orgCfg.enabled || !orgCfg.token) {
+      // WARN-shaped, not a hard fail: orgmail is dormant until enrollment.
+      checks.push({ name: "workspace mailbox (dormant — org not enrolled)", ok: true, remedy: "enroll the org (setup --only org) to activate the mailbox" });
+      return { ok: checks.every((c) => c.ok), checks };
+    }
+
+    // Best-effort, NON-BLOCKING probe: one email.inbox {limit:1} round-trip.
+    // A missing verified domain / unassigned mailbox is the ADMIN's job in
+    // Cohort → Settings → Email — warn, never fail the wizard on it.
+    let detail = "";
+    let reachable = false;
+    try {
+      const r = await emailInbox({ limit: 1 }, { base: orgCfg.base, token: orgCfg.token, orgId: orgCfg.orgId, fetchImpl: ctx.fetchImpl });
+      if (r && r.ok) {
+        reachable = true;
+        detail = r.result?.mailbox?.address ? `mailbox ${r.result.mailbox.address}` : "mailbox reachable";
+      } else {
+        detail = `${r?.error?.code || "?"}: ${r?.error?.message || "unreachable"}`;
+      }
+    } catch {
+      detail = "probe failed";
+    }
+    checks.push({
+      name: reachable ? `Cohort mailbox reachable (${detail})` : "Cohort mailbox reachability (best-effort)",
+      ok: true, // never hard-fail — the admin may not have verified a domain yet
+      remedy: reachable ? undefined : `email.inbox probe: ${detail} — an admin must verify a domain + assign this agent a mailbox in Cohort → Settings → Email`,
+    });
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};

package/lib/setup/sections/orgmail.test.mjs

@@ -0,0 +1,118 @@
+/**
+ * orgmail.test.mjs — workspace-email setup section (order 77) tests.
+ * Section shape, gate-file write/idempotency, non-blocking verify with an
+ * injected fetchImpl (org/messaging section-test pattern).
+ * Run: node --test lib/setup/sections/orgmail.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import yaml from "js-yaml";
+
+import orgmail, { readOrgmailConfig, mailboxHint } from "./orgmail.mjs";
+import * as io from "../io.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+// Ambient COHORT_* vars must not leak into hint/enrollment resolution.
+for (const k of ["COHORT_AGENT_EMAIL", "COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_ORG_ID", "COHORT_ORGMAIL_ENABLED"]) delete process.env[k];
+
+function tmpRoot() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-orgmail-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function ctxFor(root, answers = {}, fetchImpl) {
+  return { agentRoot: root, maestroRoot: MAESTRO_ROOT, flags: { headless: true }, answers, io, fetchImpl };
+}
+function writeOrg(root, cohort) {
+  writeFileSync(join(root, "config", "org.yaml"), yaml.dump({ org: { cohort } }));
+}
+const ENROLLED = { enabled: true, base: "https://org.example", orgId: "acme", token: "tok-1" };
+
+test("section shape: id/order=77/hooks are functions", () => {
+  assert.equal(orgmail.id, "orgmail");
+  assert.equal(orgmail.order, 77);
+  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof orgmail[h], "function");
+});
+
+test("detect: unenrolled org → unconfigured pointing at the org section", async () => {
+  const root = tmpRoot();
+  const d = await orgmail.detect(ctxFor(root));
+  assert.equal(d.status, "unconfigured");
+  assert.match(d.missing[0], /org/);
+});
+
+test("detect: enrolled without a gate file → unconfigured; enabled gate → complete", async () => {
+  const root = tmpRoot();
+  writeOrg(root, ENROLLED);
+  assert.equal((await orgmail.detect(ctxFor(root))).status, "unconfigured");
+  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true } }));
+  assert.equal((await orgmail.detect(ctxFor(root))).status, "complete");
+  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: false } }));
+  assert.equal((await orgmail.detect(ctxFor(root))).status, "partial");
+});
+
+test("apply: writes the gate file with defaults; idempotent; preserves operator overrides", async () => {
+  const root = tmpRoot();
+  writeOrg(root, ENROLLED);
+  await orgmail.apply(ctxFor(root, { orgmailEnabled: true }));
+  const first = await readOrgmailConfig(root);
+  assert.deepEqual(first, { enabled: true, poll_seconds: 45, mark_read: true });
+  // Operator tunes the cadence; re-apply must not clobber it.
+  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true, poll_seconds: 120, mark_read: false } }));
+  await orgmail.apply(ctxFor(root, { orgmailEnabled: true }));
+  const second = await readOrgmailConfig(root);
+  assert.deepEqual(second, { enabled: true, poll_seconds: 120, mark_read: false });
+});
+
+test("mailboxHint: env wins, else config/agent.json agentEmail/email, else empty", () => {
+  const root = tmpRoot();
+  assert.equal(mailboxHint(root, {}), "");
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ email: "astra@agents.example" }));
+  assert.equal(mailboxHint(root, {}), "astra@agents.example");
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ agentEmail: "astra@corp.example", email: "x@y.z" }));
+  assert.equal(mailboxHint(root, {}), "astra@corp.example", "agentEmail (the MemberProfileDTO field) preferred");
+  assert.equal(mailboxHint(root, { COHORT_AGENT_EMAIL: "hint@env.example" }), "hint@env.example");
+});
+
+test("verify: missing gate file fails with a remedy; dormant enrollment stays ok-with-remedy", async () => {
+  const root = tmpRoot();
+  const v = await orgmail.verify(ctxFor(root));
+  assert.equal(v.ok, false);
+  assert.match(v.checks[0].remedy, /setup --only orgmail/);
+  // gate present but org unenrolled → dormant (ok:true, remedy points at enrollment)
+  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true } }));
+  const v2 = await orgmail.verify(ctxFor(root));
+  assert.equal(v2.ok, true);
+  assert.match(v2.checks.at(-1).name, /dormant/);
+});
+
+test("verify: enrolled probe — reachable mailbox surfaces the address; failure WARNS, never hard-fails", async () => {
+  const root = tmpRoot();
+  writeOrg(root, ENROLLED);
+  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true } }));
+
+  const okFetch = async (url) => ({ ok: true, status: 200, headers: { get: () => undefined }, json: async () => ({ ok: true, result: { mailbox: { address: "astra@agents.example" }, messages: [] } }) });
+  const v = await orgmail.verify(ctxFor(root, {}, okFetch));
+  assert.equal(v.ok, true);
+  assert.match(v.checks.at(-1).name, /astra@agents\.example/);
+
+  const notFound = async () => ({ ok: false, status: 404, headers: { get: () => undefined }, json: async () => ({ ok: false, error: { code: "NOT_FOUND", message: "no mailbox for member" } }) });
+  const v2 = await orgmail.verify(ctxFor(root, {}, notFound));
+  assert.equal(v2.ok, true, "no-mailbox-yet is a WARN (admin's Settings → Email job), not a wizard failure");
+  assert.match(v2.checks.at(-1).remedy, /Settings → Email/);
+});
+
+test("prompt: headless ctx takes the default (enable) without touching the TTY", async () => {
+  const root = tmpRoot();
+  writeOrg(root, ENROLLED);
+  const ctx = ctxFor(root);
+  await orgmail.prompt(ctx);
+  assert.equal(ctx.answers.orgmailEnabled, true);
+});