@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/capability/inventory.test.mjs

@@ -0,0 +1,232 @@
+/**
+ * inventory.test.mjs — the capability inventory (SPEC §5.1).
+ * Run: node --test lib/capability/inventory.test.mjs
+ *
+ * Everything external is injected: a fake HOME for ~/.claude/settings.json, a
+ * fake org tool table, a fake org probe, a fake capability surface, a fake
+ * clock. No network, no real settings file, no real MCP spawn.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  buildInventory, writeManifest, readManifest, reachableIds, findCapability, byPlane,
+  checksumEntries, blastRadiusOfOrgTool, enumerateSkills, enumerateMcp, MANIFEST_REL,
+} from "./inventory.mjs";
+import { probeSkillPlugin, probeMcpServer, probeOrgPlane, probeGrantedPluginTools } from "./probe.mjs";
+
+const AT = "2026-08-11T09:00:00.000Z";
+
+/** A tmp agent repo + a tmp HOME, so nothing touches the real machine. */
+function fixture({ withMarketplace = false, withEnabled = false, mcp = { cohort: { command: "cohort-mcp" } }, skills = ["morning-brief", "inbox-triage"] } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "maestro-inv-"));
+  const home = mkdtempSync(join(tmpdir(), "maestro-home-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+
+  if (skills) {
+    mkdirSync(join(root, "plugins", "agent-skills", "skills"), { recursive: true });
+    for (const s of skills) writeFileSync(join(root, "plugins", "agent-skills", "skills", `${s}.md`), `# ${s}\n`);
+  }
+  if (withMarketplace) {
+    mkdirSync(join(root, "plugins", "agent-skills", ".claude-plugin"), { recursive: true });
+    writeFileSync(join(root, "plugins", "agent-skills", ".claude-plugin", "marketplace.json"), JSON.stringify({ name: "agent-skills", plugins: [] }));
+  }
+  if (withEnabled) {
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    writeFileSync(join(home, ".claude", "settings.json"), JSON.stringify({ enabledPlugins: { "agent-skills@agent-skills": true } }));
+  }
+  if (mcp) writeFileSync(join(root, ".mcp.json"), JSON.stringify({ mcpServers: mcp }));
+  return { root, home };
+}
+
+const FAKE_ORG_TOOLS = [
+  { name: "board_ready", access: "read", binding: { kind: "rpc", method: "board.ready" } },
+  { name: "task_create", access: "write", binding: { kind: "rpc", method: "task.create" } },
+  { name: "messaging_send", access: "write", outbound: true, binding: { kind: "rpc", method: "messaging.send" } },
+  { name: "books_invoice_send", access: "write", binding: { kind: "rpc", method: "books.invoiceSend" } },
+  { name: "linear_create_issue", access: "write", integration: "linear", binding: { kind: "rpc" } },
+];
+
+function deps({ home, orgOk = true, mandateFamily = true, logs = [] }) {
+  return {
+    homeDir: home,
+    now: () => AT,
+    logImpl: (m) => logs.push(m),
+    orgToolsImpl: async () => FAKE_ORG_TOOLS,
+    orgProbeImpl: async () => (orgOk
+      ? { ok: true, detail: "mandate.version round-trip ok", mandateFamily }
+      : { ok: false, detail: "org.cohort is not enabled", degraded: "org-not-enrolled", mandateFamily: false }),
+    capabilitySurface: async () => ({ workflows: [{ id: "weekly-operating-review", cadence: "weekly", purpose: "run the operating cadence" }] }),
+    wishlistImpl: async () => ([
+      { id: "cohort", env: [], optional: false, purpose: "org spine" },
+      { id: "notion", env: ["NOTION_API_KEY"], optional: true, purpose: "decision log" },
+    ]),
+  };
+}
+
+test("buildInventory: enumerates all four planes and marks unregistered skills UNREACHABLE", async () => {
+  const { root, home } = fixture();
+  const logs = [];
+  const m = await buildInventory({ agentRoot: root, archetype: { function: "executive-operator", altitude: "c-suite" } }, deps({ home, logs }));
+
+  assert.equal(m.schemaVersion, 1);
+  assert.equal(m.generatedAt, AT);
+  assert.ok(m.counts.builtin > 5, "builtins inventoried");
+  assert.ok(m.counts.skill >= 3, "2 skill files + 1 workflow");
+  assert.ok(m.counts.mcp >= 2, "cohort (declared) + notion (wished-for)");
+  assert.equal(m.counts.org, FAKE_ORG_TOOLS.length);
+
+  // The whole point: skills whose marketplace is unregistered are NOT reachable.
+  const skill = findCapability(m, "skill:agent-skills:morning-brief");
+  assert.ok(skill, "skill discovered");
+  assert.equal(skill.reachable, false);
+  assert.match(skill.probe.detail, /marketplace/);
+
+  // ...and it is LOGGED, not swallowed.
+  assert.ok(logs.some((l) => /DEGRADED skill plugin:agent-skills/.test(l)), `expected a logged degradation, got: ${logs.join(" | ")}`);
+});
+
+test("buildInventory: registered + enabled marketplace makes skills reachable", async () => {
+  const { root, home } = fixture({ withMarketplace: true, withEnabled: true });
+  const m = await buildInventory({ agentRoot: root, archetype: { function: "executive-operator", altitude: "c-suite" } }, deps({ home }));
+  const skill = findCapability(m, "skill:agent-skills:inbox-triage");
+  assert.equal(skill.reachable, true);
+  assert.ok(reachableIds(m).has("skill:agent-skills:inbox-triage"));
+});
+
+test("repair:true registers the marketplace and enables the plugin (rung 1 stops being a lie)", async () => {
+  const { root, home } = fixture();
+  const logs = [];
+  const m = await buildInventory({ agentRoot: root, repair: true, archetype: { function: "executive-operator", altitude: "c-suite" } }, deps({ home, logs }));
+  assert.ok(existsSync(join(root, "plugins", "agent-skills", ".claude-plugin", "marketplace.json")), "marketplace written");
+  const settings = JSON.parse(readFileSync(join(home, ".claude", "settings.json"), "utf8"));
+  assert.ok(Object.keys(settings.enabledPlugins).some((k) => k.startsWith("agent-skills")), "plugin enabled");
+  assert.equal(findCapability(m, "skill:agent-skills:morning-brief").reachable, true);
+  assert.ok(m.repairs.length >= 2 && logs.some((l) => /repaired/.test(l)));
+});
+
+test("mcp plane: wished-for server absent from .mcp.json is unreachable with a stated reason", async () => {
+  const { root, home } = fixture();
+  const m = await buildInventory({ agentRoot: root, archetype: { function: "executive-operator", altitude: "c-suite" } }, deps({ home }));
+  const notion = findCapability(m, "mcp:notion");
+  assert.equal(notion.reachable, false);
+  assert.match(notion.probe.detail, /absent from \.mcp\.json|credential env/);
+  const cohort = findCapability(m, "mcp:cohort");
+  assert.equal(cohort.reachable, true);
+});
+
+test("org plane: an un-enrolled agent inventories the tools but NONE are reachable", async () => {
+  const { root, home } = fixture();
+  const logs = [];
+  const m = await buildInventory({ agentRoot: root, archetype: { function: "executive-operator", altitude: "c-suite" } }, deps({ home, orgOk: false, logs }));
+  const org = byPlane(m, "org");
+  assert.equal(org.length, FAKE_ORG_TOOLS.length);
+  assert.equal(org.filter((e) => e.reachable).length, 0);
+  assert.equal(m.mandateFamily, false);
+  assert.ok(logs.some((l) => /org-not-enrolled/.test(l)));
+});
+
+test("blast radius: outbound → external, financial verbs → financial, reads → internal", () => {
+  assert.equal(blastRadiusOfOrgTool({ name: "messaging_send", access: "write", outbound: true }), "external");
+  assert.equal(blastRadiusOfOrgTool({ name: "books_invoice_send", access: "write" }), "financial");
+  assert.equal(blastRadiusOfOrgTool({ name: "board_ready", access: "read" }), "internal");
+  assert.equal(blastRadiusOfOrgTool({ name: "task_create", access: "write" }), "irreversible");
+});
+
+test("determinism: checksum is stable across runs and ignores probedAt", async () => {
+  const { root, home } = fixture({ withMarketplace: true, withEnabled: true });
+  const a = await buildInventory({ agentRoot: root, archetype: { function: "executive-operator", altitude: "c-suite" } }, deps({ home }));
+  const b = await buildInventory({ agentRoot: root, archetype: { function: "executive-operator", altitude: "c-suite" } }, { ...deps({ home }), now: () => "2027-01-01T00:00:00.000Z" });
+  assert.equal(a.checksum, b.checksum, "same capabilities → same checksum despite a different clock");
+  assert.notEqual(a.generatedAt, b.generatedAt);
+});
+
+test("checksum CHANGES when a capability's reachability flips", () => {
+  const base = [{ id: "x", plane: "org", kind: "method_tool", reachable: true }];
+  const flipped = [{ id: "x", plane: "org", kind: "method_tool", reachable: false }];
+  assert.notEqual(checksumEntries(base), checksumEntries(flipped));
+});
+
+test("write/read round-trip is atomic and queryable", async () => {
+  const { root, home } = fixture();
+  const m = await buildInventory({ agentRoot: root, archetype: { function: "executive-operator", altitude: "c-suite" } }, deps({ home }));
+  const p = writeManifest(root, m);
+  assert.equal(p, join(root, MANIFEST_REL));
+  const back = readManifest(root);
+  assert.equal(back.checksum, m.checksum);
+  assert.equal(byPlane(back, "builtin").length, byPlane(m, "builtin").length);
+});
+
+test("degradation is recorded when no archetype is supplied (never silent)", async () => {
+  const { root, home } = fixture();
+  const logs = [];
+  const m = await buildInventory({ agentRoot: root }, deps({ home, logs }));
+  assert.ok(m.degradations.some((d) => /archetype/.test(d.id)));
+  assert.ok(logs.some((l) => /archetype:workflows/.test(l)));
+});
+
+// ── probe-level units ────────────────────────────────────────────────────────
+
+test("probeMcpServer: missing credential env fails closed with the key named", () => {
+  const r = probeMcpServer({ name: "notion", declared: true, requiredEnv: ["NOTION_API_KEY"], env: {} });
+  assert.equal(r.ok, false);
+  assert.equal(r.degraded, "mcp-credential-missing");
+  assert.match(r.detail, /NOTION_API_KEY/);
+});
+
+test("probeMcpServer: an injected handshake decides the verdict", () => {
+  const ok = probeMcpServer({ name: "cohort", declared: true, env: {} }, { handshake: () => ({ ok: true, detail: "hello" }) });
+  assert.equal(ok.ok, true);
+  const bad = probeMcpServer({ name: "cohort", declared: true, env: {} }, { handshake: () => { throw new Error("spawn ENOENT"); } });
+  assert.equal(bad.ok, false);
+  assert.equal(bad.degraded, "mcp-handshake-threw");
+});
+
+test("probeOrgPlane: NOT_FOUND on mandate.version means transport LIVE, mandate family absent", async () => {
+  const r = await probeOrgPlane({ enabled: true, call: async () => ({ ok: false, error: { code: "NOT_FOUND" } }) });
+  assert.equal(r.ok, true, "the transport answered, so the plane is reachable");
+  assert.equal(r.mandateFamily, false);
+  assert.equal(r.degraded, "mandate-family-absent");
+});
+
+test("probeOrgPlane: falls back to a snapshot read, and a dead server is unreachable", async () => {
+  const ok = await probeOrgPlane({ enabled: true, call: async () => ({ ok: false, error: { code: "BAD_REQUEST" } }), read: async () => ({ ok: true }) });
+  assert.equal(ok.ok, true);
+  const dead = await probeOrgPlane({ enabled: true, call: async () => ({ ok: false, error: { code: "BAD_REQUEST" } }), read: async () => ({ ok: false, status: 503 }) });
+  assert.equal(dead.ok, false);
+  assert.equal(dead.degraded, "org-unreachable");
+});
+
+test("probeGrantedPluginTools: an absent toolset cache is reported, not swallowed", () => {
+  const { root } = fixture();
+  const r = probeGrantedPluginTools(root);
+  assert.equal(r.ok, false);
+  assert.equal(r.degraded, "toolset-absent");
+  mkdirSync(join(root, "state", "org"), { recursive: true });
+  writeFileSync(join(root, "state", "org", "toolset.json"), JSON.stringify({ version: 7, tools: [{ name: "linear_create_issue" }] }));
+  const r2 = probeGrantedPluginTools(root);
+  assert.equal(r2.ok, true);
+  assert.equal(r2.toolsetVersion, 7);
+});
+
+test("probeSkillPlugin: a plugin dir with no marketplace fails closed and names the path", () => {
+  const { root, home } = fixture();
+  const r = probeSkillPlugin({ pluginDir: join(root, "plugins", "agent-skills"), pluginId: "agent-skills" }, { homeDir: home });
+  assert.equal(r.ok, false);
+  assert.equal(r.degraded, "marketplace-unregistered");
+});
+
+test("enumerateSkills/enumerateMcp are pure over injected fs state", () => {
+  const { root, home } = fixture({ withMarketplace: true, withEnabled: true, skills: ["a", "b", "c"] });
+  const s = enumerateSkills({ agentRoot: root, at: AT }, { homeDir: home });
+  assert.equal(s.entries.length, 3);
+  assert.ok(s.entries.every((e) => e.plane === "skill" && e.reachable));
+
+  const m = enumerateMcp({ agentRoot: root, at: AT, env: {}, wishlist: [] }, {});
+  assert.deepEqual(m.entries.map((e) => e.id), ["mcp:cohort"]);
+});

package/lib/capability/probe.mjs

@@ -0,0 +1,255 @@
+/**
+ * lib/capability/probe.mjs — cheap REACHABILITY probes, one per capability plane.
+ *
+ * The inventory step (SPEC §5.1) is only worth anything if it reports what is
+ * actually *reachable*, not what is merely declared. A skill file on disk that
+ * belongs to an unregistered marketplace is not a capability; an MCP server in
+ * `.mcp.json` whose credential env is unset is not a capability; the 107 curated
+ * org tools are not capabilities until the org client is enrolled and answering.
+ *
+ * So every plane gets a probe:
+ *
+ *   skill  → is the plugin's marketplace registered AND the plugin enabled in
+ *            ~/.claude/settings.json `enabledPlugins`? (optionally repaired)
+ *   mcp    → does the server declaration hand-shake (injected), or at minimum
+ *            is it declared in .mcp.json with its required env present?
+ *   org    → does a protocol round-trip come back? (`mandate.version`, falling
+ *            back to a plain read, so this works before the mandate family ships)
+ *   plugin → is the granted tool present in state/org/toolset.json?
+ *
+ * DOCTRINE: fail-open but NEVER silent. Every probe returns
+ * `{ ok, detail, degraded? }` and never throws; a degradation is returned to the
+ * caller so the inventory can log it and record `reachable:false` — which is the
+ * whole point, since "an entry with reachable:false may not be cited by any
+ * obligation".
+ *
+ * Pure-ish + injectable: every side effect (fs, network, clock) arrives through
+ * `deps` so the tests run hermetically with fakes.
+ *
+ * @module lib/capability/probe
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/** The four capability planes an agent can act through. */
+export const PLANES = Object.freeze(["builtin", "skill", "mcp", "org"]);
+
+/** Probe verdict helper. @returns {{ok:boolean, detail:string, degraded?:string}} */
+function verdict(ok, detail, degraded) {
+  const v = { ok: !!ok, detail: String(detail || "") };
+  if (degraded) v.degraded = String(degraded);
+  return v;
+}
+
+/** Read + parse a JSON file; returns `fallback` (never throws). */
+export function readJsonSafe(path, fallback = null, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const rd = deps.readFileSync || readFileSync;
+  try {
+    if (!ex(path)) return fallback;
+    return JSON.parse(rd(path, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plane: skill (Claude Code plugins + their skills)
+// ---------------------------------------------------------------------------
+
+/**
+ * Path to the Claude Code user settings that carries `enabledPlugins`.
+ * @param {object} [deps] - { homeDir }
+ */
+export function claudeSettingsPath(deps = {}) {
+  return join(deps.homeDir || homedir(), ".claude", "settings.json");
+}
+
+/**
+ * Probe the skill plane: a plugin's skills are reachable only when the plugin's
+ * marketplace manifest exists AND the plugin is listed in `enabledPlugins`.
+ *
+ * With `repair:true` this *fixes* both halves (writes the missing
+ * `.claude-plugin/marketplace.json`, appends the enabledPlugins entry) — SPEC
+ * §5.1 explicitly allows the probe to register the marketplace, because rung 1
+ * of the execution ladder is a lie until it is.
+ *
+ * @param {object} o
+ * @param {string} o.pluginDir       absolute path to the plugin directory
+ * @param {string} o.pluginId        the plugin id (directory basename)
+ * @param {boolean} [o.repair=false] write the marketplace manifest / enable entry
+ * @param {object} [deps] - { existsSync, readFileSync, writeFileSync, mkdirSync, homeDir }
+ * @returns {{ok:boolean, detail:string, degraded?:string, repaired?:string[]}}
+ */
+export function probeSkillPlugin(o = {}, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const rd = deps.readFileSync || readFileSync;
+  const wr = deps.writeFileSync || writeFileSync;
+  const mk = deps.mkdirSync || mkdirSync;
+  const { pluginDir, pluginId, repair = false } = o;
+  if (!pluginDir || !pluginId) return verdict(false, "probeSkillPlugin: pluginDir + pluginId required", "bad-input");
+
+  const repaired = [];
+  const marketplacePath = join(pluginDir, ".claude-plugin", "marketplace.json");
+  let marketplaceOk = ex(marketplacePath);
+  if (!marketplaceOk && repair) {
+    try {
+      mk(dirname(marketplacePath), { recursive: true });
+      const manifest = {
+        name: pluginId,
+        owner: { name: "maestro" },
+        plugins: [{ name: pluginId, source: "./", description: `maestro ${pluginId} skill pack` }],
+      };
+      wr(marketplacePath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+      marketplaceOk = true;
+      repaired.push(`wrote ${marketplacePath}`);
+    } catch (e) {
+      return { ...verdict(false, `marketplace manifest missing and could not be written: ${msg(e)}`, "marketplace-unwritable"), repaired };
+    }
+  }
+  if (!marketplaceOk) {
+    return { ...verdict(false, `no .claude-plugin/marketplace.json under ${pluginDir}`, "marketplace-unregistered"), repaired };
+  }
+
+  const settingsPath = claudeSettingsPath(deps);
+  let settings = readJsonSafe(settingsPath, null, { existsSync: ex, readFileSync: rd });
+  const enabled = settings && settings.enabledPlugins && typeof settings.enabledPlugins === "object"
+    ? settings.enabledPlugins
+    : null;
+  const keyed = enabled ? Object.keys(enabled).some((k) => k === pluginId || k.startsWith(`${pluginId}@`)) : false;
+  const on = keyed && Object.entries(enabled).some(([k, v]) => (k === pluginId || k.startsWith(`${pluginId}@`)) && v !== false);
+
+  if (!on && repair) {
+    try {
+      settings = settings && typeof settings === "object" ? settings : {};
+      settings.enabledPlugins = settings.enabledPlugins && typeof settings.enabledPlugins === "object" ? settings.enabledPlugins : {};
+      settings.enabledPlugins[`${pluginId}@${pluginId}`] = true;
+      mk(dirname(settingsPath), { recursive: true });
+      wr(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+      repaired.push(`enabled ${pluginId} in ${settingsPath}`);
+      return { ...verdict(true, "marketplace registered + plugin enabled (repaired)"), repaired };
+    } catch (e) {
+      return { ...verdict(false, `plugin not enabled and settings unwritable: ${msg(e)}`, "settings-unwritable"), repaired };
+    }
+  }
+  if (!on) {
+    return { ...verdict(false, `plugin "${pluginId}" not in enabledPlugins (${settingsPath})`, "plugin-disabled"), repaired };
+  }
+  return { ...verdict(true, "marketplace registered + plugin enabled"), repaired };
+}
+
+// ---------------------------------------------------------------------------
+// Plane: mcp
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe one MCP server. The default probe is declaration + credential presence
+ * (cheap, offline, deterministic). A real hand-shake can be injected as
+ * `deps.handshake(name, entry) -> {ok, detail}` — the inventory passes one only
+ * when the operator asked for a live probe, because spawning every MCP server
+ * during setup is neither cheap nor safe.
+ *
+ * @param {object} o - { name, entry, declared, requiredEnv?, env? }
+ * @param {object} [deps] - { handshake }
+ * @returns {{ok:boolean, detail:string, degraded?:string}}
+ */
+export function probeMcpServer(o = {}, deps = {}) {
+  const { name, entry, declared, requiredEnv = [], env = process.env } = o;
+  if (!name) return verdict(false, "probeMcpServer: name required", "bad-input");
+  if (!declared) return verdict(false, `"${name}" is declared in config/mcp-servers.yaml but absent from .mcp.json`, "mcp-undeclared");
+
+  const missingEnv = (requiredEnv || []).filter((k) => !env || !env[k]);
+  if (missingEnv.length) {
+    return verdict(false, `"${name}" missing credential env: ${missingEnv.join(", ")}`, "mcp-credential-missing");
+  }
+  if (typeof deps.handshake === "function") {
+    try {
+      const r = deps.handshake(name, entry);
+      if (r && typeof r.then === "function") return verdict(false, `"${name}" handshake returned a promise; use probeMcpServerAsync`, "mcp-handshake-async");
+      return r && r.ok ? verdict(true, r.detail || "handshake ok") : verdict(false, (r && r.detail) || "handshake failed", "mcp-handshake-failed");
+    } catch (e) {
+      return verdict(false, `"${name}" handshake threw: ${msg(e)}`, "mcp-handshake-threw");
+    }
+  }
+  return verdict(true, `"${name}" declared in .mcp.json with credentials present`);
+}
+
+// ---------------------------------------------------------------------------
+// Plane: org (protocol methods + granted integration tools)
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe the org plane with one round-trip. Tries `mandate.version` first (the
+ * cheap ETag poll the SPEC defines); an `unknown method` reply still proves the
+ * transport + credential are live, so it counts as reachable-but-old-server and
+ * is reported as such. Falls back to a `snapshot` read.
+ *
+ * @param {object} o - { enabled, call?, read? }  (call/read are lib/org/client shapes)
+ * @returns {Promise<{ok:boolean, detail:string, degraded?:string, mandateFamily:boolean}>}
+ */
+export async function probeOrgPlane(o = {}) {
+  const { enabled, call, read } = o;
+  if (!enabled) return { ...verdict(false, "org.cohort is not enabled in config/org.yaml", "org-not-enrolled"), mandateFamily: false };
+
+  if (typeof call === "function") {
+    try {
+      const r = await call("mandate.version", {});
+      if (r && r.ok) return { ...verdict(true, "mandate.version round-trip ok"), mandateFamily: true };
+      const code = r && r.error && r.error.code ? r.error.code : "";
+      if (code === "NOT_FOUND") {
+        // The transport answered — the server (or the vendored protocol) simply
+        // predates the mandate family. Reachable, but the mandate spine is not.
+        return {
+          ...verdict(true, "org transport live; mandate family not present on this server/protocol", "mandate-family-absent"),
+          mandateFamily: false,
+        };
+      }
+      // fall through to the read probe before declaring the plane dead
+    } catch (e) {
+      return { ...verdict(false, `mandate.version threw: ${msg(e)}`, "org-call-threw"), mandateFamily: false };
+    }
+  }
+
+  if (typeof read === "function") {
+    try {
+      const r = await read("snapshot");
+      if (r && r.ok) return { ...verdict(true, "snapshot read ok"), mandateFamily: false };
+      return { ...verdict(false, `snapshot read failed (${(r && r.status) || "?"})`, "org-unreachable"), mandateFamily: false };
+    } catch (e) {
+      return { ...verdict(false, `snapshot read threw: ${msg(e)}`, "org-call-threw"), mandateFamily: false };
+    }
+  }
+  return { ...verdict(false, "no org call/read impl supplied", "org-no-impl"), mandateFamily: false };
+}
+
+/**
+ * Probe granted org PLUGIN tools: they are reachable iff they are present in the
+ * shared disk cache the daemon and MCP plane both read.
+ * @param {string} agentRoot
+ * @param {object} [deps] - { existsSync, readFileSync }
+ * @returns {{ok:boolean, detail:string, degraded?:string, tools:object[], toolsetVersion:number|null}}
+ */
+export function probeGrantedPluginTools(agentRoot, deps = {}) {
+  const p = join(agentRoot, "state", "org", "toolset.json");
+  const doc = readJsonSafe(p, null, deps);
+  if (!doc) {
+    return { ...verdict(false, `no state/org/toolset.json (no granted plugin tools cached)`, "toolset-absent"), tools: [], toolsetVersion: null };
+  }
+  const tools = Array.isArray(doc.tools) ? doc.tools.filter((t) => t && typeof t.name === "string") : [];
+  return {
+    ...verdict(tools.length > 0, `${tools.length} granted plugin tool(s) in state/org/toolset.json`, tools.length ? undefined : "toolset-empty"),
+    tools,
+    toolsetVersion: typeof doc.version === "number" ? doc.version : null,
+  };
+}
+
+/** @param {*} e @returns {string} */
+function msg(e) {
+  return e && e.message ? String(e.message) : String(e);
+}
+
+export default { PLANES, probeSkillPlugin, probeMcpServer, probeOrgPlane, probeGrantedPluginTools, claudeSettingsPath, readJsonSafe };

package/lib/channels/contract.mjs

@@ -32,13 +32,38 @@
 // ---------------------------------------------------------------------------
 
 /**
- * @typedef {"message"|"reaction"|"channel_cc"|"voice_note"|"call"} EventKind
+ * @typedef {"message"|"reaction"|"channel_cc"|"voice_note"|"call"
+ *          |"mention"|"thread_reply"|"task_assigned"|"task_comment"
+ *          |"file_comment"|"approval"|"decision"|"escalation"|"handoff"
+ *          |"email"} EventKind
  *
+ * Chat kinds:
  * - message     a normal directed message (DM, @mention, thread reply)
  * - reaction    an emoji reaction add/remove (rarely action-required)
  * - channel_cc  a non-directed message in a watched/cc channel (observe, don't reply)
  * - voice_note  a voice note whose transcript becomes `text` (+ a voice_note attachment)
  * - call        a live phone/voice call turn
+ *
+ * WORK-SURFACE kinds (added for wide org inbound — lib/org/inbound/surfaces.mjs).
+ * An org agent is addressed through far more than chat: hq's own responder reacts
+ * to eleven inbound triggers, and an SDK agent that tails only `messaging` is
+ * deaf to nine of them. These kinds are the ROUTING HINT the daemon classifier
+ * reads off the inbox item, so a board assignment and an @mention do not have to
+ * be told apart by parsing prose:
+ * - mention        an @mention of this agent in a public/private space
+ * - thread_reply   a reply in a thread this agent is part of
+ * - task_assigned  a board item assigned to / claimed for this agent
+ * - task_comment   a comment, block or move on an item this agent owns or reviews
+ * - file_comment   a comment on a chat file or workspace doc this agent owns/shares
+ * - approval       an approval on this agent's desk, or the outcome of its request
+ * - decision       a decision this agent proposed, commented on, or must act on
+ * - escalation     an escalation on this agent's task / room / name
+ * - handoff        a delegation offered to this agent, or its offer resolved
+ * - email          an inbound email routed to this agent's mailbox
+ *
+ * `classifyByKind` (scripts/daemon/classify-kind.mjs) deliberately returns null
+ * for every work-surface kind, so they fall through to the normal LLM classifier
+ * — unlike `reaction`/`channel_cc`, a task assignment genuinely needs triage.
  */
 export const EVENT_KINDS = Object.freeze([
   "message",
@@ -46,6 +71,17 @@ export const EVENT_KINDS = Object.freeze([
   "channel_cc",
   "voice_note",
   "call",
+  // Work surfaces (org inbound).
+  "mention",
+  "thread_reply",
+  "task_assigned",
+  "task_comment",
+  "file_comment",
+  "approval",
+  "decision",
+  "escalation",
+  "handoff",
+  "email",
 ]);
 
 /** The default kind when an event/serialized item does not specify one. */

package/lib/channels/contract.test.mjs

@@ -25,7 +25,31 @@ import {
 import { ChannelMessage } from "./index.mjs";
 
 test("EVENT_KINDS is the closed set from the design", () => {
-  assert.deepEqual([...EVENT_KINDS].sort(), ["call", "channel_cc", "message", "reaction", "voice_note"]);
+  // Two groups. The five CHAT kinds are the original design set and must not
+  // move — `message` in particular is the default and the byte-compat anchor.
+  // The ten WORK-SURFACE kinds were added for wide org inbound
+  // (lib/org/inbound/surfaces.mjs): an org agent is addressed through board
+  // items, approvals, decisions, docs and mail as well as chat, and `kind` is
+  // the routing hint the daemon classifier reads. Adding one here without a
+  // matching SURFACES entry (or vice versa) is caught by
+  // lib/org/inbound/project.test.mjs.
+  assert.deepEqual([...EVENT_KINDS].sort(), [
+    "approval",
+    "call",
+    "channel_cc",
+    "decision",
+    "email",
+    "escalation",
+    "file_comment",
+    "handoff",
+    "mention",
+    "message",
+    "reaction",
+    "task_assigned",
+    "task_comment",
+    "thread_reply",
+    "voice_note",
+  ]);
   assert.equal(DEFAULT_EVENT_KIND, "message");
 });
 

package/lib/claude-bin.mjs

@@ -105,11 +105,45 @@ export function resolveClaudeBin() {
  *
  * Operators who want full MCP support on daemon spawns can set
  * DAEMON_LOAD_MCPS=1 in .env; the spawn sites will skip these flags.
+ *
+ *   --mcp-config <AGENT_ROOT>/.mcp.json                     (added when present)
+ *     `--strict-mcp-config` ALONE is a blanket "load no MCP servers at all".
+ *     That was correct for skipping Serena/Playwright, but it also killed the
+ *     agent's OWN curated org MCP server — the one that carries the ~107 Cohort
+ *     protocol tools. Rung 0 of the execution ladder ("one protocol method,
+ *     params fully known") is a lie while every daemon spawn runs with zero org
+ *     tools loaded, and the capability manifest's `org` plane would be claiming
+ *     reachability for tools no session can actually call.
+ *
+ *     Pairing `--mcp-config <file>` WITH `--strict-mcp-config` is the precise
+ *     statement we want: load exactly this server set, and nothing globally
+ *     installed. The agent's own tools come back; the IDE-grade plugins stay out.
+ *
+ * @param {string} [agentRoot] - defaults to $AGENT_ROOT, then cwd. Callers that
+ *   pass nothing keep working; the flag is only added when the file exists, so a
+ *   scaffold without an .mcp.json degrades to exactly the previous behaviour.
+ * @param {{existsSync?:Function, env?:object}} [deps]
+ * @returns {string[]}
  */
-export function daemonClaudeArgs() {
-  if (process.env.DAEMON_LOAD_MCPS === "1") return [];
+export function daemonClaudeArgs(agentRoot, deps = {}) {
+  const env = deps.env || process.env;
+  if (env.DAEMON_LOAD_MCPS === "1") return [];
+  const ex = deps.existsSync || existsSync;
+
   const args = ["--strict-mcp-config"];
-  if (process.env.DAEMON_BARE_MODE === "1") args.unshift("--bare");
+
+  const root = agentRoot || env.AGENT_ROOT || process.cwd();
+  try {
+    const cfg = join(root, ".mcp.json");
+    // Opt-out for an operator who genuinely wants the old blanket behaviour.
+    if (env.DAEMON_SKIP_ORG_MCP !== "1" && ex(cfg)) args.unshift("--mcp-config", cfg);
+  } catch {
+    // A non-string root (bad caller) must not take the daemon down: we still
+    // return a usable arg list. Nothing is silent — the absence of the flag is
+    // visible in the spawn line every caller already logs.
+  }
+
+  if (env.DAEMON_BARE_MODE === "1") args.unshift("--bare");
   return args;
 }