@nanobpm/nano-workforce 0.201.0 → 0.201.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **delivery-graph:** actionable node escalations — node-local agent results, retry-node, inputs preflight ([#863](https://github.com/nanobpm/nano-workforce/issues/863)) ([50f7595](https://github.com/nanobpm/nano-workforce/commit/50f7595f3156b2e1e9d52e30e87d3e1c22951dc8)), closes [nano-bpm#1335](https://github.com/nanobpm/nano-bpm/issues/1335) [nano-bpm#1334](https://github.com/nanobpm/nano-bpm/issues/1334) [nano-bpm#1336](https://github.com/nanobpm/nano-bpm/issues/1336) [nanobpm/nano-workforce#866](https://github.com/nanobpm/nano-workforce/issues/866) [nano-bpm#1336](https://github.com/nanobpm/nano-bpm/issues/1336) [nano-bpm#1334](https://github.com/nanobpm/nano-bpm/issues/1334) [nano-bpm#946](https://github.com/nanobpm/nano-bpm/issues/946) [#543](https://github.com/nanobpm/nano-workforce/issues/543) [#866](https://github.com/nanobpm/nano-workforce/issues/866) [#778](https://github.com/nanobpm/nano-workforce/issues/778) [#772](https://github.com/nanobpm/nano-workforce/issues/772) [#772](https://github.com/nanobpm/nano-workforce/issues/772) [#461](https://github.com/nanobpm/nano-workforce/issues/461) [#876](https://github.com/nanobpm/nano-workforce/issues/876)
+
 ## [0.201.0](https://github.com/nanobpm/nano-workforce/compare/v0.200.9...v0.201.0) (2026-10-06)
 
 ### Features

package/SPEC.md

@@ -1039,6 +1039,159 @@ decision. The target behaviour is an **autonomy ladder**:
 A human escalation is then reserved for its one true case: **two slices that each pass
 but encode incompatible decisions about a shared contract** — a genuine design call.
 
+## 13.3 Delivery-graph node escalation — Continue / Retry / reset (PR #863)
+
+The delivery-graph compiler (`app/deliveryGraphCompiler.ts`, ADR 0005) compiles each
+`agent`/`connector` node to a `start → serviceTask → end` subProcess guarded by a
+**bounded `=nodeTimeout` boundary**. On timeout (or, for an `agent`, on a broken
+producer contract — issue #731) the stalled node parks on a **human-completable
+escalation user task** (`delivery-human-task__<el>__esc`, and the agent-only
+`__contract` twin), surfaced in the Tasks inbox and answerable by a human or an agent
+(ADR 0046). Every such escalation names **two exits** (the `delivery-escalation` form's
+`decision` select):
+
+- **Continue** (`decision="continue"`, the default) completes the node as resolved. If
+  the node declares **exactly one** emit **and that emit is a downstream-required fact**,
+  the form presents a typed-value field and maps
+  the operator-supplied `value` onto the node's emit-source var (`factSourceVar`), so the
+  subProcess output publishes the same `<el>_<fact>` a normal completion would —
+  letting work finished out of band (a draft PR the stalled agent already opened) be
+  handed onward instead of threading a null downstream. This applies to **both** `agent`
+  and `connector` emits: a connector has no producer-contract gate, so its resume keys
+  off the node's **own** declared `emits` (emit source = the fact's own name), never the
+  agent-only gate metadata. The single-emit boundary is a hard cardinality rule: the
+  form captures ONE value, so a node declaring **zero** emits has nothing to resume (the
+  field stays blank) and a node declaring **two or more** emits is **not** value-resumable
+  — one value cannot satisfy multiple distinct typed facts without corrupting them.
+  **The value is also inert for a node with no *required* (downstream-consumed) resume
+  target** — the resume keys off the **required** emit set, not the raw declared set, so a
+  node whose facts nothing downstream reads has no required resume target and its `value` is
+  discarded (there is nothing to publish it to). This covers a node that declares **zero**
+  emits, exactly **one** routing-only/unconsumed emit, or **several** routing-only/unconsumed
+  emits alike: because the required resume set (`resumeEmits`) is empty, **no post-escalation
+  validation gate is compiled at all**, so **Continue simply proceeds past the node to its
+  default (fallback) branch** — there is nothing to re-park (`serviceBodyLines` /
+  `escalationTaskLines` add the `validTarget` gate only when `resumeEmits` is non-empty). The
+  fail-closed validation gate exists **only** for a node that still owes a **required** emit:
+  there, on Continue it **fails closed and loops
+  back to the escalation** (it does NOT write nulls and does NOT advance to a fallback branch)
+  — **Retry this step** is the only way to actually produce the facts, except that a node
+  declaring exactly **one** emit — that single declared emit being its only required resume
+  target — may instead satisfy it by entering the coerced `value` (the value field stays inert
+  for a node declaring two or more emits even when only one is required, matching
+  `declaredEmits.length === 1 && emits.length === 1` in the compiler).
+  (A **wait** gate owing **two or more**
+  emits is a special case: it has no Retry exit and its single value field can resume
+  none of them, so its escalation grows **no** validation gate at all and Continue simply
+  acknowledges and proceeds to the node end — see issue #863 — rather than looping forever.)
+  Because the form
+  captures `value` as textfield **text**, the single-emit resume **coerces/validates it to
+  the emit's declared type** before publishing (`escalationResumeValueFeel`): a `boolean`
+  emit accepts `"true"`/`"false"` **case-insensitively and surrounding-whitespace-trimmed**
+  (the validity gate and the coercion share one `lower case(trim(string(value)))`
+  normalization, so a value one accepts the other can never convert differently) and
+  publishes a real boolean, a `number` emit parses via `number(trim(string(value)))`, and
+  any other (text-valued) type passes through. An **invalid** entry
+  publishes `null` — the defined failure path — so a required-emit producer gate escalates
+  and a guarded split takes its default rather than routing on a mistyped value (a raw
+  `"true"` string would silently skip a `= true` guard).
+- **Retry this step** (`decision="retry"`) re-runs the node. A none intermediate throw
+  event (never a scriptTask) resets the node-local scratch — the decision, the captured
+  `value`/`escalationNote`, and (for an agent) the **full declared result set**
+  (`AGENT_RESULT_LOCAL_VARS` — the self-reported `status`/`summary`/… **and** every other
+  node-local result field such as `transcriptUrl`, `agentCheckpoint`, and the PR aliases)
+  — or, **for a connector**, its fixed result metadata (`CONNECTOR_RESULT_LOCAL_VARS` —
+  `connectorOutcome`/`connectorDedupeKey`/`connectorDetail`) — plus the previous attempt's
+  emits — and appends the operator's `escalationNote` to the agent
+  prompt as guidance for the next attempt (re-derived from the runner-seeded
+  `nodeInputs.<el>.appendPrompt` baseline, so consecutive retries never accumulate stale
+  guidance). The guidance control is the escalation-specific `escalationNote`, never the
+  plain `note`: `note` is a worker **result** field (`plan.md` returns one) that
+  nearest-scope propagation lands in the same subProcess scope, so reading it would feed a
+  worker-produced note back as "operator guidance" on a retry submitted without one. Clearing
+  the whole declared set (not just the status fields) stops a retried
+  worker that omits an optional field from republishing the previous attempt's value
+  downstream or surfacing it in the next escalation.
+
+All retry/reset targets are **node-local** (declared on the subProcess by
+`ioMappingLines`), so a node's result vars never leak to the root and two parallel nodes
+declaring the same emit never cross-publish — with a few deliberate publish-onward
+exceptions, all written under node-unique or intentionally-shared names rather than the
+raw result var. The **outward data** exceptions: each declared emit is republished to the
+root as `<el>_<fact>` (node-unique, so siblings never collide), and an agent's
+`transcriptUrl` is propagated back to the root under the shared `transcriptUrl` name so
+Nano Explorer can render the run→transcript link (app/deliveryGraphCompiler.ts:1872-1877).
+That one shared name means parallel agents can overwrite the root `transcriptUrl` —
+acceptable, since it is a display-only correlation link, not a result a downstream node
+binds. In addition, the per-node **control signals** `<el>_contractMet` (the agent
+contract-gate's proceed flag) and `<el>_retryRequested` (the per-escalation retry gate's
+route flag) are **also root-scoped** — their gateways live outside the node's subProcess
+and so cannot read node scope, and the `<el>_`-prefixed, node-unique names can never
+collide across parallel nodes. So the node-local rule governs a node's *result/emit scratch*;
+these node-unique control booleans are intentionally published to root so the routing
+gateways can read them on either engine's scope semantics. A **preflight `assert`** on the inner leaf
+task's input fails LOUD (raising an incident naming the missing `nodeInputs.<el>`)
+before any job exists when the runner-seeded config was lost — see the `KNOWN
+LIMITATION` in `serviceBodyLines` (fail-loud-only, nano-workforce#866). Resolving that
+incident re-evaluates **only the leaf's inputs** — the subProcess-level config mappings
+(`prompt`/`appendPrompt`/`nodeTimeout`, connector `target`/`payload`/`dedupeKey`) ran once
+at subProcess entry and are **not** re-mapped on a leaf resolve, so the node would
+activate **unconfigured**. The in-subprocess **"Retry this step"** loop does **not**
+help here either: it loops directly back to the inner service task (to reset the
+node-local scratch), bypassing the subProcess entry mappings, so it too leaves the
+config null. **Recovery therefore requires re-entering the sub-process from OUTSIDE —
+relaunch/re-enter the node so its subProcess input mappings re-evaluate against the
+restored `nodeInputs`** — not merely resolving the incident or using "Retry this step".
+The correct in-model fix is to run this check at sub-process *entry* (Camunda parity,
+nano-bpm#1336); until then the preflight fails loud so the node never runs blind
+*without* an incident, and the operator re-enters the sub-process to recover.
+
+Because an `agent`/`connector` node's emit source **is the fact's own name**, declared
+node-local in the same subProcess scope as the escalation form controls and the node's
+seeded config, a fact name is not fully unrestricted: `validateDeliveryGraph` rejects an
+emit named after a **reserved delivery variable** (`reservedDeliveryFactNames(kind)`,
+app/deliveryGraph.ts) fail-closed at authoring time. The reserved set is **kind-aware**
+(issue #863 review): the **escalation controls** (`decision`/`value`/`escalationNote` — an escalation
+Continue would overwrite the fact, publishing `<el>_decision="continue"` instead of the
+agent's routing value) and the shared late-binding/preflight **scaffolding**
+(`boundFacts`/`nodeInputs`/`nodeInputsPresent`) are reserved for **every** kind, while a
+**config variable** is reserved only for the kind whose own config it is — and only for
+`agent`/`connector`, the kinds whose emit source is the fact's own name (the retry reset's
+clear-the-emits pass would null the node's own configuration, so the retried node activates
+unconfigured). A `wait`/`human` emit's source is a fixed intermediate (`detail`/
+`humanEmitValue`/…), never the fact's own name, so those kinds reserve only the escalation
+controls + scaffolding — a `wait` emitting `target` or a `human` emitting `prompt` is
+allowed. The node-local **result** fields
+(`AGENT_RESULT_LOCAL_VARS`/`CONNECTOR_RESULT_LOCAL_VARS`) are deliberately **not**
+reserved — with **one exception**: an agent emitting `pr` (the canonical
+`agent → connector[converge] → wait[pr]` shape) writes the same node-local value the
+result field holds, and the retry reset correctly clears both — reserving them would
+forbid that flagship pattern. The exception is the agent completion-control **`status`**:
+the producer status gate reads that same node-local field as the node's completion status
+and accepts only `done`/`opened`/`skipped`, so an agent emit named `status` carrying any
+other routing value (`approved`, …) always escalates, and `status="done"` can never take an
+`approved` branch — the emit contract and the gate conflict. `status` is therefore reserved
+for an **`agent`** (a connector has no producer status gate, so a connector `status` emit
+stays allowed); the rest of the result set remains unreserved.
+
+A **`human` node's required emit is gated fail-closed on completion** (PR #863 review,
+thread r4198662345). A human node has no worker self-report to producer-gate on, but its
+single emit can be a downstream-**required** fact — and the captured value is coerced and
+validated to the emit's declared type (`coerceFactValueFeel`), so an invalid entry becomes
+`null`. Without a completion gate the node ended and the unconditional edge activated the
+consumer with a `null` required fact. The compiler therefore grows a **completion gate**
+when the node's single emit is downstream-required: the user task's own output mapping
+computes a node-unique validity flag (`resumeValidVar`) from the *raw* captured field via
+the **same** per-type `resumeValueCondition` grammar the escalation resume enforces
+(presence included, so a blank required entry is invalid), and a post-task exclusive
+gateway routes a **valid** completion to the node end while an **invalid** one loops back
+to the human task for re-entry — the human analogue of the escalation resume's fail-closed
+re-park (a human node has no separate escalation twin to re-park onto). The gate is grown
+**only** when the single emit is required: a routing-only/unconsumed emit keeps the direct
+`task → end` flow (its `null` simply takes a guarded split's deadlock-safe default, exactly
+like the escalation resume's no-required-target case), and a no-emit acknowledgement node
+has nothing to validate.
+
 ## 14. Open questions / future
 
 - **Provisioning the existing PR branch** — resolved: the `c8ctl` host-git

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;
+  }
+});