@nanobpm/nano-workforce 0.201.0 → 0.201.2

package/app/deliveryHuman.ts

@@ -32,6 +32,7 @@
 //      binds and pins exactly the value the human handed forward.
 import type { DeliveryFact, DeliveryNodeHuman } from "../nano-generated/api-io.d.ts";
 import { DELIVERY_FACT_TYPES, type DeliveryFactType, FACT_NAME_MAX_LENGTH, FACT_NAME_PATTERN } from "./deliveryGraph.ts";
+import { redactFreeText } from "./redactText.ts";
 
 /** The single BPMN `bpmn:userTask` element id every `human` delivery-graph node schedules its work
  *  as (`resources/processes/delivery-human.bpmn`). One reusable engine-native body, instantiated once
@@ -54,6 +55,77 @@ export function isDeliveryHumanElement(elementId: string): boolean {
   return elementId === DELIVERY_HUMAN_ELEMENT || elementId.startsWith(`${DELIVERY_HUMAN_ELEMENT}__`);
 }
 
+/** The id suffix the S4 compiler appends for a service node's bounded-timeout escalation TWIN user task
+ *  (`delivery-human-task__<el>__esc`). */
+export const DELIVERY_ESCALATION_TWIN_SUFFIX = "__esc";
+
+/** The id suffix for an `agent` node's producer-contract escalation TWIN (`…__contract`). */
+export const DELIVERY_CONTRACT_TWIN_SUFFIX = "__contract";
+
+/** The KIND marker the S4 compiler appends to a `wait` gate's bounded-timeout escalation twin
+ *  (`delivery-human-task__<el>__esc__wait`). A wait-gate escalation has NO retry semantics — its
+ *  resolution is "supply the awaited value and continue", never "re-run the probe loop" — so the
+ *  compiler renders the select-less {@link GENERIC_HUMAN_FORM} for it, NOT the retry-capable
+ *  {@link ESCALATION_FORM} a service-node `__esc`/`__contract` twin renders. The bare `__esc` suffix is
+ *  shared by both kinds, so a form inferred from the suffix ALONE misclassifies the wait gate as
+ *  retryable (the #461 Tasks-inbox `form_key` fallback then renders a bogus "Retry this step" that the
+ *  wait process silently ignores). Stamping the kind into the id lets {@link escalationFormId} DERIVE
+ *  the compiled form from the id — no separate node-kind registry to drift (PR #863 review,
+ *  app/agentCompletion.ts:186). */
+export const DELIVERY_WAIT_ESCALATION_KIND_MARKER = "__wait";
+
+/** The full id suffix of a `wait` gate's bounded-timeout escalation twin (`__esc` + the `__wait` kind
+ *  marker). */
+export const DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX = `${DELIVERY_ESCALATION_TWIN_SUFFIX}${DELIVERY_WAIT_ESCALATION_KIND_MARKER}`;
+
+/** True for a delivery-graph SERVICE-node escalation TWIN user task — the bounded-timeout `__esc` twin
+ *  or an agent's producer-contract `__contract` twin — as opposed to a plain per-node human task
+ *  (`delivery-human-task__<el>`). Unlike that per-node human task, which renders a DIFFERENT form per
+ *  node (and so has no single static completion contract — left unvalidated, `ESCALATION_FORM_BY_ELEMENT`
+ *  deliberately omits it), a twin ALWAYS renders a FIXED escalation form — the retry-capable
+ *  {@link ESCALATION_FORM} (a strict superset of {@link GENERIC_HUMAN_FORM}: same `value`, an optional
+ *  note field (`escalationNote` on the escalation form, `note` on the generic human form), PLUS
+ *  the `decision` select) or the select-less generic form — so its completion variables CAN be validated
+ *  against `ESCALATION_FORM`'s contract (no required fields, so the generic-form twins never false-reject;
+ *  only a present-but-invalid `decision` is rejected). Matched on the convention suffix — single source of
+ *  truth with the compiler's `escalationTaskElement`/`contractEscalationTaskElement` builders — requiring
+ *  a NON-EMPTY `<el>` between prefix and suffix so the bare per-node base of a node literally named
+ *  `esc`/`contract` (`delivery-human-task__esc`) is not misread as a twin. (A node id MAY itself end in
+ *  `__esc` — `NODE_ID_PATTERN` allows it — so the twin of node `foo` and the base of a node named
+ *  `foo__esc` collide on one id; validating that rare base against the superset escalation form is
+ *  harmless, since the form has no required fields and only constrains a `decision` such a base never
+ *  sets to an out-of-range value through its own select-less form.) */
+export function isDeliveryEscalationTwin(elementId: string): boolean {
+  const prefix = `${DELIVERY_HUMAN_ELEMENT}__`;
+  if (!elementId.startsWith(prefix)) return false;
+  for (const suffix of [DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX, DELIVERY_ESCALATION_TWIN_SUFFIX, DELIVERY_CONTRACT_TWIN_SUFFIX]) {
+    if (elementId.endsWith(suffix) && elementId.length > prefix.length + suffix.length) return true;
+  }
+  return false;
+}
+
+/** True for a `wait` gate's bounded-timeout escalation twin specifically (`…__esc__wait`) — the twin
+ *  kind that renders the select-less {@link GENERIC_HUMAN_FORM} (no retry path), as opposed to a
+ *  service-node `__esc`/`__contract` twin, which renders the retry-capable {@link ESCALATION_FORM}.
+ *  This is the discriminator {@link escalationFormId} uses to DERIVE the compiled form from the id. */
+export function isDeliveryWaitEscalationTwin(elementId: string): boolean {
+  const prefix = `${DELIVERY_HUMAN_ELEMENT}__`;
+  return (
+    elementId.startsWith(prefix) &&
+    elementId.endsWith(DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX) &&
+    elementId.length > prefix.length + DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX.length
+  );
+}
+
+/** Strip the trailing escalation-twin suffix (`__esc`, the wait-gate `__esc__wait`, or `__contract`)
+ *  to recover the base per-node element id (`delivery-human-task__<el>`). The `__esc__wait` kind marker
+ *  MUST be stripped before the bare `__esc` (it ends in `__esc`, so stripping `__esc` first would leave
+ *  a dangling `__wait`). A non-twin id is returned unchanged. Single source of truth for the strip so
+ *  every "resolve the twin to its base node" lookup agrees on the suffix set. */
+export function stripDeliveryEscalationTwinSuffix(elementId: string): string {
+  return elementId.replace(/__(esc__wait|esc|contract)$/, "");
+}
+
 /** The read-model "Decision context" for a parked delivery-graph `human` node (issue #772). The Tasks
  *  surface renders the deployed `.form` against EMPTY data (it seeds no task-local variables), so the
  *  node's instruction cannot reach the operator through the form's readonly `prompt` field — it must
@@ -76,11 +148,45 @@ export function isDeliveryHumanElement(elementId: string): boolean {
 export function deliveryHumanContextQuestion(
   humanLabels: Record<string, string> | undefined,
   elementId: string,
+  livePrompt?: string | null,
 ): string {
   const labels = humanLabels ?? {};
-  const base = elementId.replace(/__esc$/, "");
+  const base = stripDeliveryEscalationTwinSuffix(elementId);
   const label = (labels[elementId] ?? labels[base] ?? "").trim();
-  return label || "A scheduled delivery-graph step is waiting to be completed.";
+  return label || (livePrompt ?? "").trim() || "A scheduled delivery-graph step is waiting to be completed.";
+}
+
+/** Whether a parked delivery task needs its LIVE engine prompt for the "Decision context": an
+ *  `__esc`/`__contract` escalation twin of a bounded agent/wait/connector node has no stamped
+ *  `human_labels` entry, so without the compiler's per-task `prompt` (node, reported status, missing
+ *  emits, the agent's own report/question/transcript, and how to resolve) the operator saw only the
+ *  static fallback — the "no actionable information" escalations of instance 171774. A real human
+ *  node (or its `__esc` twin) keeps its authored instruction label. */
+export function needsLiveDeliveryPrompt(humanLabels: Record<string, string> | undefined, elementId: string): boolean {
+  if (!/__(esc__wait|esc|contract)$/.test(elementId)) return false;
+  const labels = humanLabels ?? {};
+  const base = stripDeliveryEscalationTwinSuffix(elementId);
+  return !(labels[elementId] ?? labels[base] ?? "").trim();
+}
+
+/** Decode a `prompt` variable as the engine's variable search reports it (a JSON-encoded value) into
+ *  plain text; `null` for an absent, non-string, or truncated preview (never show a clipped prompt as
+ *  if it were whole — the caller falls back).
+ *
+ *  The decoded text is REDACTED ({@link redactFreeText}) before it is returned: the escalation prompt
+ *  embeds agent-controlled `summary`/`question`/`error`/`transcriptUrl` (the compiler's report
+ *  sentence), and the caller persists the result as the operator-facing `user_tasks.question`. An
+ *  agent report can carry a token-bearing URL or a credential copied into its report, so this path
+ *  redacts exactly like the static `human_labels` instruction (which `buildHumanLabels` runs through
+ *  `redactFreeText`, issue #778) — never store a live prompt raw (issue #863 review). */
+export function decodeLivePrompt(row: { value: string; isTruncated?: boolean } | undefined): string | null {
+  if (!row || row.isTruncated) return null;
+  try {
+    const v: unknown = JSON.parse(row.value);
+    return typeof v === "string" && v.trim() ? redactFreeText(v.trim()) : null;
+  } catch {
+    return null;
+  }
 }
 
 /** The clickable link for a parked delivery-graph `human` node's Tasks-inbox row (issue #813): the
@@ -96,7 +202,7 @@ export function deliveryHumanContextUrl(
   elementId: string,
 ): string | null {
   const labels = humanLabels ?? {};
-  const base = elementId.replace(/__esc$/, "");
+  const base = stripDeliveryEscalationTwinSuffix(elementId);
   const instruction = labels[elementId] ?? labels[base] ?? "";
   const url = firstHttpUrl(instruction);
   // The stored `human_labels` are display-REDACTED (`redactFreeText` in `buildHumanLabels`): a URL that
@@ -179,6 +285,12 @@ export function firstHttpUrl(text: string | undefined | null): string | null {
  *  declared emitted fact, so a human node with no explicit/category form can STILL emit downstream. */
 export const GENERIC_HUMAN_FORM = "delivery-human-generic";
 
+/** The bounded service-node ESCALATION form (retry-node resolution): like the generic form plus the
+ *  `decision` Resolution select (Continue / Retry this step). Kept SEPARATE from {@link GENERIC_HUMAN_FORM}
+ *  — that form is shared with plain scheduled human steps and wait-gate escalations, which have no
+ *  retry semantics and never read `decision`, so the select must not render there. */
+export const ESCALATION_FORM = "delivery-escalation";
+
 /** The "click done" category form: a degenerate no-emit acknowledgement ("now do X" → done). */
 export const HUMAN_ACK_FORM = "delivery-human-ack";
 

package/app/deliveryRunner.test.ts

@@ -238,12 +238,12 @@ test("producer contract required-emit subset (#761): a routing-only emit is NOT
   const graph: DeliveryGraph = {
     name: "routing-only producer",
     nodes: [
-      { id: "classify", kind: "agent", agent: { jobType: "senior:feature", prompt: "classify it" }, emits: [{ name: "decision", type: "string" }] },
+      { id: "classify", kind: "agent", agent: { jobType: "senior:feature", prompt: "classify it" }, emits: [{ name: "verdict", type: "string" }] },
       { id: "migrate", kind: "connector", connector: { target: "npm:install", dedupeKey: "m-1" } },
       { id: "release", kind: "connector", connector: { target: "npm:publish", dedupeKey: "r-1" } },
     ],
     edges: [
-      { from: "classify", to: "migrate", when: "classify.decision", equals: "breaking" },
+      { from: "classify", to: "migrate", when: "classify.verdict", equals: "breaking" },
       { from: "classify", to: "release", default: true },
     ],
   };
@@ -257,7 +257,7 @@ test("producer contract required-emit subset (#761): a routing-only emit is NOT
   assert(!prompt.includes("populate each of these top-level fields"), "no required-emit sentence is rendered when every emit is routing-only");
   // The classifier-emit contract STILL tells the agent to return the routing fact (and omit if undecidable).
   assert(prompt.includes("Classifier emit contract"), "the classifier-emit contract is present");
-  assert(prompt.includes("`decision`"), "the routing fact is still named by the classifier-emit contract");
+  assert(prompt.includes("`verdict`"), "the routing fact is still named by the classifier-emit contract");
 });
 
 

package/app/mergeLoopBehaviour.test.ts

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

package/app/redactText.ts

@@ -0,0 +1,88 @@
+// Free-form-prose URL-credential redaction (`redactFreeText`) lives in this LOW-LEVEL helper module so
+// both the delivery-graph compiler (`deliveryGraphCompiler.ts`, which embeds redacted prompts into the
+// generated BPMN display name/documentation) AND `deliveryHuman.ts` (which redacts a decoded live
+// prompt / human labels) can import it WITHOUT a cycle. Previously `redactFreeText` was defined in the
+// compiler and `deliveryHuman.ts` imported the compiler solely for it — a direct `compiler ⇄ human`
+// import cycle that reversed `deliveryHuman.ts`'s documented pure-helper layering and made module init
+// depend on ESM cycle ordering (PR #863 review — thread deliveryGraphCompiler.ts / deliveryHuman.ts).
+// This module depends only on the character-class strip (`deliveryGraph.ts`) and the canonical URL
+// redactors (`readiness.ts`), both strictly lower layers, so nothing here can import back.
+
+import { stripXmlInvalidChars } from "./deliveryGraph.ts";
+import { redactEmbeddedCredential, redactString } from "./readiness.ts";
+
+/** Redact credential-bearing pieces of any URL embedded in FREE-FORM prose (a node's authored
+ * `prompt`), IN PLACE. Unlike {@link redactString} — tuned for a single opaque target string, where it
+ * truncates from the first `?`/`#` to end-of-string — this finds each URL-shaped token *within*
+ * surrounding prose (`scheme://…` or a scheme-relative `//…`) and strips only that token's
+ * `user:pass@` userinfo and `?query`/`#fragment` via `redactString`, leaving the prose (and ordinary
+ * punctuation such as a `?` ending a sentence) intact. Applied to the DISPLAY name/documentation only —
+ * a prompt is up to 20 000 chars of arbitrary text that can embed a bearer token or private URL, and
+ * the deployed `<bpmn:documentation>`/name is visible to modeler/explorer readers; the RAW prompt still
+ * reaches the runtime job input (`appendPrompt`/`prompt`) unmodified (issue #778 review). Deterministic
+ * and total. */
+export function redactFreeText(value: string): string {
+  // Strip XML-invalid display characters BEFORE tokenizing/redacting so every scan runs on the exact
+  // string the renderer emits. Otherwise a control char embedded in a URL (`//us\x0Ber:pass@…`) breaks
+  // the `//[^\s]+` token match, escapes redaction, then reconstructs the credential once `escapeXml`/
+  // `stripXmlInvalidChars` drops the control at render time (issue #778 review — same class as the
+  // connector/probe strip-before-classify fix).
+  const cleaned = stripXmlInvalidChars(value);
+  // Embedded credential userinfo: DERIVE from the ONE canonical redactor {@link redactEmbeddedCredential}
+  // (`EMBEDDED_CREDENTIAL_SRC` = `//[^/?#]*@`) rather than a bespoke belt heuristic. Its `[^/?#]` class
+  // spans spaces/TABs/newlines up to the LAST `@` before a `/`/`?`/`#`, so EVERY `//<userinfo>@` shape
+  // collapses uniformly to `//***@` — a colon-prefix `//user:pass@`, a colon-LESS bearer separated from
+  // its `@host` by a word or space (`//token part@host`, `//token @host`), a userinfo split by a raw
+  // CR/LF/TAB, and a malformed multi-`@` authority (`//user:pass@ss@host`) — with NO second "what is a
+  // credential" implementation that can drift from the canonical redactor/validator (`hasEmbeddedCredential`)
+  // (issue #783 review — thread deliveryGraphCompiler.ts:1140; the earlier bespoke colon-less bridge
+  // stopped on the first non-whitespace char after the space and leaked `//token part@host`). A `//…@`
+  // span is UNAMBIGUOUSLY a credential wherever it sits, so redacting a prose `//word …@host` too is the
+  // SAFE direction: the RAW prompt still reaches the runtime job input unmodified — only the operator-
+  // visible display doc loses the span. The `[^/?#]` bound also keeps the userinfo from swallowing a `?`
+  // marker (`//host?token=secret@tail` has no userinfo — its `@` rides the query), leaving that tail to
+  // the query/fragment belt below.
+  const credStripped = redactEmbeddedCredential(cleaned);
+  // Query/fragment across a whitespace BREAK: the primary `//[^\s]+` token below stops at the break, so a
+  // `//host/?\nTOKEN=secret` would leave the value visible in the XML-preserved doc. The linear belt walks
+  // each SPACE-bounded `//`-run (crossing an embedded CR/LF/TAB the primary token stopped at) and
+  // CONSERVATIVELY redacts its `?query`/`#fragment` tail through the span's space boundary — a continuation
+  // past the break is indistinguishable from a split value, so we never keep the far side (issue #778
+  // review — thread deliveryGraphCompiler.ts:1115).
+  const belted = redactQueryFragmentSpans(credStripped);
+  return belted.replace(/(?:[a-z][a-z0-9+.-]*:)?\/\/[^\s]+/gi, (m) => redactString(m));
+}
+
+/** Linear (backtracking-free) newline-aware belt companion to {@link redactFreeText}'s primary
+ * whitespace-bounded pass. Each `//`-run is bounded by a literal SPACE (0x20) — so a single span may
+ * cross a CR/LF/TAB *inside* the URL that the primary `//[^\s]+` token stopped at. Credential userinfo is
+ * already collapsed to `//***@` by the canonical {@link redactEmbeddedCredential} before this runs, so the
+ * belt's SOLE remaining job is a `?query`/`#fragment` tail: it redacts CONSERVATIVELY from the first
+ * `?`/`#` marker through the span's space boundary — a continuation past an embedded break is
+ * indistinguishable from a split value, so the far side is never kept. A span with no `?`/`#` (ordinary
+ * prose — a `//comment` reference, an already-collapsed `//***@host`) is returned untouched. The scan is a
+ * single left-to-right walk using `indexOf`/`charCodeAt` over spans bounded by the next SPACE, with no
+ * regex backtracking, so a 20 000-char adversarial prompt cannot trigger catastrophic backtracking (issue
+ * #778 review). Deterministic and total. */
+function redactQueryFragmentSpans(text: string): string {
+  let out = "";
+  let i = 0;
+  for (;;) {
+    const start = text.indexOf("//", i);
+    if (start < 0) return out + text.slice(i);
+    out += text.slice(i, start);
+    let end = start;
+    while (end < text.length && text.charCodeAt(end) !== 0x20 /* SPACE */) end++;
+    const span = text.slice(start, end);
+    const qMark = span.indexOf("?");
+    const hMark = span.indexOf("#");
+    const qi = qMark < 0 ? hMark : hMark < 0 ? qMark : Math.min(qMark, hMark);
+    // CONSERVATIVE: keep everything up to and including the `?`/`#` marker, then collapse the whole tail
+    // (any continuation past an embedded CR/LF/TAB) to `***`. A value/prose resuming after the break is
+    // INDISTINGUISHABLE from a split-credential continuation, so we never keep the post-break side; the RAW
+    // prompt still reaches the runtime job input unmodified (issue #778 review — thread
+    // deliveryGraphCompiler.ts:1115).
+    out += qi < 0 ? span : `${span.slice(0, qi + 1)}***`;
+    i = end;
+  }
+}

package/app/service.ts

@@ -10,6 +10,7 @@
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { ABANDONED_STATUS, abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { matchAdjudication, prAdjudications, resetAdjudications } from "./adjudications.ts";
+import { AGENT_SLA_JOB_TYPES, recordAgentJobObservation } from "./agentActivationLedger.ts";
 import { completeEscalationAutoApplied, escalationFormId } from "./agentCompletion.ts";
 import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import {
@@ -34,7 +35,7 @@ import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./deliver
 import { DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels, reconcileOriginalInstanceBeforeRelaunch, reconcileStaleLaunchClaim } from "./deliveryGraphRun.ts";
-import { deliveryHumanContextQuestion, deliveryHumanContextUrl, isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { decodeLivePrompt, deliveryHumanContextQuestion, deliveryHumanContextUrl, isDeliveryHumanElement, needsLiveDeliveryPrompt } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
 import { deriveFeatureCompletion, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns, featureRunsTracking, foldCompletedFeatureRun } from "./feature.ts";
@@ -1733,6 +1734,98 @@ interface JobSearchItem {
   /** The job's `zeebe:taskDefinition` type — read to defensively re-filter the wire `$in` type
    * filter so a non-agent job can never masquerade as a leasing convergence agent. */
   type?: string;
+  /** The owning process instance — keyed into the activation ledger (issue #879). */
+  processInstanceKey?: string;
+  /** The engine job key — the unique id of THIS job attempt. The activation ledger uses it to tell one
+   * attempt of a retrying agent task from the next (issue #879 review). */
+  jobKey?: string;
+}
+
+/** One agent-activation ledger poll pass (issue #879). Unlike {@link pollJobActivationImpl} (which
+ * tracks only the review-round for the pages grid), this records — for EVERY bounded agent job type —
+ * whether a worker ever picked the job up, into the durable `agent_job_activations` ledger. When an
+ * agent-task SLA boundary later cancels a job, the job's engine state is gone, so the escalation
+ * recorder cannot ask the engine whether it was ever activated; this ledger, captured WHILE the job is
+ * live, is what lets the escalation distinguish a NEVER-ACTIVATED (queue-starved) job from an
+ * ACTIVATED-but-hung one.
+ *
+ * It reads the same activation signal as the review-round pass: the Camunda-8 `/v2/jobs/search` wire
+ * API collapses Activated -> CREATED (no ACTIVATED enum), so a leased job is recognised by its
+ * `worker`/`deadline` fields. One paged search across all bounded agent types per pass upserts the
+ * ledger by (processInstanceKey, type), keyed to the current attempt by `jobKey`. Best-effort: a
+ * transport failure leaves the ledger untouched and the next pass retries. */
+async function pollAgentActivations(
+  data: DataLayer,
+  restAddress: string,
+  engineToken: string | undefined,
+) {
+  const base = restAddress.replace(/\/+$/, "");
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (engineToken) headers.authorization = `Bearer ${engineToken}`;
+  await pollAgentActivationsImpl(data, base, headers);
+}
+
+/** Testable core of {@link pollAgentActivations}: query the engine for every CREATED bounded-agent job
+ * and upsert the activation ledger. Split out so tests can drive it with a stubbed `fetch`. */
+export async function pollAgentActivationsImpl(
+  data: DataLayer,
+  base: string,
+  headers: Record<string, string>,
+) {
+  // Page through EVERY matching open job: a single first-page read would, under fleet saturation, let
+  // long-lived jobs occupy the page on every pass while later jobs time out with their activation never
+  // recorded — exactly when the never-started/hung distinction matters most. Mirror the paging contract
+  // the other engine sweeps use (`page: { from, limit }`, stop on a short page). (#881 review)
+  const ts = now();
+  const limit = 200;
+  let from = 0;
+  for (let guard = 0; guard < 1000; guard++) {
+    let items: JobSearchItem[] = [];
+    try {
+      const res = await fetch(`${base}/jobs/search`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          filter: {
+            type: { $in: [...AGENT_SLA_JOB_TYPES] },
+            // A merely-created (queued) AND an activated-but-not-yet-completed job both project to
+            // CREATED on the wire (Camunda has no ACTIVATED enum) — so this one filter captures both,
+            // and the leasing `worker` field discriminates them at upsert time.
+            state: "CREATED",
+          },
+          page: { from, limit },
+        }),
+      });
+      if (!res.ok) return; // engine unhappy → keep the ledger as-is, retry next pass
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = (await res.json()) as { items?: JobSearchItem[] };
+      items = body.items ?? [];
+    } catch (err) {
+      console.error(`[poller] agent-activation search: ${err}`);
+      return;
+    }
+    for (const j of items) {
+      const jobType = j.type ?? "";
+      const pik = j.processInstanceKey ?? "";
+      // Defensively re-filter the wire `$in` type filter and require a process instance to key on.
+      if (pik.length === 0 || !AGENT_SLA_JOB_TYPES.includes(jobType)) continue;
+      const worker = typeof j.worker === "string" && j.worker.length > 0 ? j.worker : null;
+      const jobKey = typeof j.jobKey === "string" && j.jobKey.length > 0 ? j.jobKey : null;
+      try {
+        await recordAgentJobObservation(data, {
+          processInstanceKey: pik,
+          jobType,
+          worker,
+          jobKey,
+          now: ts,
+        });
+      } catch (err) {
+        console.error(`[poller] agent-activation upsert ${pik}:${jobType}: ${err}`);
+      }
+    }
+    if (items.length < limit) break; // last page
+    from += items.length;
+  }
 }
 
 /** One job-activation poll pass. The `converging` status means the process is parked at a
@@ -3316,7 +3409,21 @@ export async function pollUserTasks(
     // null), so this is the only link a delivery human task can offer.
     let deliverySubjectUrl: string | null = null;
     if (question === null && isDeliveryHumanElement(elementId)) {
-      question = deliveryHumanContextQuestion(subj?.humanLabels, elementId);
+      let livePrompt: string | null = null;
+      if (needsLiveDeliveryPrompt(subj?.humanLabels, elementId)) {
+        // An agent/wait/connector escalation twin: read the task's OWN compiler-rendered `prompt`, local
+        // to the user task's element instance (fail-open to the static fallback on any read error).
+        try {
+          const [ei] = await engine.searchElementInstances({ processInstanceKey, elementId, state: "ACTIVE" });
+          if (ei) {
+            const [row] = await engine.searchVariables({ scopeKey: String(ei.elementInstanceKey), name: "prompt" });
+            livePrompt = decodeLivePrompt(row);
+          }
+        } catch (err) {
+          console.error(`[poller] delivery escalation prompt (${processInstanceKey}/${elementId}): ${err}`);
+        }
+      }
+      question = deliveryHumanContextQuestion(subj?.humanLabels, elementId, livePrompt);
       deliverySubjectUrl = deliveryHumanContextUrl(subj?.humanLabels, elementId);
     }
     return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? deliverySubjectUrl, question, processKey: processInstanceKey, formKey: resolvedFormKey };
@@ -3703,6 +3810,7 @@ export async function pollOnce(
     await pollWaveGatesImpl(data, engine, token, base, headers);
     await pollCapabilityGatesImpl(data, engine, base, headers);
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
+    await pollAgentActivations(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);
   }
 }

package/db/migrations/119_agent_job_activations.sql

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

package/e2e/agent-sla-boundary.e2e.ts

@@ -307,13 +307,25 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
       );
       const task = await openTaskById(app, processKey, "trial-merge-decision");
       assert.ok(task?.userTaskKey, "the merge-cell parked a completable trial-merge decision task");
+
+      // UNKNOWN activation fixture (issue #881 review): no activation-ledger row exists for this attempt
+      // (the in-test poller records none), so the recorder must word the escalation honestly as
+      // "activation unknown" — never the removed blanket "hung or looping".
+      const slaAudit = (
+        await app.db
+          .table<{ id: number; plan_key: string; summary: string | null }>("plan_trial_merges", "id")
+          .find({ plan_key: "owner/repo#1" })
+      ).sort((a, b) => b.id - a.id)[0];
+      assert.ok(
+        (slaAudit?.summary ?? "").includes("no worker-activation was ever recorded"),
+        `an unobserved job escalates with honest ambiguity (got: ${slaAudit?.summary})`,
+      );
     } finally {
       await app.stop();
       rmSync(dbDir, { recursive: true, force: true });
     }
   });
 
-  // Regression for PR #864 review r3: on an SLA during a RERUN the recorder must not replay the
   // prior COMPLETED attempt's process-scope `result`/`summary`/`conflicts`/`failing`. The
   // `=null` ioMapping on `trial-merge` is task-local, so without a dedicated SLA recorder the
   // interrupted second attempt would inherit attempt one's stale verdict. Drive ONE instance: a
@@ -381,6 +393,19 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
       );
 
       // The second agent hangs; the SLA fires. The DEDICATED SLA recorder must pin the TIMEOUT verdict.
+      // Seed an ACTIVATED activation-ledger fixture for THIS attempt (issue #881 review) so the recorder
+      // reads the ledger and produces the activation-aware "started but hung" reason — exercising the
+      // builder's activated branch end-to-end through record-trial-merge-sla, not just the pure builder.
+      await app.db.table("agent_job_activations", "id").insert({
+        id: `${processKey}:senior:trial-merge`,
+        process_instance_key: processKey,
+        job_type: "senior:trial-merge",
+        first_seen_at: "2024-01-01T00:00:00Z",
+        activated_at: "2024-01-01T00:05:00Z",
+        worker: "agent-stuck",
+        job_key: "rerun-attempt",
+        updated_at: "2024-01-01T00:05:00Z",
+      });
       await advancePastTimer(app, PAST_AGENT_SLA_MS);
       flows = takenFlows(app);
       assert.ok(
@@ -402,11 +427,15 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
         .find({ plan_key: "owner/repo#1" });
       const slaRow = audits.sort((a, b) => b.id - a.id)[0];
       assert.equal(slaRow.result, "suite-failed", "the SLA row records the timeout verdict");
-      assert.equal(
-        slaRow.summary,
-        `The trial-merge agent exceeded its time budget (SLA ${AGENT_SLA_TIMEOUT}) without returning a machine-readable result — it is hung or looping. Acknowledge to record the timeout and decide whether to rerun the trial merge.`,
-        "the SLA row pins the timeout summary, not the stale prior-attempt summary",
+      // Activation-aware summary: names the job type, the leasing worker, and the hung diagnosis — NOT
+      // the stale first-attempt summary, and NOT the removed blanket wording.
+      assert.ok(
+        (slaRow.summary ?? "").includes("senior:trial-merge") &&
+          (slaRow.summary ?? "").includes("hung or looping") &&
+          (slaRow.summary ?? "").includes("agent-stuck"),
+        `the SLA row pins the activation-aware timeout summary (got: ${slaRow.summary})`,
       );
+      assert.equal((slaRow.summary ?? "").includes("stale prior-attempt summary"), false, "not the stale summary");
       assert.equal(slaRow.conflicts, null, "the SLA row clears the stale prior-attempt conflicts");
       assert.equal(slaRow.failing, null, "the SLA row clears the stale prior-attempt failing list");
     } finally {
@@ -552,7 +581,20 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
       assert.equal(filed?.status, "filed", "the conformance verdict was filed before synthesize");
       assert.equal(filed?.slices_met, 3);
 
-      // Fire the synthesize SLA.
+      // Fire the synthesize SLA. Seed a QUEUED (never-activated) activation-ledger fixture for the
+      // synthesize (senior:retro) attempt (issue #881 review) so the recorder reads it and APPENDS the
+      // activation-aware never-observed-activated reason — exercising the builder's queued branch
+      // end-to-end through conformance-record, not just the pure builder.
+      await app.db.table("agent_job_activations", "id").insert({
+        id: `${processKey}:senior:retro`,
+        process_instance_key: processKey,
+        job_type: "senior:retro",
+        first_seen_at: "2024-01-01T00:00:00Z",
+        activated_at: null,
+        worker: null,
+        job_key: "synthesize-attempt",
+        updated_at: "2024-01-01T00:00:00Z",
+      });
       await advancePastTimer(app, PAST_AGENT_SLA_MS);
       const flows = takenFlows(app);
       assert.ok(
@@ -587,8 +629,9 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
         `the audit summary is preserved and the SLA reason appended (got: ${row?.summary})`,
       );
       assert.ok(
-        (row?.summary ?? "").includes("retrospective-synthesis agent exceeded its time budget"),
-        "the synthesis-timeout context is appended to the summary",
+        (row?.summary ?? "").includes("No worker was ever observed to pick up") &&
+          (row?.summary ?? "").includes("senior:retro"),
+        `the activation-aware synthesis-timeout context is appended to the summary (got: ${row?.summary})`,
       );
     } finally {
       await app.stop();