@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/lib/execution/surface-policy.mjs

@@ -38,6 +38,20 @@
  *                   this surface — approvals and decisions land as `escalate`
  *                   even when the payload names the agent as the approver. This
  *                   is the same anti-self-grading law as `mandate.adopt`.
+ *   `escalationOptions`
+ *                   The concrete ways a `selfApprove:false` escalation can go,
+ *                   for surfaces where they are STRUCTURALLY KNOWN rather than
+ *                   situational. Required, in practice, by the thing on the far
+ *                   end: hq's `escalation.ask` refuses fewer than two options
+ *                   ("a question with fewer is a message, not a decision"), and
+ *                   nothing supplies `facts.ambiguousOptions` for an approval —
+ *                   the daemon has no way to invent them and no reason to,
+ *                   because an approval can only ever be approved, rejected or
+ *                   held. Without this column the ladder decided `escalate` and
+ *                   the effect then had nothing to ask, so the escalation lane
+ *                   produced nothing at all. Omitted where the options really do
+ *                   depend on the situation; `facts.ambiguousOptions` still wins
+ *                   over it when a caller knows better.
  *   `maxChainDepth` How many consecutive agent turns are allowed in one thread
  *                   before the ladder calls it a ping-pong loop and stops. Lower
  *                   for broadcast surfaces (a space) than for a private DM.
@@ -148,6 +162,13 @@ export const ORG_SURFACE_POLICY = Object.freeze({
   call: Object.freeze({
     respondable: false,
     replyMethod: null,
+    // The two verbs the row above describes in prose, as data. Read ONLY as a
+    // fallback when neither the router nor a compiled obligation named a method
+    // (see `effects.usesFor`), and used ONLY to furnish the queue row — it does
+    // not feed `need.methods`, so it moves no rung. Without it a live huddle
+    // (`calling/start` seq 8194) queued a row whose `uses` was empty: the drain
+    // was handed a call id and left to guess what one does with it.
+    queueUses: Object.freeze(["calling.getDetails", "calling.join"]),
     latency: "now",
     actionClasses: Object.freeze([]),
     offlineSafe: false,
@@ -222,6 +243,11 @@ export const ORG_SURFACE_POLICY = Object.freeze({
     actionClasses: Object.freeze(["irreversible"]),
     offlineSafe: false,
     selfApprove: false,
+    escalationOptions: Object.freeze([
+      "approve it",
+      "reject it",
+      "hold it — I need more context first",
+    ]),
     maxChainDepth: 1,
     ambientDrop: true,
   }),
@@ -233,6 +259,11 @@ export const ORG_SURFACE_POLICY = Object.freeze({
     actionClasses: Object.freeze(["irreversible"]),
     offlineSafe: false,
     selfApprove: false,
+    escalationOptions: Object.freeze([
+      "adopt it as proposed",
+      "request an adjustment",
+      "reject it",
+    ]),
     maxChainDepth: 1,
     ambientDrop: true,
   }),
@@ -263,6 +294,47 @@ export const ORG_SURFACE_POLICY = Object.freeze({
     ambientDrop: true,
   }),
 
+  // ── calendar ────────────────────────────────────────────────────────────
+  /**
+   * ADOPTED 2026-08 (JOINT 3). This row lived in EXTENDED_SURFACE_POLICY while
+   * `directedness.classifyEvent` had no `calendar` branch. It now has one, and
+   * `SURFACES.calendar` ships, so the row moves here — which is exactly what
+   * the `adoptedExtendedSurfaces` drift guard exists to force.
+   *
+   * A meeting invite / reschedule / cancellation naming me as an attendee. Not
+   * respondable: the answer is an RSVP (`calendar.rsvp`), not a sentence. It is
+   * `now` latency because a 9am invite answered on tomorrow's batch tick is a
+   * missed meeting, and NOT offline-safe because accepting commits the
+   * principal's time — and `calendar.write` queues real invite/update/cancel
+   * mail, which leaves the org.
+   */
+  calendar: Object.freeze({
+    // `replyMethod` is null because it is null for every non-respondable row:
+    // it names the method a CONVERSATIONAL reply would use, and an RSVP is an
+    // action the ladder routes, not a turn in a conversation. The routing hint
+    // lives on the obligation's `uses[]`, where it belongs.
+    respondable: false,
+    replyMethod: null,
+    // …EXCEPT that an un-adopted agent has no compiled plan, so there is no
+    // obligation and therefore no `uses[]`. That is the common case, not the
+    // exotic one: a live seat with no `config/plan.yaml` queued a real invite
+    // with `action.method: null`, and the row it wrote said only "Handle the
+    // calendar event calendar.calendar#8261" — no meeting id, no method. The
+    // session that drains it cannot RSVP something it cannot name.
+    //
+    // `queueUses` is the FALLBACK, never the override: it is read only when
+    // nothing else named a method, and only to furnish the queue row. It does
+    // NOT feed `need.methods`, so it cannot move a rung — the blast-radius and
+    // approval gates decide exactly as before.
+    queueUses: Object.freeze(["calendar.rsvp"]),
+    latency: "now",
+    actionClasses: Object.freeze(["external"]),
+    offlineSafe: false,
+    selfApprove: true,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+
   // ── outside the org ─────────────────────────────────────────────────────
   /**
    * Inbound email. The only default surface whose reply LEAVES the org, so it
@@ -284,13 +356,12 @@ export const ORG_SURFACE_POLICY = Object.freeze({
 /**
  * Surfaces this layer decides for that the org inbound table does NOT name yet.
  *
- * Three of them exist, and each is a real event class that reaches an agent
- * today with no policy at all:
+ * Two of them exist, and each is a real event class that reaches an agent
+ * today with no policy at all. (`calendar` used to be the third; JOINT 3 gave
+ * `directedness.classifyEvent` a `calendar` branch and `SURFACES` a `calendar`
+ * entry, the drift guard fired, and its row MOVED into ORG_SURFACE_POLICY — the
+ * mechanism working as designed rather than two definitions accumulating.)
  *
- *   `calendar` the protocol ships nine `calendar.*` methods and hq's classifier
- *              gains a `calendar` topic (SPEC §3), but `directedness.classifyEvent`
- *              has no `calendar` branch — an invite where I am an attendee is
- *              currently policy-less.
  *   `alert`    a LOCAL fact, not an org event: `lib/diagnostics/alerts.mjs` and
  *              `lib/telemetry/alerts.mjs` derive `{id, severity, detail}` records
  *              that have never had a route to a decision — they were emitted to a
@@ -300,33 +371,12 @@ export const ORG_SURFACE_POLICY = Object.freeze({
  *
  * Kept in a SEPARATE table rather than merged into the literal above so the
  * "every org surface has a row" coverage assertion stays exact, and so the day
- * the parallel inbound workflow adds `calendar` to `SURFACES` the drift guard
+ * the inbound layer adopts one of these the drift guard
  * {@link adoptedExtendedSurfaces} fires and someone MOVES the row instead of
- * quietly ending up with two definitions of the same surface.
+ * quietly ending up with two definitions of the same surface. That is precisely
+ * how `calendar` left this table.
  */
 export const EXTENDED_SURFACE_POLICY = Object.freeze({
-  /**
-   * A meeting invite / reschedule / cancellation naming me as an attendee. Not
-   * respondable: the answer is an RSVP (`calendar.rsvp`), not a sentence. It is
-   * `now` latency because a 9am invite answered on tomorrow's batch tick is a
-   * missed meeting, and NOT offline-safe because accepting commits the
-   * principal's time — and `calendar.write` queues real invite/update/cancel
-   * mail, which leaves the org.
-   */
-  calendar: Object.freeze({
-    // `replyMethod` is null because it is null for every non-respondable row:
-    // it names the method a CONVERSATIONAL reply would use, and an RSVP is an
-    // action the ladder routes, not a turn in a conversation. The routing hint
-    // lives on the obligation's `uses[]`, where it belongs.
-    respondable: false,
-    replyMethod: null,
-    latency: "now",
-    actionClasses: Object.freeze(["external"]),
-    offlineSafe: false,
-    selfApprove: true,
-    maxChainDepth: 1,
-    ambientDrop: true,
-  }),
   /**
    * A local health / budget / freshness alert about this agent. `offlineSafe` is
    * TRUE and deliberately so: a partition is exactly when alerts matter, and an

package/lib/goals/classify.mjs

@@ -54,6 +54,41 @@ function otherRoles(list, me, roleSet) {
   return list.filter((c) => roleSet.has(c.role) && c.memberId && c.memberId !== me);
 }
 
+/**
+ * Collaborator edges hq DERIVES from org structure rather than from anyone
+ * naming a reviewer for this work.
+ *
+ * ── WHY THIS SET EXISTS (a live, universal misroute) ──
+ * `mandate.adopt` enforces the anti-Goodhart law: the adopter can never be the
+ * objective's owner. `projectObjective` then emits that adopter as
+ * `{role:"APPROVER", source:"objective.adoptedById"}` on EVERY adopted
+ * objective. Rule 4 below ("a named APPROVER means the output needs a signature
+ * before it executes") therefore fired on **every candidate the goal steward
+ * has ever produced from a real hq mandate** — 100% of self-directed work
+ * classified NEEDS_REVIEW and went out for signature. Confirmed end-to-end
+ * against the adopted-snapshot wire shape.
+ *
+ * Adopting an objective is standing sign-off on the NUMBER, not per-task
+ * sign-off on every action taken to move it. The thing that genuinely needs a
+ * signature before execution is a gated action class (external / irreversible /
+ * financial), and that check is untouched. A human who wants per-task review
+ * says so by naming a reviewer — an edge with no derived `source`, or a
+ * `reviewBy` — and that still routes to NEEDS_REVIEW.
+ *
+ * These seats stay in `approvers[]`/`reviewers[]` regardless, so when a gate DOES
+ * fire, `goals/collaborate.routeNeedsReview` still has a real person to send it
+ * to. They just no longer MANUFACTURE the gate.
+ */
+const DERIVED_GOVERNANCE_SOURCES = new Set([
+  "objective.adoptedById",
+  "workforceMember.supervisorId",
+]);
+
+/** True when this edge was named for the work, not inferred from org structure. */
+function isNamedForTheWork(c) {
+  return !(c && c.source && DERIVED_GOVERNANCE_SOURCES.has(String(c.source)));
+}
+
 /**
  * Which of the candidate's required capabilities this seat cannot reach, and
  * which peer (if any) declares each. Pure.
@@ -163,24 +198,33 @@ export function classifyWorkItem(candidate = {}, ctx = {}) {
   // 4 — blast radius or a named APPROVER: the output needs a signature BEFORE it
   //     executes. Approval outranks collaboration; a gated action that is also
   //     collaborative is still gated.
-  if (gated.length > 0 || approvers.length > 0) {
+  // Only an edge someone NAMED for this work manufactures a review gate; a
+  // derived governance edge (the objective's adopter, this seat's supervisor)
+  // does not. See DERIVED_GOVERNANCE_SOURCES.
+  const namedApprovers = approvers.filter(isNamedForTheWork);
+  const namedReviewers = reviewers.filter(isNamedForTheWork);
+
+  if (gated.length > 0 || namedApprovers.length > 0) {
     why.push(
       gated.length
         ? `action classes ${gated.join("+")} are gated`
-        : `collaborator ${approvers[0].memberId} carries role APPROVER`
+        : `collaborator ${namedApprovers[0].memberId} carries role APPROVER`
     );
     return {
       ...base,
       disposition: "NEEDS_REVIEW",
       reason: gated.length ? "gated-action-class" : "collaborator-is-approver",
-      target: approvers.length ? approvers[0].memberId : null,
+      // A gated class still routes to the objective's adopter when that is the
+      // only approver on file — the derived edge is a fallback TARGET, never a
+      // trigger.
+      target: (namedApprovers[0] || approvers[0] || {}).memberId || null,
     };
   }
 
   // 5 — a named reviewer (candidate- or objective-level).
   const reviewBy = candidate.reviewBy || (ctx.objective && ctx.objective.reviewBy) || null;
-  if (reviewers.length > 0 || (reviewBy && reviewBy !== me)) {
-    const target = reviewers.length ? reviewers[0].memberId : reviewBy;
+  if (namedReviewers.length > 0 || (reviewBy && reviewBy !== me)) {
+    const target = namedReviewers.length ? namedReviewers[0].memberId : reviewBy;
     why.push(`review required by ${target}`);
     return { ...base, disposition: "NEEDS_REVIEW", reason: "review-required", target };
   }

package/lib/goals/classify.test.mjs

@@ -107,3 +107,61 @@ test("capabilityGaps splits missing into peer-covered and uncovered, determinist
   assert.deepEqual(g.coveredByPeer, [{ capability: "b", memberId: "p1" }, { capability: "c", memberId: "p2" }]);
   assert.deepEqual(g.uncovered, []);
 });
+
+// ---------------------------------------------------------------------------
+// The derived-governance-edge regression (found end-to-end, 2026-08-11)
+// ---------------------------------------------------------------------------
+
+test("REGRESSION — an objective's ADOPTER does not by itself force NEEDS_REVIEW", () => {
+  // hq's mandate.adopt refuses self-adoption, and projectObjective then emits the
+  // adopter as {role:"APPROVER", source:"objective.adoptedById"} on EVERY adopted
+  // objective. Rule 4 fired on it, so 100% of goal-steward candidates went out
+  // for signature and none was ever done SELF. Adopting the NUMBER is not
+  // per-task sign-off on the actions taken to move it.
+  const objective = {
+    key: "board-on-time-delivery",
+    collaborators: [{ memberId: "boss", role: "APPROVER", source: "objective.adoptedById" }],
+  };
+  const c = classifyWorkItem({ title: "Close the gap" }, { memberId: "me", objective, reachable: [] });
+  assert.equal(c.disposition, "SELF");
+  assert.equal(c.reason, "self");
+  // The edge is not discarded — it is still on file as an approver.
+  assert.deepEqual(c.approvers, ["boss"]);
+});
+
+test("REGRESSION — the seat's SUPERVISOR does not force NEEDS_REVIEW either", () => {
+  const c = classifyWorkItem(
+    { title: "Close the gap" },
+    {
+      memberId: "me",
+      objective: { collaborators: [{ memberId: "boss", role: "REVIEWER", source: "workforceMember.supervisorId" }] },
+      reachable: [],
+    }
+  );
+  assert.equal(c.disposition, "SELF");
+  assert.deepEqual(c.reviewers, ["boss"]);
+});
+
+test("a DELIBERATELY named reviewer (no derived source) still routes to NEEDS_REVIEW", () => {
+  const c = classifyWorkItem(
+    { title: "Close the gap", collaborators: [{ memberId: "peer", role: "REVIEWER" }] },
+    { memberId: "me", reachable: [] }
+  );
+  assert.equal(c.disposition, "NEEDS_REVIEW");
+  assert.equal(c.reason, "review-required");
+  assert.equal(c.target, "peer");
+});
+
+test("a GATED action class still gates — and falls back to the adopter as the target", () => {
+  const c = classifyWorkItem(
+    { title: "Wire the payment", actionClasses: ["financial"] },
+    {
+      memberId: "me",
+      objective: { collaborators: [{ memberId: "boss", role: "APPROVER", source: "objective.adoptedById" }] },
+      reachable: [],
+    }
+  );
+  assert.equal(c.disposition, "NEEDS_REVIEW");
+  assert.equal(c.reason, "gated-action-class");
+  assert.equal(c.target, "boss", "the derived edge is a fallback TARGET, never a trigger");
+});

package/lib/goals/collaborate.mjs

@@ -54,9 +54,73 @@ export function workResourceId(objectiveKey, title) {
 // Lazily-resolved defaults (so a test can inject everything and touch no I/O)
 // ---------------------------------------------------------------------------
 
+/**
+ * The org connection for this seat.
+ *
+ * THE BUG THIS EXISTS TO KILL: every default primitive here took `base`/`token`
+ * off `deps`, and NOTHING ever put them there — `runGoalSteward`'s deps carry the
+ * agent root, the clock and the sensors, not a credential. So `client.call`
+ * returned `{ok:false, BAD_REQUEST, "missing base"}` and the callers logged only
+ * the CODE, never the message. Every board item, handoff, approval and escalation
+ * the goal loop has ever produced died on this machine, and the log line
+ * ("board.create failed: BAD_REQUEST — the local backlog item still stands")
+ * read exactly like a server-side rejection. Resolve it the same way every other
+ * plane does: env first, `config/org.yaml` second, explicit deps win.
+ *
+ * @param {object} deps @returns {{base:string, token:string, orgId:string}}
+ */
+async function orgConn(deps = {}) {
+  if (deps.base && deps.token) return { base: deps.base, token: deps.token, orgId: deps.orgId };
+  let resolved = { base: "", token: "", orgId: "" };
+  try {
+    const { resolveOrgToolConfig } = await import("../org/tool-surface.mjs");
+    resolved = resolveOrgToolConfig({ agentRoot: deps.agentRoot, orgConfig: deps.cfg });
+  } catch (err) {
+    logOf(deps)("warn", `[goals] could not resolve the org connection (${err && err.message ? err.message : err}) — org writes will fail locally`);
+  }
+  const conn = {
+    base: deps.base || resolved.base || "",
+    token: deps.token || resolved.token || "",
+    orgId: deps.orgId || resolved.orgId || "",
+  };
+  if (!conn.base || !conn.token) {
+    logOf(deps)(
+      "warn",
+      `[goals] no org credential for this seat (base=${conn.base ? "set" : "MISSING"} token=${conn.token ? "set" : "MISSING"}) — the work stays in the local queue and is invisible on the board`,
+    );
+  }
+  return conn;
+}
+
+/**
+ * Post the board payload to the RIGHT method.
+ *
+ * `lib/org/board.createItem` calls **`board.create`**, whose hq schema is
+ * `.strict()` and accepts only {title, detail, status, priority, workstreamId,
+ * itemId}. It rejects `col`, `assigneeId` and — fatally for machine-created work
+ * — `why`. `board.createTask` is the method that carries the provenance block and
+ * an owner, so prefer it whenever the vendored protocol has it, and degrade to
+ * `board.create` LOUDLY (an unowned, untraceable task is still better than no
+ * task, but the operator has to be told which one they got).
+ */
 async function defaultCreateItem(item, deps) {
+  const conn = await orgConn(deps);
+  if (methodDef("board.createTask")) {
+    const { call } = await import("../org/client.mjs");
+    // `itemId` is meaningless to board.createTask (non-strict → stripped) and is
+    // the idempotency key of the legacy path; carrying it costs nothing.
+    const { itemId, ...params } = item || {};
+    return call("board.createTask", params, { ...conn, fetchImpl: deps.fetchImpl });
+  }
+  logOf(deps)(
+    "warn",
+    "[goals] board.createTask is not in the vendored protocol — falling back to board.create, which drops the assignee and the `why` provenance block",
+  );
   const { createItem } = await import("../org/board.mjs");
-  return createItem(item, { cfg: deps.cfg, base: deps.base, token: deps.token, fetchImpl: deps.fetchImpl });
+  const legacy = { title: item.title, priority: item.priority };
+  if (item.detail) legacy.detail = String(item.detail).slice(0, 5000);
+  if (item.itemId) legacy.itemId = item.itemId;
+  return createItem(legacy, { cfg: deps.cfg, ...conn, fetchImpl: deps.fetchImpl });
 }
 
 async function defaultSendHandoff(o, deps) {
@@ -76,7 +140,8 @@ async function defaultClaimLease(scope, resourceId, opts) {
 
 async function defaultCall(method, params, deps) {
   const { call } = await import("../org/client.mjs");
-  return call(method, params, { base: deps.base, token: deps.token, orgId: deps.orgId, fetchImpl: deps.fetchImpl });
+  const conn = await orgConn(deps);
+  return call(method, params, { ...conn, fetchImpl: deps.fetchImpl });
 }
 
 function pick(deps, name, fallback) {
@@ -87,6 +152,62 @@ function pick(deps, name, fallback) {
 // The board item — every disposition creates one, so the work is visible
 // ---------------------------------------------------------------------------
 
+/** Local priority word → hq's `taskPriorityEnum`. P0 stays reserved for humans. */
+export const BOARD_PRIORITY = Object.freeze({ high: "P1", normal: "P2", low: "P3" });
+
+/**
+ * Shape a candidate into `board.createTask`'s ACTUAL parameters.
+ *
+ * This used to send `{id, status:"open", priority:"normal", assignee,
+ * objectiveKey, obligationKey}`. hq's `createTaskSchema` (src/server/validation/
+ * task.ts) accepts none of those spellings: `priority` is the P0..P4 enum, the
+ * owner field is `assigneeId`, and `why` is a CLOSED block of
+ * {reason, options, clause, wouldChange}. Every self-directed item this loop
+ * ever produced was therefore rejected BAD_REQUEST — the work existed in the
+ * local queue and was invisible to every human on the board.
+ *
+ * Provenance hq will not carry in `why` (objectiveKey, obligationKey, the
+ * expected delta) is written into `detail` instead, in prose, so the trace
+ * survives the round trip even though the columns do not.
+ *
+ * @param {object} item - { id, title, objectiveKey, obligationKey, why, priority, assignee?, expectedDelta?, successCriteria? }
+ * @param {object} [deps] - { memberId, boardCol? }
+ * @returns {object} board.createTask params
+ */
+export function boardPayloadFor(item = {}, deps = {}) {
+  const why = {};
+  const src = item.why || {};
+  if (src.reason) why.reason = String(src.reason).slice(0, 2000);
+  if (src.clause) why.clause = String(src.clause).slice(0, 500);
+  if (src.wouldChange) why.wouldChange = String(src.wouldChange).slice(0, 2000);
+  if (Array.isArray(src.options) && src.options.length) why.options = src.options.slice(0, 20);
+
+  const lines = [];
+  if (item.objectiveKey) lines.push(`Advances objective: ${item.objectiveKey}`);
+  if (item.obligationKey) lines.push(`Obligation: ${item.obligationKey}`);
+  if (item.expectedDelta != null) lines.push(`Expected delta: ${item.expectedDelta}`);
+  if (src.metric) lines.push(`Metric: ${src.metric} (gap ${src.gap}, trend ${src.trend})`);
+  for (const c of [].concat(item.successCriteria || [])) lines.push(`Success: ${c}`);
+  if (item.id) lines.push(`Local queue id: ${item.id}`);
+
+  const payload = {
+    // Stripped by board.createTask (non-strict); the idempotency key of the
+    // legacy board.create fallback.
+    itemId: item.id || undefined,
+    title: String(item.title || "").slice(0, 500),
+    // `todo`, not the schema's `triage` default: this work was ADMITTED through
+    // eight gates against a measured gap. Dropping it into triage would hand a
+    // human the decision the loop just made.
+    col: deps.boardCol || "todo",
+    priority: BOARD_PRIORITY[String(item.priority || "normal")] || "P2",
+  };
+  if (lines.length) payload.detail = lines.join("\n").slice(0, 20000);
+  const assigneeId = item.assignee || deps.memberId;
+  if (assigneeId) payload.assigneeId = assigneeId;
+  if (Object.keys(why).length) payload.why = why;
+  return payload;
+}
+
 /**
  * Create the org board item that carries the work, stamped with the full
  * provenance chain (`why`). Fail-open: an unreachable org returns
@@ -98,19 +219,7 @@ function pick(deps, name, fallback) {
  */
 export async function createWorkItem(item, deps = {}) {
   const create = pick(deps, "createItem", (i) => defaultCreateItem(i, deps));
-  const payload = {
-    id: item.id,
-    title: item.title,
-    status: "open",
-    priority: item.priority || "normal",
-    assignee: item.assignee || deps.memberId || undefined,
-    // `why` is mandatory for machine-created work: {reason, objectiveKey,
-    // obligationKey, clause, expectedDelta}. A task a human cannot trace is a
-    // task a human cannot trust.
-    why: item.why || null,
-    objectiveKey: item.objectiveKey || null,
-    obligationKey: item.obligationKey || null,
-  };
+  const payload = boardPayloadFor(item, deps);
   let frame;
   try {
     frame = await create(payload);
@@ -122,7 +231,10 @@ export async function createWorkItem(item, deps = {}) {
   if (!ok) {
     logOf(deps)(
       "warn",
-      `[goals] board.create failed for "${item.title}": ${(frame && frame.error && frame.error.code) || "unknown"} — the local backlog item still stands`
+      // The MESSAGE, not just the code. "BAD_REQUEST" on its own is what let
+      // "missing base" (a local credential fault) masquerade as a server-side
+      // rejection for the whole life of this loop.
+      `[goals] ${methodDef("board.createTask") ? "board.createTask" : "board.create"} failed for "${item.title}": ${(frame && frame.error && frame.error.code) || "unknown"}${frame && frame.error && frame.error.message ? ` — ${frame.error.message}` : ""} — the local backlog item still stands`
     );
   }
   return {
@@ -381,7 +493,7 @@ export async function raiseEscalation(o = {}, deps = {}) {
   if (!ok) {
     logOf(deps)(
       "warn",
-      `[goals] ${method} failed (${(frame && frame.error && frame.error.code) || "unknown"}) — the question is still recorded in the audit ledger`
+      `[goals] ${method} failed (${(frame && frame.error && frame.error.code) || "unknown"}${frame && frame.error && frame.error.message ? `: ${frame.error.message}` : ""}) — the question is still recorded in the audit ledger`
     );
   }
   return { ok, reason: ok ? "raised" : (frame && frame.error && frame.error.code) || "failed", id: ok && frame.result ? frame.result.id || null : null, method };
@@ -404,7 +516,9 @@ export async function routeWorkItem(item, classification, deps = {}) {
 
 export default {
   WORK_LEASE_SCOPE,
+  BOARD_PRIORITY,
   workResourceId,
+  boardPayloadFor,
   createWorkItem,
   routeWorkItem,
   routeSelf,

package/lib/goals/collaborate.test.mjs

@@ -76,10 +76,22 @@ test("every work item carries the full provenance chain onto the board", async (
   assert.equal(r.ok, true);
   assert.equal(r.itemId, "bi_1");
   const payload = calls.board[0];
-  assert.equal(payload.objectiveKey, "pipeline");
-  assert.equal(payload.obligationKey, "outcome.pipeline");
+  // The payload is shaped for hq's REAL schema (board.createTask): the owner is
+  // `assigneeId`, the priority is the P0..P4 enum, and `why` is the CLOSED
+  // {reason, options, clause, wouldChange} block. `objectiveKey`/`obligationKey`
+  // have no column there, so they ride in `detail` — the trace survives even
+  // though the fields do not. (The old spellings were rejected BAD_REQUEST by
+  // every hq that ever received them.)
   assert.equal(payload.why.clause, "cs_12");
-  assert.equal(payload.assignee, SELF);
+  assert.equal(payload.why.reason, "kpi-gap");
+  assert.equal(payload.assigneeId, SELF);
+  assert.equal(payload.priority, "P1", "the item is high priority → P1, not the word \"high\"");
+  assert.equal(payload.col, "todo");
+  assert.match(payload.detail, /Advances objective: pipeline/);
+  assert.match(payload.detail, /Obligation: outcome\.pipeline/);
+  assert.equal(payload.objectiveKey, undefined, "a spelling hq rejects must not be sent");
+  assert.equal(payload.assignee, undefined);
+  assert.equal(payload.status, undefined);
 });
 
 test("SERVER UNREACHABLE: a thrown board.create is reported, logged, and never throws out", async () => {
@@ -182,7 +194,7 @@ test("HANDOFF assigns the item to the target and sends the envelope with full co
   const r = await routeHandoff(ITEM, c, deps);
   assert.equal(r.ok, true);
   assert.equal(r.primitive, "handoff.offer");
-  assert.equal(calls.board[0].assignee, PEER, "the board item must be assigned to whoever is doing it");
+  assert.equal(calls.board[0].assigneeId, PEER, "the board item must be assigned to whoever is doing it");
   const env = calls.handoff[0];
   assert.equal(env.to, PEER);
   assert.equal(env.from, SELF);