@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/lib/mandate/contract.test.mjs

@@ -0,0 +1,185 @@
+/**
+ * lib/mandate/contract.test.mjs — the SDK half of THE MANDATE BODY CONTRACT.
+ *
+ * The break this closes: hq emitted `{memberId, objectives, proposed,
+ * generatedAt}` while `compilePlan` read `{objectives, budgetCentsPerPeriod,
+ * collaborators, reactsTo}`. Three keys were absent, `Number.isFinite(undefined)`
+ * was false, and every obligation in the fleet took a hardcoded 500c allowance
+ * against a hardcoded 10000c envelope — with no error, no log and no drift row.
+ *
+ * The invariant under test, stated once: a MISSING required key is an ERROR (the
+ * body cannot be budgeted from); a key that is PRESENT AND NULL is a WARNING (hq
+ * looked and had nothing). Nothing anywhere may substitute a number for either.
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+
+import {
+  MANDATE_BODY_KEYS,
+  MANDATE_CONTRACT_VERSION,
+  MANDATE_REQUIRED_KEYS,
+  assertMandateContract,
+  bodyOf,
+  validateMandateContract,
+} from "./contract.mjs";
+
+/** A well-formed, FUNDED body in exactly the shape hq publishes. */
+function fundedBody(over = {}) {
+  return {
+    contractVersion: 1,
+    memberId: "mem_self",
+    objectives: [
+      { key: "pipeline", state: "active", weight: 3, budgetCentsPerPeriod: 18_750 },
+      { key: "inbox", state: "active", weight: 1, budgetCentsPerPeriod: 6_250 },
+    ],
+    proposed: [],
+    budgetCentsPerPeriod: null,
+    seatBudgetCents: 25_000,
+    budgetPeriod: "monthly",
+    budgetSource: "employee.payBasis.meteredBudget",
+    collaborators: [{ memberId: "mem_boss", role: "REVIEWER", source: "workforceMember.supervisorId" }],
+    reactsTo: [],
+    degradations: [],
+    generatedAt: "2026-08-11T00:00:00.000Z",
+    ...over,
+  };
+}
+
+test("a funded hq body validates clean and is NOT unmetered", () => {
+  const v = validateMandateContract(fundedBody());
+  assert.equal(v.ok, true);
+  assert.deepEqual(v.missing, []);
+  assert.equal(v.contractVersion, MANDATE_CONTRACT_VERSION);
+  assert.equal(v.unmetered, false);
+  assert.equal(v.errors.length, 0);
+});
+
+test("THE ORIGINAL BREAK: the pre-contract body is an ERROR, not a shrug", () => {
+  // Byte-for-byte the shape hq used to send.
+  const legacy = { memberId: "mem_self", objectives: [], proposed: [], generatedAt: "1970-01-01T00:00:00.000Z" };
+  const v = validateMandateContract(legacy);
+  assert.equal(v.ok, false);
+  for (const k of ["budgetCentsPerPeriod", "seatBudgetCents", "collaborators", "reactsTo", "contractVersion"]) {
+    assert.ok(v.missing.includes(k), `missing names ${k}`);
+  }
+  assert.ok(v.errors.some((e) => /PRE-CONTRACT/.test(e)));
+  assert.equal(v.unmetered, true);
+});
+
+test("PRESENT-AND-NULL is a warning, MISSING is an error — the distinction is the point", () => {
+  const unfunded = validateMandateContract(
+    fundedBody({
+      seatBudgetCents: null,
+      budgetPeriod: null,
+      budgetSource: "none",
+      objectives: [{ key: "pipeline", state: "active", weight: 1, budgetCentsPerPeriod: null }],
+      degradations: [{ field: "seatBudgetCents", reason: "no Employee row is linked to this member" }],
+    })
+  );
+  // Well-formed: the body can be trusted. Just genuinely unfunded.
+  assert.equal(unfunded.ok, true);
+  assert.deepEqual(unfunded.missing, []);
+  assert.equal(unfunded.unmetered, true);
+  assert.ok(unfunded.warnings.some((w) => /seatBudgetCents is null/.test(w)));
+  // hq's own stated reason is echoed, so one log line explains the null.
+  assert.ok(unfunded.warnings.some((w) => /hq degradation — seatBudgetCents/.test(w)));
+
+  // Delete the key instead of nulling it and the verdict flips to untrustworthy.
+  const body = fundedBody();
+  delete body.seatBudgetCents;
+  const gone = validateMandateContract(body);
+  assert.equal(gone.ok, false);
+  assert.deepEqual(gone.missing, ["seatBudgetCents"]);
+});
+
+test("apportionment that exceeds the envelope is an ERROR, not a rounding note", () => {
+  const v = validateMandateContract(
+    fundedBody({ objectives: [{ key: "a", budgetCentsPerPeriod: 20_000 }, { key: "b", budgetCentsPerPeriod: 20_000 }] })
+  );
+  assert.equal(v.ok, false);
+  assert.ok(v.errors.some((e) => /apportioned more than it holds/.test(e)));
+});
+
+test("junk in the budget fields is rejected rather than coerced", () => {
+  for (const bad of ["500", NaN, Infinity, -1, {}]) {
+    const v = validateMandateContract(fundedBody({ seatBudgetCents: bad }));
+    assert.equal(v.ok, false, `seatBudgetCents=${String(bad)} must be rejected`);
+  }
+});
+
+test("a non-object body fails closed instead of throwing", () => {
+  for (const bad of [null, undefined, 42, "body", []]) {
+    const v = validateMandateContract(bad);
+    assert.equal(v.ok, false);
+    assert.equal(v.unmetered, true);
+  }
+});
+
+test("a FUTURE contract version warns but still compiles (forward-compat)", () => {
+  const v = validateMandateContract(fundedBody({ contractVersion: MANDATE_CONTRACT_VERSION + 1 }));
+  assert.equal(v.ok, true);
+  assert.ok(v.warnings.some((w) => /upgrade the SDK/.test(w)));
+});
+
+test("bodyOf unwraps a cache record and passes a bare body through", () => {
+  const body = fundedBody();
+  assert.equal(bodyOf({ body, version: 4 }), body);
+  assert.equal(bodyOf(body), body);
+  assert.equal(bodyOf(null), null);
+  // The cache record shape must validate identically to the bare body.
+  assert.equal(validateMandateContract({ body, version: 4 }).ok, true);
+});
+
+test("assertMandateContract LOGS every error and warning — silence is the bug", () => {
+  const lines = [];
+  const v = assertMandateContract({ memberId: "m" }, (level, msg) => lines.push([level, msg]), "compilePlan");
+  assert.equal(v.ok, false);
+  assert.ok(lines.some(([l]) => l === "error"), "the violation is logged at error");
+  assert.ok(lines.every(([, m]) => m.includes("[compilePlan]")), "every line is tagged with its call site");
+  // It must never throw, whatever it is handed — it runs inside the daemon.
+  assert.doesNotThrow(() => assertMandateContract(undefined));
+  assert.doesNotThrow(() => assertMandateContract({}, "not a function"));
+});
+
+// ---------------------------------------------------------------------------
+// THE CROSS-REPO DRIFT ALARM
+// ---------------------------------------------------------------------------
+
+test("the key lists match hq's _contract.ts literal for literal", { skip: hqContractPath() ? false : "hq checkout not present" }, () => {
+  // The two repos cannot import each other, so the contract is written down
+  // twice — and a shape written down twice drifts unless something compares
+  // them. This reads hq's TypeScript source and diffs the literals. It is the
+  // single mechanical reason this joint cannot silently reopen.
+  const src = readFileSync(hqContractPath(), "utf8");
+
+  const arrayLiteral = (name) => {
+    const m = src.match(new RegExp(`export const ${name} = \\[([^\\]]*)\\]`));
+    assert.ok(m, `hq's _contract.ts declares ${name}`);
+    return m[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+  };
+
+  assert.deepEqual(arrayLiteral("MANDATE_BODY_KEYS"), [...MANDATE_BODY_KEYS], "MANDATE_BODY_KEYS drifted between the repos");
+  assert.deepEqual(arrayLiteral("MANDATE_REQUIRED_KEYS"), [...MANDATE_REQUIRED_KEYS], "MANDATE_REQUIRED_KEYS drifted between the repos");
+
+  const ver = src.match(/export const MANDATE_CONTRACT_VERSION = (\d+)/);
+  assert.ok(ver, "hq declares MANDATE_CONTRACT_VERSION");
+  assert.equal(Number(ver[1]), MANDATE_CONTRACT_VERSION, "the contract VERSION drifted between the repos");
+});
+
+/** hq's contract file, when this checkout sits beside one. */
+function hqContractPath() {
+  const p = `${process.env.HOME}/hq/src/server/methods/mandate/_contract.ts`;
+  return existsSync(p) ? p : null;
+}
+
+test("the required keys are a SUBSET of the body keys (an unreadable key cannot be required)", () => {
+  for (const k of MANDATE_REQUIRED_KEYS) {
+    assert.ok(MANDATE_BODY_KEYS.includes(k), `${k} is required but not in MANDATE_BODY_KEYS`);
+  }
+  assert.deepEqual([...MANDATE_BODY_KEYS], [...MANDATE_BODY_KEYS].slice().sort(), "MANDATE_BODY_KEYS must stay sorted");
+  assert.deepEqual([...MANDATE_REQUIRED_KEYS], [...MANDATE_REQUIRED_KEYS].slice().sort(), "MANDATE_REQUIRED_KEYS must stay sorted");
+});

package/lib/mandate/derive.mjs

@@ -31,6 +31,8 @@
 
 import { createHash } from "node:crypto";
 
+import { MANDATE_CONTRACT_VERSION } from "./contract.mjs";
+
 /** Objective kinds (mirrors hq's ObjectiveKind enum). */
 export const OBJECTIVE_KINDS = Object.freeze(["PILLAR", "OBJECTIVE", "GOAL"]);
 /** Metric directions (mirrors hq's MetricDirection enum). */
@@ -46,8 +48,14 @@ export const CADENCES = Object.freeze(["weekly", "monthly", "quarterly"]);
  * @type {Array<{re:RegExp, caps:string[], params?:object, direction?:string, unit?:string}>}
  */
 export const SENSOR_HINTS = Object.freeze([
-  { re: /(pipeline|deal|bookings|revenue|win rate|arr|mrr)/i, caps: ["crm_list_deals", "crm_next_best_action"], params: { stage: "open" }, unit: "x", direction: "up" },
-  { re: /(runway|burn|cash|invoice|billing|tax|spend|cost)/i, caps: ["books_reports", "books_invoices"], unit: "months", direction: "up" },
+  // `params` here are sent VERBATIM to the capability by lib/kpi-sensors.mjs, so
+  // they must be legal at hq. `{stage:"open"}` was not: crm.listDeals takes a
+  // strict enum (INBOUND|QUALIFIED|PROPOSAL|NEGOTIATION|CLOSED) and answered every
+  // derived pipeline sensor with BAD_REQUEST. Open-ness is a reduction, not a
+  // filter — the sensor computes it from the stage field. Likewise books.reports
+  // REQUIRES `report`, so a hint that omitted it could never execute.
+  { re: /(pipeline|deal|bookings|revenue|win rate|arr|mrr)/i, caps: ["crm_list_deals", "crm_next_best_action"], params: { metric: "open_pipeline_usd" }, unit: "usd", direction: "up" },
+  { re: /(runway|burn|cash|invoice|billing|tax|spend|cost)/i, caps: ["books_reports", "books_invoices"], params: { report: "cashflow" }, unit: "months", direction: "up" },
   { re: /(commitment|action item|follow-?through|closure|backlog|task|execution)/i, caps: ["board_ready", "task_update"], unit: "%", direction: "up" },
   { re: /(decision|governance|approval)/i, caps: ["decision_list", "approval_wait"], unit: "days", direction: "down" },
   { re: /(meeting|calendar|cadence|agenda)/i, caps: ["calendar_list", "meetings_recap_file"], unit: "%", direction: "up" },
@@ -228,16 +236,52 @@ export function deriveMandate(input = {}) {
 }
 
 /**
- * Wrap the derived tree in the mandate BODY shape the cache + compiler consume.
- * @param {object} o - { memberId, objectives, budgetCentsPerPeriod?, collaborators?, reactsTo? }
+ * Wrap the derived tree in the CANONICAL mandate body (lib/mandate/contract.mjs
+ * — the same shape hq publishes, key for key).
+ *
+ * `budgetCentsPerPeriod` used to default to 500 here. It does not any more, and
+ * that is the point: a LOCALLY DERIVED mandate is the offline fallback, and an
+ * offline agent has no way whatsoever to know what it is funded for. Emitting
+ * 500 made "I never asked" indistinguishable from "I asked and was told 500".
+ * Null says the true thing, and `degradations[]` says why — so the plan comes
+ * out unmetered-and-loud instead of budgeted-and-wrong.
+ *
+ * @param {object} o - { memberId, objectives, proposed?, budgetCentsPerPeriod?,
+ *                       seatBudgetCents?, collaborators?, reactsTo?, generatedAt? }
+ * @returns {import("./contract.mjs").MandateBody}
  */
 export function toMandateBody(o = {}) {
+  const budgetCentsPerPeriod = Number.isFinite(o.budgetCentsPerPeriod) ? o.budgetCentsPerPeriod : null;
+  const seatBudgetCents = Number.isFinite(o.seatBudgetCents) ? o.seatBudgetCents : null;
+  const degradations = [];
+  if (budgetCentsPerPeriod == null) {
+    degradations.push({
+      field: "budgetCentsPerPeriod",
+      reason:
+        "derived locally: the agent cannot know its own funding offline, so every " +
+        "obligation compiles unmetered until an adopted snapshot arrives from hq",
+    });
+  }
+  if (seatBudgetCents == null) {
+    degradations.push({
+      field: "seatBudgetCents",
+      reason: "derived locally: no seat envelope is knowable offline",
+    });
+  }
   return {
+    contractVersion: MANDATE_CONTRACT_VERSION,
     memberId: o.memberId || null,
     objectives: Array.isArray(o.objectives) ? o.objectives : [],
-    budgetCentsPerPeriod: Number.isFinite(o.budgetCentsPerPeriod) ? o.budgetCentsPerPeriod : 500,
+    proposed: Array.isArray(o.proposed) ? o.proposed : [],
+    budgetCentsPerPeriod,
+    seatBudgetCents,
+    budgetPeriod: seatBudgetCents == null ? null : "monthly",
+    budgetSource: "local-derivation",
     collaborators: Array.isArray(o.collaborators) ? o.collaborators : [],
     reactsTo: Array.isArray(o.reactsTo) ? o.reactsTo : [],
+    degradations,
+    // From the data, never the clock — the body is checksummed.
+    generatedAt: typeof o.generatedAt === "string" ? o.generatedAt : "1970-01-01T00:00:00.000Z",
   };
 }
 

package/lib/mandate/derive.test.mjs

@@ -194,7 +194,13 @@ test("toMandateBody produces the shape the cache and compiler consume", () => {
   const body = toMandateBody({ memberId: "mem_self", objectives: r.objectives });
   assert.equal(body.memberId, "mem_self");
   assert.ok(Array.isArray(body.objectives));
-  assert.equal(typeof body.budgetCentsPerPeriod, "number");
+  // NOT a number. A locally-derived body is the OFFLINE fallback, and an offline
+  // agent cannot know what it is funded for. This assertion used to demand a
+  // number and got the hardcoded 500 that made "I never asked" look exactly like
+  // "I asked and was told 500". Null is the true answer, and it must be PRESENT.
+  assert.ok(Object.prototype.hasOwnProperty.call(body, "budgetCentsPerPeriod"));
+  assert.equal(body.budgetCentsPerPeriod, null);
+  assert.ok(body.degradations.some((d) => d.field === "budgetCentsPerPeriod"));
   assert.ok(Array.isArray(body.reactsTo));
   // And it must round-trip through the validator the loop uses.
   assert.equal(validateMandateBody(body).ok, true);

package/lib/mandate/model.mjs

@@ -226,7 +226,16 @@ export function collaboratorsOf(objective) {
     const memberId = typeof c === "string" ? c : c.memberId || c.member_id || c.id;
     if (!memberId) continue;
     const role = String((typeof c === "object" && (c.role || c.kind)) || "CONTRIBUTOR").toUpperCase();
-    out.push({ memberId: String(memberId), role });
+    // `source` is hq's own provenance label for the edge and it is NOT
+    // decoration: `src/server/methods/mandate/_shared.ts#projectObjective`
+    // stamps "objective.adoptedById" on the APPROVER it synthesises from the
+    // adopter, and "workforceMember.supervisorId" on the seat-level REVIEWER.
+    // Dropping it here erased the only way a consumer could tell a DERIVED
+    // governance edge from a deliberately-named per-task reviewer — which is
+    // exactly what made `classifyWorkItem` rule 4 fire on every single
+    // candidate (see the note there).
+    const source = typeof c === "object" && c.source ? String(c.source) : null;
+    out.push({ memberId: String(memberId), role, source });
   }
   return out;
 }

package/lib/mandate/model.test.mjs

@@ -133,12 +133,31 @@ test("buildTree nests children and surfaces orphans as roots rather than droppin
 
 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" },
+    { memberId: "m1", role: "CONTRIBUTOR", source: null },
+    { memberId: "m2", role: "REVIEWER", source: null },
+    { memberId: "m3", role: "CONTRIBUTOR", source: null },
   ]);
 });
 
+test("collaboratorsOf PRESERVES hq's provenance `source` on the edge", () => {
+  // hq's projectObjective stamps this, and goals/classify.mjs is the consumer:
+  // an APPROVER derived from `objective.adoptedById` is a standing governance
+  // edge, not per-task sign-off. Dropping `source` made every self-directed
+  // candidate classify NEEDS_REVIEW.
+  assert.deepEqual(
+    collaboratorsOf({
+      collaborators: [
+        { memberId: "boss", role: "APPROVER", source: "objective.adoptedById" },
+        { memberId: "peer", role: "REVIEWER" },
+      ],
+    }),
+    [
+      { memberId: "boss", role: "APPROVER", source: "objective.adoptedById" },
+      { memberId: "peer", role: "REVIEWER", source: null },
+    ]
+  );
+});
+
 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

@@ -28,14 +28,28 @@
 "use strict";
 
 import { readCache, writeCache, stalenessTier, checksumOf } from "./cache.mjs";
+import { assertMandateContract } from "./contract.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";
 
+/**
+ * The degradation logger. Defaults to the CONSOLE, not to a no-op.
+ *
+ * `() => {}` was the default here, which meant any caller that forgot `deps.log`
+ * — and `refreshMandate` is called from the daemon, from setup, and from tests —
+ * silently discarded every contract violation and every fallback notice. That is
+ * the same failure class as an empty `catch {}`: the code is correct, reports
+ * honestly, and nobody ever hears it. Fail-open is fine; silent is not.
+ */
 function logOf(deps) {
-  return deps && typeof deps.log === "function" ? deps.log : () => {};
+  if (deps && typeof deps.log === "function") return deps.log;
+  return (level, msg) => {
+    try { (level === "error" ? console.error : console.warn)(msg); }
+    catch { /* logging may never throw into the refresh path */ }
+  };
 }
 
 /**
@@ -61,7 +75,27 @@ export async function fetchSnapshot(deps = {}) {
   }
   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" };
+    // `mandate.get` answers "this seat has NOTHING adopted" with an ok frame
+    // carrying `body: null, version: 0` — deliberately, so a brand-new seat's
+    // first beat is not a 404 (hq src/server/methods/mandate/get.ts).
+    //
+    // `body: r.body || r` read that as a hit and cached the RPC ENVELOPE
+    // ({memberId, version, checksum, body:null, publishedAt, publishedById}) as
+    // the mandate body, with `source:"server"`. Two consequences, both silent
+    // until you look: the body carries zero objectives, and `refreshMandate`
+    // then refuses forever to let the local derivation supersede it ("adopted
+    // beats proposed") — so the cache is pinned to an empty mandate that no
+    // amount of re-derivation can dislodge. Verified live against
+    // os.cohortapp.com for member cmqh0tcml004ihhl6zev6ocb5.
+    //
+    // An unadopted seat is a REPORTABLE ABSENCE, not a fetch. The caller falls
+    // through to the local derivation, which is exactly the pre-adoption
+    // posture: every objective `state:'proposed'`, no obligations, no backlog.
+    const body = r.body;
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+      return { ok: false, snapshot: null, reason: "no-adopted-mandate" };
+    }
+    return { ok: true, snapshot: { version: Number(r.version) || 0, checksum: r.checksum || null, body }, reason: "fetched" };
   }
   const code = (frame && frame.error && frame.error.code) || "unknown";
   const msg = (frame && frame.error && frame.error.message) || "";
@@ -109,13 +143,25 @@ export async function refreshMandate(agentRoot, deps = {}) {
         { version: got.snapshot.version, checksum: local, body, source: "server" },
         { now: deps.now ? () => new Date(deps.now()).toISOString() : undefined }
       );
+      // TWO checks, and they answer different questions. `validateMandateBody`
+      // asks "is the objective TREE sound?"; `assertMandateContract` asks "does
+      // this body carry the keys the compiler reads at all?" — the second is the
+      // one that was missing, which is how a body with three absent keys sailed
+      // through as valid and the plan then ran on invented money.
+      const contract = assertMandateContract(record, log, "mandate.get");
       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",
+        // A body whose contract is broken is still cached (adopted objectives
+        // beat nothing), but the caller is told it is degraded rather than being
+        // handed a clean-looking record it cannot budget from.
+        degraded: !contract.ok,
+        contract,
+        reason: contract.ok
+          ? "fetched the adopted snapshot"
+          : `fetched the adopted snapshot, but it violates mandate contract v1 (missing: ${contract.missing.join(", ") || "n/a"})`,
         changed: record.checksum !== prevChecksum,
         tier: stalenessTier(record, deps.now ? deps.now() : Date.now()),
         record,
@@ -126,7 +172,9 @@ export async function refreshMandate(agentRoot, deps = {}) {
       "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`
+        : got.reason === "no-adopted-mandate"
+          ? "[mandate] hq answered mandate.get with an EMPTY snapshot (version 0, body null): this seat has nothing adopted. Falling back to the local derivation — every objective stays `proposed`, which compiles no obligations and admits no backlog. The goal-steward loop will measure nothing and create nothing until a human adopts objectives for this seat in hq."
+          : `[mandate] could not fetch the adopted snapshot (${got.reason}) — falling back to the local derivation`
     );
   }
 

package/lib/mandate/refresh.test.mjs

@@ -32,18 +32,39 @@ function cleanup(root) {
   try { rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
 }
 
+/**
+ * A body in the shape hq ACTUALLY publishes — contract v1, every key the
+ * compiler reads present, budgets sourced and apportioned. This fixture used to
+ * carry only `{memberId, objectives}`, which is precisely the pre-contract shape
+ * that let `budgetCentsPerPeriod` be `undefined` all the way into the compiler.
+ * Keep it in sync with hq's `_contract.ts#MANDATE_BODY_KEYS`.
+ */
 const BODY = {
+  contractVersion: 1,
   memberId: "mem_self",
   objectives: [
-    { key: "revenue", kind: "PILLAR", state: "active", charterSectionId: "cs_1", adoptedById: "mem_boss" },
+    { key: "revenue", kind: "PILLAR", state: "active", charterSectionId: "cs_1", adoptedById: "mem_boss", budgetCentsPerPeriod: null },
     {
       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",
+      weight: 1, budgetCentsPerPeriod: 25_000,
     },
   ],
+  proposed: [],
+  budgetCentsPerPeriod: null,
+  seatBudgetCents: 25_000,
+  budgetPeriod: "monthly",
+  budgetSource: "employee.payBasis.meteredBudget",
+  collaborators: [{ memberId: "mem_boss", role: "REVIEWER", source: "workforceMember.supervisorId" }],
+  reactsTo: [],
+  degradations: [],
+  generatedAt: "2026-08-11T00:00:00.000Z",
 };
 
+/** The shape hq sent BEFORE the contract. Kept to prove it is now caught. */
+const LEGACY_BODY = { memberId: "mem_self", objectives: BODY.objectives, proposed: [], generatedAt: BODY.generatedAt };
+
 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"] }],
@@ -172,6 +193,34 @@ test("the online path caches the adopted snapshot and reports it changed", async
   } finally { cleanup(root); }
 });
 
+test("a PRE-CONTRACT snapshot is cached but reported DEGRADED and LOUD", async () => {
+  // The original break: hq sent this exact shape, `refreshMandate` reported
+  // `degraded:false, reason:"fetched the adopted snapshot"`, and the compiler
+  // then invented 500c for every obligation. Adopted objectives still beat
+  // nothing, so it is still cached — but it may never look clean again.
+  const root = makeRoot();
+  const logs = [];
+  try {
+    const r = await refreshMandate(root, {
+      memberId: "mem_self",
+      now: () => NOW,
+      log: (level, msg) => logs.push(`${level}: ${msg}`),
+      callImpl: async () => ({ ok: true, result: { version: 4, checksum: checksumOf(LEGACY_BODY), body: LEGACY_BODY } }),
+    });
+    assert.equal(r.ok, true);
+    assert.equal(r.source, "server");
+    assert.equal(r.degraded, true, "a body the compiler cannot budget from is degraded");
+    assert.equal(r.contract.ok, false);
+    for (const k of ["budgetCentsPerPeriod", "seatBudgetCents", "collaborators", "reactsTo", "contractVersion"]) {
+      assert.ok(r.contract.missing.includes(k), `contract.missing names ${k}`);
+    }
+    assert.match(r.reason, /violates mandate contract v1/);
+    // Still cached — the adopted tree is worth more than nothing.
+    assert.equal(readCache(root).source, "server");
+    assert.ok(logs.some((l) => l.startsWith("error:")), "the violation is logged, not swallowed");
+  } finally { cleanup(root); }
+});
+
 test("SERVER UNREACHABLE, no prior cache: falls back to the local derivation, degraded and LOUD", async () => {
   const root = makeRoot();
   try {
@@ -291,3 +340,36 @@ test("a corrupt cache does not block a fresh server refresh", async () => {
     assert.equal(JSON.parse(readFileSync(cachePath(root), "utf-8")).version, 4);
   } finally { cleanup(root); }
 });
+
+test("REGRESSION — hq's 'nothing adopted' answer must NOT be cached as a server snapshot", async () => {
+  // mandate.get answers an unadopted seat with {version:0, checksum:null,
+  // body:null} BY DESIGN (hq src/server/methods/mandate/get.ts). `body: r.body || r`
+  // read that as a hit and cached the RPC ENVELOPE as the mandate body with
+  // source:"server" — after which "a local derivation never supersedes a server
+  // snapshot" pinned the seat to an empty mandate permanently. Verified live
+  // against os.cohortapp.com.
+  const root = makeRoot();
+  try {
+    const r = await refreshMandate(root, {
+      memberId: "mem_self",
+      now: () => NOW,
+      log: () => {},
+      callImpl: async () => ({
+        ok: true,
+        result: { memberId: "mem_self", version: 0, checksum: null, body: null, publishedAt: null, publishedById: null },
+      }),
+    });
+    assert.notEqual(r.source, "server", "an empty snapshot is an absence, not a fetch");
+    assert.equal(r.source, "local");
+    const cached = JSON.parse(readFileSync(cachePath(root), "utf-8"));
+    assert.equal(cached.source, "local");
+    assert.ok(Array.isArray(cached.body.objectives), "the cached body is a real mandate body, not the RPC envelope");
+    assert.equal(cached.body.publishedAt, undefined, "the envelope's own keys never leaked into the body");
+  } finally { cleanup(root); }
+});
+
+test("fetchSnapshot names the empty-snapshot case distinctly", async () => {
+  const got = await fetchSnapshot({ callImpl: async () => ({ ok: true, result: { version: 0, body: null } }) });
+  assert.equal(got.ok, false);
+  assert.equal(got.reason, "no-adopted-mandate");
+});

package/lib/org/doctor.mjs

@@ -80,6 +80,65 @@ function identityHints(agentRoot, env) {
   return hints;
 }
 
+/**
+ * LOCAL probe: is the reactive lane in this agent repo actually wired?
+ *
+ * An agent repo carries its OWN copy of the framework (`lib/**` and
+ * `scripts/daemon/**`), copied in at enrolment and refreshed on upgrade. Those
+ * two trees can drift apart, and when they do the failure is completely silent:
+ *
+ *   `scripts/daemon/maestro-daemon.mjs` resolves `./agent-daemon.mjs` from the
+ *   AGENT's own directory. If that copy predates the execution ladder, then
+ *   `processItem` never calls `runExecutionLadder`, and `lib/execution/**` —
+ *   which the same repo may well be carrying, current — is dead code. Every
+ *   inbound event still gets classified and answered, so the agent LOOKS
+ *   healthy; what is missing is the entire decision spine: no directedness
+ *   journal, no obligation binding, no rung, no drift record, nothing written
+ *   to `state/execution/journal.jsonl`. Observed live on a real seat
+ *   (2026-08-11): the wide inbound was current to within one ledger row, and
+ *   the execution journal had not a single row from the daemon itself.
+ *
+ * Nothing else can catch this. The new build cannot warn about the old one, and
+ * the old one does not know the ladder exists — so the check has to be made
+ * from `lib/`, which is the half that gets refreshed.
+ *
+ * Pure + injectable; never throws.
+ *
+ * @param {string} agentRoot
+ * @param {object} [deps]  {existsSync, readFileSync} for tests
+ * @returns {{level:"ok"|"warn"|"fail", msg:string}|null} null when not applicable
+ */
+export function checkReactiveLaneWiring(agentRoot, deps = {}) {
+  const _exists = deps.existsSync || existsSync;
+  const _read = deps.readFileSync || readFileSync;
+  const daemonPath = join(agentRoot, "scripts", "daemon", "agent-daemon.mjs");
+  const pipelinePath = join(agentRoot, "lib", "execution", "pipeline.mjs");
+  try {
+    // Not an agent repo layout (running from the framework checkout, or a
+    // partial install) — nothing to say.
+    if (!_exists(daemonPath) || !_exists(pipelinePath)) return null;
+    const src = String(_read(daemonPath, "utf8"));
+    if (src.includes("runExecutionLadder")) {
+      return { level: "ok", msg: "Reactive lane: the daemon runs inbound events through the execution ladder" };
+    }
+    return {
+      level: "fail",
+      msg:
+        "Reactive lane: scripts/daemon/agent-daemon.mjs in THIS repo never calls runExecutionLadder, but " +
+        "lib/execution/ is present and current — the ladder is dead code here. Inbound events are still " +
+        "classified and answered, but intake/obligation-match/rung/journal DO NOT RUN and " +
+        "state/execution/journal.jsonl will stay empty. The daemon copy is stale: re-run the framework " +
+        "upgrade so scripts/daemon/ is refreshed alongside lib/.",
+    };
+  } catch (err) {
+    // Fail-open, never silent — a doctor probe must not take doctor down.
+    return {
+      level: "warn",
+      msg: `Reactive lane: could not read ${daemonPath} to check ladder wiring (${err && err.message ? err.message : String(err)})`,
+    };
+  }
+}
+
 /**
  * Run the Cohort connectivity probes.
  * @param {object} o
@@ -87,6 +146,7 @@ function identityHints(agentRoot, env) {
  * @param {Function} [o.fetchImpl]  injectable fetch (tests)
  * @param {object} [o.env]          injectable env (tests; default process.env)
  * @param {() => number} [o.now]    injectable clock for latency (tests)
+ * @param {object} [o.fs]           injectable {existsSync, readFileSync} (tests)
  * @returns {Promise<Array<{level:"ok"|"warn"|"fail", msg:string}>>}
  */
 export async function checkOrgConnectivity(o = {}) {
@@ -95,6 +155,12 @@ export async function checkOrgConnectivity(o = {}) {
   const now = typeof o.now === "function" ? o.now : Date.now;
   const results = [];
 
+  // ── 0. LOCAL: is the decision spine wired in this repo? ──────────────────
+  // Runs before the network probes and before the not-enrolled early return:
+  // a stale daemon is worth reporting even on an agent that never enrolled.
+  const wiring = checkReactiveLaneWiring(agentRoot, o.fs || {});
+  if (wiring) results.push(wiring);
+
   // ── 1. config resolution ─────────────────────────────────────────────────
   const cfg = configFromAgent(loadOrgConfig(agentRoot));
   const base = cfg.base || (env.COHORT_BASE ? String(env.COHORT_BASE).replace(/\/+$/, "") : "");