@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/plan/schema.mjs

@@ -0,0 +1,140 @@
+/**
+ * lib/plan/schema.mjs — the OBLIGATION schema + a fail-closed validator.
+ *
+ * The plan is the agent's half of the ownership split: hq owns the mandate, the
+ * agent owns the obligations, the schedule and the backlog. An obligation is the
+ * unit of that plan — one of three kinds:
+ *
+ *   REACT     — "when <topic/kind> arrives and <predicate> holds, do this"
+ *   SCHEDULE  — "at <interval|calendar>, run this"  (compiles to a launchd plist)
+ *   OUTCOME   — "this number, measured by this sensor, must reach this target"
+ *
+ * Validation is dependency-free and FAIL-CLOSED (mirrors lib/archetype.mjs's
+ * validateProfile): a plan that does not validate is not written, because a
+ * half-valid plan silently emits half a schedule, and a missing launchd job is
+ * exactly the class of silent failure this system keeps growing.
+ *
+ * Two structural laws are enforced here rather than by convention:
+ *   1. every `uses[]` id must be REACHABLE in the capability manifest
+ *   2. every OUTCOME obligation must carry a sensor, and a `source:"llm"` sensor
+ *      is never allowed to close a loop (it is advisory only)
+ *
+ * PURE. No fs, no clock, no network.
+ *
+ * @module lib/plan/schema
+ */
+
+"use strict";
+
+/** The three obligation kinds. */
+export const OBLIGATION_KINDS = Object.freeze(["REACT", "SCHEDULE", "OUTCOME"]);
+/** Where an obligation came from (its provenance origin). */
+export const ORIGINS = Object.freeze(["standard", "archetype", "mandate", "react-standard"]);
+/** Execution modes the cadence consumer understands (unchanged vocabulary). */
+export const MODES = Object.freeze(["inline", "guarded", "escalate"]);
+/** Blast-radius classes that force an approval before any rung executes. */
+export const ACTION_CLASSES = Object.freeze(["internal", "external", "irreversible", "financial"]);
+/** Sensor provenance — the honesty gate. */
+export const SENSOR_SOURCES = Object.freeze(["method", "human", "llm"]);
+/** Statuses an obligation can hold locally. */
+export const STATUSES = Object.freeze(["active", "suspended", "proposed"]);
+
+/**
+ * Validate ONE obligation.
+ * @param {object} ob
+ * @param {{reachable?:Set<string>}} [o]
+ * @returns {string[]} error strings (empty = valid)
+ */
+export function validateObligation(ob, o = {}) {
+  const errs = [];
+  const at = (m) => `obligation ${(ob && ob.key) || "<no key>"}: ${m}`;
+  if (!ob || typeof ob !== "object") return ["obligation is not an object"];
+
+  if (!ob.key || typeof ob.key !== "string") errs.push(at("missing key"));
+  else if (!/^[a-z0-9][a-z0-9._-]*$/.test(ob.key)) errs.push(at(`key "${ob.key}" is not a stable slug ([a-z0-9._-])`));
+
+  if (!OBLIGATION_KINDS.includes(ob.kind)) errs.push(at(`kind must be one of ${OBLIGATION_KINDS.join("|")} (got ${JSON.stringify(ob.kind)})`));
+
+  if (!ob.source || typeof ob.source !== "object") errs.push(at("missing source provenance"));
+  else if (!ORIGINS.includes(ob.source.origin)) errs.push(at(`source.origin must be one of ${ORIGINS.join("|")}`));
+
+  if (!STATUSES.includes(ob.status)) errs.push(at(`status must be one of ${STATUSES.join("|")}`));
+
+  if (!Array.isArray(ob.uses)) errs.push(at("uses[] must be an array"));
+  if (!Array.isArray(ob.allowed_tools)) errs.push(at("allowed_tools[] must be an array"));
+  if (!Array.isArray(ob.action_classes)) errs.push(at("action_classes[] must be an array"));
+  else for (const c of ob.action_classes) if (!ACTION_CLASSES.includes(c)) errs.push(at(`unknown action class "${c}"`));
+
+  if (typeof ob.offline_safe !== "boolean") errs.push(at("offline_safe must be a boolean"));
+  if (ob.budget_cents_per_period != null && !Number.isFinite(ob.budget_cents_per_period)) errs.push(at("budget_cents_per_period must be a number"));
+
+  // Kind-specific structure.
+  if (ob.kind === "SCHEDULE") {
+    const hasInterval = ob.schedule && Number.isFinite(ob.schedule.interval);
+    const hasCalendar = ob.schedule && ob.schedule.calendar && typeof ob.schedule.calendar === "object";
+    if (!hasInterval && !hasCalendar) errs.push(at("SCHEDULE needs schedule.interval or schedule.calendar"));
+    if (!MODES.includes(ob.mode)) errs.push(at(`SCHEDULE needs a mode (${MODES.join("|")})`));
+    // The hole this closes: an archetype cadence used to get {mode, prompt} and a
+    // blanket-permission session. An empty allowed_tools list is legal ONLY for
+    // an inline (deterministic, no-session) cadence.
+    if (ob.mode !== "inline" && (!Array.isArray(ob.allowed_tools) || ob.allowed_tools.length === 0)) {
+      errs.push(at("a session-spawning SCHEDULE must declare a non-empty allowed_tools list"));
+    }
+  }
+  if (ob.kind === "OUTCOME") {
+    if (!ob.objective_id) errs.push(at("OUTCOME must be provenance-linked to an objective_id"));
+    if (!ob.sensor || typeof ob.sensor !== "object") errs.push(at("OUTCOME must carry a sensor"));
+    else {
+      if (!SENSOR_SOURCES.includes(ob.sensor.source)) errs.push(at(`sensor.source must be one of ${SENSOR_SOURCES.join("|")}`));
+      if (ob.sensor.source === "llm") errs.push(at('sensor.source "llm" cannot back an OUTCOME obligation (advisory only)'));
+      if (ob.sensor.source === "method" && !ob.sensor.capability) errs.push(at('sensor.source "method" requires a capability'));
+    }
+    if (ob.target != null && !Number.isFinite(ob.target)) errs.push(at("target must be a number when set"));
+  }
+  if (ob.kind === "REACT") {
+    if (!ob.trigger || typeof ob.trigger !== "object" || !ob.trigger.topic) errs.push(at("REACT needs trigger.topic"));
+  }
+
+  // The capability law.
+  if (o.reachable instanceof Set && Array.isArray(ob.uses)) {
+    for (const id of ob.uses) {
+      if (!o.reachable.has(id)) errs.push(at(`cites capability "${id}" which is not reachable:true in the capability manifest`));
+    }
+  }
+  return errs;
+}
+
+/**
+ * Validate a whole plan. Fail-closed: `ok:false` means DO NOT WRITE.
+ * @param {{obligations:object[]}} plan
+ * @param {{manifest?:object, reachable?:Set<string>}} [o]
+ * @returns {{ok:boolean, errors:string[], counts:object}}
+ */
+export function validatePlan(plan, o = {}) {
+  const errors = [];
+  const obligations = plan && Array.isArray(plan.obligations) ? plan.obligations : null;
+  if (!obligations) return { ok: false, errors: ["plan.obligations must be an array"], counts: {} };
+
+  const reachable = o.reachable instanceof Set
+    ? o.reachable
+    : o.manifest
+      ? new Set(((o.manifest.entries) || []).filter((e) => e && e.reachable).map((e) => e.id))
+      : null;
+
+  const seen = new Set();
+  for (const ob of obligations) {
+    if (ob && ob.key) {
+      if (seen.has(ob.key)) errors.push(`duplicate obligation key "${ob.key}"`);
+      seen.add(ob.key);
+    }
+    errors.push(...validateObligation(ob, { reachable }));
+  }
+
+  const counts = {};
+  for (const k of OBLIGATION_KINDS) counts[k] = obligations.filter((ob) => ob && ob.kind === k).length;
+  counts.total = obligations.length;
+
+  return { ok: errors.length === 0, errors, counts };
+}
+
+export default { OBLIGATION_KINDS, ORIGINS, MODES, ACTION_CLASSES, SENSOR_SOURCES, STATUSES, validateObligation, validatePlan };

package/lib/resource-governor.mjs

@@ -169,11 +169,57 @@ export function _resetLiveCache() { _liveCache = { at: 0, value: null }; }
  * Build the real-world deps snapshot the governor reasons over. Tests bypass
  * this entirely by passing their own `deps`.
  */
+// How long an availableMemoryBytes() probe is reused. vm_stat costs a few ms and
+// the governor is consulted on every admission decision; memory pressure does not
+// meaningfully move inside a 2s window.
+const AVAIL_CACHE_MS = 2000;
+let availCache = { at: 0, bytes: 0 };
+
+/**
+ * Bytes of memory the OS can actually hand to a new session.
+ *
+ * On Darwin `os.freemem()` reports ONLY vm_stat's "Pages free" — it excludes
+ * inactive, speculative and purgeable pages, every one of which macOS reclaims on
+ * demand. Any warm Mac therefore reports near-zero free memory forever (measured:
+ * 263MB "free" on a 24GB box that `memory_pressure` simultaneously called 76%
+ * free), so a percentage floor could never be satisfied and the governor deferred
+ * every spawn indefinitely. Counting the reclaimable pages is what macOS itself
+ * means by available memory.
+ *
+ * Falls back to `os.freemem()` on non-Darwin platforms and on any probe failure —
+ * a governor that cannot measure must not silently admit everything.
+ *
+ * @param {number} [now] injectable clock (tests)
+ * @returns {number} bytes
+ */
+export function availableMemoryBytes(now = Date.now()) {
+  if (process.platform !== "darwin") return os.freemem();
+  if (availCache.at && now - availCache.at < AVAIL_CACHE_MS) return availCache.bytes;
+
+  let bytes = os.freemem();
+  try {
+    const out = execFileSync("vm_stat", { encoding: "utf8", timeout: 2000 });
+    const pageSize = Number(/page size of (\d+) bytes/.exec(out)?.[1]) || 4096;
+    const pages = (label) => {
+      const m = new RegExp(`^${label}:\\s+(\\d+)\\.`, "m").exec(out);
+      return m ? Number(m[1]) : 0;
+    };
+    const reclaimable =
+      pages("Pages free") + pages("Pages inactive") + pages("Pages speculative") + pages("Pages purgeable");
+    if (reclaimable > 0) bytes = reclaimable * pageSize;
+  } catch {
+    // vm_stat missing or unparseable — keep the os.freemem() reading.
+  }
+
+  availCache = { at: now, bytes };
+  return bytes;
+}
+
 export function defaultDeps(extra = {}) {
   const live = liveClaudeStats();
   const throttle = readThrottle(extra);
   return {
-    freemem: os.freemem(),
+    freemem: availableMemoryBytes(),
     totalmem: os.totalmem(),
     loadavg: os.loadavg(),
     cpus: os.cpus().length || 1,

package/lib/resource-governor.test.mjs

@@ -11,7 +11,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { promises as fsp } from "node:fs";
 import { writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { tmpdir, freemem as osFreemem, totalmem as totalmemBytes } from "node:os";
 import { join } from "node:path";
 
 import {
@@ -21,8 +21,28 @@ import {
   PER_SESSION_MB,
   RAM_FRACTION,
   DECISIONS,
+  availableMemoryBytes,
+  FREEMEM_FLOOR_FRACTION,
 } from "./resource-governor.mjs";
 
+test("availableMemoryBytes counts reclaimable pages, not just free ones", () => {
+  const bytes = availableMemoryBytes();
+  assert.ok(Number.isFinite(bytes) && bytes > 0, "always a usable number");
+
+  if (process.platform !== "darwin") {
+    assert.equal(bytes, osFreemem(), "non-Darwin defers to os.freemem()");
+    return;
+  }
+
+  // The regression: os.freemem() on macOS reports only "Pages free", which sits
+  // near zero on any warm box and pinned the governor at DEFER. Availability must
+  // include the inactive/speculative/purgeable pages macOS reclaims on demand,
+  // so it is always >= the raw reading and should clear the floor on an idle host.
+  assert.ok(bytes >= osFreemem(), "availability is never below raw free memory");
+  const floor = totalmemBytes() * FREEMEM_FLOOR_FRACTION;
+  assert.ok(bytes > floor, `an idle Mac must clear its own floor (${bytes} vs ${floor})`);
+});
+
 const GB = 1024 * 1024 * 1024;
 const MB = 1024 * 1024;
 

package/lib/setup/enroll-from-cohort.mjs

@@ -40,15 +40,20 @@ import { isPlaceholder } from "./completeness.mjs";
 // Archetype axes the identity section also offers. Keep these in sync with
 // lib/setup/sections/identity.mjs FUNCTIONS/ALTITUDES — a derived value MUST be
 // one the wizard's select() can render and the archetype resolver accepts.
+// These are the seven archetypes that exist on disk. `people-leader`/`compliance-leader`
+// were derivable here but resolve to no archetype file — a pull could therefore
+// write an un-resolvable function into config/agent.json and make the identity
+// section's apply() fatal. They map onto `operations-leader`/`compliance-officer`.
 const FUNCTIONS = Object.freeze([
   "executive-operator",
   "technical-leader",
   "commercial-leader",
-  "people-leader",
+  "product-leader",
+  "operations-leader",
   "finance-leader",
-  "compliance-leader",
+  "compliance-officer",
 ]);
-const ALTITUDES = Object.freeze(["c-suite", "svp", "vp", "senior-manager"]);
+const ALTITUDES = Object.freeze(["founder", "c-suite", "svp", "vp", "senior-manager"]);
 
 const DEFAULT_FUNCTION = "executive-operator";
 const DEFAULT_ALTITUDE = "c-suite";
@@ -69,9 +74,50 @@ export function cohortPullEnv(env = process.env) {
 }
 
 function str(v) {
-  return v == null ? "" : String(v).trim();
+  if (v == null) return "";
+  // NEVER stringify an object/array leaf. The live MemberProfileDTO nests
+  // role/team as objects; `String({})` yields the TRUTHY literal
+  // "[object Object]", which used to satisfy every `if (value)` guard below and
+  // then poison the keyword derivations — a silent fall-back to defaults rather
+  // than an honest empty. Nested shapes are read via the accessors below.
+  if (typeof v === "object") return "";
+  return String(v).trim();
 }
 
+/**
+ * The live Cohort MemberProfileDTO nests the fields the mapper needs:
+ *   role: { title, level, status }   team: { slug, name, shortLabel }
+ * Older/flattened payloads (and the wizard's own fixtures) carry them as plain
+ * strings. These accessors read BOTH shapes so a pull maps identically either
+ * way. Each returns "" when the profile genuinely carries nothing.
+ */
+function profileTitle(p) {
+  return str(p.title) || str(p.role?.title);
+}
+
+function profileRoleText(p) {
+  return str(p.role) || str(p.role?.title) || str(p.role?.level);
+}
+
+function profileTeamText(p) {
+  return str(p.team) || str(p.team?.name) || str(p.team?.shortLabel) || str(p.team?.slug);
+}
+
+/** The org's explicit seniority band, when it ships one (`role.level`). */
+function profileLevel(p) {
+  return str(p.level) || str(p.role?.level);
+}
+
+// Cohort's `role.level` enum → the archetype `altitude` axis. An EXPLICIT band
+// from the org beats guessing at the title string, so this is consulted first.
+const LEVEL_TO_ALTITUDE = Object.freeze({
+  FOUNDER: "founder",
+  C_SUITE: "c-suite",
+  SVP: "svp",
+  VP: "vp",
+  SENIOR_MANAGER: "senior-manager",
+});
+
 /**
  * Map a Cohort MemberProfileDTO to the config/agent.json field subset it
  * authoritatively provides. Only sets a field when the profile carries a real
@@ -88,6 +134,7 @@ function str(v) {
  *   operatingPrinciples          ← profileSections (operating-principles section)
  *   communication.defaultTone    ← profileSections (communication/tone section)
  *   responsibilities             ← profileSections (responsibilities section)
+ *   persona                      ← profileSections (persona/background/bio section)
  *
  * @param {object|null} profile MemberProfileDTO
  * @returns {object} the config/agent.json patch (deep-mergeable)
@@ -104,7 +151,7 @@ export function mapProfileToAgentConfig(profile) {
   const fullName = display || [first, last].filter(Boolean).join(" ").trim();
   if (fullName) patch.fullName = fullName;
 
-  const title = str(p.title);
+  const title = profileTitle(p);
   if (title) patch.title = title;
 
   const email = str(p.agentEmail) || str(p.email);
@@ -115,7 +162,7 @@ export function mapProfileToAgentConfig(profile) {
   // leaving the wizard to prompt). When signal IS present, derivation always
   // resolves to a VALID axis (safe default when unmappable) so the wizard renders
   // + confirms it rather than failing the pull.
-  const hasAxisSignal = !!(str(p.role) || str(p.team) || str(p.title));
+  const hasAxisSignal = !!(profileRoleText(p) || profileTeamText(p) || profileTitle(p) || profileLevel(p));
   if (hasAxisSignal) {
     patch.function = deriveFunction(p);
     patch.altitude = deriveAltitude(p);
@@ -135,6 +182,22 @@ export function mapProfileToAgentConfig(profile) {
   if (responsibilities.length) patch.responsibilities = responsibilities;
   const tone = sectionText(sections, ["communication", "tone", "communication-style"]);
   if (tone) patch.communication = { defaultTone: tone };
+  // persona/background — free prose describing who this member is. Rendered into
+  // the "Background" section of the prompt persona block (lib/identity/persona.mjs)
+  // so the agent writes with its own history behind it rather than as a generic
+  // seat-holder. The org is the SoT for this; we never synthesise one.
+  // Real Cohort records put this prose in one of two places, and the section
+  // list alone missed both for a live seat: the section is named SUMMARY (not
+  // "persona"/"background"), and the DTO also carries a top-level `bio` with the
+  // same text. Missing it is not cosmetic — an empty persona leaves
+  // `{{agent.persona}}` unresolved in CLAUDE.md and drops the Background line
+  // from the prompt block, which is the exact "generic assistant" failure this
+  // whole change exists to remove. Section first (it is the richer, explicitly
+  // authored field), then the top-level bio.
+  const persona =
+    sectionText(sections, ["persona", "background", "bio", "about", "profile", "summary"]) ||
+    str(p.bio);
+  if (persona) patch.persona = persona;
 
   // charter — the Cohort-authored operating charter (CharterDTO:
   // approvedByLine/gatesText/sections). When present this is the SOURCE OF TRUTH
@@ -218,14 +281,17 @@ function mapSupervisor(sup) {
   }
   if (typeof sup === "object") {
     const fullName = str(sup.displayName) || str(sup.fullName) || [str(sup.firstName), str(sup.lastName)].filter(Boolean).join(" ").trim();
-    if (!fullName && !str(sup.email) && !str(sup.title)) return null;
+    // A supervisor DTO nests its title under `role`, exactly as the member does.
+    const title = profileTitle(sup);
+    const email = str(sup.email) || str(sup.agentEmail);
+    if (!fullName && !email && !title) return null;
     const [pf, ...pr] = fullName.split(/\s+/);
     return {
       firstName: str(sup.firstName) || pf || "",
       lastName: str(sup.lastName) || pr.join(" "),
       fullName,
-      title: str(sup.title),
-      email: str(sup.email) || str(sup.agentEmail),
+      title,
+      email,
     };
   }
   return null;
@@ -239,14 +305,16 @@ function mapSupervisor(sup) {
  * @returns {string} one of FUNCTIONS
  */
 export function deriveFunction(p) {
-  const hay = `${str(p.role)} ${str(p.team)} ${str(p.title)}`.toLowerCase();
+  const hay = `${profileRoleText(p)} ${profileTeamText(p)} ${profileTitle(p)}`.toLowerCase();
   const rules = [
     [/\b(eng|engineer|platform|infra|technical|cto|devops|software|sre)\b/, "technical-leader"],
+    [/\b(product|design|ux|research|pm|cpo)\b/, "product-leader"],
     [/\b(sales|revenue|gtm|growth|commercial|marketing|bd|biz dev|partnerships)\b/, "commercial-leader"],
-    [/\b(people|hr|talent|recruit|org design|human resources)\b/, "people-leader"],
+    [/\b(people|hr|talent|recruit|org design|human resources)\b/, "operations-leader"],
     [/\b(finance|fp&a|accounting|treasury|capital|corp dev|cfo)\b/, "finance-leader"],
-    [/\b(compliance|legal|risk|regulatory|counsel|audit|dfsa)\b/, "compliance-leader"],
-    [/\b(ops|operations|chief of staff|coo|executive|operator)\b/, "executive-operator"],
+    [/\b(compliance|legal|risk|regulatory|counsel|audit|dfsa)\b/, "compliance-officer"],
+    [/\b(ops|operations|delivery|supply|logistics)\b/, "operations-leader"],
+    [/\b(chief of staff|coo|executive|operator)\b/, "executive-operator"],
   ];
   for (const [re, fn] of rules) if (re.test(hay)) return fn;
   return DEFAULT_FUNCTION;
@@ -259,9 +327,19 @@ export function deriveFunction(p) {
  * @returns {string} one of ALTITUDES
  */
 export function deriveAltitude(p) {
-  const hay = `${str(p.role)} ${str(p.title)}`.toLowerCase();
-  // Order matters: most-senior cue wins (check c-suite/SVP before VP/manager).
-  if (/\b(c-?suite|chief|ceo|cto|cfo|coo|cmo|cpo|founder)\b/.test(hay)) return "c-suite";
+  // An explicit `role.level` from the org is authoritative — prefer it over
+  // guessing at prose. (An SVP reporting to a CPTO reads as "chief" to the
+  // keyword pass below only because their manager's title is nearby; the band
+  // removes that whole class of error.)
+  const level = profileLevel(p).toUpperCase().replace(/[\s-]+/g, "_");
+  if (LEVEL_TO_ALTITUDE[level]) return LEVEL_TO_ALTITUDE[level];
+
+  const hay = `${profileRoleText(p)} ${profileTitle(p)}`.toLowerCase();
+  // Order matters: most-senior cue wins (check founder/c-suite/SVP before
+  // VP/manager). `founder` is its own altitude — it resolves the runway-review
+  // and investor-update cadences a generic c-suite seat does not get.
+  if (/\b(founder|co-?founder)\b/.test(hay)) return "founder";
+  if (/\b(c-?suite|chief|ceo|cto|cfo|coo|cmo|cpo)\b/.test(hay)) return "c-suite";
   if (/\bsvp\b|senior vice president/.test(hay)) return "svp";
   if (/\bvp\b|vice president|head of|director/.test(hay)) return "vp";
   if (/\b(senior manager|sr\.? manager|manager|lead)\b/.test(hay)) return "senior-manager";
@@ -277,7 +355,17 @@ function findSection(sections, names) {
       const id = str(s.id).toLowerCase();
       const title = str(s.title).toLowerCase();
       const heading = str(s.heading).toLowerCase();
-      return wanted.includes(id) || wanted.includes(title) || wanted.includes(heading);
+      // `kind` is what a real Cohort ProfileSection identifies itself by
+      // (SUMMARY, VISUAL_PROMPT, COUNTERPARTS_NARRATIVE). Matching only
+      // id/title/heading silently missed EVERY section on a live seat, so a
+      // fully-populated org profile still yielded an empty persona.
+      const kind = str(s.kind).toLowerCase();
+      return (
+        wanted.includes(id) ||
+        wanted.includes(title) ||
+        wanted.includes(heading) ||
+        wanted.includes(kind)
+      );
     }) || null
   );
 }

package/lib/setup/enroll-from-cohort.test.mjs

@@ -52,6 +52,46 @@ const PROFILE = {
   ],
 };
 
+// The shape the LIVE org-data API actually returns: role/team are objects, and
+// the supervisor nests its title the same way. The flat PROFILE above is the
+// legacy/wizard shape — both must map identically. Regression fixture for the
+// enrolment that shipped an agent with title:"", altitude:"c-suite" and a
+// principal with no title, because every field below was read one level too high.
+const NESTED_PROFILE = {
+  slug: "A016",
+  kind: "AI_AGENT",
+  status: "ACTIVE",
+  displayName: "Agent One",
+  firstName: "Agent",
+  lastName: "One",
+  team: { slug: "ai-systems-agent-platform", name: "AI Systems & Agent Platform", shortLabel: "AI Systems" },
+  role: { title: "SVP AI Systems & Agent Platform", level: "SVP", status: "ACTIVE" },
+  agentEmail: "agent-one@example.test",
+  supervisor: {
+    slug: "A002",
+    displayName: "Samir Al Sulaiti",
+    role: { title: "Chief Product & Technology Officer", level: "C_SUITE", status: "ACTIVE" },
+    team: { slug: "product-technology-platform", name: "Product, Technology & Platform" },
+  },
+};
+
+test("mapProfileToAgentConfig reads the nested (live) DTO shape", () => {
+  const patch = mapProfileToAgentConfig(NESTED_PROFILE);
+  assert.equal(patch.title, "SVP AI Systems & Agent Platform", "title comes from role.title");
+  assert.equal(patch.function, "technical-leader", "derived from the platform/AI-systems team");
+  assert.equal(patch.altitude, "svp", "role.level beats keyword-guessing the title");
+  assert.equal(patch.principal.fullName, "Samir Al Sulaiti");
+  assert.equal(patch.principal.title, "Chief Product & Technology Officer", "supervisor title comes from role.title");
+});
+
+test("an object leaf never stringifies into a derivation", () => {
+  // `String({})` is the truthy "[object Object]"; letting it through made every
+  // derivation silently fall back to its default instead of reporting no signal.
+  assert.equal(mapProfileToAgentConfig({ role: {}, team: {} }).function, undefined, "no axis signal → no axis emitted");
+  assert.equal(deriveFunction({ role: { title: "Staff Engineer" } }), "technical-leader");
+  assert.equal(deriveAltitude({ role: { level: "SENIOR_MANAGER" } }), "senior-manager");
+});
+
 test("mapProfileToAgentConfig maps the authoritative fields", () => {
   const patch = mapProfileToAgentConfig(PROFILE);
   assert.equal(patch.firstName, "Robin");
@@ -130,7 +170,9 @@ test("charter/orgProfile absent → no charter/orgProfile keys (empty patch stay
 test("deriveFunction + deriveAltitude resolve to valid axes (safe default)", () => {
   assert.ok(FUNCTIONS.includes(deriveFunction({ role: "sales lead", team: "Revenue" })));
   assert.equal(deriveFunction({ role: "sales lead", team: "Revenue" }), "commercial-leader");
-  assert.equal(deriveFunction({ role: "general counsel", team: "Legal" }), "compliance-leader");
+  // `compliance-leader` resolves to no archetype on disk; the rule map returns
+  // the archetype that does exist. The expectation, not the code, was stale.
+  assert.equal(deriveFunction({ role: "general counsel", team: "Legal" }), "compliance-officer");
   assert.equal(deriveFunction({ role: "weird-unknown-role" }), "executive-operator");
   assert.ok(ALTITUDES.includes(deriveAltitude({ title: "Chief Technology Officer" })));
   assert.equal(deriveAltitude({ title: "Chief Technology Officer" }), "c-suite");
@@ -231,3 +273,28 @@ test("pullAndPlan: a local override is NOT clobbered without --force", async ()
   const forced = await pullAndPlan({ agentRoot: root, env, force: true, fetchSelfProfileImpl: async () => ({ ok: true, result: PROFILE }) });
   assert.equal(forced.patch.title, "VP of Engineering", "--force overwrites");
 });
+
+test("persona falls back to the SUMMARY section and then the top-level bio", () => {
+  // A live Cohort seat had its prose in a section named SUMMARY and in the
+  // DTO's top-level `bio` — neither of which the original name list matched.
+  // The result was an empty persona, an unresolved {{agent.persona}} in
+  // CLAUDE.md, and no Background line in the prompt: exactly the generic-seat
+  // failure this mapping exists to prevent.
+  const fromSummary = mapProfileToAgentConfig({
+    profileSections: [{ kind: "SUMMARY", body: "I build the agent substrate." }],
+  });
+  assert.equal(fromSummary.persona, "I build the agent substrate.");
+
+  const fromBio = mapProfileToAgentConfig({ bio: "I run platform engineering." });
+  assert.equal(fromBio.persona, "I run platform engineering.");
+
+  // An explicitly authored section still wins over the terser bio.
+  const both = mapProfileToAgentConfig({
+    bio: "short bio",
+    profileSections: [{ kind: "background", body: "the long authored version" }],
+  });
+  assert.equal(both.persona, "the long authored version");
+
+  // Nothing to say stays empty — we never synthesise a persona.
+  assert.equal(mapProfileToAgentConfig({}).persona, undefined);
+});

package/lib/setup/sections/identity.mjs

@@ -20,15 +20,26 @@ import { runGenerator } from "../run-generator.mjs";
 import { cohortPullEnv, pullAndPlan } from "../enroll-from-cohort.mjs";
 import { fetchSelfProfile } from "../../org/client.mjs";
 
-const FUNCTIONS = [
+// The seven archetypes that ACTUALLY EXIST on disk (archetypes/*.yaml). This
+// list used to offer `people-leader` and `compliance-leader`, neither of which
+// has an archetype file — picking either resolved to nothing and made apply()
+// fatal, and it omitted `operations-leader` and `product-leader`, which do
+// exist. The whole init pipeline downstream (capability pack → cadences →
+// plan compiler) keys off this value, so it must name a real archetype.
+// Keep in sync with lib/setup/enroll-from-cohort.mjs FUNCTIONS.
+export const FUNCTIONS = [
   { value: "executive-operator", label: "Executive operator (chief of staff / COO-style)" },
   { value: "technical-leader", label: "Technical leader (eng / platform / CTO-style)" },
   { value: "commercial-leader", label: "Commercial leader (sales / GTM / revenue)" },
-  { value: "people-leader", label: "People leader (HR / talent / org)" },
+  { value: "product-leader", label: "Product leader (product / design / research)" },
+  { value: "operations-leader", label: "Operations leader (ops / people / delivery)" },
   { value: "finance-leader", label: "Finance leader (finance / corp dev / capital)" },
-  { value: "compliance-leader", label: "Compliance leader (legal / risk / regulatory)" },
+  { value: "compliance-officer", label: "Compliance officer (legal / risk / regulatory)" },
 ];
-const ALTITUDES = [
+// `founder` carries its own ALTITUDE_CADENCES entry (runway review + investor
+// update) in lib/cadences.mjs but was unreachable from the wizard.
+export const ALTITUDES = [
+  { value: "founder", label: "Founder" },
   { value: "c-suite", label: "C-suite" },
   { value: "svp", label: "SVP" },
   { value: "vp", label: "VP" },