@cohortapp/agent-sdk 2.3.1 → 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
@@ -120,19 +121,46 @@ function logEvent(type, entry) {
 // ---------------------------------------------------------------------------
 
 async function poll() {
-  const services = [
-    { name: "slack", fn: pollSlack },
-    { name: "gmail", fn: pollGmail },
-    { name: "alex-gmail", fn: pollSecondaryGmail },
-    { name: "calendar", fn: pollCalendar },
-    { name: "voice", fn: pollVoice },
+  // COHORT IS THE DEFAULT SUBSTRATE. An agent's messaging, email, calendar,
+  // CRM, directory, spaces, boards, books and calls all live on the Cohort
+  // server. The third-party adapters below are LEGACY BRIDGES for agents that
+  // additionally sit in someone else's Slack or Gmail — they are not what a new
+  // agent should be doing by default.
+  //
+  // They used to be polled unconditionally, which meant every freshly-created
+  // agent burned a poll cycle on Slack, two Gmail accounts, Google Calendar and
+  // voice on a loop, and filled its log with "SLACK_TOKEN not set" /
+  // "App password not set" forever. Worse, the noise made a REAL failure
+  // (Cohort inbound not wired at all) invisible in the same log.
+  //
+  // Each is now gated on evidence that it is actually configured, exactly like
+  // the channel-bus platforms below. Nothing is removed — an agent that IS on
+  // Slack keeps working the moment its token exists.
+  const services = [];
+  const legacyBridges = [
+    { name: "slack", fn: pollSlack, on: () => Boolean(process.env.SLACK_TOKEN || process.env.SLACK_USER_TOKEN) },
+    { name: "gmail", fn: pollGmail, on: () => Boolean(process.env.GMAIL_APP_PASSWORD) },
+    { name: "alex-gmail", fn: pollSecondaryGmail, on: () => Boolean(process.env.SECONDARY_GMAIL_APP_PASSWORD) },
+    { name: "calendar", fn: pollCalendar, on: () => _existsSync(join(AGENT_REPO_DIR, "config/google-calendar.yaml")) || Boolean(process.env.GOOGLE_CALENDAR_CREDENTIALS) },
+    { name: "voice", fn: pollVoice, on: () => _existsSync(join(AGENT_REPO_DIR, "config/voice.yaml")) || Boolean(process.env.TWILIO_ACCOUNT_SID) },
   ];
+  for (const b of legacyBridges) {
+    let enabled = false;
+    try { enabled = b.on(); } catch { enabled = false; }
+    if (enabled) services.push({ name: b.name, fn: b.fn });
+  }
 
   // WS2: channel-bus platforms (Telegram, Baileys WhatsApp) deliver events as
   // inbox YAML via the daemon's channel loop. They have no API poller, so a
   // generic inbox scanner drains their items into the same pipeline. Gate on
   // the platform's config file so we don't scan dirs for disabled channels.
-  for (const [name, gate] of [["telegram", "config/telegram.yaml"], ["whatsapp", "config/whatsapp.yaml"], ["orgmail", "config/orgmail.yaml"]]) {
+  // `cohort` is the SAME shape: the messaging-inbound cadence pulls org
+  // messages / @mentions / call-invites directed at this agent and writes them
+  // as inbox YAML under state/inbox/cohort/ — but nothing drained that
+  // directory, so the items simply accumulated and the agent never answered.
+  // The whole SP10 inbound chain existed except this last hop. Gated on org
+  // enrolment (config/org.yaml) exactly like the other channel sources.
+  for (const [name, gate] of [["telegram", "config/telegram.yaml"], ["whatsapp", "config/whatsapp.yaml"], ["orgmail", "config/orgmail.yaml"], ["cohort", "config/org.yaml"]]) {
     if (_existsSync(join(AGENT_REPO_DIR, gate))) {
       services.push({ name, fn: makeInboxScanPoller(name, { agentRoot: AGENT_REPO_DIR }) });
     }
@@ -808,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) => {