@cohortapp/agent-sdk 2.3.0

package/lib/org/protocol.test.mjs

@@ -0,0 +1,264 @@
+/**
+ * Tests for lib/org/protocol.mjs — the shared Cohort protocol contract.
+ * Locks the load-bearing invariants: scope resolution (default-deny + reserved
+ * namespaces), the hash chain (determinism + tamper detection), and frame
+ * validation. @module lib/org/protocol.test
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  PROTOCOL_VERSION, METHODS, FAMILIES, BOARD_STATUS,
+  scopeForMethod, actorCan, isReservedAdminNamespace,
+  computeRowHash, verifyChain, canonicalize,
+  validateReqFrame, buildReqFrame, okFrame, errFrame,
+} from "./protocol.mjs";
+
+test("protocol: every method's family is a known family", () => {
+  for (const [name, def] of Object.entries(METHODS)) {
+    assert.ok(FAMILIES.includes(def.family), `${name} family ${def.family} is known`);
+  }
+});
+
+test("scopeForMethod: reserved namespaces always resolve to admin", () => {
+  assert.equal(scopeForMethod("admin.deactivate"), "admin");
+  assert.equal(scopeForMethod("pairing.request"), "admin");
+  assert.equal(scopeForMethod("policy.anything"), "admin");
+  assert.equal(scopeForMethod("governance.x"), "admin");
+  // unknown method → admin (deny)
+  assert.equal(scopeForMethod("totally.unknown"), "admin");
+  // ordinary method → its declared scope
+  assert.equal(scopeForMethod("board.claim"), "board.work");
+});
+
+test("actorCan: default-deny; admin satisfies everything", () => {
+  assert.equal(actorCan(["board.work"], "board.claim"), true);
+  assert.equal(actorCan(["board.read"], "board.claim"), false, "wrong scope denied");
+  assert.equal(actorCan(["admin"], "board.claim"), true, "admin is a superset");
+  assert.equal(actorCan(["board.work"], "admin.deactivate"), false, "non-admin cannot kill-switch");
+  assert.equal(actorCan([], "board.claim"), false);
+  assert.equal(actorCan(null, "board.claim"), false);
+});
+
+test("isReservedAdminNamespace", () => {
+  assert.equal(isReservedAdminNamespace("admin.x"), true);
+  assert.equal(isReservedAdminNamespace("board.claim"), false);
+});
+
+test("canonicalize: key order does not change the bytes", () => {
+  assert.equal(canonicalize({ b: 1, a: 2 }), canonicalize({ a: 2, b: 1 }));
+  assert.equal(canonicalize({ a: { y: 1, x: 2 } }), '{"a":{"x":2,"y":1}}');
+});
+
+test("computeRowHash: deterministic + sensitive to every field", () => {
+  const row = { seq: 1, family: "board", kind: "create", entity_id: "i1", actor: "a", at: "2026-06-11T00:00:00Z", payload: { title: "x" } };
+  const h1 = computeRowHash("", row);
+  const h2 = computeRowHash("", { ...row });
+  assert.equal(h1, h2, "same input → same hash");
+  assert.notEqual(h1, computeRowHash("prev", row), "prev hash matters");
+  assert.notEqual(h1, computeRowHash("", { ...row, payload: { title: "y" } }), "payload matters");
+  assert.notEqual(h1, computeRowHash("", { ...row, seq: 2 }), "seq matters");
+  assert.match(h1, /^[0-9a-f]{64}$/, "lowercase hex sha-256");
+});
+
+test("verifyChain: accepts a valid chain, pinpoints tampering", () => {
+  const mk = (seq, prev, payload) => {
+    const base = { seq, family: "board", kind: "create", entity_id: `i${seq}`, actor: "a", at: `2026-06-11T00:00:0${seq}Z`, payload };
+    return { ...base, prev_hash: prev, row_hash: computeRowHash(prev, base) };
+  };
+  const e1 = mk(1, "", { n: 1 });
+  const e2 = mk(2, e1.row_hash, { n: 2 });
+  const e3 = mk(3, e2.row_hash, { n: 3 });
+  assert.equal(verifyChain([e1, e2, e3]), null, "clean chain verifies");
+
+  // Tamper with e2's payload but keep its stored row_hash → detected at index 1.
+  const tampered = { ...e2, payload: { n: 999 } };
+  const break1 = verifyChain([e1, tampered, e3]);
+  assert.ok(break1 && break1.index === 1, "tamper detected at the rewritten row");
+
+  // Splice/delete e2 → e3.prev_hash no longer matches → detected at index 1.
+  const break2 = verifyChain([e1, e3]);
+  assert.ok(break2 && break2.index === 1, "deletion detected");
+});
+
+test("validateReqFrame: registry-checked", () => {
+  assert.equal(validateReqFrame(buildReqFrame("board.claim", { id: "x" })).ok, true);
+  assert.equal(validateReqFrame({ method: "nope.method" }).ok, false);
+  assert.equal(validateReqFrame({}).ok, false);
+  assert.equal(validateReqFrame({ method: "board.claim", params: 7 }).ok, false);
+});
+
+test("ok/err frames + version", () => {
+  assert.deepEqual(okFrame({ a: 1 }), { ok: true, result: { a: 1 } });
+  const e = errFrame("FORBIDDEN_SCOPE", "no");
+  assert.equal(e.ok, false);
+  assert.equal(e.error.code, "FORBIDDEN_SCOPE");
+  assert.equal(errFrame("MADE_UP", "x").error.code, "INTERNAL", "unknown code coerces to INTERNAL");
+  assert.equal(PROTOCOL_VERSION, 1);
+  assert.ok(BOARD_STATUS.includes("ready") && BOARD_STATUS.includes("done"));
+});
+
+test("protocol phase 2: governance gating + new families/scopes", async () => {
+  const p = await import("./protocol.mjs");
+  // handoffs + assignment/decomposition are governance-gated; ordinary board ops are not.
+  for (const m of ["handoff.offer", "handoff.accept", "handoff.decline", "handoff.cancel", "board.assign", "board.decompose"]) {
+    assert.equal(p.isGovernanceGated(m), true, `${m} is governance-gated`);
+  }
+  for (const m of ["board.create", "board.claim", "lease.claim", "registry.heartbeat"]) {
+    assert.equal(p.isGovernanceGated(m), false, `${m} is NOT governance-gated`);
+  }
+  // new scopes resolve; lease/handoff are in the default agent set, governance is admin-only.
+  assert.equal(p.scopeForMethod("lease.claim"), "lease.write");
+  assert.equal(p.scopeForMethod("handoff.offer"), "handoff.send");
+  assert.equal(p.scopeForMethod("governance.set_decision_rights"), "admin");
+  assert.ok(p.DEFAULT_AGENT_SCOPES.includes("lease.write") && p.DEFAULT_AGENT_SCOPES.includes("handoff.send"));
+  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "governance.set_decision_rights"), false, "agents cannot set decision rights");
+  assert.ok(p.FAMILIES.includes("lease") && p.FAMILIES.includes("handoff") && p.FAMILIES.includes("governance"));
+});
+
+test("protocol: frozen family + method counts (additive evolution guard)", () => {
+  // These counts move ONLY when the protocol intentionally grows; pinning them
+  // catches an accidental method drop/addition that the checksum alone wouldn't
+  // explain. Bump deliberately alongside the descriptors.
+  // 47 = the 19 mesh-protocol families + 20 agent UI-parity families (charter,
+  // member, team, channel, persona, profile, sop, escalation, annotation,
+  // contact, file, memory, compact, notification, invitation, user, settings,
+  // billing, org, integration) + 1 Brand Studio v2 family (branding) + 1
+  // workspace-email family (email; 2026-07-21 agent-email-server spec §8.1)
+  // + 1 generative-UI artifact family (artifact; GU program 2026-07)
+  // + 5 agent-desk families (2026-07): books (Books desk), calendar
+  // (workspace calendar), crm (CRM desk), files (workspace drive — distinct
+  // from the UI-parity "file" pins/comments family), and directory (external
+  // people + organisations; the Design half of that program rides the existing
+  // `branding` family — the section is renamed, the wire name is not).
+  assert.equal(FAMILIES.length, 47, "family count");
+  // 357 = the mesh-protocol + agent UI-parity + calling + branding + email
+  // methods, plus the Live Integrations surface: integration.toolsetVersion +
+  // integration.listAgentTools (SP1) and integration.invokeTool (SP5, execute a
+  // granted plugin tool as the seat), plus the six artifact methods
+  // (create/act/patch/get/list/catalog — GU program 2026-07), plus the 141
+  // agent-desk methods (2026-07, the integration manifest's definitive table):
+  // books 43, calendar 8, crm 43 (38 + the guest-call trio addCallGuest/
+  // mintGuestToken/linkEmail back-ported from Cohort 2026-07-25 + the
+  // articulation program's proposeTerms/revokeDealShare), the email Inbox-app
+  // surface 31, files 20, and meetings.recapFile. Then the 2026-07 Directory &
+  // Design program adds 44: directory 34 (11 reads + 23 writes, of which the
+  // merge/awareness/archive verbs are human-gated in the hq domain) and 10 new
+  // branding methods (getFoundation, getVoice, listTemplates, renderTemplate,
+  // rewriteInVoice, exportKit, generateImage, proposeChange, saveFoundation,
+  // restoreFoundation) taking branding 14 → 24. The 2026-08 mobile-program
+  // parity pass adds 16: email 5 (reportSpam/react/moveMailbox/summarise/ask),
+  // files 9 (sheetTabOp/docTabOp/docSuggestResolve/docSuggestions/commentAdd/
+  // commentResolve/comments/sheetFedRange/ask), calendar.ask and crm.ask.
+  // The 2026-08 host-moderation pass adds 2: calling.removeParticipant +
+  // calling.setLock (host-gated remove-from-room + room lock) → 424.
+  // The 2026-08 call working-sessions pass adds 6: calling.appShareStart/
+  // appShareAct/appShareEnd (agent app-share lifecycle) + getAppShare/
+  // getVisualContext/getCallEvents (participation-gated reads) → 430.
+  // Bumped deliberately alongside
+  // the descriptors; the checksum (read at runtime) is the primary drift guard.
+  assert.equal(Object.keys(METHODS).length, 430, "method count");
+});
+
+test("protocol SP3: messaging + calling families/methods/scopes", async () => {
+  const p = await import("./protocol.mjs");
+  // new families exist.
+  assert.ok(p.FAMILIES.includes("messaging") && p.FAMILIES.includes("calling"));
+  // messaging methods + their declared scopes / side-effect posture.
+  const messagingMethods = {
+    "messaging.send": { scope: "messaging.write", sideEffecting: true, idempotent: true },
+    "messaging.react": { scope: "messaging.write", sideEffecting: true },
+    "messaging.edit": { scope: "messaging.write", sideEffecting: true },
+    "messaging.history": { scope: "messaging.read", sideEffecting: false },
+    "messaging.channels": { scope: "messaging.read", sideEffecting: false },
+  };
+  for (const [m, want] of Object.entries(messagingMethods)) {
+    const def = p.METHODS[m];
+    assert.ok(def, `${m} is registered`);
+    assert.equal(def.family, "messaging", `${m} family`);
+    assert.equal(def.scope, want.scope, `${m} scope`);
+    assert.equal(p.scopeForMethod(m), want.scope, `${m} scopeForMethod`);
+    assert.equal(def.sideEffecting, want.sideEffecting, `${m} sideEffecting`);
+    if (want.idempotent) assert.equal(def.idempotent, true, `${m} idempotent`);
+  }
+  // send is idempotent via the client-supplied message id.
+  assert.equal(p.METHODS["messaging.send"].idempotent, true);
+  // calling methods: all calling.write + side-effecting. removeParticipant +
+  // setLock are the 2026-08 host-moderation verbs (host-gated in the hq domain).
+  for (const m of ["calling.start", "calling.join", "calling.end", "calling.invite", "calling.removeParticipant", "calling.setLock"]) {
+    const def = p.METHODS[m];
+    assert.ok(def, `${m} is registered`);
+    assert.equal(def.family, "calling", `${m} family`);
+    assert.equal(def.scope, "calling.write", `${m} scope`);
+    assert.equal(p.scopeForMethod(m), "calling.write", `${m} scopeForMethod`);
+    assert.equal(def.sideEffecting, true, `${m} sideEffecting`);
+  }
+  // messaging/calling are NOT reserved-admin namespaces (scope is NOT forced to admin).
+  assert.equal(p.isReservedAdminNamespace("messaging.send"), false);
+  assert.equal(p.isReservedAdminNamespace("calling.start"), false);
+  // new scopes are first-class capabilities.
+  for (const s of ["messaging.read", "messaging.write", "calling.write"]) {
+    assert.ok(p.SCOPES.includes(s), `SCOPES includes ${s}`);
+  }
+  // agents participate in the human app: the new scopes are in the default set.
+  for (const s of ["messaging.read", "messaging.write", "calling.write"]) {
+    assert.ok(p.DEFAULT_AGENT_SCOPES.includes(s), `DEFAULT_AGENT_SCOPES includes ${s}`);
+  }
+  // a default-scoped agent can actually exercise the new surfaces.
+  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "messaging.send"), true);
+  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "messaging.history"), true);
+  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "calling.start"), true);
+  // default-deny still holds: a read-only token cannot send.
+  assert.equal(p.actorCan(["messaging.read"], "messaging.send"), false);
+});
+
+test("protocol agent desks: per-family scope pairs, counts, and default grants", async () => {
+  const p = await import("./protocol.mjs");
+  // Each desk family rides its OWN read/write scope pair (the integration
+  // manifest's declared contract) so a key can be minted for exactly one desk.
+  // 2026-08 mobile-parity delta: crm +ask (44), calendar +ask (9), files +9
+  // (tab/suggestion/comment/fed-range ops + ask → 29).
+  const desks = { books: 43, crm: 44, files: 29, calendar: 9 };
+  for (const [fam, want] of Object.entries(desks)) {
+    const rows = Object.entries(p.METHODS).filter(([, d]) => d.family === fam);
+    assert.equal(rows.length, want, `${fam} method count`);
+    for (const [name, d] of rows) {
+      assert.ok(
+        d.scope === `${fam}.read` || d.scope === `${fam}.write`,
+        `${name} rides the ${fam}.read/${fam}.write pair (got ${d.scope})`,
+      );
+      if (d.scope === `${fam}.read` && name !== "files.exportRequest") {
+        assert.equal(d.sideEffecting, false, `${name} read is sideEffecting:false`);
+      }
+    }
+    assert.ok(p.SCOPES.includes(`${fam}.read`) && p.SCOPES.includes(`${fam}.write`), `${fam} scope pair declared`);
+    assert.ok(
+      p.DEFAULT_AGENT_SCOPES.includes(`${fam}.read`) && p.DEFAULT_AGENT_SCOPES.includes(`${fam}.write`),
+      `${fam} scopes in the default agent set`,
+    );
+  }
+  // The email Inbox-app surface rides the existing email pair: 41 methods
+  // total (36 + the 2026-08 spam/react/moveMailbox/summarise/ask delta).
+  assert.equal(Object.entries(p.METHODS).filter(([, d]) => d.family === "email").length, 41, "email method count");
+  assert.equal(p.scopeForMethod("email.draftSend"), "email.write");
+  assert.equal(p.scopeForMethod("email.mailboxes"), "email.read");
+  // files.exportRequest is the AUDITED export: read scope, side-effecting.
+  assert.deepEqual(
+    { scope: p.METHODS["files.exportRequest"].scope, se: p.METHODS["files.exportRequest"].sideEffecting },
+    { scope: "files.read", se: true },
+  );
+  // meetings.recapFile is knowledge capture (meetings family, knowledge.write).
+  assert.equal(p.METHODS["meetings.recapFile"].scope, "knowledge.write");
+  assert.equal(p.METHODS["meetings.recapFile"].family, "meetings");
+  // Spot-check idempotency posture from the manifest: draftSend/ruleSave are
+  // NOT idempotent (each send/save is a new act); holdReplies/markAllRead are.
+  assert.ok(!p.METHODS["email.draftSend"].idempotent);
+  assert.ok(!p.METHODS["email.ruleSave"].idempotent);
+  assert.equal(p.METHODS["email.holdReplies"].idempotent, true);
+  assert.equal(p.METHODS["email.markAllRead"].idempotent, true);
+  // A default-scoped agent can work the desks; a single-desk token stays fenced.
+  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "books.invoiceDraft"), true);
+  assert.equal(p.actorCan(p.DEFAULT_AGENT_SCOPES, "crm.listDeals"), true);
+  assert.equal(p.actorCan(["books.read"], "books.invoiceDraft"), false, "read tier cannot write");
+  assert.equal(p.actorCan(["books.read", "books.write"], "crm.createDeal"), false, "books key cannot touch crm");
+});

package/lib/org/registry.mjs

@@ -0,0 +1,194 @@
+/**
+ * lib/org/registry.mjs — the org-directory source of truth (file-backed).
+ *
+ * Assembles THIS agent's directory entry from data that already exists in the
+ * repo — identity (config/agent.json), company (config/company.json), resolved
+ * archetype (function × altitude → towers), current backlog focus (state/queues),
+ * and live presence — then publishes it to state/org/self.json. Peers come from
+ * config/known-agents.json (+ any state/org/peers/*.json synced from cohort).
+ *
+ * The entry shape is the contract the cohort client (lib/org/cohort-client.mjs)
+ * publishes and that humans read in the org-pulse digest. Pure assembly +
+ * fail-open I/O; never throws.
+ *
+ * @module lib/org/registry
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const ORG_REL = "state/org";
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+let _yaml = null;
+async function getYaml() {
+  if (_yaml) return _yaml;
+  const m = await import("js-yaml");
+  _yaml = m.default || m;
+  return _yaml;
+}
+
+/** Parse config/agent.json (identity SOT). Tolerant. */
+export function readIdentity(agentRoot) {
+  return readJson(join(agentRoot, "config", "agent.json")) || {};
+}
+
+/** Parse config/company.json. Tolerant. */
+export function readCompany(agentRoot) {
+  return readJson(join(agentRoot, "config", "company.json")) || {};
+}
+
+/** Parse config/known-agents.json → peer list. Tolerant. */
+export function readPeers(agentRoot) {
+  const obj = readJson(join(agentRoot, "config", "known-agents.json"));
+  return obj && Array.isArray(obj.agents) ? obj.agents : [];
+}
+
+/**
+ * Build a directory entry from already-loaded pieces. Pure.
+ *
+ * @param {object} o - { identity, company, profile?, focus?, presence?, nowMs? }
+ * @returns {object} entry
+ */
+export function buildSelfEntry(o = {}) {
+  const id = o.identity || {};
+  const company = o.company || {};
+  const profile = o.profile || null;
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const towers = profile && Array.isArray(profile.towers)
+    ? profile.towers.map((t) => ({ id: t.id, name: t.name })).slice(0, 12)
+    : [];
+  const repo = id.repoSlug || (id.firstName ? `${String(id.firstName).toLowerCase()}-ai` : "");
+  return {
+    id: id.repoSlug || repo || String(id.firstName || "agent").toLowerCase(),
+    name: id.firstName || "",
+    fullName: id.fullName || "",
+    title: id.title || "",
+    email: id.email || "",
+    phone: id.phone || "",
+    slackId: id.slackMemberId || id.slackId || "",
+    repo,
+    archetype: {
+      function: id.function || (profile && profile.function) || "",
+      altitude: id.altitude || (profile && profile.altitude) || "",
+      label: (profile && profile.label) || id.archetype || "",
+    },
+    towers,
+    focus: Array.isArray(o.focus) ? o.focus.slice(0, 8) : [],
+    company: { name: company.name || id.company || "", domain: company.domain || id.companyDomain || "" },
+    principal: id.principal
+      ? { fullName: id.principal.fullName || "", title: id.principal.title || "" }
+      : { fullName: "", title: "" },
+    presence: o.presence || { active: 0 },
+    status: o.status || "active",
+    updatedAt: new Date(nowMs).toISOString(),
+  };
+}
+
+/**
+ * Read the agent's current backlog focus from queue files. Returns the top open
+ * items as { title, queue, priority }. `items` may be injected for testing.
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts] - { limit=5, queues=["action-stack","backlog"], items? }
+ * @returns {Promise<object[]>}
+ */
+export async function currentFocus(agentRoot, opts = {}) {
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 5;
+  if (Array.isArray(opts.items)) return opts.items.slice(0, limit);
+  const queues = opts.queues || ["action-stack", "backlog"];
+  const out = [];
+  try {
+    const yaml = await getYaml();
+    for (const q of queues) {
+      const p = join(agentRoot, "state", "queues", `${q}.yaml`);
+      if (!existsSync(p)) continue;
+      let doc;
+      try { doc = yaml.load(readFileSync(p, "utf8")); } catch { continue; }
+      const items = Array.isArray(doc) ? doc : (doc && Array.isArray(doc.items) ? doc.items : []);
+      for (const it of items) {
+        if (!it || typeof it !== "object") continue;
+        const status = String(it.status || "open").toLowerCase();
+        if (status === "done" || status === "closed" || status === "cancelled") continue;
+        out.push({ title: String(it.title || it.next_action || "").slice(0, 140), queue: q, priority: it.priority || "normal" });
+        if (out.length >= limit) return out;
+      }
+    }
+  } catch { /* fail-open */ }
+  return out;
+}
+
+/** Assemble + return this agent's full self entry (does the I/O). Fail-open. */
+export async function assembleSelfEntry(agentRoot, opts = {}) {
+  const identity = readIdentity(agentRoot);
+  const company = readCompany(agentRoot);
+  let profile = opts.profile || null;
+  if (!profile && identity.function && identity.altitude) {
+    try {
+      const mod = await import("../archetype.mjs");
+      profile = await mod.resolveArchetype({ function: identity.function, altitude: identity.altitude });
+    } catch { profile = null; }
+  }
+  let presence = opts.presence;
+  if (!presence) {
+    try {
+      const mod = await import("../collective/presence.mjs");
+      presence = { active: mod.list(agentRoot, {}).length };
+    } catch { presence = { active: 0 }; }
+  }
+  const focus = opts.focus || await currentFocus(agentRoot, opts);
+  return buildSelfEntry({ identity, company, profile, focus, presence, nowMs: opts.nowMs });
+}
+
+function orgDir(agentRoot) { return join(agentRoot, ORG_REL); }
+
+/** Persist the self entry to state/org/self.json. Fail-open → false. */
+export function writeSelfEntry(agentRoot, entry) {
+  try {
+    mkdirSync(orgDir(agentRoot), { recursive: true });
+    writeFileSync(join(orgDir(agentRoot), "self.json"), JSON.stringify(entry, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+export function readSelfEntry(agentRoot) {
+  return readJson(join(orgDir(agentRoot), "self.json"));
+}
+
+/**
+ * Read the merged org directory: peers from known-agents.json, enriched with any
+ * synced peer entries under state/org/peers/, plus this agent's self entry. Each
+ * entry is shape-normalized to at least { id, name, fullName, title, slackId,
+ * role/archetype }. Newest/self first.
+ */
+export function readDirectory(agentRoot) {
+  const byId = new Map();
+  // Peers from the static known-agents registry (name/role/slackId).
+  for (const p of readPeers(agentRoot)) {
+    const id = p.repo || p.name || p.slackId;
+    if (!id) continue;
+    byId.set(String(id).toLowerCase(), {
+      id: String(id).toLowerCase(), name: p.name || "", fullName: p.fullName || "",
+      title: p.role || "", slackId: p.slackId || "", repo: p.repo || "", source: "known-agents",
+    });
+  }
+  // Richer synced peer entries (e.g. from cohort) override the static ones.
+  const peersDir = join(orgDir(agentRoot), "peers");
+  if (existsSync(peersDir)) {
+    try {
+      for (const f of readdirSync(peersDir).filter((x) => x.endsWith(".json"))) {
+        const e = readJson(join(peersDir, f));
+        if (e && e.id) byId.set(String(e.id).toLowerCase(), { ...e, source: e.source || "synced" });
+      }
+    } catch { /* ignore */ }
+  }
+  // Self entry last so it overrides any peer copy of itself.
+  const self = readSelfEntry(agentRoot);
+  if (self && self.id) byId.set(String(self.id).toLowerCase(), { ...self, self: true });
+  return [...byId.values()];
+}

package/lib/org/registry.test.mjs

@@ -0,0 +1,100 @@
+/**
+ * registry.test.mjs — tests for the file-backed org registry.
+ * Run: node --test lib/org/registry.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  buildSelfEntry, currentFocus, writeSelfEntry, readSelfEntry, readDirectory,
+} from "./registry.mjs";
+
+function tmp() { return mkdtempSync(join(tmpdir(), "org-registry-")); }
+function repo() {
+  const root = tmp();
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+
+test("buildSelfEntry: maps identity + company + profile + focus", () => {
+  const entry = buildSelfEntry({
+    identity: {
+      firstName: "Alex", fullName: "Alex Chen", title: "Chief of Staff",
+      email: "alex@example.com", slackMemberId: "U1", repoSlug: "alex-ai",
+      function: "executive-operator", altitude: "c-suite",
+      principal: { fullName: "Sam Smith", title: "CEO" },
+    },
+    company: { name: "Northwind", domain: "northwind.example.com" },
+    profile: { label: "C-Suite Executive Operator", towers: [{ id: "t1", name: "Strategic Initiatives", focus: "x" }] },
+    focus: [{ title: "Ship Q3 plan", queue: "action-stack", priority: "high" }],
+    nowMs: Date.parse("2026-06-03T12:00:00Z"),
+  });
+  assert.equal(entry.id, "alex-ai");
+  assert.equal(entry.fullName, "Alex Chen");
+  assert.equal(entry.archetype.function, "executive-operator");
+  assert.equal(entry.archetype.label, "C-Suite Executive Operator");
+  assert.equal(entry.towers.length, 1);
+  assert.equal(entry.towers[0].name, "Strategic Initiatives");
+  assert.equal(entry.focus[0].title, "Ship Q3 plan");
+  assert.equal(entry.principal.fullName, "Sam Smith");
+  assert.equal(entry.company.name, "Northwind");
+  assert.equal(entry.updatedAt, "2026-06-03T12:00:00.000Z");
+});
+
+test("buildSelfEntry: derives repo + id from firstName when no repoSlug", () => {
+  const entry = buildSelfEntry({ identity: { firstName: "Robin" } });
+  assert.equal(entry.repo, "robin-ai");
+  assert.equal(entry.id, "robin-ai");
+});
+
+test("currentFocus: uses injected items, capped", async () => {
+  const items = Array.from({ length: 9 }, (_, i) => ({ title: `t${i}`, queue: "q", priority: "normal" }));
+  const focus = await currentFocus("/x", { items, limit: 3 });
+  assert.equal(focus.length, 3);
+});
+
+test("currentFocus: reads + filters queue YAML (open only)", async () => {
+  const root = repo();
+  try {
+    mkdirSync(join(root, "state", "queues"), { recursive: true });
+    writeFileSync(join(root, "state", "queues", "action-stack.yaml"),
+      "items:\n  - title: Open one\n    status: open\n    priority: high\n  - title: Done one\n    status: done\n");
+    const focus = await currentFocus(root, { queues: ["action-stack"], limit: 5 });
+    assert.equal(focus.length, 1);
+    assert.equal(focus[0].title, "Open one");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("writeSelfEntry/readSelfEntry: round-trip", () => {
+  const root = repo();
+  try {
+    const e = buildSelfEntry({ identity: { firstName: "Alex", repoSlug: "alex-ai" } });
+    assert.equal(writeSelfEntry(root, e), true);
+    assert.equal(readSelfEntry(root).id, "alex-ai");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("readDirectory: merges known-agents peers + self; self + synced override", () => {
+  const root = repo();
+  try {
+    writeFileSync(join(root, "config", "known-agents.json"), JSON.stringify({
+      agents: [{ name: "Bob", fullName: "Bob Lee", slackId: "U2", role: "Head of Eng", repo: "bob-ai" }],
+    }));
+    // synced richer peer overrides the static known-agents entry
+    mkdirSync(join(root, "state", "org", "peers"), { recursive: true });
+    writeFileSync(join(root, "state", "org", "peers", "bob.json"), JSON.stringify({ id: "bob-ai", name: "Bob", title: "VP Engineering", source: "cohort" }));
+    writeSelfEntry(root, buildSelfEntry({ identity: { firstName: "Alex", repoSlug: "alex-ai", title: "CoS" } }));
+    const dir = readDirectory(root);
+    const bob = dir.find((d) => d.id === "bob-ai");
+    const alex = dir.find((d) => d.id === "alex-ai");
+    assert.equal(bob.title, "VP Engineering", "synced peer overrides known-agents role");
+    assert.equal(bob.source, "cohort");
+    assert.equal(alex.self, true, "self entry flagged");
+    assert.equal(dir.length, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});