@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/mandate/model.test.mjs

@@ -0,0 +1,145 @@
+/**
+ * model.test.mjs — the pillar spine: validation, provenance, anti-Goodhart.
+ * Run: `node --test lib/mandate/model.test.mjs`
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  objectivesOf,
+  validateMandateBody,
+  buildTree,
+  ancestry,
+  pillarFor,
+  provenanceOf,
+  adoptedObjectives,
+  isSelfAdopted,
+  collaboratorsOf,
+} from "./model.mjs";
+
+const ME = "mem_self";
+const BOSS = "mem_boss";
+
+function tree(over = {}) {
+  return {
+    memberId: ME,
+    objectives: [
+      { key: "growth", kind: "PILLAR", parentKey: null, charterSectionId: "cs_12", state: "active", adoptedById: BOSS, source: { origin: "charter", ref: "cs_12" } },
+      {
+        key: "pipeline",
+        kind: "OBJECTIVE",
+        parentKey: "growth",
+        state: "active",
+        metric: "pipeline_coverage_x",
+        target: 3,
+        tolerance: 0.2,
+        direction: "up",
+        cadence: "weekly",
+        sensor: { capability: "crm_list_deals", params: {}, source: "method" },
+        adoptedById: BOSS,
+        collaborators: [{ memberId: "mem_peer", role: "REVIEWER" }],
+        ...over.pipeline,
+      },
+      { key: "win-rate", kind: "GOAL", parentKey: "pipeline", state: "proposed", metric: "win_rate", target: null, cadence: "monthly" },
+    ],
+  };
+}
+
+test("objectivesOf accepts a cache record, a bare body, or an array", () => {
+  const body = tree();
+  assert.equal(objectivesOf(body).length, 3);
+  assert.equal(objectivesOf({ body }).length, 3);
+  assert.equal(objectivesOf(body.objectives).length, 3);
+  assert.deepEqual(objectivesOf(null), []);
+});
+
+test("a well-formed tree validates and yields exactly the adopted, measurable nodes", () => {
+  const body = tree();
+  const v = validateMandateBody(body, { ownerMemberId: ME });
+  assert.equal(v.ok, true, v.errors.join("; "));
+  const adopted = adoptedObjectives(body, { ownerMemberId: ME, badKeys: v.badKeys });
+  assert.deepEqual(adopted.map((o) => o.key), ["pipeline"], "the PILLAR is not measurable; the GOAL is only proposed");
+});
+
+test("ANTI-GOODHART: a seat that adopted its own objective is an ERROR and drives no work", () => {
+  const body = tree({ pipeline: { adoptedById: ME } });
+  const v = validateMandateBody(body, { ownerMemberId: ME });
+  assert.equal(v.ok, false);
+  assert.match(v.errors.join(" "), /self-adopted/);
+  assert.ok(v.badKeys.includes("pipeline"));
+  assert.deepEqual(adoptedObjectives(body, { ownerMemberId: ME }), [], "a self-adopted objective may never drive work");
+  assert.equal(isSelfAdopted(body.objectives[1], ME), true);
+});
+
+test("an active objective with no target / no metric fails closed", () => {
+  const body = tree({ pipeline: { target: null, metric: null } });
+  const v = validateMandateBody(body, { ownerMemberId: ME });
+  assert.equal(v.ok, false);
+  assert.match(v.errors.join(" "), /no metric/);
+  assert.match(v.errors.join(" "), /no numeric target/);
+  assert.ok(v.badKeys.includes("pipeline"));
+});
+
+test("structural errors: bad kind, missing parent, illegal parentage, duplicate key, cycle", () => {
+  const v = validateMandateBody({
+    memberId: ME,
+    objectives: [
+      { key: "a", kind: "WIDGET", state: "proposed" },
+      { key: "b", kind: "GOAL", parentKey: "nope", state: "proposed" },
+      { key: "c", kind: "PILLAR", parentKey: "d", state: "proposed" },
+      { key: "d", kind: "PILLAR", parentKey: null, state: "proposed" },
+      { key: "d", kind: "PILLAR", parentKey: null, state: "proposed" },
+      { key: "x", kind: "OBJECTIVE", parentKey: "y", state: "proposed" },
+      { key: "y", kind: "OBJECTIVE", parentKey: "x", state: "proposed" },
+    ],
+  });
+  const joined = v.errors.join(" | ");
+  assert.match(joined, /unknown kind "WIDGET"/);
+  assert.match(joined, /parent "nope" not found/);
+  assert.match(joined, /PILLAR may not hang from a PILLAR/);
+  assert.match(joined, /duplicate key "d"/);
+  assert.match(joined, /cycle in the objective tree/);
+});
+
+test("an active objective with no adoptedById WARNS (unverifiable) but is not an error", () => {
+  const body = tree({ pipeline: { adoptedById: null } });
+  const v = validateMandateBody(body, { ownerMemberId: ME });
+  assert.equal(v.ok, true, v.errors.join("; "));
+  assert.match(v.warnings.join(" "), /carries no adoptedById/);
+});
+
+test("provenance walks node → objective → pillar → charter clause, offline", () => {
+  const body = tree();
+  assert.deepEqual(ancestry(body, "win-rate").map((n) => n.key), ["win-rate", "pipeline", "growth"]);
+  assert.equal(pillarFor(body, "win-rate").key, "growth");
+  const p = provenanceOf(body, "pipeline");
+  assert.deepEqual(p.chain, ["pipeline", "growth"]);
+  assert.equal(p.clause, "cs_12");
+  assert.equal(p.adoptedBy, BOSS);
+});
+
+test("buildTree nests children and surfaces orphans as roots rather than dropping them", () => {
+  const roots = buildTree({ objectives: [
+    { key: "p", kind: "PILLAR" },
+    { key: "o", kind: "OBJECTIVE", parentKey: "p" },
+    { key: "orphan", kind: "GOAL", parentKey: "vanished" },
+  ] });
+  assert.deepEqual(roots.map((r) => r.key).sort(), ["orphan", "p"]);
+  assert.equal(roots.find((r) => r.key === "p").children[0].key, "o");
+});
+
+test("collaboratorsOf normalises strings, objects and casing", () => {
+  assert.deepEqual(collaboratorsOf({ collaborators: ["m1", { memberId: "m2", role: "reviewer" }, { id: "m3" }, null] }), [
+    { memberId: "m1", role: "CONTRIBUTOR" },
+    { memberId: "m2", role: "REVIEWER" },
+    { memberId: "m3", role: "CONTRIBUTOR" },
+  ]);
+});
+
+test("badKeys are excluded from adoptedObjectives so a broken node cannot drive work", () => {
+  const body = tree();
+  assert.deepEqual(adoptedObjectives(body, { ownerMemberId: ME, badKeys: ["pipeline"] }), []);
+});

package/lib/mandate/refresh.mjs

@@ -0,0 +1,187 @@
+/**
+ * lib/mandate/refresh.mjs — "derived at init from charter/role, refreshed on a
+ * cadence" — the one function both callers use.
+ *
+ * Init (`lib/setup/sections/mandate.mjs`) and the `goal-steward` cadence want
+ * the same thing with different fallbacks:
+ *
+ *   ONLINE   `mandate.get` returns the seat's ADOPTED snapshot → cache it with
+ *            `source:"server"`. That snapshot is authoritative; the local
+ *            derivation is not consulted.
+ *   OFFLINE  no org, an org that does not carry the `mandate` family yet, or a
+ *            failed call → derive locally from charter + strategy + archetype
+ *            (`lib/mandate/derive.mjs`) and cache it with `source:"local"`.
+ *            EVERY derived objective is `state:'proposed'`, and proposed
+ *            objectives compile no obligations and admit no backlog — so the
+ *            offline path can never cause the agent to invent its own targets.
+ *
+ * The degradation is always REPORTED (`{degraded, reason}` plus a log line).
+ * The specific case worth naming: maestro's vendored `lib/org/protocol.mjs` does
+ * not yet carry the `mandate` family, so `client.call("mandate.get", …)` returns
+ * `NOT_FOUND: unknown method` WITHOUT touching the network. That is a vendoring
+ * gap, not an outage, and it is logged as such rather than looking like a dead
+ * server.
+ *
+ * @module lib/mandate/refresh
+ */
+
+"use strict";
+
+import { readCache, writeCache, stalenessTier, checksumOf } from "./cache.mjs";
+import { deriveMandate, toMandateBody } from "./derive.mjs";
+import { validateMandateBody } from "./model.mjs";
+
+/** The protocol method that returns a seat's adopted snapshot. */
+export const GET_METHOD = "mandate.get";
+
+function logOf(deps) {
+  return deps && typeof deps.log === "function" ? deps.log : () => {};
+}
+
+/**
+ * Fetch the adopted snapshot from the org. Never throws; every failure mode is
+ * a distinct, reportable reason.
+ *
+ * @param {object} deps - { callImpl, base, token, orgId, fetchImpl, memberId, log }
+ * @returns {Promise<{ok:boolean, snapshot:object|null, reason:string}>}
+ */
+export async function fetchSnapshot(deps = {}) {
+  const callImpl =
+    typeof deps.callImpl === "function"
+      ? deps.callImpl
+      : async (method, params) => {
+          const { call } = await import("../org/client.mjs");
+          return call(method, params, { base: deps.base, token: deps.token, orgId: deps.orgId, fetchImpl: deps.fetchImpl });
+        };
+  let frame;
+  try {
+    frame = await callImpl(GET_METHOD, { memberId: deps.memberId || undefined });
+  } catch (err) {
+    return { ok: false, snapshot: null, reason: `call-threw:${err && err.message ? err.message : err}` };
+  }
+  if (frame && frame.ok) {
+    const r = frame.result || {};
+    return { ok: true, snapshot: { version: Number(r.version) || 0, checksum: r.checksum || null, body: r.body || r }, reason: "fetched" };
+  }
+  const code = (frame && frame.error && frame.error.code) || "unknown";
+  const msg = (frame && frame.error && frame.error.message) || "";
+  if (code === "NOT_FOUND" && /unknown method/i.test(msg)) {
+    return { ok: false, snapshot: null, reason: "protocol-missing-mandate-family" };
+  }
+  return { ok: false, snapshot: null, reason: `call-failed:${code}` };
+}
+
+/**
+ * Refresh (or first-time populate) the local mandate cache.
+ *
+ * @param {string} agentRoot
+ * @param {object} [deps] - {
+ *   now, log, memberId, callImpl?, base?, token?, orgId?, fetchImpl?,
+ *   offline?:boolean,          // skip the fetch entirely (init --headless)
+ *   derivation?: {             // inputs for the local fallback
+ *     charterSections, strategy, kpiCategories, priorities, manifest, overrides
+ *   }
+ * }
+ * @returns {Promise<{
+ *   ok:boolean, source:'server'|'local'|'cache', degraded:boolean, reason:string,
+ *   changed:boolean, tier:string, record:object|null, counts?:object, degradations?:object[]
+ * }>}
+ */
+export async function refreshMandate(agentRoot, deps = {}) {
+  const log = logOf(deps);
+  const prev = readCache(agentRoot);
+  const prevChecksum = prev && !prev.corrupt ? prev.checksum : null;
+
+  // --- online path ---------------------------------------------------------
+  if (!deps.offline) {
+    const got = await fetchSnapshot(deps);
+    if (got.ok && got.snapshot && got.snapshot.body) {
+      const body = got.snapshot.body;
+      const local = checksumOf(body);
+      if (got.snapshot.checksum && got.snapshot.checksum !== local) {
+        log(
+          "warn",
+          `[mandate] snapshot checksum mismatch (server=${String(got.snapshot.checksum).slice(0, 12)} local=${local.slice(0, 12)}) — caching anyway; re-vendor lib/org/protocol.mjs if this persists`
+        );
+      }
+      const record = writeCache(
+        agentRoot,
+        { version: got.snapshot.version, checksum: local, body, source: "server" },
+        { now: deps.now ? () => new Date(deps.now()).toISOString() : undefined }
+      );
+      const validation = validateMandateBody(record, { ownerMemberId: deps.memberId });
+      for (const e of validation.errors) log("warn", `[mandate] adopted snapshot is invalid: ${e}`);
+      return {
+        ok: true,
+        source: "server",
+        degraded: false,
+        reason: "fetched the adopted snapshot",
+        changed: record.checksum !== prevChecksum,
+        tier: stalenessTier(record, deps.now ? deps.now() : Date.now()),
+        record,
+        validation,
+      };
+    }
+    log(
+      "warn",
+      got.reason === "protocol-missing-mandate-family"
+        ? "[mandate] the vendored protocol carries no `mandate` family — falling back to the local derivation. Re-vendor lib/org/protocol.mjs (by hand: sync-protocol is unsafe while maestro main lacks the crm family) to pick up adopted objectives."
+        : `[mandate] could not fetch the adopted snapshot (${got.reason}) — falling back to the local derivation`
+    );
+  }
+
+  // --- offline / fallback path ---------------------------------------------
+  const d = deps.derivation || {};
+  const derived = deriveMandate({
+    charterSections: d.charterSections,
+    strategy: d.strategy,
+    kpiCategories: d.kpiCategories,
+    priorities: d.priorities,
+    manifest: d.manifest,
+    memberId: deps.memberId,
+    overrides: d.overrides,
+  });
+  for (const deg of derived.degradations || []) {
+    log("warn", `[mandate] derivation degradation (${deg.kind}): ${deg.reason}`);
+  }
+  const body = toMandateBody({ memberId: deps.memberId, objectives: derived.objectives });
+
+  // Never overwrite a SERVER snapshot with a local derivation: adopted beats
+  // proposed, always. A stale server snapshot is still the real mandate.
+  if (prev && !prev.corrupt && prev.source === "server") {
+    log(
+      "info",
+      "[mandate] keeping the cached SERVER snapshot; a local derivation never supersedes adopted objectives"
+    );
+    return {
+      ok: true,
+      source: "cache",
+      degraded: true,
+      reason: deps.offline ? "offline; kept the cached adopted snapshot" : "fetch failed; kept the cached adopted snapshot",
+      changed: false,
+      tier: stalenessTier(prev, deps.now ? deps.now() : Date.now()),
+      record: prev,
+      counts: derived.counts,
+      degradations: derived.degradations,
+    };
+  }
+
+  const record = writeCache(
+    agentRoot,
+    { version: 0, body, source: "local" },
+    { now: deps.now ? () => new Date(deps.now()).toISOString() : undefined }
+  );
+  return {
+    ok: true,
+    source: "local",
+    degraded: true,
+    reason: deps.offline ? "derived locally (offline)" : "derived locally (the org could not supply an adopted snapshot)",
+    changed: record.checksum !== prevChecksum,
+    tier: stalenessTier(record, deps.now ? deps.now() : Date.now()),
+    record,
+    counts: derived.counts,
+    degradations: derived.degradations,
+  };
+}
+
+export default { GET_METHOD, fetchSnapshot, refreshMandate };

package/lib/mandate/refresh.test.mjs

@@ -0,0 +1,293 @@
+/**
+ * lib/mandate/refresh.test.mjs — "derived at init from charter/role, refreshed
+ * on a cadence", plus the cache and its staleness ladder.
+ *
+ * The load-bearing rule under test: **an adopted server snapshot always beats a
+ * local derivation.** A partitioned agent falls back to what it can derive, but
+ * the moment it has once held a real mandate, no local derivation may overwrite
+ * it — otherwise a network blip would silently demote adopted objectives to
+ * proposed ones and the agent would quietly stop working toward them.
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { refreshMandate, fetchSnapshot, GET_METHOD } from "./refresh.mjs";
+import {
+  readCache, writeCache, cachePath, checksumOf, canonical,
+  staleSeconds, stalenessTier, permissionsForTier, adoptedObjectives, TIERS,
+} from "./cache.mjs";
+
+const NOW = Date.parse("2026-08-11T09:00:00.000Z");
+
+function makeRoot() {
+  return mkdtempSync(join(tmpdir(), "mandate-refresh-"));
+}
+function cleanup(root) {
+  try { rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+const BODY = {
+  memberId: "mem_self",
+  objectives: [
+    { key: "revenue", kind: "PILLAR", state: "active", charterSectionId: "cs_1", adoptedById: "mem_boss" },
+    {
+      key: "pipeline", kind: "OBJECTIVE", parentKey: "revenue", state: "active",
+      metric: "pipeline_coverage_x", target: 3, direction: "up", cadence: "weekly",
+      sensor: { capability: "crm_list_deals", source: "method" }, adoptedById: "mem_boss",
+    },
+  ],
+};
+
+const DERIVATION = {
+  charterSections: [{ id: "cs_1", kind: "PILLAR", order: 1, title: "Revenue growth", body: "Own revenue." }],
+  kpiCategories: [{ id: "pipeline", name: "Pipeline coverage", examples: ["pipeline_coverage_x"] }],
+};
+
+// ---------------------------------------------------------------------------
+// Cache primitives
+// ---------------------------------------------------------------------------
+
+test("canonical JSON is key-order independent, so the checksum is stable", () => {
+  assert.equal(canonical({ b: 1, a: 2 }), canonical({ a: 2, b: 1 }));
+  assert.equal(checksumOf({ b: 1, a: 2 }), checksumOf({ a: 2, b: 1 }));
+  assert.notEqual(checksumOf({ a: 1 }), checksumOf({ a: 2 }));
+});
+
+test("a missing cache is null; a CORRUPT cache is reported as corrupt, never as empty", () => {
+  const root = makeRoot();
+  try {
+    assert.equal(readCache(root), null);
+    mkdirSync(join(root, "state", "mandate"), { recursive: true });
+    writeFileSync(cachePath(root), "{not json", "utf-8");
+    const rec = readCache(root);
+    assert.equal(rec.corrupt, true);
+    assert.ok(rec.reason, "a corrupt cache must carry the parse reason — silence is the bug");
+  } finally { cleanup(root); }
+});
+
+test("the staleness ladder degrades on a ramp, not a cliff", () => {
+  const at = (secs) => ({ fetchedAt: new Date(NOW - secs * 1000).toISOString() });
+  assert.equal(stalenessTier(at(3600), NOW), "fresh");
+  assert.equal(stalenessTier(at(TIERS.fresh + 1), NOW), "aging");
+  assert.equal(stalenessTier(at(TIERS.aging + 1), NOW), "stale");
+  assert.equal(stalenessTier(at(TIERS.stale + 1), NOW), "expired");
+  // Never fetched at all is maximally stale, not accidentally fresh.
+  assert.equal(staleSeconds(null, NOW), Infinity);
+  assert.equal(stalenessTier({}, NOW), "expired");
+
+  // The ramp itself: OUTCOME work dies first, REACT last.
+  assert.deepEqual(permissionsForTier("fresh"), { react: "full", schedule: "full", outcome: "full" });
+  assert.equal(permissionsForTier("aging").outcome, "suspended");
+  assert.equal(permissionsForTier("aging").react, "full");
+  assert.equal(permissionsForTier("stale").react, "offline_safe");
+  assert.equal(permissionsForTier("expired").react, "none");
+});
+
+test("adoptedObjectives from the cache admits only active nodes", () => {
+  const rec = { body: { objectives: [{ key: "a", state: "active" }, { key: "b", state: "proposed" }] } };
+  assert.deepEqual(adoptedObjectives(rec).map((o) => o.key), ["a"]);
+  assert.deepEqual(adoptedObjectives(null), []);
+});
+
+test("writeCache round-trips and stamps a checksum over the body", () => {
+  const root = makeRoot();
+  try {
+    const rec = writeCache(root, { version: 7, body: BODY, source: "server" });
+    assert.equal(rec.version, 7);
+    assert.equal(rec.checksum, checksumOf(BODY));
+    const back = readCache(root);
+    assert.deepEqual(back.body, BODY);
+    assert.equal(back.source, "server");
+  } finally { cleanup(root); }
+});
+
+// ---------------------------------------------------------------------------
+// fetchSnapshot — every failure mode is a distinct reason
+// ---------------------------------------------------------------------------
+
+test("fetchSnapshot returns the snapshot on an ok frame", async () => {
+  const seen = [];
+  const r = await fetchSnapshot({
+    memberId: "mem_self",
+    callImpl: async (method, params) => {
+      seen.push({ method, params });
+      return { ok: true, result: { version: 4, checksum: "abc", body: BODY } };
+    },
+  });
+  assert.equal(seen[0].method, GET_METHOD);
+  assert.equal(r.ok, true);
+  assert.equal(r.snapshot.version, 4);
+});
+
+test("SERVER UNREACHABLE: a thrown call is a distinct, reportable reason", async () => {
+  const r = await fetchSnapshot({ callImpl: async () => { throw new Error("ECONNREFUSED"); } });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /^call-threw:/);
+  assert.match(r.reason, /ECONNREFUSED/);
+});
+
+test("a protocol without the mandate family is named exactly, not lumped in with a 404", async () => {
+  const r = await fetchSnapshot({
+    callImpl: async () => ({ ok: false, error: { code: "NOT_FOUND", message: "unknown method mandate.get" } }),
+  });
+  assert.equal(r.reason, "protocol-missing-mandate-family");
+});
+
+test("an ordinary error frame carries its code", async () => {
+  const r = await fetchSnapshot({ callImpl: async () => ({ ok: false, error: { code: "FORBIDDEN" } }) });
+  assert.equal(r.reason, "call-failed:FORBIDDEN");
+});
+
+// ---------------------------------------------------------------------------
+// refreshMandate
+// ---------------------------------------------------------------------------
+
+test("the online path caches the adopted snapshot and reports it changed", async () => {
+  const root = makeRoot();
+  try {
+    const r = await refreshMandate(root, {
+      memberId: "mem_self",
+      now: () => NOW,
+      callImpl: async () => ({ ok: true, result: { version: 4, checksum: checksumOf(BODY), body: BODY } }),
+    });
+    assert.equal(r.ok, true);
+    assert.equal(r.source, "server");
+    assert.equal(r.degraded, false);
+    assert.equal(r.changed, true);
+    assert.equal(r.tier, "fresh");
+    assert.equal(readCache(root).source, "server");
+
+    // A second identical refresh must report NO change, so nothing on disk churns.
+    const again = await refreshMandate(root, {
+      memberId: "mem_self", now: () => NOW,
+      callImpl: async () => ({ ok: true, result: { version: 4, checksum: checksumOf(BODY), body: BODY } }),
+    });
+    assert.equal(again.changed, false);
+  } finally { cleanup(root); }
+});
+
+test("SERVER UNREACHABLE, no prior cache: falls back to the local derivation, degraded and LOUD", async () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    const r = await refreshMandate(root, {
+      memberId: "mem_self",
+      now: () => NOW,
+      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
+      callImpl: async () => { throw new Error("ECONNREFUSED"); },
+      derivation: DERIVATION,
+    });
+    assert.equal(r.ok, true);
+    assert.equal(r.source, "local");
+    assert.equal(r.degraded, true, "a local derivation is ALWAYS degraded — it is proposed, not adopted");
+    assert.ok(r.counts.pillars >= 1);
+    assert.ok(logs.some((l) => l.startsWith("warn:")), "the degradation must be logged, never silent");
+
+    // And critically: everything it derived is PROPOSED, so it drives no work.
+    for (const o of readCache(root).body.objectives) assert.equal(o.state, "proposed");
+  } finally { cleanup(root); }
+});
+
+test("SERVER UNREACHABLE with a prior SERVER snapshot: the adopted mandate is KEPT, not overwritten", async () => {
+  const root = makeRoot();
+  try {
+    // The agent once held a real, adopted mandate.
+    writeCache(root, { version: 4, body: BODY, source: "server" });
+
+    const logs = [];
+    const r = await refreshMandate(root, {
+      memberId: "mem_self",
+      now: () => NOW,
+      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
+      callImpl: async () => { throw new Error("ECONNREFUSED"); },
+      derivation: DERIVATION,
+    });
+
+    assert.equal(r.source, "cache");
+    assert.equal(r.degraded, true);
+    assert.equal(r.changed, false);
+    // The adopted objectives survive the partition intact.
+    const cached = readCache(root);
+    assert.equal(cached.source, "server");
+    assert.deepEqual(cached.body, BODY);
+    assert.equal(cached.body.objectives[1].state, "active");
+    assert.ok(logs.some((l) => /never supersedes adopted/.test(l)));
+  } finally { cleanup(root); }
+});
+
+test("offline:true skips the fetch entirely and derives locally", async () => {
+  const root = makeRoot();
+  try {
+    let called = 0;
+    const r = await refreshMandate(root, {
+      memberId: "mem_self", now: () => NOW, offline: true,
+      callImpl: async () => { called += 1; return { ok: true, result: { body: BODY } }; },
+      derivation: DERIVATION,
+    });
+    assert.equal(called, 0, "offline must not touch the network");
+    assert.equal(r.source, "local");
+    assert.match(r.reason, /offline/);
+  } finally { cleanup(root); }
+});
+
+test("a checksum mismatch is warned about but still cached — the mandate is not lost to a vendoring drift", async () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    const r = await refreshMandate(root, {
+      memberId: "mem_self", now: () => NOW,
+      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
+      callImpl: async () => ({ ok: true, result: { version: 4, checksum: "sha256:not-the-real-one", body: BODY } }),
+    });
+    assert.equal(r.source, "server");
+    assert.ok(logs.some((l) => /checksum mismatch/.test(l)));
+    // The LOCAL checksum is what gets stored, so drift detection stays honest.
+    assert.equal(readCache(root).checksum, checksumOf(BODY));
+  } finally { cleanup(root); }
+});
+
+test("an invalid adopted snapshot is cached but every error is surfaced", async () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    const bad = {
+      memberId: "mem_self",
+      objectives: [
+        // Active, measurable, and adopted by its own owner: the Goodhart hole.
+        {
+          key: "self-graded", kind: "OBJECTIVE", state: "active", metric: "m", target: 1,
+          cadence: "weekly", adoptedById: "mem_self",
+        },
+      ],
+    };
+    const r = await refreshMandate(root, {
+      memberId: "mem_self", now: () => NOW,
+      log: (lvl, msg) => logs.push(`${lvl}:${msg}`),
+      callImpl: async () => ({ ok: true, result: { version: 5, body: bad } }),
+    });
+    assert.equal(r.ok, true);
+    assert.equal(r.validation.ok, false);
+    assert.ok(r.validation.errors.some((e) => /self-adopted/.test(e)));
+    assert.ok(logs.some((l) => /invalid/.test(l)), "an invalid snapshot must be logged, not quietly trusted");
+  } finally { cleanup(root); }
+});
+
+test("a corrupt cache does not block a fresh server refresh", async () => {
+  const root = makeRoot();
+  try {
+    mkdirSync(join(root, "state", "mandate"), { recursive: true });
+    writeFileSync(cachePath(root), "}}}garbage", "utf-8");
+    const r = await refreshMandate(root, {
+      memberId: "mem_self", now: () => NOW,
+      callImpl: async () => ({ ok: true, result: { version: 4, body: BODY } }),
+    });
+    assert.equal(r.source, "server");
+    assert.equal(JSON.parse(readFileSync(cachePath(root), "utf-8")).version, 4);
+  } finally { cleanup(root); }
+});

package/lib/mcp/server.test.mjs

@@ -145,19 +145,19 @@ test("tools/list: full active surface (email tools present — family is vendore
   const r = await h.request("tools/list", {});
   const tools = r.result.tools;
   assert.equal(tools.length, getOrgTools().length, "one MCP tool per active table entry");
-  assert.equal(tools.length, 107, "email + artifact + desk families vendored → 107 tools");
+  assert.equal(tools.length, 108, "email + artifact + desk families vendored → 108 tools");
   const names = tools.map((t) => t.name);
-  for (const expected of ["org_whoami", "org_describe", "org_rpc", "org_read", "messaging_send", "board_ready", "email_send", "email_inbox", "artifact_create", "artifact_act", "artifact_catalog", "email_mailboxes", "email_draft_send", "files_list", "calendar_find_a_time", "crm_list_deals", "books_reports", "meetings_recap_file"]) {
+  for (const expected of ["org_whoami", "org_describe", "org_rpc", "org_read", "messaging_send", "task_assign", "board_ready", "email_send", "email_inbox", "artifact_create", "artifact_act", "artifact_catalog", "email_mailboxes", "email_draft_send", "files_list", "calendar_find_a_time", "crm_list_deals", "books_reports", "meetings_recap_file"]) {
     assert.ok(names.includes(expected), `${expected} listed`);
   }
   assert.ok(tools.every((t) => t.inputSchema && t.inputSchema.type === "object"));
   h.server.stop();
 });
 
-test("tools/list honours the email gate (emailAvailable:false → 102 tools)", async () => {
+test("tools/list honours the email gate (emailAvailable:false → 103 tools)", async () => {
   const h = harness({ emailAvailable: false });
   const r = await h.request("tools/list", {});
-  assert.equal(r.result.tools.length, 102, "the 5 own-mailbox email tools drop out");
+  assert.equal(r.result.tools.length, 103, "the 5 own-mailbox email tools drop out");
   const names = new Set(r.result.tools.map((t) => t.name));
   // The five own-mailbox tools (email:true) are gated out …
   for (const gated of ["email_send", "email_inbox", "email_message", "email_thread", "email_mark_read"]) {

package/lib/org/approvals.mjs

@@ -301,15 +301,27 @@ export async function requestApproval(o = {}) {
   }
 
   const c = configFromAgent(o.cfg);
+  // WIRE CONTRACT (hq `methods/approval/request.ts`): the gated action's class is
+  // `actionClass` and it is REQUIRED — this helper sent `kind`, so hq threw
+  // "actionClass is required" and the whole SDK-side governance gate filed ZERO
+  // approvals. Likewise the digest is `payloadHash` (not `payload_hash`) and the
+  // expiry is an absolute `expiresAt` (not a relative `expiresInMs`).
+  // `requester` is derived server-side from the authenticated actor and is never
+  // read from the body. The legacy names ride along for an older server; the
+  // canonical ones are what hq validates.
   const params = {
     id,
+    actionClass: kind,
     kind,
     subject,
+    payloadHash: payloadHash,
     payload_hash: payloadHash,
-    requester: o.requester || c.orgId || undefined,
   };
   if (o.itemId) params.itemId = String(o.itemId);
-  if (Number.isFinite(o.expiresInMs)) params.expiresInMs = o.expiresInMs;
+  if (Number.isFinite(o.expiresInMs)) {
+    params.expiresAt = new Date(Date.now() + Number(o.expiresInMs)).toISOString();
+    params.expiresInMs = o.expiresInMs;
+  }
 
   const frame = await approvalRequest(params, {
     base: c.base,