@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/scripts/ci/conformance-org-api.test.mjs

@@ -0,0 +1,417 @@
+/**
+ * conformance-org-api.test.mjs — the PURE parts of the live conformance probe.
+ *
+ * The probe's value rests entirely on one judgement: given an hq error frame,
+ * is this WIRE-CONTRACT DRIFT (fail) or a legitimate refusal (skip/warn)? Get
+ * that wrong in the lenient direction and the probe is decorative; get it wrong
+ * in the strict direction and nobody will keep it in CI. So `classifyFrame` and
+ * `citedParams` are tested against the ACTUAL error strings hq's handlers emit
+ * — including the real message from every P0 row of the 2026-08 audit.
+ *
+ * Hermetic: no network, no disk, no credentials. The runner is exercised through
+ * injected `callImpl`/`readImpl`.
+ *
+ * Run: node --test scripts/ci/conformance-org-api.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  classifyFrame,
+  citedParams,
+  buildProbes,
+  parseArgs,
+  probeSelected,
+  runProbes,
+  referencesGhost,
+  wireBodyFor,
+  uncoveredContractMethods,
+  ghostId,
+  SCHEMA_PASSED_CODES,
+} from "./conformance-org-api.mjs";
+import { PARAM_CONTRACT } from "../../lib/org/param-contract.mjs";
+import { methodDef } from "../../lib/org/protocol.mjs";
+
+const err = (code, message) => ({ ok: false, error: { code, message } });
+const probe = (method) => ({ method, params: {} });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// citedParams — parsing hq's four error dialects
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("citedParams: zod path prefix (the `parse()` helper's shape)", () => {
+  assert.deepEqual(citedParams("channelId: Required").cited, ["channelId"]);
+  assert.deepEqual(citedParams("itemId: itemId is required").cited, ["itemId"]);
+  // A nested path reports its ROOT — that is the key the caller controls.
+  assert.deepEqual(citedParams("participantIds.0: Expected string").cited, ["participantIds"]);
+});
+
+test("citedParams: zod .strict() unrecognized keys", () => {
+  const r = citedParams("Unrecognized key(s) in object: 'note', 'stray'");
+  assert.deepEqual(r.unrecognized.sort(), ["note", "stray"]);
+});
+
+test("citedParams: hq's hand-written guards", () => {
+  assert.ok(citedParams("title is required").cited.includes("title"));
+  assert.ok(citedParams("actionClass is required").cited.includes("actionClass"));
+  assert.ok(citedParams("memoryClass must be one of: framework, ledger").cited.includes("memoryClass"));
+  assert.ok(citedParams("payloadHash must be a sha-256 hex digest").cited.includes("payloadHash"));
+});
+
+test("citedParams: a message naming nothing yields nothing (never invents a field)", () => {
+  assert.deepEqual(citedParams("an escalation must reference a task or a channel").unrecognized, []);
+  assert.deepEqual(citedParams("").cited, []);
+  assert.deepEqual(citedParams(null).cited, []);
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// classifyFrame — the discriminator
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("ok:true → pass", () => {
+  assert.equal(classifyFrame(probe("member.get"), { slug: "x" }, { ok: true, result: {} }).verdict, "pass");
+});
+
+test("every legitimate-refusal code → skip, NOT fail (the schema was accepted)", () => {
+  for (const code of SCHEMA_PASSED_CODES) {
+    const v = classifyFrame(probe("board.claim"), { itemId: "i" }, err(code, "nope"));
+    assert.equal(v.verdict, "skip", `${code} must not be reported as drift`);
+  }
+});
+
+test("a non-BAD_REQUEST failure (INTERNAL/5xx) → warn, never a silent pass", () => {
+  const v = classifyFrame(probe("board.claim"), { itemId: "i" }, err("INTERNAL", "boom"));
+  assert.equal(v.verdict, "warn");
+});
+
+test("a missing/garbled frame → warn, never a pass", () => {
+  assert.equal(classifyFrame(probe("x.y"), {}, null).verdict, "warn");
+  assert.equal(classifyFrame(probe("x.y"), {}, undefined).verdict, "warn");
+});
+
+// ── the FAIL cases: this is the drift the audit found ──────────────────────
+
+test("DRIFT: hq requires a name we never send → fail (the messaging.send P0)", () => {
+  // What hq actually returned while the SDK minted `clientMsgId`.
+  const v = classifyFrame(
+    probe("messaging.send"),
+    { channelId: "C1", body: "hi", clientMsgId: "cm-1" },
+    err("BAD_REQUEST", "idempotencyId: Required"),
+  );
+  assert.equal(v.verdict, "fail");
+  assert.match(v.reason, /idempotencyId/);
+});
+
+test("DRIFT: hq's .strict() schema rejects a key we DO send → fail (the board.complete P0)", () => {
+  const v = classifyFrame(
+    probe("board.complete"),
+    { itemId: "i-1", note: "done" },
+    err("BAD_REQUEST", "Unrecognized key(s) in object: 'note'"),
+  );
+  assert.equal(v.verdict, "fail");
+  assert.match(v.reason, /REJECTS the param name/);
+  assert.match(v.reason, /note/);
+});
+
+test("DRIFT: the registry.register P0 — a raw self-entry into a strict schema", () => {
+  const v = classifyFrame(
+    probe("registry.register"),
+    { id: "A016", name: "isla", towers: ["eng"] },
+    err("BAD_REQUEST", "Unrecognized key(s) in object: 'id', 'name', 'towers'"),
+  );
+  assert.equal(v.verdict, "fail");
+});
+
+test("DRIFT: each remaining P0 hand-written guard is caught", () => {
+  const rows = [
+    ["escalation.create", { severity: "high", subject: "s", body: "b" }, "title is required", "title"],
+    ["approval.request", { kind: "external_comms", payload_hash: "x" }, "actionClass is required", "actionClass"],
+    ["decision.comment", { decisionId: "d", body: "b" }, "text is required", "text"],
+    ["member.get", { memberId: "m" }, "slug is required", "slug"],
+    ["memory.author", { content: "c", kind: "note" }, "memoryClass must be one of: framework, ledger", "memoryClass"],
+  ];
+  for (const [method, sent, message, expect] of rows) {
+    const v = classifyFrame(probe(method), sent, err("BAD_REQUEST", message));
+    assert.equal(v.verdict, "fail", `${method} must be flagged`);
+    assert.match(v.reason, new RegExp(expect), `${method} must name ${expect}`);
+  }
+});
+
+// ── the WARN case: a value complaint is not drift ──────────────────────────
+
+test("NOT DRIFT: hq disliking the VALUE of a param we sent → warn", () => {
+  const v = classifyFrame(
+    probe("approval.request"),
+    { actionClass: "x", payloadHash: "not-a-hash" },
+    err("BAD_REQUEST", "payloadHash must be a sha-256 hex digest"),
+  );
+  assert.equal(v.verdict, "warn", "we send the right NAME; the probe's placeholder was the problem");
+  assert.match(v.reason, /probe placeholder/);
+});
+
+test("NOT DRIFT: a refine() that names no field → warn, not a false FAIL", () => {
+  const v = classifyFrame(
+    probe("escalation.create"),
+    { title: "t" },
+    err("BAD_REQUEST", "an escalation must reference a task or a channel"),
+  );
+  assert.equal(v.verdict, "warn");
+});
+
+test("a BAD_REQUEST we cannot parse is a warn — never an assumed pass", () => {
+  const v = classifyFrame(probe("x.y"), { a: 1 }, err("BAD_REQUEST", "computer says no"));
+  assert.equal(v.verdict, "warn");
+  assert.match(v.reason, /unparsed/);
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// the probe table — coverage + safety
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("every probe names a real protocol method and declares its write posture", () => {
+  for (const p of buildProbes()) {
+    assert.ok(methodDef(p.method), `${p.method} is not in the vendored protocol table`);
+    assert.equal(typeof p.writes, "boolean", `${p.method} must declare writes`);
+    assert.ok(p.why && p.why.length > 8, `${p.method} must justify its safety posture`);
+    assert.ok(p.params && typeof p.params === "object", `${p.method} needs params`);
+  }
+});
+
+test("COVERAGE: every contracted method has a probe (a new contract row cannot ship unprobed)", () => {
+  assert.deepEqual(
+    uncoveredContractMethods(),
+    [],
+    "add a probe to buildProbes() for each new PARAM_CONTRACT entry",
+  );
+});
+
+test("SAFETY: every probe declares a guard, and a `ghost` guard really carries a ghost id", () => {
+  const GUARDS = new Set(["read", "ghost", "audit-only", "no-op", "write"]);
+  const offenders = [];
+  for (const p of buildProbes()) {
+    if (!GUARDS.has(p.guard)) {
+      offenders.push(`${p.method} declares no valid guard (got ${JSON.stringify(p.guard)})`);
+      continue;
+    }
+    if (p.writes && p.guard !== "write") offenders.push(`${p.method} writes but is not guarded "write"`);
+    if (!p.writes && p.guard === "write") offenders.push(`${p.method} is guarded "write" but claims writes:false`);
+    // The load-bearing one: a side-effecting method run BY DEFAULT is safe only
+    // because its target cannot exist.
+    if (p.guard === "ghost" && !referencesGhost(p.params)) {
+      offenders.push(`${p.method} claims guard "ghost" but its params carry no ghost id`);
+    }
+    // And nothing side-effecting may run by default under a "read" guard.
+    const def = methodDef(p.method);
+    if (p.guard === "read" && def && def.sideEffecting) {
+      offenders.push(`${p.method} is side-effecting but guarded "read"`);
+    }
+  }
+  assert.deepEqual(offenders, [], `unsafe probes:\n  ${offenders.join("\n  ")}`);
+});
+
+test("SAFETY: a create-or-upsert method is never guarded `ghost` — an unknown id CREATES", () => {
+  // REGRESSION. The `ghost` guard assumes the handler REQUIRES its entity to
+  // exist, so an impossible id makes a side-effecting probe harmless. That
+  // assumption inverts for create-or-upsert handlers: hq's knowledge.replace
+  // treats an unknown id as the CREATE branch and appends `knowledge.created`
+  // at version 1, so a ghost id GUARANTEES a durable row. It shipped declared
+  // `writes:false` and a read-only run created a junk fact in the live org.
+  //
+  // These methods are upserts on hq's side and must stay `--write`-gated.
+  const UPSERTS = ["knowledge.replace", "contacts.upsert", "meetings.record"];
+  const byMethod = new Map(buildProbes().map((p) => [p.method, p]));
+  for (const method of UPSERTS) {
+    const p = byMethod.get(method);
+    if (!p) continue; // coverage is asserted elsewhere
+    assert.equal(p.writes, true, `${method} is create-or-upsert: it must declare writes:true`);
+    assert.notEqual(p.guard, "ghost", `${method} is an upsert — a ghost id creates a row, it does not prevent one`);
+  }
+});
+
+test("SAFETY: no outbound-content probe is ever unguarded — a real send must be impossible", () => {
+  // messaging.send is probed, and is safe ONLY because its channel cannot exist.
+  const send = buildProbes().find((p) => p.method === "messaging.send");
+  assert.ok(send, "messaging.send IS probed — it was the worst drift row");
+  assert.equal(send.writes, false);
+  assert.equal(send.guard, "ghost");
+  assert.ok(referencesGhost(send.params), "the channel id must be a ghost or a message could be delivered");
+  // No probe touches the outbound email lane at all.
+  const emailSends = buildProbes().filter((p) => /^email\.(send|draftSend)$/.test(p.method));
+  assert.deepEqual(emailSends, [], "email sends are never probed");
+});
+
+test("SAFETY: ghost ids are unique per run, so a probe can never collide with real data", () => {
+  const a = ghostId("task");
+  const b = ghostId("task");
+  assert.notEqual(a, b);
+  assert.match(a, /^probe-task-[0-9a-f-]{36}$/, "the `probe-` marker is load-bearing for the safety test");
+  assert.equal(referencesGhost({ taskId: a }), true);
+  assert.equal(referencesGhost({ taskId: "t-real-123" }), false);
+});
+
+test("the probe payloads are already canonical — the contract rewrites nothing", () => {
+  // If a probe needed rewriting, it would be testing the contract against itself
+  // rather than against hq.
+  for (const p of buildProbes()) {
+    const sent = wireBodyFor(p.method, p.params);
+    for (const k of Object.keys(p.params)) {
+      assert.ok(k in sent, `${p.method}: probe param ${k} vanished`);
+    }
+    const c = PARAM_CONTRACT[p.method];
+    if (!c || !c.alias) continue;
+    for (const legacy of Object.keys(c.alias)) {
+      if (c.serverAccepts && c.serverAccepts.includes(legacy)) continue;
+      assert.ok(!(legacy in p.params), `${p.method}: probe uses the LEGACY name ${legacy}`);
+    }
+  }
+});
+
+test("every probe payload satisfies what hq requires (no self-inflicted BAD_REQUEST)", () => {
+  for (const p of buildProbes()) {
+    const sent = wireBodyFor(p.method, p.params);
+    const c = PARAM_CONTRACT[p.method];
+    if (!c) continue;
+    const missing = (c.required || []).filter((k) => sent[k] === undefined || sent[k] === "");
+    assert.deepEqual(missing, [], `${p.method} probe omits required ${missing.join(",")}`);
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// argv + filtering
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("parseArgs: flags, --only list, --agent-root, and unknown-arg capture", () => {
+  const a = parseArgs(["--write", "--json", "-v", "--only=board, messaging", "--agent-root=/tmp/x"]);
+  assert.equal(a.write, true);
+  assert.equal(a.json, true);
+  assert.equal(a.verbose, true);
+  assert.deepEqual(a.only, ["board", "messaging"]);
+  assert.equal(a.agentRoot, "/tmp/x");
+  assert.deepEqual(a.bad, []);
+  assert.deepEqual(parseArgs(["--nope"]).bad, ["--nope"]);
+  assert.equal(parseArgs([]).write, false, "write is OFF by default");
+});
+
+test("probeSelected: no filter selects everything; a family filter narrows", () => {
+  const p = { method: "board.claim" };
+  assert.equal(probeSelected(p, []), true);
+  assert.equal(probeSelected(p, ["board"]), true);
+  assert.equal(probeSelected(p, ["messaging"]), false);
+  assert.equal(probeSelected(p, ["board.claim"]), true, "an exact method name also selects");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// the runner (injected transport)
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("runProbes: row-creating probes are SKIPPED without --write, and never dispatched", async () => {
+  const dispatched = [];
+  const callImpl = async (method) => {
+    dispatched.push(method);
+    return { ok: true, result: {} };
+  };
+  const readImpl = async () => ({ ok: true, payload: {} });
+  const { results } = await runProbes({ base: "https://x", token: "t", callImpl, readImpl });
+
+  const writers = buildProbes().filter((p) => p.writes).map((p) => p.method);
+  assert.ok(writers.length > 0, "there ARE row-creating probes to gate");
+  for (const m of writers) {
+    assert.ok(!dispatched.includes(m), `${m} must not be dispatched without --write`);
+    const row = results.find((r) => r.method === m);
+    assert.equal(row.verdict, "skip");
+    assert.match(row.reason, /--write/);
+  }
+});
+
+test("runProbes: --write dispatches the row-creating probes too", async () => {
+  const dispatched = [];
+  const callImpl = async (method) => {
+    dispatched.push(method);
+    return { ok: true, result: {} };
+  };
+  const readImpl = async () => ({ ok: true, payload: {} });
+  await runProbes({ base: "https://x", token: "t", write: true, callImpl, readImpl });
+  for (const p of buildProbes()) assert.ok(dispatched.includes(p.method), `${p.method} dispatched`);
+});
+
+test("runProbes: a BAD_REQUEST naming an unsent param surfaces as a failure", async () => {
+  // Simulates FUTURE drift: hq starts requiring a name this SDK does not send.
+  // (The historical bug was the mirror image — hq wanted `idempotencyId` while we
+  // sent `clientMsgId` — and the probe would have caught it identically.)
+  const callImpl = async (method) =>
+    method === "messaging.send" ? err("BAD_REQUEST", "conversationId: Required") : { ok: true, result: {} };
+  const readImpl = async () => ({ ok: true, payload: {} });
+  const { failures } = await runProbes({
+    base: "https://x",
+    token: "t",
+    only: ["messaging"],
+    callImpl,
+    readImpl,
+  });
+  assert.equal(failures.length, 1);
+  assert.equal(failures[0].method, "messaging.send");
+});
+
+test("runProbes: NOT_FOUND everywhere is a clean run — that is the expected shape", async () => {
+  const callImpl = async () => err("NOT_FOUND", "no such thing");
+  const readImpl = async () => ({ ok: true, payload: {} });
+  const { failures, results } = await runProbes({ base: "https://x", token: "t", callImpl, readImpl });
+  assert.deepEqual(failures, []);
+  assert.ok(results.every((r) => r.verdict === "skip"));
+});
+
+test("runProbes: a transport throw is contained as a warn, never an unhandled rejection", async () => {
+  const callImpl = async () => {
+    throw new Error("socket hang up");
+  };
+  const readImpl = async () => ({ ok: true, payload: {} });
+  const { results, failures } = await runProbes({
+    base: "https://x",
+    token: "t",
+    only: ["messaging"],
+    callImpl,
+    readImpl,
+  });
+  assert.deepEqual(failures, []);
+  assert.ok(results.every((r) => r.verdict === "warn"));
+});
+
+test("runProbes: a BAD_REQUEST on a GET read path is drift too", async () => {
+  const callImpl = async () => ({ ok: true, result: {} });
+  const readImpl = async (path) =>
+    path === "snapshot" ? { ok: false, error: { code: "BAD_REQUEST", message: "bad" }, status: 400 } : { ok: true, payload: {} };
+  const { reads, failures } = await runProbes({ base: "https://x", token: "t", only: ["reads"], callImpl, readImpl });
+  assert.ok(reads.length >= 12, "every read path probed");
+  assert.equal(failures.length, 1);
+  assert.equal(failures[0].path, "snapshot");
+});
+
+// ---------------------------------------------------------------------------
+// A run that proved nothing must not report success
+// ---------------------------------------------------------------------------
+
+test("UNAUTHORIZED is a CREDENTIAL verdict, never a pass or a skip", () => {
+  // hq returns UNAUTHORIZED for a bad bearer key on every method and every GET
+  // read. It used to sit in SCHEMA_PASSED_CODES, so a rotated/revoked token made
+  // all 36 method probes `skip`, all 12 read paths `pass`, and the run print
+  // "No wire-contract drift." and exit 0 — green forever while probing nothing.
+  const v = classifyFrame(
+    { method: "board.createTask" },
+    {},
+    { ok: false, error: { code: "UNAUTHORIZED", message: "bad key" } },
+  );
+  assert.equal(v.verdict, "credential");
+  assert.match(v.reason, /nothing was tested/i);
+});
+
+test("a genuinely declined handler is still a skip (we did test the schema)", () => {
+  const v = classifyFrame(
+    { method: "board.createTask" },
+    {},
+    { ok: false, error: { code: "NOT_FOUND", message: "no such item" } },
+  );
+  assert.equal(v.verdict, "skip");
+});

package/scripts/daemon/agent-daemon.mjs

@@ -57,7 +57,8 @@ import { sendQuickResponse, sendHoldingMessage, isQuickReply } from "./responder
 import { recordPoll, recordClassification, recordSession, writeHealthDashboard } from "./health.mjs";
 import { acquireLock, releaseLock, updateLock, scanStaleLocks, acquireThreadLock, claimRequest, hasActiveClaim, sweepStaleItemClaims, sanitiseItemId } from "./session-lock.mjs";
 import { markDeferred } from "./inbox-deferral.mjs";
-import { parseQueueItems } from "../../lib/backlog.mjs";
+import { parseQueueItems, rankBacklog, resolveBacklogWeights } from "../../lib/backlog.mjs";
+import { readLatestGaps } from "../../lib/goals/gaps.mjs";
 // Org shared-memory write-back (central store via memory.author / knowledge.append
 // RPC). After a daemon turn completes cleanly we distil a one-line record of the
 // work and land it in the org's shared, ACL'd store so the fleet's memory
@@ -835,9 +836,40 @@ async function sweepBacklog() {
       }
     }
 
-    // Sort: critical first, then high, then normal
-    const priorityOrder = { critical: 0, high: 1, normal: 2, low: 3 };
-    actionableItems.sort((a, b) => (priorityOrder[a.priority] || 3) - (priorityOrder[b.priority] || 3));
+    // Rank: flat priority (critical → low) as the base term, PROMOTED by the
+    // measured KPI gap of whatever objective the item claims to advance
+    // (SPEC §6.3 step 6: score = w_p·priority + w_g·(normalizedGap × expectedDelta)
+    // − w_a·age). Items with no `advances[]` — every seeded/hand-written item —
+    // score exactly as they do today, so nothing regresses. Weights come from
+    // the charter's rewardWeights when present.
+    //
+    // Fail-open: any error here falls back to the flat sort rather than
+    // stalling the sweep, and says so.
+    let ranked = actionableItems;
+    try {
+      const gapsByObjective = readLatestGaps(AGENT_REPO_DIR, {
+        log: (lvl, msg) => console.log(`[daemon] ${msg}`),
+      });
+      let charter = null;
+      try {
+        charter = JSON.parse(readFileSync(join(AGENT_REPO_DIR, "config", "agent.json"), "utf-8")).charter || null;
+      } catch { /* no charter on disk yet — defaults apply */ }
+      ranked = rankBacklog(actionableItems, {
+        gapsByObjective,
+        weights: resolveBacklogWeights(charter),
+        now: Date.now(),
+      });
+      const promoted = ranked.filter((r) => r._scoreParts && r._scoreParts.gapTerm > 0).length;
+      if (promoted > 0) {
+        console.log(`[daemon] Backlog ranking: ${promoted} item(s) promoted by a measured KPI gap`);
+      }
+    } catch (err) {
+      console.error(`[daemon] Backlog gap-ranking failed, falling back to flat priority order: ${err.message}`);
+      const priorityOrder = { critical: 0, high: 1, normal: 2, low: 3 };
+      ranked = [...actionableItems].sort((a, b) => (priorityOrder[a.priority] || 3) - (priorityOrder[b.priority] || 3));
+    }
+    actionableItems.length = 0;
+    actionableItems.push(...ranked);
 
     // Filter out items that already have active sessions or exceeded retries
     const dispatchable = actionableItems.filter((qi) => {

package/scripts/daemon/cadence-handlers.mjs

@@ -917,6 +917,122 @@ async function guardBrandSteward({ event, agentRoot, log }, opts = {}) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// goal-steward (D3, SPEC §6.3) — the self-directed reconciliation loop
+// ---------------------------------------------------------------------------
+
+/**
+ * Refresh the cached mandate, then run one goal-steward pass INLINE.
+ *
+ * Guarded rather than escalate on purpose. The whole measure → gap → decide →
+ * admit → classify → route pass is deterministic local computation plus sensor
+ * reads; there is nothing for a model to do unless a gap needs *candidates*
+ * that the deterministic planner cannot produce. So:
+ *
+ *   - no adopted mandate                     → inline, zero cost, one log line
+ *   - every objective within tolerance       → inline
+ *   - a gap that produced admitted work      → inline (the work is already
+ *                                              queued + routed)
+ *   - a gap the loop wants richer candidates
+ *     for (observe-only, or a repeatedly
+ *     failed intervention)                   → escalate to a planning session
+ *
+ * Never throws: every failure path returns `{ok:false, …}` with a reason so the
+ * consumer can archive/DLQ, and every degradation is logged.
+ *
+ * @param {object} ctx - { event, agentRoot, log }
+ * @param {object} [opts] - injectable seams: { runImpl, refreshImpl, cfg, enforcement, now, fetchImpl }
+ */
+async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
+  const cadence = event && event.cadence ? event.cadence : "goal-steward";
+  const say = typeof log === "function" ? log : () => {};
+  try {
+    // 1. Refresh the mandate cache first — a goal loop running off a week-old
+    //    mandate is worse than one that does not run. Fail-open: the loop's own
+    //    staleness ladder is what actually decides what it may do.
+    if (opts.refreshImpl !== null) {
+      try {
+        const refresh = opts.refreshImpl || (await import("../../lib/mandate/refresh.mjs")).refreshMandate;
+        const r = await refresh(agentRoot, { fetchImpl: opts.fetchImpl, log: say, now: opts.now });
+        if (r && r.ok === false) {
+          say("warn", `[goal-steward] mandate refresh failed (${r.reason}) — running on the cached mandate`);
+        }
+      } catch (err) {
+        say("warn", `[goal-steward] mandate refresh threw (${err && err.message ? err.message : err}) — running on the cached mandate`);
+      }
+    }
+
+    // 2. Enforcement posture. OBSERVE unless config/plan.yaml says otherwise —
+    //    the loop must not create work on day one.
+    let enforcement = opts.enforcement;
+    if (enforcement === undefined) {
+      enforcement = "observe";
+      try {
+        const p = join(agentRoot, "config", "plan.yaml");
+        if (existsSync(p)) {
+          const m = readFileSync(p, "utf-8").match(/^\s*enforcement:\s*["']?(\w+)["']?/m);
+          if (m && m[1] === "active") enforcement = "active";
+        }
+      } catch (err) {
+        say("warn", `[goal-steward] could not read config/plan.yaml enforcement (${err && err.message ? err.message : err}) — staying observe-only`);
+      }
+    }
+
+    const run = opts.runImpl || (await import("../../lib/goals/loop.mjs")).runGoalSteward;
+    const report = await run({ agentRoot, log: say, enforcement, now: opts.now, ...(opts.runDeps || {}) });
+
+    if (!report || report.ok === false) {
+      // Not an error for the bus: "no mandate" is the normal pre-adoption state.
+      return {
+        ok: true,
+        decision: "inline",
+        cadence,
+        reason: (report && report.skipped) || "goal loop could not run",
+        measured: 0,
+        admitted: 0,
+      };
+    }
+
+    const measured = (report.measured || []).length;
+    const admitted = (report.admitted || []).length;
+    const rejected = (report.rejected || []).length;
+    const escalations = (report.escalations || []).length;
+    const drift = (report.drift || []).length;
+
+    if (report.skipped) {
+      return { ok: true, decision: "inline", cadence, reason: report.skipped, measured, admitted, drift };
+    }
+
+    say(
+      "info",
+      `[goal-steward] ${enforcement}: measured ${measured}, admitted ${admitted}, rejected ${rejected}, escalations ${escalations}, drift ${drift}`
+    );
+
+    // 3. Escalate only when a model would actually add something: an open gap
+    //    that produced no admitted work and no escalation of its own.
+    const unserved = (report.decisions || []).filter(
+      (d) => d.action === "create" && !(report.admitted || []).some((a) => a.objectiveKey === d.objectiveKey)
+    );
+    if (unserved.length > 0 && enforcement === "active") {
+      return {
+        ok: true,
+        decision: "escalate",
+        cadence,
+        reason: `${unserved.length} objective(s) have an open gap the deterministic planner could not serve`,
+        objectives: unserved.map((d) => d.objectiveKey),
+        measured,
+        admitted,
+      };
+    }
+
+    return { ok: true, decision: "inline", cadence, measured, admitted, rejected, escalations, drift, enforcement };
+  } catch (err) {
+    // Fail-open but LOUD: the daemon keeps running, the failure is on the record.
+    say("error", `[goal-steward] guard threw: ${err && err.message ? err.message : err}`);
+    return { ok: false, decision: "inline", cadence, error: String(err && err.message ? err.message : err) };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
@@ -1098,6 +1214,23 @@ export const CADENCE_REGISTRY = {
       "design_propose_change", "messaging_send",
     ],
   },
+
+  "goal-steward": {
+    mode: "guarded",
+    guard: guardGoalSteward,
+    prompt: "schedules/triggers/goal-steward.md",
+    description:
+      "The self-directed loop (SPEC §6.3): measure every adopted objective whose window is open, compute the gap against target/tolerance/trend, and turn a real gap into real, provenance-linked backlog — classified SELF/COLLABORATE/HANDOFF/NEEDS_REVIEW and routed through the existing handoff/lease/approval primitives. Guarded: the whole pass runs inline; it escalates only when an open gap needs candidates the deterministic planner cannot produce. Observe-only until config/plan.yaml sets enforcement: active.",
+    // Reads + the collaboration primitives. No shell, no send-to-external:
+    // the loop proposes and routes; anything gated goes through approval.
+    allowedTools: [
+      "Read", "Grep", "Glob", "LS",
+      "mandate_get", "mandate_propose", "mandate_sample",
+      "board_create", "board_comment", "board_context",
+      "handoff_offer", "approval_request", "escalation_ask",
+      "task_create", "messaging_send",
+    ],
+  },
 };
 
 // Optional config-driven cadence registry (config/.cadence-registry.json),
@@ -1126,7 +1259,17 @@ export function getCadenceDef(name) {
   if (CADENCE_REGISTRY[name]) return CADENCE_REGISTRY[name];
   const cfg = loadConfigRegistry()[name];
   if (cfg && cfg.prompt) {
-    return { mode: cfg.mode || "escalate", prompt: cfg.prompt, description: "archetype cadence (config-driven)" };
+    // EXTENDED registry shape (plan compiler, lib/plan/emit.mjs): a plan-derived
+    // cadence carries its own tool scope, guard and budget. Passing these through
+    // is what lets lib/session-permissions.resolveAllowlist() scope the spawn
+    // instead of falling back to the conservative default — without it, every
+    // derived cadence would run wider than its obligation declares.
+    const def = { mode: cfg.mode || "escalate", prompt: cfg.prompt, description: "archetype/plan cadence (config-driven)" };
+    if (Array.isArray(cfg.allowedTools) && cfg.allowedTools.length) def.allowedTools = cfg.allowedTools;
+    if (cfg.guardModule) def.guardModule = cfg.guardModule;
+    if (Number.isFinite(cfg.budgetCents)) def.budgetCents = cfg.budgetCents;
+    if (cfg.obligationKey) def.obligationKey = cfg.obligationKey;
+    return def;
   }
   return null;
 }
@@ -1156,4 +1299,5 @@ export {
   guardMessagingInbound,
   guardDirectoryHygiene,
   guardBrandSteward,
+  guardGoalSteward,
 };