@cohortapp/agent-sdk 2.4.1 → 2.5.0

package/lib/org/inbound/hydrate.mjs

@@ -114,6 +114,8 @@ export async function hydrate(o = {}) {
         return hydrateApproval(c, facts);
       case "handoff":
         return hydrateHandoff(c, facts);
+      case "calendar":
+        return hydrateCalendar(c, facts);
       case "email":
         return await hydrateEmail(c, facts, io, cache);
       default:
@@ -324,6 +326,44 @@ function hydrateEscalation(c, facts) {
   };
 }
 
+/**
+ * A calendar event. The body came back on the ACL'd `calendar.list` read in the
+ * facts pass — that read IS the probe, so there is no second request here and
+ * nothing is rendered that hq did not already hand this seat.
+ */
+function hydrateCalendar(c, facts) {
+  const id = s(c.ids.eventId);
+  const e = facts.myEvents instanceof Map ? facts.myEvents.get(id) : null;
+  const title = s((e && e.title) || c.ids.title || id);
+  const lines = [`${describeCalendarKind(c.kind)} — "${title}"`];
+  const startsAt = s((e && e.startsAt) || c.ids.startsAt);
+  if (startsAt) lines.push(`Starts: ${startsAt}${e && e.endsAt ? ` · ends ${s(e.endsAt)}` : ""}`);
+  if (c.kind === "event.rsvp" && c.ids.rsvp) lines.push(`RSVP: ${s(c.ids.rsvp)}`);
+  if (e && e.location) lines.push(`Location: ${s(e.location)}`);
+  if (e && e.description) lines.push(clip(e.description, 1200));
+  return {
+    ok: true,
+    text: clip(lines.join("\n")),
+    subjectDetail: title,
+    threadId: id,
+    from: { id: s(c.actor), name: s(c.actor) },
+    channelId: s(c.ids.channelId || (e && e.channelId) || ""),
+    channelLabel: `calendar/${title}`,
+  };
+}
+
+/** Human phrasing for a `calendar.*` event kind. */
+export function describeCalendarKind(kind) {
+  switch (kind) {
+    case "event.created": return "Calendar event created";
+    case "event.updated": return "Calendar event updated";
+    case "event.rescheduled": return "Calendar event rescheduled";
+    case "event.rsvp": return "Calendar RSVP";
+    case "event.deleted": return "Calendar event cancelled";
+    default: return "Calendar update";
+  }
+}
+
 /** An approval — already read back by the facts pass (that IS the probe). */
 function hydrateApproval(c, facts) {
   const id = s(c.ids.approvalId);

package/lib/org/inbound/index.test.mjs

@@ -322,3 +322,86 @@ test("an empty ledger window is a no-op that still advances nothing", async () =
   assert.deepEqual(out.events, []);
   assert.equal(out.nextCursor, 5);
 });
+
+// ---------------------------------------------------------------------------
+// Calendar (JOINT 3) — the surface hq's own agent.wait lanes do not carry
+// ---------------------------------------------------------------------------
+
+/**
+ * The calendar payload is redacted like every other family: `event.created`
+ * carries `attendeeCount` and the CALENDAR OWNER, never the attendee list. So
+ * "am I in this meeting?" is answered by `calendar.list` — hq's seat-scoped
+ * query (owner OR attendeeRows, under the PERSONAL_RESTRICTED lens floor) — and
+ * NEVER by widening the chain payload.
+ */
+test("calendar: an event I attend arrives; a colleague's event never does", async () => {
+  const io = fakeIo({
+    "read:events": okRead({
+      events: [
+        // Mine — I am an attendee (owner is someone else).
+        { seq: 900, family: "calendar", kind: "event.created", entity_id: "EV-mine", actor: BOSS,
+          at: "2026-08-11T10:00:00.000Z",
+          payload: { title: "Transport review", startsAt: "2026-08-12T10:00:00.000Z", endsAt: "2026-08-12T11:00:00.000Z",
+                     eventKind: "MEETING", attendeeCount: 4, calendarMemberId: BOSS } },
+        // NOT mine — a meeting between two colleagues. `calendar.list` will not
+        // return it, so it must never be delivered or hydrated.
+        { seq: 901, family: "calendar", kind: "event.created", entity_id: "EV-theirs", actor: THEM,
+          at: "2026-08-11T10:05:00.000Z",
+          payload: { title: "Their 1:1", startsAt: "2026-08-12T14:00:00.000Z",
+                     eventKind: "MEETING", attendeeCount: 2, calendarMemberId: THEM } },
+      ],
+      nextCursor: 901,
+    }),
+    "calendar.list": okFrame({
+      events: [
+        { id: "EV-mine", title: "Transport review", startsAt: "2026-08-12T10:00:00.000Z",
+          endsAt: "2026-08-12T11:00:00.000Z", location: "Huddle 2", description: "Walk the five hops",
+          calendarMemberId: BOSS, channelId: "C-pub" },
+      ],
+    }),
+  });
+
+  const res = await pullWideInbound({ cfg: CFG, agentId: ME, cursor: 899, io });
+
+  assert.equal(res.events.length, 1, "exactly one calendar item — the one I am in");
+  const ev = res.events[0];
+  assert.equal(ev.kind, "calendar");
+  assert.equal(ev.cohort.surface, "calendar");
+  assert.equal(ev.cohort.reason, "attendee", "attendance was proven by an ACL'd read, not by a payload");
+  assert.match(ev.text, /Calendar event created — "Transport review"/);
+  assert.match(ev.text, /Walk the five hops/);
+  assert.equal(res.stats.bySurface.calendar, 1);
+  assert.equal(res.stats.dropped.calendar_not_mine, 1, "the colleague's meeting was dropped with a named reason");
+
+  // ACL by call log: hq was asked ONE seat-scoped question, and we never probed
+  // the event we were not entitled to.
+  const calendarCalls = io.calls.filter((c) => c.method === "calendar.list");
+  assert.equal(calendarCalls.length, 1, "one list read per pull, not one probe per event");
+  assert.ok(
+    calendarCalls[0].params.calendarMemberId === undefined,
+    "no calendarMemberId → hq uses the ACTING SEAT's viewpoint; naming one would be asking about someone else's calendar",
+  );
+  assert.equal(io.calls.filter((c) => c.method === "calendar.get").length, 0, "no per-event probe at all");
+});
+
+test("calendar: an unreadable calendar fails CLOSED and says so", async () => {
+  const io = fakeIo({
+    "read:events": okRead({
+      events: [
+        { seq: 910, family: "calendar", kind: "event.rescheduled", entity_id: "EV-mine", actor: BOSS,
+          at: "2026-08-11T10:00:00.000Z", payload: { title: "Transport review", to: "2026-08-13T10:00:00.000Z" } },
+      ],
+      nextCursor: 910,
+    }),
+    // calendar.list not routed → the fake returns NOT_FOUND, i.e. a failed read.
+  });
+
+  const res = await pullWideInbound({ cfg: CFG, agentId: ME, cursor: 909, io });
+  assert.equal(res.events.length, 0, "a private surface guesses CLOSED, never open");
+  assert.equal(res.stats.dropped.calendar_unknown, 1);
+  assert.ok(res.stats.degraded.includes("calendar"), "and the degradation is reported, not swallowed");
+  assert.ok(
+    io.logs.some((l) => l.level === "warn" && /calendar\.list unreadable/.test(l.message)),
+    `fail-open is fine, silent is not; got ${JSON.stringify(io.logs)}`,
+  );
+});

package/lib/org/inbound/project.mjs

@@ -144,6 +144,14 @@ export function toMessageEvent(o = {}) {
       family: c.family,
       event_kind: c.kind,
       entity_id: entityId || null,
+      // The subject this surface hangs off, when it is NOT a channel: the task
+      // an approval blocks or an escalation flags, the decision a comment sits
+      // on, the file a comment is against. `channel_id` above deliberately only
+      // ever carries a real Cohort channel — a reply routes with it — so
+      // without this the downstream ladder has the event and no handle on the
+      // thing the event is about. `effects.escalate` needs exactly this to
+      // satisfy hq's "an escalation must reference a task or a channel".
+      scope_id: s(c.ids.taskId || c.ids.decisionId || c.ids.fileId || "") || null,
       seq: c.seq ?? null,
       me: s(me),
     },

package/lib/org/inbound/surfaces.mjs

@@ -127,6 +127,26 @@ export const SURFACES = Object.freeze({
     scope: "channel",
     default: true,
   }),
+  /**
+   * A calendar event on MY calendar, or one I am an attendee of: created,
+   * updated, rescheduled, RSVP'd, deleted.
+   *
+   * ADDRESSING. The `calendar.*` payload is redacted like every other family —
+   * `event.created` carries `attendeeCount`, `invitesQueued` and the CALENDAR
+   * OWNER (`calendarMemberId`), never the attendee list. So ownership is the
+   * only thing the frame can prove, and attendance has to come from
+   * `calendar.list`, which is ACL'd to the acting seat: it returns events where
+   * `calendarMemberId = viewpoint` OR `attendeeRows.some(memberId = viewpoint)`,
+   * under hq's PERSONAL_RESTRICTED lens floor (a colleague's restricted event is
+   * ABSENT, never redacted). We never widen the payload to carry attendees.
+   */
+  calendar: Object.freeze({
+    topic: "calendar",
+    kind: "calendar",
+    subject: "Cohort calendar",
+    scope: "channel",
+    default: true,
+  }),
   /** A delegation offered to me, or one I offered being accepted/declined. */
   handoff: Object.freeze({
     topic: "handoff",

package/lib/org/param-contract.mjs

@@ -422,11 +422,25 @@ export const PARAM_CONTRACT = {
     note: "hq resolves a member by SLUG, not id.",
   },
   "escalation.create": {
-    alias: { subject: "title", body: "detail", description: "detail" },
+    alias: { subject: "title", body: "detail", description: "detail", summary: "title" },
     enums: { severity: ESCALATION_SEVERITIES },
     required: ["title"],
     oneOf: [["taskId", "channelId"]],
-    note: "hq requires a title AND a target (taskId or channelId).",
+    unsupported: ["waitingOnMemberId", "options", "context"],
+    note:
+      "hq requires a title AND a target (taskId or channelId). `summary` is aliased " +
+      "because lib/execution/effects.mjs sent exactly that and 400'd on every call; " +
+      "`waitingOnMemberId`/`options`/`context` are NOT fields of this method — an " +
+      "escalation carrying OPTIONS is an OpenQuestion and belongs at escalation.ask.",
+  },
+  "escalation.ask": {
+    // hq methods/escalation/ask.ts: `question` (<=2000) + >=2 DISTINCT options,
+    // `context` is a STRING (<=4000) — not an object — and `trigger` <=100.
+    // The two-option floor is enforced server-side and is the whole point: an
+    // escalation with one option is a notification, with none it is prose.
+    alias: { text: "question", prompt: "question", choices: "options" },
+    required: ["question", "options"],
+    note: "at least two distinct options, or hq 400s; `context` is a string, not an object.",
   },
 
   // ── leases ───────────────────────────────────────────────────────────────

package/lib/org/protocol.checksum

@@ -1 +1 @@
-85e71129422236b2de83d7f2da1ed04821b9f7c3f7a025a31939cf95d5a4a7db
+1946d98145f4c1e56d80e58c37d9b54d5ea8d88c7d30251a694484418327dddf

package/lib/org/protocol.mjs

@@ -55,6 +55,27 @@ export const FAMILIES = Object.freeze([
   // the Directory (2026-07): the canonical registry of external people and
   // organisations every other desk resolves its counterparties through.
   "directory",
+  // the sub-agent registry (2026-08): layer 1 of the SDK / workspace /
+  // agent-local resolution model — org-scoped, versioned sub-agent definitions
+  // pinned per seat. Governs the DISTRIBUTION and provenance of agent prose;
+  // resolution itself runs locally on the agent, never here.
+  "subagent",
+  // the agent's own control lane (2026-08): agent.wait, the bounded long-poll a
+  // daemon parks on instead of polling every 45s. Read-only — nothing in this
+  // family appends to the chain; it only READS the chain by seq.
+  "agent",
+  // the MANDATE spine (2026-08, SPEC "Three-Dimensional Agent Autonomy"): the
+  // objective tree, its KPI samples, the published per-seat mandate snapshot,
+  // and the agent's own capability/plan/drift reports. hq owns the MANDATE
+  // (outcomes, owners, targets, budgets, kill-switch); the agent owns the PLAN
+  // (obligations, schedule, rung) and compiles it locally. This family is the
+  // wire between the two halves.
+  "mandate",
+  // member-scoped PREFERENCES (2026-08, SPEC §9 reverse parity). hq has always
+  // injected these into responder context automatically; the family exists so a
+  // seat can PERSIST one it learned rather than re-deriving it every session.
+  // The chain rows carry subject + domain + key only — never the value.
+  "preference",
 ]);
 
 /**
@@ -131,6 +152,17 @@ export const SCOPES = Object.freeze([
   "directory.write", // Directory writes: create/update parties, channels, captures, links, lists. Structural verbs (merge execution, awareness change, archive) refuse an agent actor in-domain and create a review item instead
   "design.read",     // Design reads: the SAVED brand foundation snapshot (never a draft), voice, visible templates. Renders and voice rewrites are AUDITED side-effecting reads under this scope (files.exportRequest precedent)
   "design.write",    // Design writes: generate imagery, propose a foundation change. Foundation mutation itself is admin-only and human-gated -- a proposal creates a reviewable diff, it does not write
+  // mandate spine (2026-08). The read/propose/write split is the anti-Goodhart
+  // law expressed as scopes, and it deliberately mirrors approval.request vs
+  // approval.decide: an agent may READ its mandate and PROPOSE against it, but
+  // ADOPTING an objective (making it live, work-creating and graded) is a
+  // human/manager act the seat's own credential cannot perform.
+  "mandate.read",    // read own mandate snapshot + version + KPI series
+  "mandate.propose", // propose/update objectives — `state:'proposed'` ONLY, never an adopted row
+  "mandate.write",   // adopt / retire an objective. NOT in DEFAULT_AGENT_SCOPES — human/manager only
+  "kpi.write",       // report a KPI sample against an objective. Honesty is enforced by the
+                     //   server-set `source` field, never by scope: a seat may always report,
+                     //   but an `llm`-sourced number is advisory and cannot create work.
   "admin",           // pairing approval, deactivate (kill switch), governance, policy, credential put/revoke
 ]);
 
@@ -148,6 +180,11 @@ export const DEFAULT_AGENT_SCOPES = Object.freeze([
   "files.read", "files.write", "calendar.read", "calendar.write",
   "crm.read", "crm.write", "books.read", "books.write",
   "directory.read", "directory.write", "design.read", "design.write",
+  // mandate spine (2026-08): a seat reads its own mandate, proposes against it,
+  // and reports its own samples. `mandate.write` (adopt/retire) is POINTEDLY
+  // ABSENT — that is the whole anti-Goodhart law. A seat cannot define, measure
+  // AND be graded on the same number.
+  "mandate.read", "mandate.propose", "kpi.write",
 ]);
 
 /** Knowledge group scopes: org-wide, per-unit, or an information-barrier cell (deny-override). */
@@ -240,6 +277,13 @@ export const METHODS = Object.freeze({
   "messaging.react": { family: "messaging", scope: "messaging.write", sideEffecting: true },
   "messaging.edit": { family: "messaging", scope: "messaging.write", sideEffecting: true },
   "messaging.history": { family: "messaging", scope: "messaging.read", sideEffecting: false },
+  // --- messaging.search (2026-08 REVERSE PARITY, SPEC §9): the family carried
+  //     thirteen methods and no search, so an SDK-driven seat could not answer
+  //     "what did we decide about X anywhere?" while the hq responder in the
+  //     same workspace could (its `search_messages` tool). Postgres FTS across
+  //     every channel the paired member can read; the ACL floor is computed
+  //     server-side, so `channelId`/`channelSlug` narrow and can never widen. ---
+  "messaging.search": { family: "messaging", scope: "messaging.read", sideEffecting: false },
   // --- messaging.typing (2026-08): the "is composing…" indicator an agent raises
   //     while it works. The ONE write-less method in the family — it appends NO
   //     chain event and writes NO row, it publishes an EPHEMERAL frame that
@@ -357,6 +401,14 @@ export const METHODS = Object.freeze({
   "escalation.create": { family: "escalation", scope: "org.write", sideEffecting: true, idempotent: true },
   "escalation.resolve": { family: "escalation", scope: "org.write", sideEffecting: true },
   "escalation.list": { family: "escalation", scope: "org.read", sideEffecting: false },
+  // `OpenQuestion`'s FIRST WRITERS. The model has had readers and a UI for
+  // months with no producer, so a charter `escalationTrigger` firing could only
+  // ever emit prose. `ask` requires >= 2 concrete options (a one-option question
+  // is a notification, not a decision); `answer` is deliberately NOT idempotent
+  // — a second answer is a CONFLICT so the first decision stands — and refuses
+  // the asker, the same law as `Approval.requester ≠ approver`.
+  "escalation.ask": { family: "escalation", scope: "org.write", sideEffecting: true },
+  "escalation.answer": { family: "escalation", scope: "org.write", sideEffecting: true },
   // --- annotation ---
   "annotation.create": { family: "annotation", scope: "org.write", sideEffecting: true, idempotent: true },
   "annotation.comment": { family: "annotation", scope: "org.write", sideEffecting: true },
@@ -380,6 +432,26 @@ export const METHODS = Object.freeze({
   "memory.proposeAmendment": { family: "memory", scope: "knowledge.write", sideEffecting: true },
   "memory.mergeAmendment": { family: "memory", scope: "knowledge.write", sideEffecting: true },
   "memory.list": { family: "memory", scope: "knowledge.read", sideEffecting: false },
+  // --- memory.recall (2026-08 REVERSE PARITY, SPEC §9): layered semantic recall
+  //     over the unified agent memory, with the FULL contract the hq responder's
+  //     `recall_memory` tool has had since the agent-memory program shipped —
+  //     scope (org|self|channel) / refType+refId / time range / depth /
+  //     drill-down pointers. `knowledge.search` is a narrowed projection of this
+  //     (shared facts only, no controls), so until now an SDK seat reasoned off
+  //     a strictly smaller memory than the chat lane in the same workspace.
+  //     ACL is server-side off the paired member — fail-closed, never a param. ---
+  "memory.recall": { family: "memory", scope: "knowledge.read", sideEffecting: false },
+  // --- preference (2026-08 REVERSE PARITY, SPEC §9): there was NO preference.*
+  //     family at all. An SDK agent could LEARN a durable member-scoped fact and
+  //     had nowhere to put it, while the hq responder's `remember_preference`
+  //     wrote straight into PreferenceMemory — which hq then injects into every
+  //     future conversation. Same workspace, two memories. `upsert` converges on
+  //     one row per (subject, domain, key) and REQUIRES evidence; the chain
+  //     append carries whose/which-key and never the value (a preference value
+  //     is content). `list` ships with it because a write-only family is not
+  //     parity: hq SEES injected preferences for free, a seat has to ask. ---
+  "preference.upsert": { family: "preference", scope: "org.write", sideEffecting: true, idempotent: true },
+  "preference.list": { family: "preference", scope: "org.read", sideEffecting: false },
   // --- compact ---
   "compact.upsert": { family: "compact", scope: "org.write", sideEffecting: true, idempotent: true },
   // --- notification ---
@@ -775,8 +847,124 @@ export const METHODS = Object.freeze({
   "files.comments": { family: "files", scope: "files.read", sideEffecting: false },
   "files.sheetFedRange": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
   "files.ask": { family: "files", scope: "files.read", sideEffecting: false },
+  // --- subagent (2026-08): the org-scoped sub-agent registry. NO NEW SCOPES —
+  //     a sub-agent definition is org-structural authored content exactly like
+  //     a persona, an SOP or an annotation, which is what `org.write` covers,
+  //     and both org.read/org.write are already in DEFAULT_AGENT_SCOPES.
+  //     Curation (`yank`) is admin, like every other destructive verb.
+  //
+  //     `resolve` is the EXPENSIVE read (bodies + provenance + rewire hints);
+  //     the cheap poll is the `subagent.roster` GET in READS, which returns
+  //     {slug, definitionId, version, contentHash} and no bodies. Naming a
+  //     memberId other than the caller's own seat requires `admin` — enforced
+  //     in-domain (methods/subagent/_shared.ts), the invokeTool doctrine. ---
+  "subagent.list": { family: "subagent", scope: "org.read", sideEffecting: false },
+  "subagent.get": { family: "subagent", scope: "org.read", sideEffecting: false },
+  "subagent.resolve": { family: "subagent", scope: "org.read", sideEffecting: false },
+  "subagent.create": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.publishVersion": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.fork": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.pin": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.unpin": { family: "subagent", scope: "org.write", sideEffecting: true },
+  "subagent.yank": { family: "subagent", scope: "admin", sideEffecting: true },
+  // --- agent control lane (2026-08): the bounded long-poll a daemon parks on so
+  //     it learns about its own work in ~0s instead of on a 45s poll cadence.
+  //     Modelled on the `approval.wait` precedent (READS, a held request), but
+  //     registered here as a POST method because it takes a CURSOR + a page of
+  //     structured results, which is the METHODS shape — and because a held GET
+  //     is far more likely to be cached/coalesced by an intermediary.
+  //
+  //     NO NEW SCOPE. `org.read` is the floor to call it at all (it is in
+  //     DEFAULT_AGENT_SCOPES, so every paired agent can park), and each LANE it
+  //     reports on is gated separately in-domain against the key's own scopes
+  //     (messaging.read / board.read / email.read) — a key minted without
+  //     email.read is never told that mail arrived. sideEffecting:false: it
+  //     appends NOTHING to the chain, it only reads the chain by seq. ---
+  "agent.wait": { family: "agent", scope: "org.read", sideEffecting: false },
+  // --- mandate (2026-08): the MANDATE half of the mandate/plan split. hq is
+  //     authoritative for WHAT the outcomes are; the agent compiles the plan.
+  //
+  //     The scope split is the design: `mandate.read`/`mandate.propose`/
+  //     `kpi.write` are in DEFAULT_AGENT_SCOPES, `mandate.write` is not.
+  //     `adopt`/`retire` are ALSO governanceGated — the decision-rights matrix
+  //     must exist before a seat can be handed a live, graded objective, the
+  //     same ordering rule that gates board.assign and handoff.*.
+  //
+  //     `declareCapability`/`publishPlan`/`reportDrift` reuse `registry.write`:
+  //     they are a seat reporting facts about ITSELF, exactly like
+  //     registry.register, and every paired agent already holds it. ---
+  "mandate.get": { family: "mandate", scope: "mandate.read", sideEffecting: false },
+  "mandate.version": { family: "mandate", scope: "mandate.read", sideEffecting: false },
+  "mandate.tree": { family: "mandate", scope: "org.read", sideEffecting: false },
+  "mandate.series": { family: "mandate", scope: "mandate.read", sideEffecting: false },
+  "mandate.propose": { family: "mandate", scope: "mandate.propose", sideEffecting: true, idempotent: true },
+  "mandate.adopt": { family: "mandate", scope: "mandate.write", sideEffecting: true, governanceGated: true },
+  "mandate.retire": { family: "mandate", scope: "mandate.write", sideEffecting: true, governanceGated: true },
+  "mandate.sample": { family: "mandate", scope: "kpi.write", sideEffecting: true, idempotent: true },
+  "mandate.declareCapability": { family: "mandate", scope: "registry.write", sideEffecting: true, idempotent: true },
+  "mandate.publishPlan": { family: "mandate", scope: "registry.write", sideEffecting: true, idempotent: true },
+  "mandate.reportDrift": { family: "mandate", scope: "registry.write", sideEffecting: true },
+  // --- board review lane (2026-08 consensus fix): `Task.reviewerId` has existed
+  //     since T19 and had NO writer on the agent plane, so "send it for review"
+  //     was unreachable from a daemon and every review round-trip degraded to a
+  //     comment. These two methods are the writer. ---
+  "board.requestReview": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.resolveReview": { family: "board", scope: "board.write", sideEffecting: true },
+  // --- escalation as a QUESTION (2026-08): `OpenQuestion` shipped with readers
+  //     and no writer at all. `escalation.ask` is its first one. The difference
+  //     from `escalation.create` matters: an Escalation is "a human is needed
+  //     here"; an OpenQuestion is "here are 2-3 concrete options, pick one",
+  //     which is what a Charter.escalationTriggers hit should actually produce. ---
+  // NOTE: `escalation.ask` / `escalation.answer` (raise an OpenQuestion with
+  // concrete options, and the human picking one) are deliberately NOT registered
+  // yet — `ask` needs a `_question` projector that is not written. A METHODS
+  // entry with no working handler is not a placeholder, it is a live promise the
+  // dispatcher cannot keep: the protocol advertises the method, the caller gets
+  // through scope resolution, and the call 500s. Register each in the same
+  // change that lands its handler.
+  // NOTE: `escalation.answer` (the human picking one of the offered options) is
+  // deliberately NOT registered yet — its handler is not written. A METHODS
+  // entry with no handler file is not a placeholder, it is a live promise the
+  // dispatcher cannot keep: the protocol advertises the method, callers get
+  // through scope resolution, and the call 500s. Register it in the same change
+  // that adds src/server/methods/escalation/answer.ts.
 });
 
+/**
+ * The ONE action-class table (SPEC §8 "Approvals"). Replaces maestro's local
+ * `GATED_CLASSES` and hq's free-form `Approval.actionClass` strings with a
+ * shared vocabulary both sides validate against.
+ *
+ * `GATED_ACTION_CLASSES` is the blast-radius gate: an action in one of these
+ * classes forces an approval BEFORE any execution rung runs, at every rung.
+ * @type {readonly string[]}
+ */
+export const ACTION_CLASSES = Object.freeze([
+  "internal",     // stays inside the workspace; reversible; no spend
+  "external",     // leaves the org (email to a third party, a public post)
+  "irreversible", // cannot be undone by a subsequent method call
+  "financial",    // moves money or commits spend
+]);
+
+/** Action classes that force a human approval before execution. */
+export const GATED_ACTION_CLASSES = Object.freeze(["external", "irreversible", "financial"]);
+
+/**
+ * PlanDrift kinds — the reconciler's vocabulary for "the plan and the world
+ * disagree". Shared so hq can index/report on them without string drift.
+ * @type {readonly string[]}
+ */
+export const DRIFT_KINDS = Object.freeze([
+  "uncovered_event",        // a directed event matched no REACT obligation
+  "unreachable_capability", // an obligation cites a capability that failed its probe
+  "stale_sensor",           // no sample within 2x the objective's cadence
+  "schedule_missing",       // a SCHEDULE obligation has no launchd trigger on disk
+  "kpi_gap",                // measured value is outside tolerance of target
+  "budget_breach",          // an obligation exhausted its envelope
+  "orphan_work",            // open work with no objective behind it
+  "mandate_stale",          // the cached mandate aged past the staleness ladder
+]);
+
 /**
  * Is a method refused until the org server is `governance_ready` (decision_rights
  * populated AND signing live)? A partially deployed control plane is worse than
@@ -806,6 +994,12 @@ export const READS = Object.freeze({
   // phase 4 reads
   "contacts.list": "knowledge.read",   // org contacts registry (ACL-filtered)
   "meetings.list": "knowledge.read",   // org meetings registry (ACL-filtered)
+  // sub-agent registry (2026-08): the CHEAP roster poll. Returns the bare
+  // {rosterVersion, entries:[{slug, definitionId, version, contentHash}]} — no
+  // bodies — so a seat can diff its `.maestro/subagents.lock.json` on every
+  // beat without paying for prose. `subagent.resolve` (METHODS) is the
+  // expensive twin that carries bodies.
+  "subagent.roster": "org.read",
 });
 
 /** Error codes (the error contract; HTTP status hints are advisory). */
@@ -822,8 +1016,26 @@ export const ERROR_CODES = Object.freeze({
   INTERNAL: { http: 500 },
 });
 
-/** Directive kinds the presence.beat response may carry (kill-switch + nudges). */
-export const DIRECTIVES = Object.freeze(["halt", "rotate_token", "policy_stale", "resync"]);
+/**
+ * Directive kinds the presence.beat response may carry (kill-switch + nudges).
+ *
+ * Levels 1-3 of the four-level kill-switch (SPEC §8) live here and are
+ * COOPERATIVE: they only work while the daemon is healthy enough to beat and
+ * honest enough to obey. Level 4 — `credential.revoke` + API-key disable — is
+ * the only control that works against a wedged or compromised laptop. Say that
+ * out loud rather than implying the beat is a hard stop.
+ */
+export const DIRECTIVES = Object.freeze([
+  "halt",            // stop entirely. hq ALSO closes the SSE lane (`event: bye`) so a
+                     //   daemon that stopped beating stops receiving work to do.
+  "rotate_token",
+  "policy_stale",
+  "resync",
+  // --- mandate spine (2026-08) ---
+  "pause_schedules", // stop INITIATING (Loop B + Loop C); keep answering when addressed
+  "plan_stale",      // the seat's mandate moved — refetch `mandate.get` and recompile
+  "revoke_scope",    // a scope was withdrawn; drop it locally and re-probe capabilities
+]);
 
 // ---------------------------------------------------------------------------
 // Helpers (shared, pure)

package/lib/org/protocol.test.mjs

@@ -131,7 +131,10 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // 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");
+  // The 2026-08 protocol-convergence pass adds 4: subagent (the org-scoped
+  // sub-agent registry), agent (the agent.wait control lane), mandate (the
+  // MANDATE spine) and preference (member-scoped preferences) → 51.
+  assert.equal(FAMILIES.length, 51, "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
@@ -160,8 +163,14 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // "is composing…" indicator an SDK-driven agent raises while it works —
   // sideEffecting:false, no chain event, expires client-side) → 431.
   // Bumped deliberately alongside
+  // The 2026-08 protocol-convergence pass closes the 29-method gap against hq's
+  // vendored table (the client rejected every one of them BEFORE the network,
+  // so mandate.* et al were unreachable from a daemon): messaging.search,
+  // escalation.ask/answer, memory.recall, preference.upsert/list (6 reverse-
+  // parity methods), the 9 subagent.* registry methods, agent.wait, the 11
+  // mandate.* spine methods, and board.requestReview/resolveReview → 460.
   // the descriptors; the checksum (read at runtime) is the primary drift guard.
-  assert.equal(Object.keys(METHODS).length, 431, "method count");
+  assert.equal(Object.keys(METHODS).length, 460, "method count");
 });
 
 test("protocol SP3: messaging + calling families/methods/scopes", async () => {