@nanobpm/nano-workforce 0.201.0 → 0.201.2

package/app/agentCompletion.test.ts

@@ -18,6 +18,7 @@ import {
   completeEscalationAsAgent,
   completeEscalationAsHuman,
   completeUserTaskAttributed,
+  escalationFormId,
   latestCompletion,
   revertAgentCompletion,
   type TaskCompletion,
@@ -884,6 +885,57 @@ test("validateEscalationVariables derives its contract from the canonical .form
   assertEquals(validateEscalationVariables("some-other-task", { whatever: 1 }), null);
 });
 
+test("validateEscalationVariables enforces the `decision` select on a delivery-graph service-escalation twin (retry-node)", async () => {
+  // A delivery-graph service-node escalation twin (`…__esc`/`…__contract`) ALWAYS renders the fixed
+  // `delivery-escalation` form, whose `decision` select is {continue, retry}. The canonical completers
+  // must therefore reject a present-but-invalid `decision` (e.g. an agent/direct-API typo `retrry`),
+  // instead of silently computing `retryRequested=false` and taking the deadlock-safe Continue default
+  // — which would skip the node (PR #863 review — MEDIUM "Validate decision values" advisory).
+  const escTwin = "delivery-human-task__n1__esc";
+  const contractTwin = "delivery-human-task__n2__contract";
+  // present-but-invalid decision → rejected on BOTH twin kinds
+  assert(validateEscalationVariables(escTwin, { decision: "retrry" }) !== null, "invalid decision rejected on __esc twin");
+  assert(validateEscalationVariables(contractTwin, { decision: "nope" }) !== null, "invalid decision rejected on __contract twin");
+  // valid decisions pass
+  assertEquals(validateEscalationVariables(escTwin, { decision: "retry" }), null);
+  assertEquals(validateEscalationVariables(escTwin, { decision: "continue" }), null);
+  // decision OMITTED → still valid (defaults to Continue); the generic-form wait-escalation twins, which
+  // never submit `decision`, must not be false-rejected (the form has no required fields).
+  assertEquals(validateEscalationVariables(escTwin, { value: "something", escalationNote: "n" }), null);
+  // the bare per-node human task (NOT a twin) stays unenforced — it renders a different form per node.
+  assertEquals(validateEscalationVariables("delivery-human-task__n1", { decision: "retrry" }), null);
+  // a node literally named `esc` has base id `delivery-human-task__esc` — NOT misread as a twin.
+  assertEquals(validateEscalationVariables("delivery-human-task__esc", { decision: "retrry" }), null);
+});
+
+test("escalationFormId derives the COMPILED form per twin kind — wait-gate twins get the generic form, not the retry form (PR #863 review)", () => {
+  // Regression guard (Copilot thread app/agentCompletion.ts:186): the bare `__esc` suffix is shared by a
+  // service-node timeout twin (retry-capable → `delivery-escalation`) AND a `wait`-gate twin (no retry
+  // path → `delivery-human-generic`). Inferring one form from the suffix misclassified the wait gate, so
+  // the #461 Tasks-inbox `form_key` fallback rendered a bogus "Retry this step" the wait process silently
+  // ignores. The compiler now stamps a `__wait` kind marker into the wait twin's id so the form is
+  // DERIVED from the id.
+  // service-node twins → retry-capable escalation form
+  assertEquals(escalationFormId("delivery-human-task__n1__esc"), "delivery-escalation");
+  assertEquals(escalationFormId("delivery-human-task__n2__contract"), "delivery-escalation");
+  // wait-gate twin (kind marker) → select-less generic form
+  assertEquals(escalationFormId("delivery-human-task__gate__esc__wait"), "delivery-human-generic");
+  // a bare per-node human task (variable form per node) has no static contract
+  assertEquals(escalationFormId("delivery-human-task__n1"), undefined);
+  // a node literally named `esc`/`esc__wait` is NOT misread as a twin (needs a non-empty base before the suffix)
+  assertEquals(escalationFormId("delivery-human-task__esc"), undefined);
+  assertEquals(escalationFormId("delivery-human-task__esc__wait"), undefined);
+});
+
+test("validateEscalationVariables: a wait-gate twin is validated against the generic form (no `decision` select to enforce)", () => {
+  // The wait-gate twin renders the select-less generic form, so a `decision` value is out of contract
+  // there — but the generic form declares no `decision` allowed-set, so the completer does not enforce
+  // one (the wait process ignores `decision` entirely; there is no retry path to guard).
+  const waitTwin = "delivery-human-task__gate__esc__wait";
+  assertEquals(validateEscalationVariables(waitTwin, { value: "pkg@1.2.3" }), null, "a value-only wait-gate resume is valid");
+  assertEquals(validateEscalationVariables(waitTwin, {}), null, "the generic form has no required fields");
+});
+
 test("feature-escalation demands non-blank answer on the answer path, but not on the hidden abandon path", async () => {
   // resolution=answer shows the conditional `answer` field, which is required → blank/missing rejected.
   assert(

package/app/agentCompletion.ts

@@ -24,7 +24,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient, GatewayDataSource } from "@nanobpm/urban";
 import { invalidateAdjudication, invalidateAdjudicationByCompletion } from "./adjudications.ts";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
-import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { DELIVERY_HUMAN_ELEMENT, ESCALATION_FORM, GENERIC_HUMAN_FORM, isDeliveryEscalationTwin, isDeliveryHumanElement, isDeliveryWaitEscalationTwin } from "./deliveryHuman.ts";
 import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT, PR_MERGE_APPROVAL_ELEMENT, READINESS_ESCALATION_ELEMENT, READINESS_ESCALATION_PF_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
@@ -165,17 +165,32 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   // contract is enforced instead by `bindHumanEmits` against the node's declared `emits[]` (binds are
   // validated, not stringly — Decision 3/4), so `validateEscalationVariables` leaves it unenforced
   // (returns `null`) and the completer accepts the captured form variables for the emit binder to type.
+  // (Its SERVICE-node escalation TWINS — `…__esc`/`…__contract` — are different: they render a FIXED
+  // form, so `escalationFormId` maps them to `ESCALATION_FORM` via `isDeliveryEscalationTwin` rather
+  // than listing each per-node id here.)
 };
 
 /** The fixed `.form` linkage (a `zeebe:formDefinition formId`) that governs a fixed-form escalation
- *  kind's completion, or `undefined` for a kind with no static form (the delivery-graph `human` node,
- *  which renders DIFFERENT forms per node — its `formKey` only ever comes from the engine at runtime).
+ *  kind's completion, or `undefined` for a kind with no static form (the per-node delivery-graph `human`
+ *  task, which renders DIFFERENT forms per node — its `formKey` only ever comes from the engine at
+ *  runtime). A delivery-graph SERVICE-node escalation TWIN (`…__esc`/`…__contract`), by contrast, ALWAYS
+ *  renders the fixed {@link ESCALATION_FORM} — a strict superset of the generic form — so it DOES carry a
+ *  static contract here (via {@link isDeliveryEscalationTwin}): this is what lets the canonical completers
+ *  reject a present-but-invalid `decision` (continue/retry) on a retry-node escalation, while leaving the
+ *  select-less generic-form twins unaffected (the form has no required fields, so they never false-reject).
  *  Exposed so the Tasks-inbox poller can denormalise a row's `form_key` from this SAME single source of
  *  truth when the raw `/v2/user-tasks/search` result omits the engine-resolved key (issue #461) — the
  *  REST gateway addresses a deployed form by value whether that value is a deploy key or an authored
  *  form id, so this id resolves the same deployed `.form` the completer validates against. */
 export function escalationFormId(elementId: string): string | undefined {
-  return ESCALATION_FORM_BY_ELEMENT[elementId];
+  // Derive the twin's COMPILED form from its id rather than inferring one form from the shared `__esc`
+  // suffix: a `wait`-gate twin (`…__esc__wait`, kind marker stamped by the compiler) renders the
+  // select-less GENERIC_HUMAN_FORM (no retry path); a service-node `__esc`/`__contract` twin renders the
+  // retry-capable ESCALATION_FORM. Mapping the wait twin to ESCALATION_FORM would denormalise a bogus
+  // "Retry this step" onto its Tasks row (the wait process silently ignores `decision`) whenever the
+  // engine omits `formKey` (PR #863 review, app/agentCompletion.ts:186).
+  if (isDeliveryWaitEscalationTwin(elementId)) return GENERIC_HUMAN_FORM;
+  return ESCALATION_FORM_BY_ELEMENT[elementId] ?? (isDeliveryEscalationTwin(elementId) ? ESCALATION_FORM : undefined);
 }
 
 /** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use
@@ -261,7 +276,7 @@ export function validateEscalationVariables(
   elementId: string,
   variables: Record<string, unknown>,
 ): string | null {
-  const formId = ESCALATION_FORM_BY_ELEMENT[elementId];
+  const formId = escalationFormId(elementId);
   if (!formId) return null;
   const { required, allowed, hideWhen } = formContract(formId);
   for (const key of required) {

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

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/contracts.ts

@@ -559,6 +559,15 @@ export const WIRE_CONTRACTS = {
       "The engine-native AgentInstance/AgentHistory READ path (issue #745/#747, umbrella #746 — the CONSUMER half of the PRODUCER `agentTask.agentDefinition` marker). The Cockpit HISTORICAL transcript + per-turn/instance metrics are sourced from the engine read model through the SINGLE engine-read seam — `@nanobpm/urban`'s `EngineClient.searchAgentInstances`/`searchAgentInstanceHistory`/`getAgentInstance` (added in urban 0.93 / nanobpm/nano-ide#563; the escalation's option (a) — NO `orchestration-cluster-api-js` fork / no second broker-REST client, so the read path is exercised by the testkit WASM double, which records read-as-absence — an empty list / null — while a live engine validates the behavioural parity). ONE narrow reader (`AgentHistoryReader`) + ONE projection (`listAgentInstances`/`readAgentHistory`) in app/agentic/agent-history.ts, served by `GET /agentic/agent-instances` + `GET /agentic/agent-instances/{agentInstanceKey}/history`. Correlation keys are the AGENT-INSTANCE / PROCESS-INSTANCE / ELEMENT-INSTANCE keys (the same #544 per-occupancy element-instance handle the relay correlation uses) — NEVER the slash-bearing `job:<jobKey>` relay stream id, so the #744 gateway-proxy bug class is moot for settled history. The token-granular relay stays the LIVE overlay only (settled history = engine, live tail = relay). Advisory read-only (ADR 0056): it observes the engine read model, never activates/completes a job or gates a sequence flow. The wire shapes (`AgentInstance`/`AgentInstanceList`/`AgentHistoryRecord`/`AgentHistory` + the metrics shapes) are declared in openapi.yaml and reuse the `@nanobpm/agentic/transcript` parity conversation grammar the transcript store already models. Consume this ONE read path — do not add a second agent-history client or a synonym endpoint.",
     shape: "GET /agentic/agent-instances[?processInstanceKey&rootProcessInstanceKey&elementId&status] → AgentInstanceList; GET /agentic/agent-instances/{agentInstanceKey}/history[?role&loopIteration&elementInstanceKey] → AgentHistory",
   },
+  "deliveryGraph.workerResult": {
+    category: "wire",
+    name: "deliveryGraph.workerResult",
+    owner: "app/deliveryGraph.ts",
+    semantics:
+      "The delivery-graph worker-completion RESULT envelope (issue #863) — the canonical set of variable names a fleet worker (agent/connector) or an escalation completion returns on a delivery node's job, which the deliveryGraph compiler declares node-LOCAL on the node's subProcess (and clears on retry) so a parallel node never overwrites a sibling's result and a retry never reads a stale one. Three sibling sets, all exported from app/deliveryGraph.ts (the validator's home, so the reserved-fact-name set derives from them without an import cycle): `AGENT_RESULT_LOCAL_VARS` (status/summary/question/output/error/pr/prUrl/pullRequest/branch/commits/exitCode/next_steps/issue/completed/pushed/truncated/agentCheckpoint/transcriptUrl/delta/approved/findings/commentUrl/hasDeviations/slicesMet/slicesReduced/slicesNotVerified/deviationsRaised/deviationsUnraised, plus the prompt-contract outputs dependsOn/adversarialFindings/adversarialSummary/scopeBlocked/scopeBlockReason/tasks/result/conflicts/failing/note), `CONNECTOR_RESULT_LOCAL_VARS` (connectorOutcome/connectorDedupeKey/connectorDetail), and `ESCALATION_LOCAL_VARS` (decision/value/escalationNote — the escalation-completion controls; the retry-guidance note is `escalationNote`, NOT the plain `note`, which is a plan.md WORKER result field that would otherwise be fed back as operator guidance on a note-less retry). These are job-completion outputs and escalation-form variables, NOT message payloads, so the scalar-only message-envelope rule does not apply (array-typed fields like dependsOn/tasks/conflicts/failing are legal here). A new worker/escalation result field MUST be added to the matching set here — never re-declared as a synonym list in the compiler or a worker — or it leaks to the shared root scope.",
+    shape:
+      "AGENT_RESULT_LOCAL_VARS: readonly string[] (28 base + 10 prompt-contract outputs); CONNECTOR_RESULT_LOCAL_VARS: readonly ['connectorOutcome','connectorDedupeKey','connectorDetail']; ESCALATION_LOCAL_VARS: readonly ['decision','value','escalationNote']",
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {