@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/lib/execution/effects.mjs

@@ -20,8 +20,12 @@
  *                     the daemon's 2-minute backlog sweep already dispatches. No
  *                     dispatcher edit, no new transport.
  *   delegate        → `lib/org/handoff.mjs sendHandoff` (the A2A envelope path).
- *   escalate        → `escalation.create` via `lib/org/client.mjs call`, which is
- *                     the first real writer for the escalation lane.
+ *   escalate        → `escalation.ask` when the decision carries ≥2 concrete
+ *                     options (an OpenQuestion a human can settle in one click),
+ *                     else `escalation.create` against the task/channel the
+ *                     event names (a blockage flag). Both via `lib/org/client.mjs
+ *                     call`, whose `{base, token}` this module now resolves from
+ *                     the agent root — see `orgConn` for why it had to.
  *   requestApproval → `lib/org/approvals.mjs requestApproval` + `awaitDecision`,
  *                     including the `payloadHash` single-use binding.
  *   arbitrate       → `lib/org/leases.mjs preSendArbitration` (3s fail-open).
@@ -42,6 +46,68 @@ import { dirname, join } from "node:path";
 import { resolveAgentRoot } from "../agent-root.mjs";
 import { appendJsonl } from "../fs-atomic.mjs";
 import { yamlScalar } from "../channels/inbox-item.mjs";
+import { policyFor } from "./surface-policy.mjs";
+
+/**
+ * Resolve `{base, token, orgId}` for an agent root.
+ *
+ * ── WHY THIS EXISTS ──
+ * `lib/org/client.mjs call()` resolves NOTHING from an agent root: its first
+ * line is `const {base, token, orgId} = o; if (!base) return errFrame(...)`.
+ * Every effect below was calling it as `call(m, p, {agentRoot, client, base,
+ * token})` with `base`/`token` undefined, because `defaultEffects` is built by
+ * `scripts/daemon/agent-daemon.mjs#runExecutionLadder` as
+ * `defaultEffects({agentRoot, me, react})` — the daemon has an agent root and
+ * nothing else to give.
+ *
+ * The result, live: EVERY network effect the execution ladder owns returned
+ *
+ *     {ok:false, error:{code:"BAD_REQUEST", message:"missing base"}}
+ *
+ * before a single byte left the machine. The ladder could decide to escalate and
+ * could never actually escalate. `agentRoot` was accepted, forwarded, and
+ * silently ignored one layer down.
+ *
+ * An agent root IS the org binding (`config/org.yaml` + the env token fallbacks
+ * in `client.configFromAgent`), so resolving it here is not a new mechanism —
+ * it is calling the loader every other org module already calls.
+ *
+ * @param {object} o {agentRoot, base, token, orgId}
+ * @returns {Promise<{base:string, token:string, orgId:string}>}
+ */
+async function orgConn(o = {}) {
+  if (o.base) return { base: o.base, token: o.token, orgId: o.orgId };
+  const { loadOrgConfig, configFromAgent } = await import("../org/client.mjs");
+  const c = configFromAgent(loadOrgConfig(resolveAgentRoot(o.agentRoot)));
+  return {
+    base: c.base,
+    token: o.token || c.token,
+    orgId: o.orgId || c.orgId,
+  };
+}
+
+/**
+ * Render an RPC error frame as a LINE, not as `[object Object]`.
+ *
+ * `String({code, message})` is `"[object Object]"`, and that is exactly what
+ * every effect below used to hand back — so the daemon's fall-through logged
+ * `escalate effect failed for … ([object Object])` and the operator learned
+ * nothing at all about why. Errors are the one thing that must never be lossy.
+ *
+ * @param {any} err
+ * @returns {string|null}
+ */
+export function errText(err) {
+  if (err == null) return null;
+  if (typeof err === "string") return err;
+  if (typeof err === "object") {
+    const code = err.code ? String(err.code) : "";
+    const msg = err.message ? String(err.message) : "";
+    if (code || msg) return code && msg ? `${code}: ${msg}` : code || msg;
+    try { return JSON.stringify(err); } catch { return String(err); }
+  }
+  return String(err);
+}
 
 /** Where scheduled work lands — a queue file the daemon's sweep already reads. */
 export const INBOUND_QUEUE_REL = "state/queues/inbound.yaml";
@@ -67,13 +133,68 @@ function queueItemId(decision) {
   return `inb-${raw.replace(/[^A-Za-z0-9._#:@-]/g, "-").slice(0, 80)}`;
 }
 
+/**
+ * One line saying what the queued work actually IS, for the session that will
+ * drain the row. Collapsed to a single line because `parseQueueItems` splits
+ * items on a `- ` at line start — a body line beginning with a dash would tear
+ * the item in half — and truncated because a queue row is an instruction, not
+ * an archive.
+ */
+function contextLine(item, candidate) {
+  const bits = [];
+  const subject = item && typeof item.subject === "string" ? item.subject.trim() : "";
+  const content = item && typeof item.content === "string" ? item.content.trim() : "";
+  // WHERE it happened. A call invite hydrates to the two words "Call invite";
+  // the room it was called in is the only thing that makes it answerable.
+  const where = item && typeof item.channel === "string" ? item.channel.trim() : "";
+  const who = item && typeof item.sender === "string" ? item.sender.trim() : "";
+  if (subject) bits.push(subject);
+  if (where) bits.push(`in ${where}`);
+  if (who) bits.push(`from ${who}`);
+  if (content && content !== subject) bits.push(content);
+  if (!bits.length && candidate && candidate.ids) {
+    // No inbox body (a raw-event caller). The candidate's own ids are still a
+    // better instruction than nothing at all.
+    for (const [k, v] of Object.entries(candidate.ids)) {
+      if (typeof v === "string" && v) bits.push(`${k}=${v}`);
+    }
+  }
+  return bits.join(" — ").replace(/\s*\n+\s*/g, " · ").slice(0, 600);
+}
+
+/**
+ * The concrete protocol method the queued work would call, in priority order:
+ * what the router already decided, then the bound obligation's `uses[]`, then
+ * the surface policy's `queueUses` fallback. Returns [] when nothing knows —
+ * and an empty list is written as an empty field rather than a guess.
+ */
+function usesFor(decision) {
+  const fromAction = decision && decision.action && decision.action.method;
+  if (fromAction) return [String(fromAction)];
+  const fromObligation = decision && Array.isArray(decision.uses) ? decision.uses.filter(Boolean) : [];
+  if (fromObligation.length) return fromObligation.map(String);
+  const policy = policyFor(decision && decision.policySurface ? decision.policySurface : decision && decision.surface);
+  const fallback = policy && Array.isArray(policy.queueUses) ? policy.queueUses : [];
+  return fallback.map(String);
+}
+
 /**
  * Append one item to `state/queues/inbound.yaml`, creating the file with its
  * header when absent. Idempotent on the item id: an id already present in the
  * file is a no-op, so a retry of the same decision cannot double-queue.
  *
+ * THE ROW MUST BE ACTIONABLE. It used to carry the decision and nothing else:
+ * `event_key`, `thread`, `rung`, `why`. A live calendar invite queued through
+ * it produced `next_action: "Handle the calendar event calendar.calendar#8261
+ * at rung 1"` — an event key built from the LEDGER SEQ, with the meeting id
+ * buried inside `thread` and the title, the time and the method absent
+ * entirely. `buildBacklogContext` then rendered that row into a prompt, and the
+ * session it dispatched had nothing to RSVP. The decision reached the queue;
+ * the WORK did not. So the subject travels with it now: `entity_id`,
+ * `source_ref`, `context`, `uses`.
+ *
  * @param {object} decision
- * @param {object} [o] { agentRoot, nowMs }
+ * @param {object} [o] { agentRoot, nowMs, candidate, item }
  * @returns {{ok:boolean, ref:object|null, error:string|null}}
  */
 export function scheduleToQueue(decision, o = {}) {
@@ -107,11 +228,36 @@ export function scheduleToQueue(decision, o = {}) {
       }
     }
 
-    const title = `${decision.surface || "inbound"}: ${decision.reason || "queued"}`;
-    const nextAction =
-      decision.disposition === "schedule" && decision.surface
-        ? `Handle the ${decision.surface} event ${decision.key} at rung ${decision.rung ?? "?"}`
-        : `Handle ${decision.key}`;
+    const candidate = o.candidate || null;
+    const item = o.item || null;
+    const entityId =
+      (candidate && (candidate.entityId || (candidate.ids && candidate.ids.entityId))) ||
+      (item && (item.thread_id || item.id)) ||
+      "";
+    const sourceRef = (item && item.raw_ref) || (candidate && candidate.rawRef) || "";
+    const context = contextLine(item, candidate);
+    const uses = usesFor(decision);
+
+    // The title is what an operator scanning the queue reads, so it names the
+    // thing, not the verdict. "calendar: not_respondable" told nobody anything.
+    const subject = (item && typeof item.subject === "string" && item.subject.trim()) || "";
+    const title = subject
+      ? `${decision.surface || "inbound"}: ${subject}`.slice(0, 160)
+      : `${decision.surface || "inbound"}: ${decision.reason || "queued"}`;
+
+    let nextAction;
+    if (decision.disposition === "schedule" && decision.surface) {
+      const target = entityId ? ` ${entityId}` : "";
+      const method = uses.length ? ` using ${uses.join(" / ")}` : "";
+      nextAction = `Handle the ${decision.surface}${target}${method} (rung ${decision.rung ?? "?"}, ${decision.reason || "queued"})`;
+      if (!entityId) {
+        // FAIL-OPEN IS FINE; SILENT IS NOT. A row with no subject is the exact
+        // dead end this field exists to close, so say so on the row itself.
+        nextAction += " — WARNING: no entity id reached the queue; the drain cannot address this";
+      }
+    } else {
+      nextAction = `Handle ${decision.key}`;
+    }
 
     const lines = [
       `  - id: ${yamlScalar(id)}`,
@@ -122,9 +268,32 @@ export function scheduleToQueue(decision, o = {}) {
       `    created: ${yamlScalar(new Date(nowMs).toISOString())}`,
       `    surface: ${yamlScalar(decision.surface || "")}`,
       `    event_key: ${yamlScalar(decision.key || "")}`,
+      // The three fields that make the row addressable rather than merely
+      // traceable. `entity_id` is the thing to act ON, `uses` is the method to
+      // act WITH, `context` is what actually arrived.
+      `    entity_id: ${yamlScalar(entityId)}`,
+      `    source_ref: ${yamlScalar(sourceRef)}`,
+      `    uses: ${yamlScalar(uses.join(","))}`,
+      `    context: ${yamlScalar(context)}`,
       `    thread: ${yamlScalar(decision.thread || "")}`,
       `    rung: ${Number.isFinite(decision.rung) ? decision.rung : "null"}`,
       `    obligation_key: ${yamlScalar(decision.obligationKey || "")}`,
+      // THE LEARNING LINK. `lib/goals/loop.openItemsFor` selects the work that is
+      // in flight against an objective by reading `advances: [...]`, and
+      // `journalRealizedDeltas` scores each of those against the next KPI sample
+      // via `lib/kpi.recordIntervention`. Without these two lines a board item the
+      // ladder queued was structurally invisible to that loop: the row named its
+      // obligation but never the OBJECTIVE that obligation serves, so reactive
+      // work could never move a number, and no intervention was ever scored for
+      // it. Traced end-to-end on a live board assignment — the journey reached
+      // the queue and stopped dead there.
+      //
+      // `decision.objectiveId` comes from the matched obligation
+      // (lib/execution/disposition.mjs). An UNCOVERED event has none; the row then
+      // says `advances: []`, which reads correctly as "this advances nothing
+      // anyone has adopted" rather than silently omitting the field.
+      `    advances: [${decision.objectiveId ? String(decision.objectiveId) : ""}]`,
+      `    expected_delta: ${Number.isFinite(decision.expectedDelta) ? decision.expectedDelta : "null"}`,
       // The reasoning travels WITH the work. A queue item whose provenance is a
       // mystery is a queue item nobody trusts enough to action.
       `    why: ${yamlScalar((decision.why || []).join(" | "))}`,
@@ -227,7 +396,12 @@ export function defaultEffects(o = {}) {
   return {
     react: typeof o.react === "function" ? o.react : undefined,
 
-    schedule: async ({ decision }) => scheduleToQueue(decision, common),
+    // `candidate` was already on the wire from `drive` and was being dropped on
+    // the floor here — it carries the entity id the queued row needs to be
+    // addressable at all. `item` is the originating inbox item when the caller
+    // has one (the daemon's ladder passes it); absent for raw-event callers.
+    schedule: async ({ decision, candidate, item }) =>
+      scheduleToQueue(decision, { ...common, candidate, item: item || o.item || null }),
 
     delegate: async ({ decision, candidate }) => {
       const { sendHandoff } = await import("../org/handoff.mjs");
@@ -248,27 +422,111 @@ export function defaultEffects(o = {}) {
       return { ok: r && r.ok !== false, ref: r, error: r && r.error ? String(r.error) : null };
     },
 
-    escalate: async ({ decision }) => {
+    /**
+     * Raise the decision up the line.
+     *
+     * ── TWO METHODS, CHOSEN BY SHAPE ──
+     * hq's `escalation` family carries two different entities and this effect
+     * has to pick the right one, because neither accepts the other's params:
+     *
+     *   `escalation.ask`    → an **OpenQuestion**. Requires ≥2 distinct options
+     *                         (hq `methods/escalation/ask.ts` 400s on fewer:
+     *                         "a question with fewer is a message, not a
+     *                         decision"). This is the shape a human can act on
+     *                         in one click, and it is what `disposition.mjs`
+     *                         rules 6/7/8 are documented to produce.
+     *   `escalation.create` → an **Escalation**: a blockage flag. Requires
+     *                         `title` AND at least one of `taskId`/`channelId`
+     *                         (hq `methods/escalation/create.ts`).
+     *
+     * ── WHAT WAS BROKEN ──
+     * This effect sent `escalation.create({summary, waitingOnMemberId, options,
+     * context:{…}})`. Against the live handler that is four faults at once:
+     * `summary` is not `title` (the param contract aliases `subject→title`, not
+     * `summary`), no `taskId`/`channelId` was ever supplied so the `oneOf`
+     * refine could not pass, `waitingOnMemberId` is not a field hq reads on this
+     * method, and `context` is a STRING there, not an object. So the escalation
+     * lane 400'd on every call — and `escalation.ask`, the method the ladder's
+     * own comments name, had no caller anywhere in the repo.
+     *
+     * ── REDACTION ──
+     * Unchanged and load-bearing: ids, surfaces and machine reasons only. No
+     * message body, no room name, no address ever reaches either method. The
+     * question below is assembled from the decision, never from the event text.
+     */
+    escalate: async ({ decision, candidate }) => {
       const { call } = await import("../org/client.mjs");
+      const conn = await orgConn({ agentRoot, base: o.base, token: o.token, orgId: o.orgId });
+      if (!conn.base) {
+        return { ok: false, ref: null, error: "org not configured (no base) — cannot escalate" };
+      }
+
+      const surface = decision.surface || "inbound";
+      const ids = (candidate && candidate.ids) || {};
+      const options = (decision.options || [])
+        .map((l) => String(l || "").trim())
+        .filter(Boolean);
+
+      // ≥2 concrete options ⇒ a DECISION. Ask it.
+      if (options.length >= 2) {
+        const r = await call(
+          "escalation.ask",
+          {
+            question:
+              `${surface} ${decision.key || ""}: I stopped at \`${decision.reason}\` and may not ` +
+              "decide this myself. Which way should it go?",
+            options: options.map((label) => ({ label })),
+            // hq's `context` is a STRING (≤4000). Ids + reasoning only.
+            context: [
+              `event_key: ${decision.key || "?"}`,
+              `surface: ${surface}`,
+              `obligation: ${decision.obligationKey || "(uncovered)"}`,
+              `rung: ${decision.rung ?? "?"} (${decision.mechanism || "?"})`,
+              ...(decision.why || []).map((w) => `why: ${w}`),
+            ].join("\n").slice(0, 4000),
+            trigger: String(decision.reason || "escalate").slice(0, 100),
+          },
+          { ...conn, agentRoot },
+        );
+        return {
+          ok: !!r && r.ok !== false,
+          ref: { method: "escalation.ask", frame: r },
+          error: r && r.error ? errText(r.error) : null,
+        };
+      }
+
+      // Fewer than two options ⇒ a BLOCKAGE. Flag it — but only if there is
+      // something to flag it against, because hq requires a target and a made-up
+      // one is worse than an honest refusal.
+      const taskId = ids.taskId || ids.itemId || null;
+      const channelId = ids.channelId || null;
+      if (!taskId && !channelId) {
+        return {
+          ok: false,
+          ref: null,
+          error:
+            `escalation.create needs a taskId or channelId and ${surface} event ` +
+            `${decision.key} carries neither; escalation.ask needs ≥2 options and ` +
+            `the decision offered ${options.length}. Nothing was raised.`,
+        };
+      }
       const r = await call(
         "escalation.create",
         {
-          // No message bodies, ever — ids and reasons only. `assertRedactionSafe`
-          // bans addresses and content, not member ids.
-          summary: `${decision.surface || "inbound"}: ${decision.reason}`,
-          waitingOnMemberId: decision.escalateTo || o.escalationTarget || undefined,
-          options: (decision.options || []).map((label) => ({ label: String(label) })),
-          context: {
-            event_key: decision.key,
-            surface: decision.surface,
-            thread: decision.thread,
-            obligation_key: decision.obligationKey || null,
-            why: decision.why,
-          },
+          title: `${surface}: ${decision.reason}`.slice(0, 500),
+          detail: (decision.why || []).join("; ").slice(0, 2000),
+          waitingOn: decision.escalateTo || o.escalationTarget || undefined,
+          resolvable: true,
+          ...(taskId ? { taskId: String(taskId) } : {}),
+          ...(channelId ? { channelId: String(channelId) } : {}),
         },
-        { agentRoot, client: o.client, base: o.base, token: o.token },
+        { ...conn, agentRoot },
       );
-      return { ok: !!r && r.ok !== false, ref: r, error: r && r.error ? String(r.error) : null };
+      return {
+        ok: !!r && r.ok !== false,
+        ref: { method: "escalation.create", frame: r },
+        error: r && r.error ? errText(r.error) : null,
+      };
     },
 
     requestApproval: async ({ decision, classes }) => {

package/lib/execution/effects.test.mjs

@@ -17,6 +17,7 @@ import {
   writeDrift,
   writeProposal,
   defaultEffects,
+  errText,
   INBOUND_QUEUE_REL,
   DRIFT_REL,
   PROPOSED_REL,
@@ -191,3 +192,114 @@ test("the default propose + reportDrift effects write through", async () => {
     assert.ok(existsSync(join(root, DRIFT_REL)));
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
+
+// ───────────────────────────────────────────────────────────────────────────
+// The joint: does the escalate effect actually reach the org?
+// ───────────────────────────────────────────────────────────────────────────
+
+import { writeFileSync as _wf, mkdirSync as _mk } from "node:fs";
+
+/** An agent root with a real config/org.yaml, as `maestro setup` writes it. */
+function enrolledRoot() {
+  const root = mkdtempSync(join(tmpdir(), "effects-org-"));
+  _mk(join(root, "config"), { recursive: true });
+  _wf(
+    join(root, "config", "org.yaml"),
+    "org:\n  cohort:\n    enabled: true\n    base: https://example.invalid\n    orgId: org_t\n    token: tok_t\n",
+  );
+  return root;
+}
+
+test("escalate resolves the org binding from the agent root — `agentRoot` alone used to be ignored", async () => {
+  // `client.call()` reads `o.base` and nothing else; `defaultEffects` is built by
+  // the daemon as `{agentRoot, me, react}`. So every network effect returned
+  // BAD_REQUEST "missing base" before a byte left the machine: the ladder could
+  // decide to escalate and could never escalate.
+  const root = enrolledRoot();
+  const seen = [];
+  const orig = globalThis.fetch;
+  globalThis.fetch = async (url, init) => {
+    seen.push({ url: String(url), body: JSON.parse(init.body) });
+    return new Response(JSON.stringify({ ok: true, result: { id: "oq_1" } }), {
+      status: 200, headers: { "content-type": "application/json" },
+    });
+  };
+  try {
+    const eff = defaultEffects({ agentRoot: root, me: "M-1" });
+    const r = await eff
+      .escalate({
+        decision: {
+          key: "approval.requested#1", surface: "approval", reason: "cannot_self_decide",
+          rung: 1, mechanism: "claude-skill", why: ["a", "b"],
+          options: ["approve it", "reject it"],
+        },
+        candidate: { ids: { taskId: "T-1" } },
+      });
+    {
+        assert.equal(r.ok, true, r.error || "escalate failed");
+        assert.equal(seen.length, 1, "no request was made");
+        assert.match(seen[0].url, /escalation\.ask$/, "≥2 options must go to ask, not create");
+        assert.equal(seen[0].body.options.length, 2);
+        assert.equal(typeof seen[0].body.context, "string", "hq's `context` is a STRING");
+        assert.equal(seen[0].body.trigger, "cannot_self_decide");
+        assert.ok(seen[0].body.question, "hq requires a question");
+    }
+  } finally {
+    globalThis.fetch = orig;
+  }
+});
+
+test("fewer than two options falls back to escalation.create WITH a target", async () => {
+  const root = enrolledRoot();
+  const seen = [];
+  const orig = globalThis.fetch;
+  globalThis.fetch = async (url, init) => {
+    seen.push({ url: String(url), body: JSON.parse(init.body) });
+    return new Response(JSON.stringify({ ok: true, result: { id: "esc_1" } }), {
+      status: 200, headers: { "content-type": "application/json" },
+    });
+  };
+  try {
+    const eff = defaultEffects({ agentRoot: root, me: "M-1" });
+    const r = await eff
+      .escalate({
+        decision: { key: "k", surface: "task_comment", reason: "stuck", why: ["x"], options: [] },
+        candidate: { ids: { taskId: "T-7" } },
+      });
+    {
+        assert.equal(r.ok, true);
+        assert.match(seen[0].url, /escalation\.create$/);
+        assert.ok(seen[0].body.title, "hq requires a title, not a `summary`");
+        assert.equal(seen[0].body.taskId, "T-7", "hq requires a taskId or channelId");
+    }
+  } finally {
+    globalThis.fetch = orig;
+  }
+});
+
+test("no options AND no target REFUSES loudly rather than 400ing on the wire", async () => {
+  const root = enrolledRoot();
+  const orig = globalThis.fetch;
+  let called = 0;
+  globalThis.fetch = async () => { called += 1; return new Response("{}", { status: 200 }); };
+  try {
+    const eff = defaultEffects({ agentRoot: root, me: "M-1" });
+    const r = await eff
+      .escalate({ decision: { key: "k", surface: "approval", reason: "r", why: [], options: [] }, candidate: { ids: {} } });
+    {
+        assert.equal(r.ok, false);
+        assert.match(r.error, /needs a taskId or channelId/);
+        assert.match(r.error, /Nothing was raised/);
+        assert.equal(called, 0, "a call that cannot succeed must not be made");
+    }
+  } finally {
+    globalThis.fetch = orig;
+  }
+});
+
+test("errText renders an RPC error frame as a line, never `[object Object]`", () => {
+  assert.equal(errText({ code: "BAD_REQUEST", message: "title is required" }), "BAD_REQUEST: title is required");
+  assert.equal(errText("plain"), "plain");
+  assert.equal(errText(null), null);
+  assert.notEqual(String(errText({ code: "X" })), "[object Object]");
+});

package/lib/execution/index.mjs

@@ -137,6 +137,7 @@ export async function handleInboundEvent(o = {}) {
 
   const res = await drive(decision, {
     candidate: o.candidate,
+    item: o.item,
     effects: o.effects,
     agentRoot: o.agentRoot,
     nowMs,

package/lib/execution/intake.mjs

@@ -319,26 +319,60 @@ export function fromInboxItem(item, o = {}) {
   }
 
   const mentions = !!(item.priority_signals && item.priority_signals.mentions_agent);
-  let reason = RECONSTRUCTED_REASON[surface] || "direct";
-  if (mentions && (reason === "thread" || reason === "shared" || reason === "owner")) {
-    // The one signal the flattening preserves, and it upgrades a lane-tier
-    // reason to a structural one — being named IS the strongest reason there is.
-    reason = "named";
-    why.push("priority_signals.mentions_agent → the item names me outright (T0)");
+
+  // PREFER THE REAL REASON. `lib/org/inbound/directedness.mjs` already worked
+  // out WHY this event is mine and `lib/channels/inbox-item.mjs` now carries the
+  // answer across the flattening as `direct_reason`. Guessing it from a
+  // per-surface default is a last resort, not the normal path: the guess feeds
+  // `disposition.tierOf`, so being wrong about the reason can be being wrong
+  // about the tier, and therefore about the decision. Observed: an approval
+  // blocking a task the seat REVIEWS was journalled "directed: approver on
+  // approval" — a false statement about the agent's own reasoning.
+  const carried = s(item.direct_reason);
+  let reason;
+  if (carried) {
+    reason = carried;
+    why.push(`org inbox item carries its directedness reason: ${reason}`);
+  } else {
+    reason = RECONSTRUCTED_REASON[surface] || "direct";
+    if (mentions && (reason === "thread" || reason === "shared" || reason === "owner")) {
+      // The one signal the flattening preserves, and it upgrades a lane-tier
+      // reason to a structural one — being named IS the strongest reason there is.
+      reason = "named";
+      why.push("priority_signals.mentions_agent → the item names me outright (T0)");
+    }
+    degraded.push(`verdict_reconstructed:${surface}`);
+    why.push(`org inbox item: reconstructing directed:true (it was written because the join said so), reason ${reason}`);
   }
-  degraded.push(`verdict_reconstructed:${surface}`);
-  why.push(`org inbox item: reconstructing directed:true (it was written because the join said so), reason ${reason}`);
 
   const ids = {};
   if (item.channel_id) ids.channelId = s(item.channel_id);
   if (item.thread_id) ids.threadId = s(item.thread_id);
   if (ref && ref.entityId) ids.entityId = ref.entityId;
   if (item.id) ids.messageId = s(item.id);
+  // The surface's own subject id (the blocked task, the decision, the file).
+  // Named per family so the consumers that ask for `ids.taskId` find it where
+  // they already look.
+  if (item.scope_id) {
+    const scopeId = s(item.scope_id);
+    const family = SURFACE_FAMILY[surface];
+    if (family === "decision") ids.decisionId = scopeId;
+    else if (family === "files") ids.fileId = scopeId;
+    else ids.taskId = scopeId;
+  }
 
   const candidate = candidateFrom({
     seq: ref ? ref.seq : null,
     family: SURFACE_FAMILY[surface],
-    kind: s(item.kind) || surface,
+    // PREFER THE CHAIN KIND. `item.event_kind` is the hq event kind the wide
+    // projection carried through the flattening (`item.blocked`,
+    // `item.commented`, …). `item.kind` is only the SURFACE, and ten board kinds
+    // share the surface `task_comment` — so without this an obligation written
+    // `{topic:task, kind:blocked}` binds on the push lane (where the candidate
+    // still has the chain kind) and reads UNCOVERED on the poll lane.
+    // `kindAliases` still derives the surface tokens from the verdict, so both
+    // vocabularies stay bindable on both lanes.
+    kind: s(item.event_kind) || s(item.kind) || surface,
     entityId: ref ? ref.entityId : s(item.id) || null,
     actor: s(item.sender_id) || s(item.sender),
     at: s(item.timestamp) || s(o.now),

package/lib/execution/intake.test.mjs

@@ -341,3 +341,49 @@ test("KIND_SURFACE covers every event kind the channel contract ships", async ()
   const missing = EVENT_KINDS.filter((k) => !["reaction", "channel_cc"].includes(k) && !KIND_SURFACE[k]);
   assert.deepEqual(missing, [], "a shipped event kind with no surface would fall through to the default policy");
 });
+
+// ───────────────────────────────────────────────────────────────────────────
+// The poll lane must agree with the push lane about WHY an event is mine.
+// ───────────────────────────────────────────────────────────────────────────
+
+test("a carried `direct_reason` beats the per-surface guess — the guess sets the TIER", () => {
+  // Before this, `fromInboxItem` re-derived the reason from a default table, so
+  // an approval blocking a task the seat REVIEWS was journalled as "directed:
+  // approver on approval". Since `disposition.tierOf` maps the reason onto the
+  // T0/T1 tier, guessing wrong is deciding wrong.
+  const guessed = fromInboxItem({
+    raw_ref: "cohort:approval:aprv_1:99",
+    kind: "approval",
+    id: "cohort-approval-99",
+    timestamp: NOW,
+  }, { me: ME });
+  assert.equal(guessed.verdict.reason, "approver", "the fallback guess is unchanged");
+  assert.ok(guessed.degraded.some((d) => /verdict_reconstructed/.test(d)));
+
+  const carried = fromInboxItem({
+    raw_ref: "cohort:approval:aprv_1:99",
+    kind: "approval",
+    id: "cohort-approval-99",
+    timestamp: NOW,
+    direct_reason: "reviewer",
+  }, { me: ME });
+  assert.equal(carried.verdict.reason, "reviewer");
+  assert.ok(
+    !carried.degraded.some((d) => /verdict_reconstructed/.test(d)),
+    "a carried reason is not a reconstruction and must not be reported as one",
+  );
+});
+
+test("`scope_id` lands on the id its family is looked up by", () => {
+  const approval = fromInboxItem(
+    { raw_ref: "cohort:approval:aprv_1:99", kind: "approval", id: "i", timestamp: NOW, scope_id: "T-9" },
+    { me: ME },
+  );
+  assert.equal(approval.candidate.ids.taskId, "T-9", "effects.escalate reads ids.taskId");
+
+  const decision = fromInboxItem(
+    { raw_ref: "cohort:decision:dec_1:99", kind: "decision", id: "i", timestamp: NOW, scope_id: "D-1" },
+    { me: ME },
+  );
+  assert.equal(decision.candidate.ids.decisionId, "D-1");
+});

package/lib/execution/pipeline.mjs

@@ -162,6 +162,11 @@ export async function processOne(o = {}) {
   const res = await handleInboundEvent({
     candidate: norm.candidate,
     verdict: norm.verdict,
+    // The ORIGINATING item travels with the decision. `intake` distils it down
+    // to a candidate + verdict — which is right for DECIDING — but an effect
+    // that has to hand the work to something else (the schedule queue, and any
+    // later drain) needs the subject back: the title, the body, the raw_ref.
+    item: o.item,
     me: o.me,
     history,
     runtime: o.runtime,