@nanobpm/nano-workforce 0.201.1 → 0.201.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.201.2](https://github.com/nanobpm/nano-workforce/compare/v0.201.1...v0.201.2) (2026-10-08)
+
+### Bug Fixes
+
+* distinguish never-started agent jobs from hung ones in SLA escalations ([#881](https://github.com/nanobpm/nano-workforce/issues/881)) ([da2bc79](https://github.com/nanobpm/nano-workforce/commit/da2bc7915c6cd8ef72bae7bdec2069d09ba091eb)), closes [#879](https://github.com/nanobpm/nano-workforce/issues/879) [#879](https://github.com/nanobpm/nano-workforce/issues/879) [#879](https://github.com/nanobpm/nano-workforce/issues/879)
+
 ## [0.201.1](https://github.com/nanobpm/nano-workforce/compare/v0.201.0...v0.201.1) (2026-10-07)
 
 ### Bug Fixes

package/app/agentActivationLedger.test.ts

@@ -0,0 +1,109 @@
+// Issue #879: the activation ledger upsert must capture the FIRST activation only, be idempotent on a
+// steady state, and never move/clear an earlier activation timestamp — so the SLA escalation reads a
+// stable never-started-vs-activated signal regardless of how many poll passes observe the job.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { getAgentJobActivation, recordAgentJobObservation } from "./agentActivationLedger.ts";
+import { memDataFor } from "../test/worldDb.ts";
+
+function ledger() {
+  return memDataFor(["119_agent_job_activations.sql"]).data;
+}
+
+test("first observation of a queued job records first_seen_at, no activation", async () => {
+  const data = ledger();
+  await recordAgentJobObservation(data, {
+    processInstanceKey: "PI-1",
+    jobType: "senior:feature",
+    worker: null,
+    now: "t0",
+  });
+  const row = await getAgentJobActivation(data, "PI-1", "senior:feature");
+  assertEquals(row?.first_seen_at, "t0");
+  assertEquals(row?.activated_at, null);
+  assertEquals(row?.worker, null);
+});
+
+test("a later observation with a worker records the activation", async () => {
+  const data = ledger();
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-2", jobType: "senior:feature", worker: null, now: "t0" });
+  await recordAgentJobObservation(data, {
+    processInstanceKey: "PI-2",
+    jobType: "senior:feature",
+    worker: "agent-a",
+    now: "t1",
+  });
+  const row = await getAgentJobActivation(data, "PI-2", "senior:feature");
+  assertEquals(row?.first_seen_at, "t0");
+  assertEquals(row?.activated_at, "t1");
+  assertEquals(row?.worker, "agent-a");
+});
+
+test("the FIRST activation is sticky — a later re-observation never moves it", async () => {
+  const data = ledger();
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-3", jobType: "senior:feature", worker: "agent-a", now: "t1" });
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-3", jobType: "senior:feature", worker: "agent-b", now: "t2" });
+  const row = await getAgentJobActivation(data, "PI-3", "senior:feature");
+  assertEquals(row?.activated_at, "t1");
+  assertEquals(row?.worker, "agent-a");
+});
+
+test("observations are keyed by (instance, jobType) — distinct jobs do not collide", async () => {
+  const data = ledger();
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-4", jobType: "senior:conformance", worker: null, now: "t0" });
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-4", jobType: "senior:retro", worker: "agent-c", now: "t0" });
+  const conf = await getAgentJobActivation(data, "PI-4", "senior:conformance");
+  const retro = await getAgentJobActivation(data, "PI-4", "senior:retro");
+  assertEquals(conf?.activated_at, null);
+  assertEquals(retro?.worker, "agent-c");
+});
+
+test("an empty-string worker is treated as not-yet-activated", async () => {
+  const data = ledger();
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-5", jobType: "senior:feature", worker: "", now: "t0" });
+  const row = await getAgentJobActivation(data, "PI-5", "senior:feature");
+  assertEquals(row?.activated_at, null);
+  assertEquals(row?.worker, null);
+});
+
+test("a new job key (a retry) RESETS the row — an activated attempt followed by an unactivated retry reads never-activated", async () => {
+  // Issue #879 review: implement-cell/merge-cell/merge-loop retry the SAME (instance, jobType), so a
+  // sticky first-activation would make a queued retry read the EARLIER attempt's worker and misdiagnose
+  // it as started/hung. The attempt's engine jobKey discriminates them.
+  const data = ledger();
+  // Attempt 1: activated by agent-a.
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-6", jobType: "senior:feature", worker: "agent-a", jobKey: "J1", now: "t1" });
+  // A steady re-observation of the SAME attempt never moves the first activation.
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-6", jobType: "senior:feature", worker: "agent-a", jobKey: "J1", now: "t2" });
+  let row = await getAgentJobActivation(data, "PI-6", "senior:feature");
+  assertEquals(row?.activated_at, "t1");
+  assertEquals(row?.worker, "agent-a");
+  // Attempt 2 (retry): a DIFFERENT jobKey, still queued → the row resets to the current attempt.
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-6", jobType: "senior:feature", worker: null, jobKey: "J2", now: "t3" });
+  row = await getAgentJobActivation(data, "PI-6", "senior:feature");
+  assertEquals(row?.first_seen_at, "t3");
+  assertEquals(row?.activated_at, null);
+  assertEquals(row?.worker, null);
+  assertEquals(row?.job_key, "J2");
+});
+
+test("a new job key that is itself activated reflects the CURRENT attempt's worker, not the prior one", async () => {
+  const data = ledger();
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-7", jobType: "senior:trial-merge", worker: "agent-a", jobKey: "J1", now: "t1" });
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-7", jobType: "senior:trial-merge", worker: "agent-b", jobKey: "J2", now: "t2" });
+  const row = await getAgentJobActivation(data, "PI-7", "senior:trial-merge");
+  assertEquals(row?.activated_at, "t2");
+  assertEquals(row?.worker, "agent-b");
+  assertEquals(row?.job_key, "J2");
+});
+
+test("the SAME job key keeps the first-activation sticky across re-observations", async () => {
+  const data = ledger();
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-8", jobType: "senior:feature", worker: null, jobKey: "J1", now: "t0" });
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-8", jobType: "senior:feature", worker: "agent-a", jobKey: "J1", now: "t1" });
+  await recordAgentJobObservation(data, { processInstanceKey: "PI-8", jobType: "senior:feature", worker: "agent-b", jobKey: "J1", now: "t2" });
+  const row = await getAgentJobActivation(data, "PI-8", "senior:feature");
+  assertEquals(row?.first_seen_at, "t0");
+  assertEquals(row?.activated_at, "t1");
+  assertEquals(row?.worker, "agent-a");
+});

package/app/agentActivationLedger.ts

@@ -0,0 +1,144 @@
+// Agent-job activation ledger (issue #879) — the durable "did a worker ever pick this agent job up?"
+// record every agent-task SLA-escalation reads to tell a NEVER-ACTIVATED (queue-starved) job apart
+// from an ACTIVATED-but-hung one.
+//
+// Why it exists: an agent-task SLA boundary timer (`<bpmn:timeDuration>=agentSlaTimeout`) starts when
+// the service task is ENTERED, so it bounds QUEUE time + RUN time together. Under fleet saturation a
+// job can sit CREATED (no worker can take its type) for the whole budget and the boundary fires — but
+// the escalation reported it as "hung or looping" and told the human to "check its progress" when
+// there is none (issue #879: a `senior:feature` job queued 2h, never activated, then SLA-cancelled).
+// The engine knows JobState::Created vs ::Activated, but once the boundary CANCELS the job that state
+// is gone — so the observation must be captured WHILE the job is live and persisted. `pollAgentActivations`
+// (app/service.ts) does exactly that, writing this ledger; the SLA-escalation recorders read it.
+//
+// The activation signal is the same one the review-round visibility uses (migration 005): 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 — a merely-queued job carries neither. This
+// ledger generalises that to EVERY bounded agent job type and persists first-seen + first-activated.
+//
+// Advisory & best-effort (ADR 0056): this is an app-tier read model over the engine's job read model.
+// It never activates/completes a job, publishes a message, or gates a BPMN sequence flow — it only
+// enriches the human-facing escalation wording. A missing row (poller never observed the job) degrades
+// to "activation unknown", never an error.
+import type { DataLayer } from "@nanobpm/urban";
+
+/** The agent job types that today carry an interrupting SLA timer boundary whose elapse escalates to a
+ * human with a "hung or looping" reason — the class issue #879 guards. Kept as one list so the
+ * activation poll's `/v2/jobs/search` type filter and the escalation recorders agree on exactly which
+ * jobs are tracked. (The convergence-loop / plan-fanout agent tasks are NOT yet bounded — pre-seeded
+ * for #868 — so they are deliberately absent until their boundaries land.) */
+export const AGENT_SLA_JOB_TYPES: readonly string[] = [
+  "senior:feature", // implement-cell
+  "senior:trial-merge", // merge-cell
+  "senior:conformance", // retro conformance
+  "senior:retro", // retro synthesize
+  "senior:fix-ci", // merge-loop CI-fix cell (be_fixci_sla)
+  "senior:rebase", // merge-loop rebase cell (be_rebase_sla)
+];
+
+/** One ledger row: whether (and when) a worker picked up an agent job for a given process instance. */
+export interface AgentJobActivation {
+  /** Surrogate key `<process_instance_key>:<job_type>`. */
+  id: string;
+  process_instance_key: string;
+  job_type: string;
+  /** ISO ts the poller first observed the job (queued/CREATED). */
+  first_seen_at: string;
+  /** ISO ts first observed ACTIVATED (a leasing worker appeared); NULL ⇒ never started. */
+  activated_at: string | null;
+  /** The leasing worker's name at activation; NULL until activated. */
+  worker: string | null;
+  /** The engine job key of the attempt this row currently tracks; NULL when unknown (an old row or a
+   * caller that did not supply one). A poll observation carrying a DIFFERENT job key is a new attempt
+   * and resets the row — see {@link recordAgentJobObservation}. */
+  job_key: string | null;
+  updated_at: string;
+}
+
+/** The surrogate key for a (process instance, job type) pair — the agent job and its SLA-escalation
+ * recorder share one process instance, so both sides key the ledger identically. */
+export function agentActivationId(processInstanceKey: string, jobType: string): string {
+  return `${processInstanceKey}:${jobType}`;
+}
+
+/** Record gateway over the activation ledger. */
+export const agentActivations = (data: DataLayer) =>
+  data.table<AgentJobActivation>("agent_job_activations", "id");
+
+/** Upsert one poll observation of an agent job. On first sight records `first_seen_at`; the FIRST time
+ * a leasing `worker` is observed it records `activated_at` + `worker` (a later re-observation of the
+ * SAME attempt never moves the first-activation timestamp). Idempotent on a steady state.
+ *
+ * Retry isolation (issue #879 review): the same (process instance, job type) runs MULTIPLE times within
+ * one instance when its cell retries (`ic_reImplement`, `mc_rerun`, merge-loop fix-ci/rebase reloops).
+ * Each attempt is a distinct engine job with its own `jobKey`, so when an observation carries a job key
+ * DIFFERENT from the one the row tracks, it is a NEW attempt and the row is RESET to it (first_seen_at /
+ * activated_at / worker), discarding the earlier attempt's activation. Without this a sticky
+ * first-activation row would make a later queued retry read the earlier attempt's worker and misdiagnose
+ * a queue-starved retry as started/hung, and its elapsed times would fold in the prior attempt + human
+ * wait. When the job key is unknown on either side the row keeps its prior first-sticky-activation
+ * behaviour (the caller cannot prove a new attempt). */
+export async function recordAgentJobObservation(
+  data: DataLayer,
+  input: {
+    processInstanceKey: string;
+    jobType: string;
+    worker: string | null;
+    jobKey?: string | null;
+    now: string;
+  },
+): Promise<void> {
+  const table = agentActivations(data);
+  const id = agentActivationId(input.processInstanceKey, input.jobType);
+  const worker = input.worker && input.worker.length > 0 ? input.worker : null;
+  const jobKey = input.jobKey && input.jobKey.length > 0 ? input.jobKey : null;
+  const existing = await table.get(id);
+  if (!existing) {
+    await table.insert({
+      id,
+      process_instance_key: input.processInstanceKey,
+      job_type: input.jobType,
+      first_seen_at: input.now,
+      activated_at: worker ? input.now : null,
+      worker,
+      job_key: jobKey,
+      updated_at: input.now,
+    });
+    return;
+  }
+  const existingKey = existing.job_key && existing.job_key.length > 0 ? existing.job_key : null;
+  // A different engine job key for the same (instance, jobType) is a NEW attempt — reset the row so it
+  // reflects only the current attempt, never a stale earlier activation/wait.
+  if (jobKey && existingKey && jobKey !== existingKey) {
+    await table.update(id, {
+      first_seen_at: input.now,
+      activated_at: worker ? input.now : null,
+      worker,
+      job_key: jobKey,
+      updated_at: input.now,
+    });
+    return;
+  }
+  // Same attempt (or job key unknown): capture the FIRST activation only, and adopt a newly-known job
+  // key so a subsequent different one is recognised as a new attempt.
+  const patch: Partial<AgentJobActivation> = {};
+  if (worker && !existing.activated_at) {
+    patch.activated_at = input.now;
+    patch.worker = worker;
+  }
+  if (jobKey && !existingKey) patch.job_key = jobKey;
+  if (Object.keys(patch).length > 0) {
+    patch.updated_at = input.now;
+    await table.update(id, patch);
+  }
+}
+
+/** Read the activation record for a (process instance, job type), or `undefined` when the poller never
+ * observed the job. */
+export async function getAgentJobActivation(
+  data: DataLayer,
+  processInstanceKey: string,
+  jobType: string,
+): Promise<AgentJobActivation | undefined> {
+  return agentActivations(data).get(agentActivationId(processInstanceKey, jobType));
+}

package/app/agentActivationsPoll.test.ts

@@ -0,0 +1,180 @@
+// Issue #879: `pollAgentActivationsImpl` must persist, for every bounded agent job type, whether a
+// worker ever leased the job — keyed by (processInstanceKey, jobType) — so a later SLA escalation can
+// tell a never-activated (queue-starved) job from an activated one even after the boundary cancels it.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { getAgentJobActivation } from "./agentActivationLedger.ts";
+import { pollAgentActivationsImpl } from "./service.ts";
+import { memDataFor } from "../test/worldDb.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: test stub over the engine job-search wire shape.
+type JobItem = any;
+
+function jobsFetch(items: JobItem[], opts: { ignoreTypeFilter?: boolean } = {}) {
+  return (_url: string, init?: { body?: string }) => {
+    const body = init?.body ? JSON.parse(init.body) : {};
+    const t = body.filter?.type;
+    const wanted: string[] | null = Array.isArray(t?.$in) ? t.$in : typeof t === "string" ? [t] : null;
+    const matched = opts.ignoreTypeFilter || wanted == null ? items : items.filter((j) => wanted.includes(j.type ?? ""));
+    // Honour the `page: { from, limit }` paging contract so a pagination regression can observe
+    // whether the poller actually advances past the first page.
+    const from = typeof body.page?.from === "number" ? body.page.from : 0;
+    const limit = typeof body.page?.limit === "number" ? body.page.limit : matched.length;
+    const out = matched.slice(from, from + limit);
+    return Promise.resolve(
+      new Response(JSON.stringify({ items: out }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+const headers = { "content-type": "application/json" };
+
+test("poll records a queued (unleased) agent job as not-yet-activated", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const prev = globalThis.fetch;
+  globalThis.fetch = jobsFetch([
+    { type: "senior:feature", processInstanceKey: "PI-10", state: "CREATED" },
+  ]) as typeof fetch;
+  try {
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prev;
+  }
+  const row = await getAgentJobActivation(data, "PI-10", "senior:feature");
+  assertEquals(row?.activated_at, null);
+  assertEquals(row?.worker, null);
+});
+
+test("poll records an activation when a leasing worker appears, across passes", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const prev = globalThis.fetch;
+  try {
+    globalThis.fetch = jobsFetch([
+      { type: "senior:trial-merge", processInstanceKey: "PI-11", state: "CREATED" },
+    ]) as typeof fetch;
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+    assertEquals((await getAgentJobActivation(data, "PI-11", "senior:trial-merge"))?.activated_at, null);
+
+    globalThis.fetch = jobsFetch([
+      { type: "senior:trial-merge", processInstanceKey: "PI-11", worker: "agent-m", deadline: "2024-01-01T00:15:00Z", state: "CREATED" },
+    ]) as typeof fetch;
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+    const row = await getAgentJobActivation(data, "PI-11", "senior:trial-merge");
+    assertEquals(row?.worker, "agent-m");
+    assertEquals(typeof row?.activated_at === "string", true);
+  } finally {
+    globalThis.fetch = prev;
+  }
+});
+
+test("poll defensively excludes a non-agent job even if the wire $in filter is ignored", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const prev = globalThis.fetch;
+  globalThis.fetch = jobsFetch(
+    [{ type: "pr.capture-head", processInstanceKey: "PI-12", worker: "host-internal", state: "CREATED" }],
+    { ignoreTypeFilter: true },
+  ) as typeof fetch;
+  try {
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prev;
+  }
+  assertEquals(await getAgentJobActivation(data, "PI-12", "pr.capture-head"), undefined);
+});
+
+test("poll skips an item with no process instance to key on", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const prev = globalThis.fetch;
+  globalThis.fetch = jobsFetch([{ type: "senior:feature", state: "CREATED" }]) as typeof fetch;
+  try {
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prev;
+  }
+  assertEquals(await getAgentJobActivation(data, "", "senior:feature"), undefined);
+});
+
+test("poll leaves the ledger untouched when the engine search fails", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const prev = globalThis.fetch;
+  globalThis.fetch = (() =>
+    Promise.resolve(new Response("boom", { status: 500 }))) as typeof fetch;
+  try {
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prev;
+  }
+  assertEquals(await getAgentJobActivation(data, "PI-13", "senior:feature"), undefined);
+});
+
+test("poll records the merge-loop bounded agent jobs (senior:fix-ci, senior:rebase)", async () => {
+  // Regression for the #881 adversarial finding: merge-loop.bpmn arms an interrupting SLA boundary
+  // on its fix-ci and rebase agent tasks and routes the escalation through agentSlaEscalationQuestion
+  // — but if AGENT_SLA_JOB_TYPES omits those job types the poller never observes them and every such
+  // escalation degrades to "activation unknown" instead of the never-started/hung distinction.
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const prev = globalThis.fetch;
+  globalThis.fetch = jobsFetch([
+    { type: "senior:fix-ci", processInstanceKey: "PI-20", state: "CREATED" },
+    { type: "senior:rebase", processInstanceKey: "PI-20", worker: "agent-r", deadline: "2024-01-01T00:15:00Z", state: "CREATED" },
+  ]) as typeof fetch;
+  try {
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prev;
+  }
+  const fixCi = await getAgentJobActivation(data, "PI-20", "senior:fix-ci");
+  assertEquals(fixCi?.activated_at, null);
+  const rebase = await getAgentJobActivation(data, "PI-20", "senior:rebase");
+  assertEquals(rebase?.worker, "agent-r");
+  assertEquals(typeof rebase?.activated_at === "string", true);
+});
+
+test("poll records jobs BEYOND the first page (pagination)", async () => {
+  // Issue #881 review: a single first-page read lets long-lived jobs occupy the page every pass while
+  // later jobs time out with no activation recorded. 450 queued jobs > one 200-item page must all land.
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const many: JobItem[] = Array.from({ length: 450 }, (_v, i) => ({
+    type: "senior:feature",
+    processInstanceKey: `PI-${i}`,
+    jobKey: `J-${i}`,
+    state: "CREATED",
+  }));
+  const prev = globalThis.fetch;
+  globalThis.fetch = jobsFetch(many) as typeof fetch;
+  try {
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prev;
+  }
+  // A job on the first page, one straddling the page boundary, and the very last job are all recorded.
+  assertEquals((await getAgentJobActivation(data, "PI-0", "senior:feature"))?.first_seen_at != null, true);
+  assertEquals((await getAgentJobActivation(data, "PI-200", "senior:feature"))?.first_seen_at != null, true);
+  assertEquals((await getAgentJobActivation(data, "PI-449", "senior:feature"))?.first_seen_at != null, true);
+});
+
+test("poll resets the ledger to a retry (new jobKey) so an earlier attempt's activation is not replayed", async () => {
+  // Issue #881 review: a retrying agent task reuses (instance, jobType); a new engine jobKey is a new
+  // attempt and must reset the activation the recorder reads.
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const prev = globalThis.fetch;
+  try {
+    globalThis.fetch = jobsFetch([
+      { type: "senior:feature", processInstanceKey: "PI-30", jobKey: "A1", worker: "agent-a", deadline: "2024-01-01T00:15:00Z", state: "CREATED" },
+    ]) as typeof fetch;
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+    assertEquals((await getAgentJobActivation(data, "PI-30", "senior:feature"))?.worker, "agent-a");
+
+    // The retry is a different jobKey, still queued → the recorder must see never-activated, not agent-a.
+    globalThis.fetch = jobsFetch([
+      { type: "senior:feature", processInstanceKey: "PI-30", jobKey: "A2", state: "CREATED" },
+    ]) as typeof fetch;
+    await pollAgentActivationsImpl(data, "http://engine/v2", headers);
+    const row = await getAgentJobActivation(data, "PI-30", "senior:feature");
+    assertEquals(row?.activated_at, null);
+    assertEquals(row?.worker, null);
+    assertEquals(row?.job_key, "A2");
+  } finally {
+    globalThis.fetch = prev;
+  }
+});

package/app/agentSlaEscalation.test.ts

@@ -0,0 +1,137 @@
+// Red/green for issue #879: the agent-task SLA escalation must distinguish a NEVER-ACTIVATED
+// (queue-starved) agent job from an ACTIVATED-but-hung one, name the job type, and say how long it
+// waited — never the old blanket "it is hung or looping" for a job no worker ever picked up.
+import { test } from "node:test";
+import { assertEquals, assertStringIncludes } from "#test-assert";
+import { recordAgentJobObservation } from "./agentActivationLedger.ts";
+import {
+  agentSlaEscalationQuestion,
+  buildAgentSlaEscalationReason,
+  humanizeIsoDuration,
+  humanizeMs,
+} from "./agentSlaEscalation.ts";
+import { memDataFor } from "../test/worldDb.ts";
+
+const RECOVERY = "Answer to resume, or abandon it.";
+
+test("humanizeMs renders a compact span and floors sub-minute to seconds", () => {
+  assertEquals(humanizeMs(2 * 3600_000 + 5 * 60_000), "2h 5m");
+  assertEquals(humanizeMs(45 * 60_000), "45m");
+  assertEquals(humanizeMs(30_000), "30s");
+  assertEquals(humanizeMs(0), "less than a minute");
+  assertEquals(humanizeMs(-5), "less than a minute");
+  assertEquals(humanizeMs(Number.NaN), "less than a minute");
+});
+
+test("humanizeIsoDuration humanizes the SLA budget", () => {
+  assertEquals(humanizeIsoDuration("PT2H"), "2h");
+  assertEquals(humanizeIsoDuration("PT15M"), "15m");
+});
+
+test("never-observed-activated: queue starvation is reported hedged, NOT as hung or looping", () => {
+  const reason = buildAgentSlaEscalationReason({
+    jobType: "senior:feature",
+    sla: "PT2H",
+    // Observed queued, never leased (activated_at null) → the defect scenario.
+    activation: { firstSeenAt: "2024-01-01T00:00:00Z", activatedAt: null, worker: null },
+    now: "2024-01-01T02:00:00Z",
+    recovery: RECOVERY,
+  });
+  assertStringIncludes(reason, "senior:feature");
+  // Observational, hedged wording — never the over-confident "the agent never started".
+  assertStringIncludes(reason, "No worker was ever observed to pick up");
+  assertStringIncludes(reason, "queue starvation");
+  // Names how long it waited and the SLA budget.
+  assertStringIncludes(reason, "2h");
+  // Acknowledges the poll-window race rather than claiming certainty (issue #881 review).
+  assertStringIncludes(reason, "that would not have been recorded");
+  // Must NOT misdiagnose it as hung/looping.
+  assertEquals(reason.includes("may be hung or looping"), false);
+  assertEquals(reason.includes("agent never started"), false);
+  assertStringIncludes(reason, RECOVERY);
+});
+
+test("started-but-exceeded: a leased job may be hung or looping", () => {
+  const reason = buildAgentSlaEscalationReason({
+    jobType: "senior:trial-merge",
+    sla: "PT2H",
+    activation: {
+      firstSeenAt: "2024-01-01T00:00:00Z",
+      activatedAt: "2024-01-01T00:10:00Z",
+      worker: "agent-7",
+    },
+    now: "2024-01-01T02:10:00Z",
+    recovery: RECOVERY,
+  });
+  assertStringIncludes(reason, "senior:trial-merge");
+  assertStringIncludes(reason, "started");
+  assertStringIncludes(reason, "hung or looping");
+  // Reports both the queue wait and the run time, plus the worker.
+  assertStringIncludes(reason, "10m");
+  assertStringIncludes(reason, "agent-7");
+  assertEquals(reason.includes("never started"), false);
+});
+
+test("activation unknown: the poller never observed the job → honest ambiguity", () => {
+  const reason = buildAgentSlaEscalationReason({
+    jobType: "senior:retro",
+    sla: "PT2H",
+    activation: null,
+    now: "2024-01-01T02:00:00Z",
+    recovery: RECOVERY,
+  });
+  assertStringIncludes(reason, "senior:retro");
+  assertStringIncludes(reason, "no worker-activation was ever recorded");
+  assertEquals(reason.includes("hung or looping"), false);
+});
+
+test("agentSlaEscalationQuestion reads the ledger and distinguishes never-started", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  // A queued-but-never-activated observation (worker null).
+  await recordAgentJobObservation(data, {
+    processInstanceKey: "PI-1",
+    jobType: "senior:feature",
+    worker: null,
+    now: "2024-01-01T00:00:00Z",
+  });
+  const q = await agentSlaEscalationQuestion(data, {
+    processInstanceKey: "PI-1",
+    jobType: "senior:feature",
+    sla: "PT2H",
+    recovery: RECOVERY,
+    now: "2024-01-01T02:00:00Z",
+  });
+  assertStringIncludes(q, "No worker was ever observed to pick up");
+  assertEquals(q.includes("may be hung or looping"), false);
+});
+
+test("agentSlaEscalationQuestion reads an activated observation as started-but-hung", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  await recordAgentJobObservation(data, {
+    processInstanceKey: "PI-2",
+    jobType: "senior:feature",
+    worker: "agent-x",
+    now: "2024-01-01T00:05:00Z",
+  });
+  const q = await agentSlaEscalationQuestion(data, {
+    processInstanceKey: "PI-2",
+    jobType: "senior:feature",
+    sla: "PT2H",
+    recovery: RECOVERY,
+    now: "2024-01-01T02:05:00Z",
+  });
+  assertStringIncludes(q, "hung or looping");
+  assertStringIncludes(q, "agent-x");
+});
+
+test("agentSlaEscalationQuestion with no ledger row reports activation unknown", async () => {
+  const { data } = memDataFor(["119_agent_job_activations.sql"]);
+  const q = await agentSlaEscalationQuestion(data, {
+    processInstanceKey: "PI-404",
+    jobType: "senior:feature",
+    sla: "PT2H",
+    recovery: RECOVERY,
+    now: "2024-01-01T02:00:00Z",
+  });
+  assertStringIncludes(q, "no worker-activation was ever recorded");
+});