@nanobpm/nano-workforce 0.201.1 → 0.201.2

package/app/agentSlaEscalation.ts

@@ -0,0 +1,169 @@
+// Agent-task SLA-escalation reason builder (issue #879) — the single canonical, pure text builder for
+// the human-facing escalation raised when an agent service task's interrupting SLA timer boundary
+// fires. It distinguishes the two outcomes the old wording conflated:
+//
+//   • NEVER OBSERVED ACTIVATED — no worker was ever observed to pick the job up (almost certainly
+//     queue starvation / no capacity for the job type). The job sat CREATED for ~the whole SLA budget
+//     and was cancelled by the boundary. Telling the human it is "hung or looping" and to "check its
+//     progress" is a false diagnosis — the likely fix is CAPACITY, not intervention. The wording is
+//     hedged (a worker could lease it in the final moment before the boundary fires, between activation
+//     polls, unrecorded), so it reports the likely cause without over-claiming certainty.
+//   • STARTED BUT EXCEEDED — a worker leased the job (an agent ran) but did not complete within the
+//     budget — it may genuinely be hung or looping, and intervening / checking its progress is apt.
+//
+// The distinction is read from the durable activation ledger (`app/agentActivationLedger.ts`), which
+// the poller populates while the job is live. Every escalation names the JOB TYPE and HOW LONG it
+// waited, per the issue's acceptance criteria.
+//
+// Derivation over duplication: this is the ONE builder every agent-SLA recorder (implement-cell,
+// merge-cell, retro) routes through, so the never-started/hung wording can never drift between sites.
+// The pure `buildAgentSlaEscalationReason` is exhaustively testable; `agentSlaEscalationQuestion` is
+// the thin async wrapper that reads the ledger and calls it.
+import type { DataLayer } from "@nanobpm/urban";
+import { type AgentJobActivation, getAgentJobActivation } from "./agentActivationLedger.ts";
+import { isoDurationToMs } from "./reviewWait.ts";
+
+/** The activation facts the builder needs (a slice of the ledger row), or `null` when the poller never
+ * observed the job (activation unknown). */
+export interface AgentSlaActivation {
+  /** ISO ts a leasing worker was first observed; `null`/absent ⇒ never activated. */
+  activatedAt?: string | null;
+  /** ISO ts the job was first observed queued. */
+  firstSeenAt?: string | null;
+  /** The leasing worker's name, when known. */
+  worker?: string | null;
+}
+
+export interface AgentSlaEscalationInput {
+  /** The agent job type that timed out, e.g. `senior:feature`. Named in the reason. */
+  jobType: string;
+  /** The SLA budget (ISO-8601 duration) the boundary armed, e.g. `PT2H`. */
+  sla: string;
+  /** The activation record for this job, or `null` when the poller never observed it. */
+  activation: AgentSlaActivation | null;
+  /** The escalation moment (ISO ts) — the elapsed wait is measured against it. */
+  now: string;
+  /** How the human resumes after answering — appended verbatim so each caller keeps its own
+   * routing hint (e.g. "answer to resume … or abandon it"). */
+  recovery: string;
+}
+
+/** Humanise a millisecond span to a compact, human-facing string (e.g. `2h 5m`, `45m`, `30s`). A
+ * non-positive/NaN span renders `less than a minute`. */
+export function humanizeMs(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "less than a minute";
+  const totalMinutes = Math.floor(ms / 60_000);
+  if (totalMinutes < 1) return `${Math.max(1, Math.round(ms / 1000))}s`;
+  const days = Math.floor(totalMinutes / 1440);
+  const hours = Math.floor((totalMinutes % 1440) / 60);
+  const minutes = totalMinutes % 60;
+  const parts: string[] = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  return parts.join(" ") || "less than a minute";
+}
+
+/** Humanise an ISO-8601 duration (the SLA budget) to the same compact form, via the canonical parser. */
+export function humanizeIsoDuration(iso: string): string {
+  return humanizeMs(isoDurationToMs(iso, iso));
+}
+
+const elapsedMs = (fromIso: string | null | undefined, toIso: string): number | null => {
+  if (!fromIso) return null;
+  const from = Date.parse(fromIso);
+  const to = Date.parse(toIso);
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
+  return to - from;
+};
+
+/** Build the accurate, self-contained agent-SLA escalation reason. Pure — distinguishes never-started
+ * (queue starvation) from started-but-hung, names the job type and how long it waited, then appends
+ * the caller's recovery hint. */
+export function buildAgentSlaEscalationReason(input: AgentSlaEscalationInput): string {
+  const { jobType, sla, activation, now, recovery } = input;
+  const slaHuman = humanizeIsoDuration(sla);
+  const activatedAt = activation?.activatedAt ?? null;
+
+  if (activatedAt) {
+    // STARTED BUT EXCEEDED: a worker leased the job, so it may genuinely be hung or looping.
+    const queueMs = elapsedMs(activation?.firstSeenAt, activatedAt);
+    const queuedClause = queueMs !== null && queueMs > 0
+      ? ` (after waiting ~${humanizeMs(queueMs)} in the queue)`
+      : "";
+    const ranMs = elapsedMs(activatedAt, now);
+    const ranClause = ranMs !== null && ranMs > 0 ? ` and then ran for ~${humanizeMs(ranMs)}` : "";
+    const workerClause = activation?.worker ? ` (worker "${activation.worker}")` : "";
+    return (
+      `The ${jobType} agent started${queuedClause}${workerClause}${ranClause} but exceeded its time budget ` +
+      `(SLA ${sla} ≈ ${slaHuman}) without completing — it may be hung or looping. ${recovery}`
+    );
+  }
+
+  // Measure the wait: from first-seen to now when the poller observed the queued job, else the full
+  // SLA budget (the boundary fired exactly one budget after the task was entered).
+  const waitedMs = elapsedMs(activation?.firstSeenAt, now);
+  const waited = waitedMs !== null && waitedMs > 0 ? humanizeMs(waitedMs) : slaHuman;
+
+  if (activation === null) {
+    // ACTIVATION UNKNOWN: the poller never observed the job (e.g. the activation poll was unavailable).
+    // Report the ambiguity honestly rather than guessing "hung" or "never started".
+    return (
+      `The ${jobType} agent did not complete within its time budget (SLA ${sla} ≈ ${slaHuman}), and no ` +
+      `worker-activation was ever recorded for it, so we cannot confirm whether a worker ever picked it ` +
+      `up — it may have been starved of capacity for ${jobType}, or started and hung. ${recovery}`
+    );
+  }
+
+  // NEVER OBSERVED ACTIVATED: seen queued, never seen leased. This is the best-effort observation of
+  // queue starvation — hedged, because a worker could in principle lease the job in the final moment
+  // before the boundary cancels it, between activation polls, and that would not be recorded. We report
+  // the likely diagnosis (and its capacity fix) without over-claiming certainty.
+  return (
+    `No worker was ever observed to pick up the ${jobType} agent's job for its entire SLA budget ` +
+    `(SLA ${sla} ≈ ${slaHuman}): it was seen queued for ~${waited}, then the SLA boundary cancelled it. ` +
+    `This is almost certainly queue starvation (no capacity for ${jobType}) rather than a hung or ` +
+    `looping agent, so the likely fix is to add capacity for ${jobType} (enrol a worker that serves it, ` +
+    `or reduce concurrent demand) rather than to check a non-existent agent's progress. (If a worker ` +
+    `leased it in the final moment before the boundary fired, between activation polls, that would not ` +
+    `have been recorded here.) ${recovery}`
+  );
+}
+
+/** Read the activation ledger for this job and build the escalation reason — the thin async wrapper the
+ * recorder workers call. `processInstanceKey` is the instance the agent job AND its SLA recorder share,
+ * so the lookup is by (instance, jobType). An absent ledger row ⇒ activation unknown. */
+export async function agentSlaEscalationQuestion(
+  data: DataLayer,
+  input: {
+    processInstanceKey: string;
+    jobType: string;
+    sla: string;
+    recovery: string;
+    now?: string;
+  },
+): Promise<string> {
+  const now = input.now ?? new Date().toISOString();
+  let activation: AgentSlaActivation | null = null;
+  if (input.processInstanceKey && input.processInstanceKey.length > 0) {
+    const row: AgentJobActivation | undefined = await getAgentJobActivation(
+      data,
+      input.processInstanceKey,
+      input.jobType,
+    );
+    if (row) {
+      activation = {
+        activatedAt: row.activated_at,
+        firstSeenAt: row.first_seen_at,
+        worker: row.worker,
+      };
+    }
+  }
+  return buildAgentSlaEscalationReason({
+    jobType: input.jobType,
+    sla: input.sla,
+    activation,
+    now,
+    recovery: input.recovery,
+  });
+}

package/app/agentSlaMarkerGuard.test.ts

@@ -0,0 +1,172 @@
+// DEFECT-CLASS GUARD (PR #881 review, thread r4214170285): `agentSlaJobType` is the marker that
+// selects the agent-SLA escalation builder in the four recorder workers (`pr.persist-escalation`,
+// `pr.record-feature-escalation`, `pr.record-trial-merge`, `pr.conformance-record`). It is set
+// ONLY by the BPMN SLA arm (an interrupting timer boundary's route), never by the agent — but the
+// c8ctl harness HOISTS the agent's result-JSON keys into the SAME process-variable namespace the
+// recorders read it from. So a NORMAL (non-SLA) agent result that happens to carry an
+// `agentSlaJobType` key would wrongly select the SLA builder and replace a genuine question or
+// audit summary with a timeout diagnosis.
+//
+// This is the exact defect class PR #864 (review r4181010853) already closed for the boolean
+// SLA-control flags `agentSlaElapsed` / `preserveConformance` — by pinning each to a LITERAL on
+// every recorder task's ioMapping so hoisted agent output can never select the internal control
+// path. `agentSlaJobType` was left unpinned. This guard closes that gap: every NORMAL-path recorder
+// (one that does NOT set the marker to a real job-type literal) must pin `agentSlaJobType` to the
+// `=null` literal, so a hoisted agent-supplied value is overridden to null on the normal path.
+// SLA-arm recorders legitimately pin it to a job-type literal (e.g. `="senior:feature"`); those
+// are the trusted source and are NOT required to pin null.
+//
+// The guard scans the deployed corpus and fails if any recorder task reads `agentSlaJobType`
+// without pinning it to a literal (null on the normal path, a job-type on an SLA arm) — so a
+// newly-added or edited recorder can never re-open the hole.
+//
+// EXCEPTION — merge-loop's SHARED SLA-sink recorders (PR #881 review, adversarial round 3): unlike
+// the other processes, merge-loop has NO dedicated `*-sla` recorder task. Its fix-ci / rebase
+// interrupting-SLA arms (`end_ci_sla` → "senior:fix-ci", `end_reb_sla` → "senior:rebase") and its
+// NON-SLA escalation arms CONVERGE on the SAME two recorders (`merge-esc-attempt`,
+// `merge-esc-conflict`). So those two recorders MUST READ `agentSlaJobType` from process scope
+// (set by the trusted SLA end event) — a blanket `=null` input pin there would clobber the
+// legitimate SLA job type and silently regress the issue-#879 never-started-vs-hung diagnosis. The
+// hoisted-agent-output hole is closed on these shared sinks a DIFFERENT way: every path that can
+// carry a hoisted (spoofable) value CLEARS `agentSlaJobType` to null via an OUTPUT mapping before
+// it reaches the recorder — at the loop head (`arm-merge`, scrubbing any stale/cross-iteration
+// value), on the two non-SLA escalate end events that bypass the loop head (`end_ci_esc`,
+// `end_reb_blocked`), and on the CI reconcile re-check exit (`end_ci_recheck`, which re-enters the
+// merge wait via `gw-merge-entry` without passing through `arm-merge`). Only the trusted SLA arms
+// leave it set. This guard therefore (a) requires the shared sinks to NOT pin, and (b) requires
+// those clears + the SLA-arm literals to exist.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert } from "#test-assert";
+
+const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../resources/processes");
+const PROCESS_FILES = [
+  "convergence-loop.bpmn",
+  "merge-loop.bpmn",
+  "implement-cell.bpmn",
+  "merge-cell.bpmn",
+  "plan-fanout.bpmn",
+  "retro.bpmn",
+];
+
+// The recorder job types that read `agentSlaJobType` to select the SLA builder.
+const RECORDER_TYPES = [
+  "pr.persist-escalation",
+  "pr.record-feature-escalation",
+  "pr.record-trial-merge",
+  "pr.conformance-record",
+];
+
+const SERVICE_TASK = /<bpmn:serviceTask\b[\s\S]*?<\/bpmn:serviceTask>/g;
+// A trusted pin is a LITERAL input: `=null` (normal path) or `="..."`/`=&#34;...&#34;` (SLA arm's
+// job-type). A process-variable REFERENCE (e.g. `=agentSlaJobType`) is NOT a pin — it would read
+// hoisted agent output, which is exactly the hole being closed.
+const LITERAL_PIN =
+  /<zeebe:input\s+source="=(?:null|&#[0-9]+;[^"]*&#[0-9]+;|"[^"]*")"\s+target="agentSlaJobType"\s*\/>/;
+
+// Any INPUT mapping on `agentSlaJobType` (literal OR reference) — used to assert the shared SLA-sink
+// recorders carry NONE (they must read the SLA arm's value from process scope, not shadow it).
+const ANY_INPUT_PIN = /<zeebe:input\s+source="=[^"]*"\s+target="agentSlaJobType"\s*\/>/;
+// A `=null` OUTPUT clear (writes process scope) — the fail-closed scrub on merge-loop's spoofable
+// non-SLA paths.
+const NULL_OUTPUT_CLEAR = /<zeebe:output\s+source="=null"\s+target="agentSlaJobType"\s*\/>/;
+
+// merge-loop's two SHARED SLA-sink recorders: both SLA and non-SLA arms converge on them, so they
+// MUST read `agentSlaJobType` from scope and MUST NOT pin it (see header).
+const SHARED_SLA_SINKS = new Set(["merge-esc-attempt", "merge-esc-conflict"]);
+
+/** Extract the XML block for a BPMN element by id (any element tag). */
+function elementBlock(xml: string, id: string): string | undefined {
+  const re = new RegExp(`<bpmn:(\\w+)\\b[^>]*\\bid="${id}"[\\s\\S]*?</bpmn:\\1>`);
+  return xml.match(re)?.[0];
+}
+
+test("DEFECT-CLASS GUARD: every SLA-builder recorder pins agentSlaJobType to a literal (agent output cannot select the SLA path)", () => {
+  let recorderCount = 0;
+  for (const file of PROCESS_FILES) {
+    const xml = readFileSync(join(PROCESSES_DIR, file), "utf8");
+    for (const [block] of xml.matchAll(SERVICE_TASK)) {
+      if (!RECORDER_TYPES.some((t) => block.includes(`type="${t}"`))) continue;
+      const id = block.match(/<bpmn:serviceTask\b[^>]*\bid="([^"]*)"/)?.[1] ?? "(unknown)";
+      // The shared SLA-sink recorders read the marker from scope — they must NOT pin it, else a
+      // `=null` pin would clobber the trusted SLA job type (issue #879 regression). They are
+      // protected by the OUTPUT clears asserted below, not by an input pin.
+      if (SHARED_SLA_SINKS.has(id)) {
+        assert(
+          !ANY_INPUT_PIN.test(block),
+          `${file}: shared SLA-sink recorder "${id}" must NOT pin agentSlaJobType — both the SLA ` +
+            `and non-SLA arms converge on it, so it must READ the SLA end event's value from ` +
+            `process scope. A =null pin here clobbers the trusted SLA job type and regresses the ` +
+            `never-started-vs-hung diagnosis (PR #881 adversarial review). Remove the pin; the ` +
+            `hole is closed by the =null OUTPUT clears on arm-merge / end_ci_esc / end_reb_blocked.`,
+        );
+        continue;
+      }
+      recorderCount++;
+      assert(
+        LITERAL_PIN.test(block),
+        `${file}: recorder task "${id}" reads agentSlaJobType but does not pin it to a literal ` +
+          `(=null on the normal path, a job-type literal on an SLA arm). A hoisted agent result ` +
+          `carrying agentSlaJobType would wrongly select the SLA escalation builder (PR #881 review ` +
+          `r4214170285). Pin it: <zeebe:input source="=null" target="agentSlaJobType" /> on the ` +
+          `normal path.`,
+      );
+    }
+  }
+  // Sanity: the guard is not vacuously green — the corpus really has these recorders (the
+  // normal-path recorders + the SLA arms across the six processes).
+  assert(recorderCount >= 11, `expected >=11 SLA-builder recorder tasks, found ${recorderCount}`);
+});
+
+test("DEFECT-CLASS GUARD: merge-loop's shared SLA sinks are fed a trusted agentSlaJobType (SLA arms set it; spoofable non-SLA paths clear it)", () => {
+  const xml = readFileSync(join(PROCESSES_DIR, "merge-loop.bpmn"), "utf8");
+
+  // The two shared sinks really exist and read from scope (no input pin) — guards against the file
+  // being renamed/removed and silently passing.
+  for (const id of SHARED_SLA_SINKS) {
+    const block = elementBlock(xml, id);
+    assert(block, `merge-loop.bpmn: expected shared SLA-sink recorder "${id}" to exist`);
+    assert(
+      !ANY_INPUT_PIN.test(block),
+      `merge-loop.bpmn: "${id}" must read agentSlaJobType from scope, not pin it`,
+    );
+  }
+
+  // The trusted SLA arms SET the job-type literal (this is the value the shared sinks must receive).
+  for (const [id, literal] of [
+    ["end_ci_sla", "senior:fix-ci"],
+    ["end_reb_sla", "senior:rebase"],
+  ] as const) {
+    const block = elementBlock(xml, id);
+    assert(block, `merge-loop.bpmn: expected SLA arm "${id}" to exist`);
+    const re = new RegExp(
+      `<zeebe:output\\s+source="=&#34;${literal.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&")}&#34;"\\s+target="agentSlaJobType"\\s*/>`,
+    );
+    assert(
+      re.test(block),
+      `merge-loop.bpmn: SLA arm "${id}" must set agentSlaJobType to the "${literal}" literal via ` +
+        `an output mapping (the trusted source the shared sink reads).`,
+    );
+  }
+
+  // Every spoofable path that can carry a hoisted agentSlaJobType into a shared sink CLEARS it to
+  // null via output BEFORE the recorder: the loop head (stale/cross-iteration), the two non-SLA
+  // escalate end events that bypass the loop head (same-iteration agent spoof), and the CI
+  // reconcile re-check exit (`end_ci_recheck`), which re-enters the merge wait via `gw-merge-entry`
+  // — bypassing `arm-merge` — so a fix-ci result with status:"blocked"/pushed:false carrying a
+  // hoisted marker would otherwise reach `merge-esc-conflict` on a later draft/budget-exhausted
+  // merge with no SLA timer having fired (PR #881 review, "Previously missed" r5451284362).
+  for (const id of ["arm-merge", "end_ci_esc", "end_reb_blocked", "end_ci_recheck"]) {
+    const block = elementBlock(xml, id);
+    assert(block, `merge-loop.bpmn: expected "${id}" to exist`);
+    assert(
+      NULL_OUTPUT_CLEAR.test(block),
+      `merge-loop.bpmn: "${id}" must clear agentSlaJobType to null via ` +
+        `<zeebe:output source="=null" target="agentSlaJobType" /> so a hoisted (spoofable) agent ` +
+        `value can never reach the shared SLA-sink recorder and fabricate a never-started/hung ` +
+        `SLA diagnosis (PR #881 adversarial review).`,
+    );
+  }
+});

package/app/mergeLoopBehaviour.test.ts

@@ -28,7 +28,7 @@
 // Plus the terminate semantics the refactor had to preserve: `MergeAbandoned`
 // terminates the whole instance (it stays at the root, not inside a sub-process).
 import { after, test } from "node:test";
-import { assert, assertStringIncludes } from "#test-assert";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import { readFileSync } from "node:fs";
 import {
   assertThatInstance,
@@ -562,6 +562,10 @@ test("the fix-ci agent SLA interrupts the sub-process and escalates", async () =
   await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
   assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
   assertStringIncludes(String(escalation(engine).question ?? ""), "time budget (SLA)", "the SLA escalation must name the SLA trigger");
+  // #879 regression: the trusted fix-ci SLA arm must deliver its job-type marker to the shared
+  // persist-escalation sink so the worker builds the never-started-vs-hung diagnosis — a =null
+  // input pin on the shared recorder silently clobbered this (PR #881 adversarial review).
+  assertEquals(escalation(engine).agentSlaJobType, "senior:fix-ci", "the fix-ci SLA arm must reach the recorder with its job-type marker");
 });
 
 // ---------------------------------------------------------------------------
@@ -613,8 +617,49 @@ test("the rebase agent SLA interrupts the sub-process and escalates as not-merge
   await engine.advanceTime(AGENT_SLA_MS + 1);
   await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
   assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  // #879 regression: the trusted rebase SLA arm must deliver its job-type marker to the shared sink.
+  assertEquals(escalation(engine).agentSlaJobType, "senior:rebase", "the rebase SLA arm must reach the recorder with its job-type marker");
 });
 
+test("a non-SLA escalation carrying a spoofed agentSlaJobType is scrubbed before the recorder (#879 fail-closed)", async () => {
+  // The c8ctl harness hoists an agent's result-JSON keys into process scope, so a NON-SLA rebase
+  // agent that returns a bogus `agentSlaJobType` must NOT be able to fabricate an SLA diagnosis on
+  // the shared persist-escalation sink. The loop head / non-SLA escalate end events clear it.
+  const engine = await boot({ responses: { "senior:rebase": { status: "blocked", agentSlaJobType: "senior:evil" } } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  const spoofed = escalation(engine).agentSlaJobType;
+  assert(spoofed === null || spoofed === undefined, `a spoofed agentSlaJobType must be scrubbed, got ${JSON.stringify(spoofed)}`);
+});
+
+test("a spoofed agentSlaJobType surviving the CI-reconcile re-check route is scrubbed before a later merge-esc-conflict (#881 Previously-missed)", async () => {
+  // The CI reconcile route (fix-ci blocked/pushed:false → ci-reconcile → end_ci_recheck →
+  // gw-merge-entry) re-enters the merge wait WITHOUT passing through the loop head `arm-merge` or
+  // the non-SLA escalate clears. A hoisted (spoofable) agentSlaJobType from that fix-ci result
+  // would otherwise survive into a later draft / budget-exhausted merge and fabricate an SLA
+  // never-started/hung diagnosis on the shared merge-esc-conflict sink with NO SLA timer having
+  // fired. `end_ci_recheck` must clear it (PR #881 review, "Previously missed" r5451284362).
+  const engine = await boot({
+    responses: { "senior:fix-ci": { status: "blocked", pushed: false, agentSlaJobType: "senior:evil" } },
+  });
+  await driveToCiFix(engine); // blocked/pushed:false → ci-reconcile → end_ci_recheck → re-check mergeable
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("ci-reconcile")
+    .hasVariable("ciBlockedReconciled", true);
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "the reconcile pass must not escalate yet");
+  // A later merge-ready reports the PR as draft → f_m_mDraft → merge-esc-conflict reads the marker
+  // directly (the fix-ci agent does NOT run again on this route).
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "draft" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  const spoofed = escalation(engine).agentSlaJobType;
+  assert(spoofed === null || spoofed === undefined, `the reconcile-route spoof must be scrubbed, got ${JSON.stringify(spoofed)}`);
+  // The human gets the genuine draft question, not a fabricated SLA diagnosis.
+  assertStringIncludes(String(escalation(engine).question ?? ""), "draft", "the escalation must be the genuine draft question, not an SLA diagnosis");
+});
 // ---------------------------------------------------------------------------
 // Escalation user task (mergeEscalationUserTask #256, mergeEscalationQuestion #329/#454)
 // ---------------------------------------------------------------------------

package/app/service.ts

@@ -10,6 +10,7 @@
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { ABANDONED_STATUS, abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { matchAdjudication, prAdjudications, resetAdjudications } from "./adjudications.ts";
+import { AGENT_SLA_JOB_TYPES, recordAgentJobObservation } from "./agentActivationLedger.ts";
 import { completeEscalationAutoApplied, escalationFormId } from "./agentCompletion.ts";
 import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import {
@@ -1733,6 +1734,98 @@ interface JobSearchItem {
   /** The job's `zeebe:taskDefinition` type — read to defensively re-filter the wire `$in` type
    * filter so a non-agent job can never masquerade as a leasing convergence agent. */
   type?: string;
+  /** The owning process instance — keyed into the activation ledger (issue #879). */
+  processInstanceKey?: string;
+  /** The engine job key — the unique id of THIS job attempt. The activation ledger uses it to tell one
+   * attempt of a retrying agent task from the next (issue #879 review). */
+  jobKey?: string;
+}
+
+/** One agent-activation ledger poll pass (issue #879). Unlike {@link pollJobActivationImpl} (which
+ * tracks only the review-round for the pages grid), this records — for EVERY bounded agent job type —
+ * whether a worker ever picked the job up, into the durable `agent_job_activations` ledger. When an
+ * agent-task SLA boundary later cancels a job, the job's engine state is gone, so the escalation
+ * recorder cannot ask the engine whether it was ever activated; this ledger, captured WHILE the job is
+ * live, is what lets the escalation distinguish a NEVER-ACTIVATED (queue-starved) job from an
+ * ACTIVATED-but-hung one.
+ *
+ * It reads the same activation signal as the review-round pass: the Camunda-8 `/v2/jobs/search` wire
+ * API collapses Activated -> CREATED (no ACTIVATED enum), so a leased job is recognised by its
+ * `worker`/`deadline` fields. One paged search across all bounded agent types per pass upserts the
+ * ledger by (processInstanceKey, type), keyed to the current attempt by `jobKey`. Best-effort: a
+ * transport failure leaves the ledger untouched and the next pass retries. */
+async function pollAgentActivations(
+  data: DataLayer,
+  restAddress: string,
+  engineToken: string | undefined,
+) {
+  const base = restAddress.replace(/\/+$/, "");
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (engineToken) headers.authorization = `Bearer ${engineToken}`;
+  await pollAgentActivationsImpl(data, base, headers);
+}
+
+/** Testable core of {@link pollAgentActivations}: query the engine for every CREATED bounded-agent job
+ * and upsert the activation ledger. Split out so tests can drive it with a stubbed `fetch`. */
+export async function pollAgentActivationsImpl(
+  data: DataLayer,
+  base: string,
+  headers: Record<string, string>,
+) {
+  // Page through EVERY matching open job: a single first-page read would, under fleet saturation, let
+  // long-lived jobs occupy the page on every pass while later jobs time out with their activation never
+  // recorded — exactly when the never-started/hung distinction matters most. Mirror the paging contract
+  // the other engine sweeps use (`page: { from, limit }`, stop on a short page). (#881 review)
+  const ts = now();
+  const limit = 200;
+  let from = 0;
+  for (let guard = 0; guard < 1000; guard++) {
+    let items: JobSearchItem[] = [];
+    try {
+      const res = await fetch(`${base}/jobs/search`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          filter: {
+            type: { $in: [...AGENT_SLA_JOB_TYPES] },
+            // A merely-created (queued) AND an activated-but-not-yet-completed job both project to
+            // CREATED on the wire (Camunda has no ACTIVATED enum) — so this one filter captures both,
+            // and the leasing `worker` field discriminates them at upsert time.
+            state: "CREATED",
+          },
+          page: { from, limit },
+        }),
+      });
+      if (!res.ok) return; // engine unhappy → keep the ledger as-is, retry next pass
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = (await res.json()) as { items?: JobSearchItem[] };
+      items = body.items ?? [];
+    } catch (err) {
+      console.error(`[poller] agent-activation search: ${err}`);
+      return;
+    }
+    for (const j of items) {
+      const jobType = j.type ?? "";
+      const pik = j.processInstanceKey ?? "";
+      // Defensively re-filter the wire `$in` type filter and require a process instance to key on.
+      if (pik.length === 0 || !AGENT_SLA_JOB_TYPES.includes(jobType)) continue;
+      const worker = typeof j.worker === "string" && j.worker.length > 0 ? j.worker : null;
+      const jobKey = typeof j.jobKey === "string" && j.jobKey.length > 0 ? j.jobKey : null;
+      try {
+        await recordAgentJobObservation(data, {
+          processInstanceKey: pik,
+          jobType,
+          worker,
+          jobKey,
+          now: ts,
+        });
+      } catch (err) {
+        console.error(`[poller] agent-activation upsert ${pik}:${jobType}: ${err}`);
+      }
+    }
+    if (items.length < limit) break; // last page
+    from += items.length;
+  }
 }
 
 /** One job-activation poll pass. The `converging` status means the process is parked at a
@@ -3717,6 +3810,7 @@ export async function pollOnce(
     await pollWaveGatesImpl(data, engine, token, base, headers);
     await pollCapabilityGatesImpl(data, engine, base, headers);
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
+    await pollAgentActivations(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);
   }
 }

package/db/migrations/119_agent_job_activations.sql

@@ -0,0 +1,50 @@
+-- 119_agent_job_activations.sql — issue #879: distinguish a NEVER-ACTIVATED (queue-starved) agent
+-- job from an ACTIVATED-but-hung one when an agent-task SLA boundary fires.
+--
+-- The agent-task SLA timer (`<bpmn:timeDuration>=agentSlaTimeout`) starts when the service task is
+-- ENTERED, so it measures QUEUE time + RUN time. When no worker can take the job type (fleet
+-- saturation / no capacity), the job sits CREATED (never leased) for the whole budget and the
+-- boundary fires — yet the escalation reported it as "hung or looping", telling the human to "check
+-- its progress" when there is none. (The reported case: a `senior:feature` job queued 2h, never
+-- activated, then cancelled by its SLA boundary.)
+--
+-- The engine tracks JobState::Created vs ::Activated, but the Camunda-8 `/v2/jobs/search` wire API
+-- collapses Activated -> CREATED (no ACTIVATED enum value); activation is read off the `worker` +
+-- `deadline` fields — an activated job carries a leasing worker's name and a lock deadline, a
+-- merely-queued one carries neither (same signal `pull_requests.active_worker`/`lease_until` use for
+-- the review-round, migration 005). This ledger generalises that observation to EVERY bounded agent
+-- job type (not just the review-round) and PERSISTS it, so when the SLA boundary cancels the job the
+-- escalation recorder can still tell whether a worker ever picked it up.
+--
+-- The poller (`pollAgentActivations`, app/service.ts) upserts one row per (process_instance_key,
+-- job_type) each pass: `first_seen_at` on first observation (job CREATED), and `activated_at` +
+-- `worker` the first time it observes a leasing worker. The SLA-escalation recorders read it by the
+-- same key (the agent job and its escalation recorder share one process instance) to word the
+-- escalation accurately — "never started (queue starvation)" vs "started but exceeded its budget" —
+-- including the job type and how long it waited.
+--
+-- `job_key` holds the engine job key of the CURRENT attempt so the row tracks that attempt, not a
+-- stale earlier one: the same (process_instance_key, job_type) runs MULTIPLE times within one instance
+-- when its cell retries (implement-cell `ic_reImplement`, merge-cell `mc_rerun`, merge-loop fix-ci /
+-- rebase reloops). Keyed only by (instance, job_type) a sticky first-activation would make a later
+-- queued retry read the EARLIER attempt's worker and misdiagnose it as started/hung. When the poller
+-- observes a different `job_key` for the pair it RESETS the row to the new attempt (first_seen_at /
+-- activated_at / worker), so the escalation always reflects the attempt the SLA boundary cancelled.
+--
+-- Keyed by a surrogate TEXT id (`<process_instance_key>:<job_type>`) so the single-pk `data.table`
+-- accessor can upsert it; the (process_instance_key, job_type) pair is unique per id. FK-free by
+-- design — the owning instance lives in the durable ENGINE store, not app.db, so there is no app-tier
+-- parent row to reference (mirrors `worker_durable_resume`/`worker_harness_protocol`). EXPAND
+-- (additive) phase: one new table; nothing is dropped or renamed. The runner wraps each file in its
+-- own transaction, so this file must NOT contain BEGIN/COMMIT.
+CREATE TABLE IF NOT EXISTS agent_job_activations (
+  id                   TEXT PRIMARY KEY,  -- surrogate: `<process_instance_key>:<job_type>`
+  process_instance_key TEXT NOT NULL,     -- the engine instance the agent job (and its SLA recorder) runs in
+  job_type             TEXT NOT NULL,     -- the agent job's `<zeebe:taskDefinition>` type (e.g. senior:feature)
+  first_seen_at        TEXT NOT NULL,     -- ISO ts the poller first observed the job (CREATED/queued)
+  activated_at         TEXT,              -- ISO ts first observed ACTIVATED (leasing worker seen); NULL = never started
+  worker               TEXT,              -- the leasing worker's name at activation; NULL until activated
+  job_key              TEXT,              -- the engine job key of the CURRENT attempt; a new key RESETS the row (retry isolation)
+  updated_at           TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_agent_job_activations_instance ON agent_job_activations (process_instance_key);