@nanobpm/nano-workforce 0.138.0 → 0.138.2

package/AGENTS.md

@@ -211,6 +211,42 @@ Two different `nano:dataEnvelope` uses have different rules — don't conflate t
   deriving a worker's array inputs from the model this way over a hand-typed
   `interface In`; don't "fix" a modelled `list="true"` array back to a joined
   scalar.
+- **A service-task/worker `dataEnvelope.in` field is read from PROCESS scope, not
+  task-local `ioMapping`.** (This applies to service-task/worker job envelopes; a
+  `dataEnvelope.in` on a **message subscription** — e.g. `CapsResolved` at
+  `plan-fanout.bpmn:12` — is instead populated from the correlated **message
+  payload**, so this gotcha does not apply there.) At runtime the engine populates
+  each declared `.in` field *by name* from the process variables in scope — a
+  `<zeebe:ioMapping>` input that synthesises a **new** name with no backing process
+  variable is silently ignored, so the field arrives **blank**. The engine itself
+  raises no incident for that *omitted* field (an `.in` name with no backing
+  variable resolves to null and blanks) — but this is distinct from a FEEL
+  `ioMapping` that **errors**: on the pinned engine (`@nanobpm/engine-wasm` 0.8.1's
+  `IO_MAPPING_ERROR` fix — before it, a failed mapping silently blanked, e.g. a
+  blocked converge-gate's escalation *question*; see the `e2e/*escalation*.e2e.ts`
+  comments) a failed FEEL mapping now raises an **incident** rather than blanking
+  through. A consumer that fails fast on the blank value will also incident (e.g.
+  `pr.readiness-probe` once read an empty `gateKey`;
+  `readGateVars` in `workers/readiness-probe/worker.ts` now *throws* on a blank
+  `gateKey`, creating an incident). Tasks like `ensure-base-branch` work only because
+  `repo`/`baseBranch` already exist as process variables. Seed any field a task must
+  read — **that is not already created in the task's visible process scope** — as a
+  real process variable at plan start (e.g. in `startPlan`); don't rely on
+  `ioMapping` to synthesise it. (A field already materialised in scope by the
+  process — e.g. `ReadinessProbeIn.probe`, seeded per multi-instance child via
+  `inputElement="probe"` in `resources/processes/feature.bpmn` — needs no such
+  seeding.) A **constant/literal** ioMapping source is different again: a
+  `<zeebe:input source="=true" target="lastAttempt"/>` (the readiness-gate
+  boundary's last-attempt marker — `readiness-gate.bpmn:125`, `feature.bpmn:105`,
+  `plan-fanout.bpmn:198`, and the generated `deliveryGraphCompiler.ts:1011`) is
+  *evaluated* and materialised into the job's scope, so it needs **no** backing
+  process variable — its value is the literal, not a reference to an (absent)
+  variable. The "arrives blank" failure above is specific to a field whose value
+  must be *derived from a process variable that isn't in scope* (the `gateKey`
+  case). Do **not** "fix" a working literal marker like `lastAttempt` by seeding
+  it as a process variable: besides being unnecessary, seeding a var an
+  in-subprocess gateway reads re-introduces the multi-instance `=null`-shadow
+  gotcha above.
 
 ## Urban page runtime: rendering primitives are not JS-truthy
 
@@ -235,6 +271,21 @@ silently — cheap to avoid, annoying to debug after the fact.
   `showWhenField` is hidden for `0`/`null`/`""` alike — so a `0`-or-`NULL` flag
   correctly hides it either way. (This is why the same flag can need `NULL` for a
   badge yet work as `0` for a `showWhenField` button.)
+- **Renderer kinds are a version-pinned set — verify against the installed
+  package, not an issue reference.** The page renderers are a finite set fixed by
+  the pinned `@nanobpm/urban`; a version *range* only guarantees *some* matching
+  build is installed. Do **not** assume a primitive exists because an issue,
+  changelog, or *Links* section mentions it — `urban check` (a CI gate) rejects
+  unknown renderer kinds only *after* you've authored a page around a phantom one
+  (epic #254 bounced three review rounds asserting a page-level "stepper" that
+  never shipped). Confirm the kind against the installed `RENDERERS` map
+  (`node_modules/@nanobpm/urban/dist/runtime/core/modules/pages.js`) and the kinds
+  already used across `pages/*.page.json`. Note a **nano-ide issue can ship a data
+  read-model, not a page renderer** (nano-ide#254 shipped the lineage projection, a data
+  primitive) — read *what kind* of primitive it delivers. Build composite visuals
+  as a `dataGrid` column renderer over stored columns (e.g. the `"kind":
+  "pipeline"` column in `pages/feature.page.json`), not a page-level primitive,
+  unless you've verified that primitive exists in the installed build.
 
 ### The top nav has a single source of truth — edit `pages/_nav.json`
 
@@ -271,10 +322,24 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
 - Number a new migration after the current highest prefix (they apply in order).
   Check `origin/main`, not your branch point — a fan-out epic branch forks at one
   prefix while `main` keeps advancing, so the branch-local "next" number collides
-  on merge. Two files must never share a prefix; `npm run check:migrations`
+  on merge. **In a *simultaneous* fan-out wave, checking `origin/main` isn't
+  enough**: every sibling forks at the same commit, sees the same highest prefix,
+  and independently takes the same next number (main hasn't advanced yet), so the
+  planner must **pre-assign each slice a disjoint prefix block at decomposition
+  time** (e.g. give slice A `NNN`–`NNN+1`, slice B `NNN+2`–`NNN+3`, plus a separate
+  cleanup block — start the whole allocation *after* the current highest committed
+  prefix, never at fixed literals like `060`, which are long occupied) rather than
+  have each
+  agent compute "the next free" prefix. (This is the same "coarsen parallel work on
+  a shared surface" principle as the one-task-owns-each-`.bpmn` rule above — a
+  migration-prefix block is a shared numbering surface just like a `.bpmn`
+  diagram.) Two files must never share a prefix; `npm run check:migrations`
   (a CI gate) enforces this and fails the build on any new duplicate. Because a
-  prefix collision only exists in the *union* of two branches, this gate — like
-  `layout:check` and the generated-artifact `--check`s — is also re-run on the
+  **merge-skew** prefix collision only exists in the *union* of two branches (a
+  single branch that adds two same-prefix files is a self-collision
+  `check:migrations` already catches on the PR itself), this gate — like
+  `layout:check`, the navigation-index check (`sync:nav:check`), and a catch-all
+  committed-artifact backstop (`git diff --exit-code`) — is also re-run on the
   merge queue's **prospective merged commit** and on **push to `main`** by
   `.github/workflows/invariants.yml` (issue #366), so a merge-skew collision is
   blocked at merge time or fails a `main`-scoped build within minutes rather than

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.138.2](https://github.com/nanobpm/nano-workforce/compare/v0.138.1...v0.138.2) (2026-08-24)
+
+### Documentation
+
+* **agents:** consolidate retro feedback ([#268](https://github.com/nanobpm/nano-workforce/issues/268), [#322](https://github.com/nanobpm/nano-workforce/issues/322), [#449](https://github.com/nanobpm/nano-workforce/issues/449)); drop stale [#415](https://github.com/nanobpm/nano-workforce/issues/415) ([#518](https://github.com/nanobpm/nano-workforce/issues/518)) ([3c47cb2](https://github.com/nanobpm/nano-workforce/commit/3c47cb21d079b6b9f5470abacb0190373208d0ca)), closes [#416](https://github.com/nanobpm/nano-workforce/issues/416) [#887](https://github.com/nanobpm/nano-workforce/issues/887) [#254](https://github.com/nanobpm/nano-workforce/issues/254) [#254](https://github.com/nanobpm/nano-workforce/issues/254) [nano-ide#254](https://github.com/nanobpm/nano-ide/issues/254)
+
+## [0.138.1](https://github.com/nanobpm/nano-workforce/compare/v0.138.0...v0.138.1) (2026-08-24)
+
+### Bug Fixes
+
+* **delivery-graph:** self-diagnosing + resumable capability wait-gate escalation ([#514](https://github.com/nanobpm/nano-workforce/issues/514)) ([#515](https://github.com/nanobpm/nano-workforce/issues/515)) ([b13ae50](https://github.com/nanobpm/nano-workforce/commit/b13ae50bf9638a5eabd12342e9c3d1ba7d70eaab)), closes [#499](https://github.com/nanobpm/nano-workforce/issues/499)
+
 ## [0.138.0](https://github.com/nanobpm/nano-workforce/compare/v0.137.0...v0.138.0) (2026-08-24)
 
 ### Features

package/app/deliveryGraphCompiler.test.ts

@@ -160,6 +160,99 @@ test("#499 escalation context: an agent-node timeout escalation seeds a context
   assert(escBlock.includes('="none"') && escBlock.includes('target="emitMode"'), "the escalation labels its emit field N/A so the generic form hides the inert value input");
 });
 
+// The #514 motivating case: a `capability` wait gate that emits a version, escalating on a
+// false-negative. Its escalation must be self-diagnosing (Defect A) AND resumable with its emit
+// (Defect B). Two emit shapes (`version` → `detail`, `artifact` → `resolvedArtifact`) exercise the
+// per-emit-type mapping.
+const CAP_GATE = {
+  name: "capability gate",
+  nodes: [
+    { id: "gv", kind: "agent", agent: { jobType: "senior:feature", prompt: "ship the rollup" } },
+    {
+      id: "n2",
+      kind: "wait",
+      wait: {
+        kind: "capability",
+        target: "github-releases:nanobpm/nano-ide",
+        match: { package: "@nanobpm/urban", capabilityRef: "#468" },
+        onTimeout: "escalate",
+      },
+      emits: [{ name: "publishedVersion", type: "version" }],
+    },
+    {
+      id: "n3",
+      kind: "wait",
+      wait: {
+        kind: "capability",
+        target: "github-releases:nanobpm/nano-ide",
+        match: { package: "@nanobpm/urban", capabilityRef: "#469" },
+        onTimeout: "escalate",
+      },
+      emits: [{ name: "artifactRef", type: "artifact" }],
+    },
+    { id: "sink", kind: "connector", connector: { target: "npm:install", dedupeKey: "c1" } },
+  ],
+  edges: [
+    { from: "gv", to: "n2" },
+    { from: "n2.publishedVersion", to: "n3" },
+    { from: "n3.artifactRef", to: "sink" },
+  ],
+};
+
+/** The subProcess element id the compiler assigned to a node (elements are positional `n<k>`, not the
+ * node id). Located via the subProcess `name="<kind>: <nodeId>"`. */
+function elementForNode(bpmn: string, nodeId: string): string {
+  const m = bpmn.match(new RegExp(`<bpmn:subProcess id="([^"]+)" name="[^"]*: ${nodeId}"`));
+  assert(m, `a subProcess for node ${nodeId} exists`);
+  return m![1];
+}
+
+/** Slice a compiled BPMN to a node's escalation user task body. */
+function escBlockForNode(bpmn: string, nodeId: string): string {
+  const esc = `delivery-human-task__${elementForNode(bpmn, nodeId)}__esc`;
+  const start = bpmn.indexOf(`<bpmn:userTask id="${esc}"`);
+  assert(start !== -1, `escalation task ${esc} for node ${nodeId} exists`);
+  return bpmn.slice(start, bpmn.indexOf("</bpmn:userTask>", start));
+}
+
+test("#514 Defect A: a capability wait-gate escalation surfaces the probe's last detail, target/match, and observed releases so it is self-diagnosing", async () => {
+  const r = await compileOk(CAP_GATE);
+  const esc = escBlockForNode(r.bpmn, "n2");
+  // The read-only prompt context now folds in the RUNTIME last probe detail + observed candidate summary.
+  assert(esc.includes('target="prompt"'), "the escalation seeds a prompt context line");
+  assert(esc.includes("Last probe: ") && esc.includes("if (is defined(detail)) then string(detail)"), "the prompt folds in the last probe detail");
+  assert(esc.includes("Observed: ") && esc.includes("if (is defined(observed)) then string(observed)"), "the prompt folds in the observed candidate summary");
+  // Discrete diagnostic task variables the form/agent can bind directly.
+  assert(esc.includes('target="probeDetail"'), "the escalation surfaces the probe's last detail as a discrete variable");
+  assert(esc.includes('target="observedReleases"'), "the escalation surfaces the observed candidate releases");
+  assert(/source="=nodeInputs\.[^"]+\.probe\.target" target="probeTarget"/.test(esc), "the escalation surfaces the resolved probe target");
+  assert(/source="=nodeInputs\.[^"]+\.probe\.match" target="probeMatch"/.test(esc), "the escalation surfaces the resolved probe match");
+});
+
+test("#514 Defect B: a resumed wait-node escalation maps the operator-supplied value onto the node's emit source (version→detail, artifact→resolvedArtifact)", async () => {
+  const r = await compileOk(CAP_GATE);
+  // Red before the fix: the wait escalation forced emitMode="none" (hiding the value field) and carried
+  // NO output mapping, so a resume published `<el>_<fact> = null`, starving the downstream consumer.
+  const escV = escBlockForNode(r.bpmn, "n2");
+  // A `version` emit is sourced from `detail` — the operator's captured `value` must be mapped there.
+  assert(escV.includes('="typed"') && escV.includes('target="emitMode"'), "a wait node with emits PRESENTS its value field on escalation, not 'none'");
+  assert(escV.includes("publishedVersion (version)") && escV.includes('target="emitLabel"'), "the emit label names the awaited fact");
+  assert(/source="=if \(is defined\(value\)\) then value else null" target="detail"/.test(escV), "the operator's value is mapped onto the version emit's source var (detail)");
+
+  const escA = escBlockForNode(r.bpmn, "n3");
+  // An `artifact` emit is ALSO sourced from the generic form's single `value` field (the form has no
+  // `resolvedArtifact` field), mapped onto the artifact emit's source var (resolvedArtifact) — so an
+  // artifact wait-node escalation is actually resumable via the UI.
+  assert(/source="=if \(is defined\(value\)\) then value else null" target="resolvedArtifact"/.test(escA), "the operator's value is mapped onto the artifact emit's source var (resolvedArtifact)");
+});
+
+test("#514 Defect B: a service-node escalation (agent) stays inert — no emit field, no resume output mapping (only wait resumes)", async () => {
+  const r = await compileOk(CAP_GATE);
+  const esc = escBlockForNode(r.bpmn, "gv");
+  assert(esc.includes('="none"') && esc.includes('target="emitMode"'), "an agent-node escalation keeps its emit field hidden");
+  assert(!esc.includes("<bpmn:output") && !esc.includes("<zeebe:output"), "an agent-node escalation carries no emit-source output mapping");
+});
+
 
 test("rejects unknown kind (by construction) with a path-qualified error, nothing compiled", async () => {
   const errors = await compileFail({

package/app/deliveryGraphCompiler.ts

@@ -882,7 +882,7 @@ function innerBodyLines(w: NodeWiring): string[] {
     case "connector":
       return serviceBodyLines(el, node.id, `type="${DELEGATE_TASK_TYPE.connector}"`, [], `connector → ${node.connector.target}`);
     case "wait":
-      return waitBodyLines(el, node.id);
+      return waitBodyLines(el, node);
     case "human":
       return humanBodyLines(el, node.id);
     default:
@@ -951,8 +951,19 @@ function serviceBodyLines(
 /** `wait` body: `start → pr.readiness-probe (poll) → ready? → end`, escalating on not-ready or on the
  * `=probeTimeout` engine bound. The probe polls its OWN target, so an unrelated upstream event can
  * never flip it to ready (#274/S2 concurrency-correctness); the `pr` kind (S2) binds `mergedSha`. */
-function waitBodyLines(el: string, nodeId: string): string[] {
+function waitBodyLines(el: string, node: DeliveryNode): string[] {
+  const nodeId = node.id;
   const esc = escalationTaskElement(el);
+  const emits = normaliseEmits(node);
+  // Defect A: read-only probe diagnostics seeded onto the escalation task so the operator/agent can
+  // tell a genuine "not published yet" from a transient false-negative — the probe's last detail, the
+  // resolved target/match, and a compact summary of the candidate releases the probe observed.
+  const diagnosticInputs = [
+    { source: "=if (is defined(detail)) then detail else null", target: "probeDetail" },
+    { source: "=if (is defined(observed)) then observed else null", target: "observedReleases" },
+    { source: `=nodeInputs.${el}.probe.target`, target: "probeTarget" },
+    { source: `=nodeInputs.${el}.probe.match`, target: "probeMatch" },
+  ];
   return [
     `      <bpmn:startEvent id="${el}_start"><bpmn:outgoing>${el}_i0</bpmn:outgoing></bpmn:startEvent>`,
     `      <bpmn:subProcess id="${el}_probeLoop" name="Probe readiness loop: ${escapeXml(nodeId)}">`,
@@ -962,6 +973,7 @@ function waitBodyLines(el: string, nodeId: string): string[] {
     '            <zeebe:output source="=if (is defined(detail)) then detail else null" target="detail" />',
     '            <zeebe:output source="=if (is defined(resolvedArtifact)) then resolvedArtifact else null" target="resolvedArtifact" />',
     '            <zeebe:output source="=if (is defined(mergedSha)) then mergedSha else null" target="mergedSha" />',
+    '            <zeebe:output source="=if (is defined(observed)) then observed else null" target="observed" />',
     "          </zeebe:ioMapping>",
     "        </bpmn:extensionElements>",
     `        <bpmn:incoming>${el}_i0</bpmn:incoming>`,
@@ -1024,7 +1036,8 @@ function waitBodyLines(el: string, nodeId: string): string[] {
       nodeId,
       [`${el}_i4`],
       `${el}_i5`,
-      escalationContextFeel(nodeId, "readiness gate", "probeTimeout", " before its ReadinessProbe went green — decide how to proceed."),
+      waitEscalationContextFeel(nodeId),
+      { resume: { kind: node.kind, emits }, diagnosticInputs },
     ),
     `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i5</bpmn:incoming><bpmn:incoming>${el}_i7</bpmn:incoming></bpmn:endEvent>`,
     flow(`${el}_i0`, `${el}_start`, `${el}_probeLoop`),
@@ -1084,15 +1097,60 @@ function humanBodyLines(el: string, nodeId: string): string[] {
  * convention) that a human OR an agent (ADR 0046) answers to unstick a stalled node. `contextFeel` is
  * a FEEL expression yielding the context line seeded onto the generic form's read-only prompt field
  * (issue #499) — e.g. "Node n1 (senior:feature) exceeded its SLA (PT30M); …" — so the operator can see
- * WHICH node timed out and that in-flight work may already exist, instead of a blank form. The emit
- * field is labelled "none" so the generic form hides its (inert on an escalation) typed-value input. */
+ * WHICH node timed out and that in-flight work may already exist, instead of a blank form.
+ *
+ * `opts.resume` turns an inert escalation into a RESUMABLE one (issue #514 Defect B): when the parked
+ * `wait` node declares emits, the form must both PRESENT its typed-value field (so `emitMode`/
+ * `emitLabel` are derived from those emits, not forced to "none") and, on completion, MAP the
+ * operator-supplied value onto the node's emit-source variable (`detail` for scalar/version,
+ * `resolvedArtifact` for artifact, `mergedSha` for a merge oid — {@link factSourceVar}). Without that
+ * mapping a naive resume publishes `<el>_<fact> = null`, silently starving the downstream consumer.
+ * `opts.diagnosticInputs` seeds read-only probe context (issue #514 Defect A) onto the same task so the
+ * operator can see WHY the gate escalated (its last probe detail + observed candidate releases). */
 function escalationTaskLines(
   esc: string,
   nodeId: string,
   incoming: readonly string[],
   outgoing: string,
   contextFeel: string,
+  opts?: {
+    resume?: { kind: DeliveryNode["kind"]; emits: readonly DeliveryFact[] };
+    diagnosticInputs?: readonly { source: string; target: string }[];
+  },
 ): string[] {
+  const emits = opts?.resume?.emits ?? [];
+  const emitMode = emits.length > 0 ? "typed" : "none";
+  const emitLabel = emits.map((e) => `${e.name} (${e.type})`).join(", ");
+  const inputs: string[] = [
+    `            <zeebe:input ${attr("source", contextFeel)} target="prompt" />`,
+    `            <zeebe:input ${attr("source", `=${feelStr(nodeId)}`)} target="nodeId" />`,
+    `            <zeebe:input ${attr("source", `=${feelStr(emitMode)}`)} target="emitMode" />`,
+  ];
+  if (emits.length > 0) {
+    inputs.push(`            <zeebe:input ${attr("source", `=${feelStr(emitLabel)}`)} target="emitLabel" />`);
+  }
+  for (const di of opts?.diagnosticInputs ?? []) {
+    inputs.push(`            <zeebe:input ${attr("source", di.source)} target="${di.target}" />`);
+  }
+  // Defect B: map the operator's captured typed value onto the node's emit-source var, so the
+  // subProcess output ioMapping publishes the SAME `<el>_<fact>` shape a normally-completing node does.
+  const outputs: string[] = [];
+  if (opts?.resume) {
+    const seen = new Set<string>();
+    for (const fact of emits) {
+      const target = factSourceVar(opts.resume.kind, fact);
+      if (seen.has(target)) continue;
+      seen.add(target);
+      // The generic escalation form (`GENERIC_HUMAN_FORM`) captures the operator's answer in a single
+      // `value` field — it has NO `resolvedArtifact` field — so every emit type resumes from `value`,
+      // mapped onto that fact's emit-source var (artifact→resolvedArtifact, version→detail, …). Sourcing
+      // an artifact from a `resolvedArtifact` form field the form never sets would publish null and make
+      // an artifact wait-node escalation non-resumable via the UI.
+      outputs.push(
+        `            <zeebe:output ${attr("source", `=if (is defined(value)) then value else null`)} target="${target}" />`,
+      );
+    }
+  }
   return [
     `      <bpmn:userTask id="${esc}" name="Escalate: ${escapeXml(nodeId)}">`,
     "        <bpmn:extensionElements>",
@@ -1100,9 +1158,8 @@ function escalationTaskLines(
     "          <zeebe:userTask />",
     '          <zeebe:assignmentDefinition candidateGroups="operators" />',
     "          <zeebe:ioMapping>",
-    `            <zeebe:input ${attr("source", contextFeel)} target="prompt" />`,
-    `            <zeebe:input ${attr("source", `=${feelStr(nodeId)}`)} target="nodeId" />`,
-    `            <zeebe:input ${attr("source", '="none"')} target="emitMode" />`,
+    ...inputs,
+    ...outputs,
     "          </zeebe:ioMapping>",
     "        </bpmn:extensionElements>",
     ...incoming.map((id) => `        <bpmn:incoming>${id}</bpmn:incoming>`),
@@ -1120,6 +1177,23 @@ function escalationContextFeel(nodeId: string, descriptor: string, timeoutVar: s
   return `=${head} + string(${timeoutVar}) + ${feelStr(`)${tail}`)}`;
 }
 
+/** The escalation context line for a `wait` gate (issue #514 Defect A). Extends the base #499 line with
+ * the probe's RUNTIME last `detail` and its observed-candidate summary (`observed`), so a human/agent
+ * reading the (read-only) prompt can immediately tell a genuine "not published yet" from a transient
+ * false-negative — without hunting for the internal variables. Both are folded in defensively (an
+ * as-yet-unset var renders "—", never a FEEL error). */
+function waitEscalationContextFeel(nodeId: string): string {
+  const base = escalationContextFeel(
+    nodeId,
+    "readiness gate",
+    "probeTimeout",
+    " before its ReadinessProbe went green — decide how to proceed.",
+  );
+  const lastProbe = `(if (is defined(detail)) then string(detail) else "—")`;
+  const observed = `(if (is defined(observed)) then string(observed) else "—")`;
+  return `${base} + " Last probe: " + ${lastProbe} + ". Observed: " + ${observed} + "."`;
+}
+
 /** A plain `<bpmn:sequenceFlow>` (6-space indented). */
 function flow(id: string, source: string, target: string): string {
   return `      <bpmn:sequenceFlow id="${id}" sourceRef="${source}" targetRef="${target}" />`;

package/app/readiness.test.ts

@@ -28,6 +28,7 @@ import {
   normalizePoll,
   parseProbe,
   parsePrTarget,
+  summariseCapabilityCandidates,
   parsePrView,
   parseReleases,
   parseReleasesTarget,
@@ -214,6 +215,68 @@ test("matchCapability: the bare '#274' ref form resolves identically to 'nano-id
   assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@1.2.3");
 });
 
+// ── #514 Defect A: the capability gate is self-diagnosing on escalation ──────────────────────────
+
+test("#514 Defect A summariseCapabilityCandidates: lists candidate releases (newest first) and whether each references the ref", () => {
+  const summary = summariseCapabilityCandidates(capMatch, [
+    rel("@nanobpm/urban@0.9.0", [200]),
+    rel("@nanobpm/urban@0.82.0", [274]),
+    rel("@nanobpm/other@1.0.0", [274]), // wrong package — excluded from the per-package summary
+  ]);
+  assertStringIncludes(summary, "2 @nanobpm/urban release(s) observed");
+  assertStringIncludes(summary, "1 referencing #274");
+  // Newest candidate first, and the ref-flag per candidate.
+  assertStringIncludes(summary, "@nanobpm/urban@0.82.0 refs #274");
+  assertStringIncludes(summary, "@nanobpm/urban@0.9.0 no #274");
+  assert(!summary.includes("@nanobpm/other"), "a sibling package never leaks into the per-package summary");
+});
+
+test("#514 Defect A summariseCapabilityCandidates: no matching releases yields a plain observed note (never throws)", () => {
+  assertEquals(summariseCapabilityCandidates(capMatch, []), "no @nanobpm/urban releases observed");
+  assertEquals(summariseCapabilityCandidates(capMatch, [rel("@nanobpm/other@1.0.0", [274])]), "no @nanobpm/urban releases observed");
+});
+
+test("#514 Defect A summariseCapabilityCandidates: an unparseable capabilityRef is labelled distinctly and omits the meaningless per-candidate refs/no flags", () => {
+  const badRef = { ...capMatch, capabilityRef: "not-a-number" };
+  const summary = summariseCapabilityCandidates(badRef, [rel("@nanobpm/urban@0.82.0", [274])]);
+  assertStringIncludes(summary, "1 @nanobpm/urban release(s) observed (unparseable ref)");
+  assertStringIncludes(summary, "@nanobpm/urban@0.82.0");
+  assert(!summary.includes("(no ref configured)"), "a configured-but-unparseable ref is NOT reported as missing");
+  assert(!summary.includes("no #") && !summary.includes("refs #"), "no meaningless per-candidate ref flags when there is no parseable number");
+  assert(!summary.includes("referencing"), "no aggregate referencing count when there is no parseable number");
+});
+
+test("#514 Defect A summariseCapabilityCandidates: a genuinely absent ref is labelled '(no ref configured)'", () => {
+  const noRef = { ...capMatch, capabilityRef: undefined };
+  const summary = summariseCapabilityCandidates(noRef, [rel("@nanobpm/urban@0.82.0", [274])]);
+  assertStringIncludes(summary, "1 @nanobpm/urban release(s) observed (no ref configured)");
+  assert(!summary.includes("unparseable"), "a missing ref is not reported as unparseable");
+});
+
+test("#514 Defect A summariseCapabilityCandidates: caps the newest 8 candidates so a >100-release repo cannot bloat the form/log", () => {
+  const many: GithubRelease[] = [];
+  for (let i = 1; i <= 20; i++) many.push(rel(`@nanobpm/urban@0.${i}.0`, [200]));
+  const summary = summariseCapabilityCandidates(capMatch, many);
+  assertStringIncludes(summary, "20 @nanobpm/urban release(s) observed");
+  assertStringIncludes(summary, "(+12 more)");
+  assertStringIncludes(summary, "@nanobpm/urban@0.20.0 no #274"); // newest is shown
+  assert(!summary.includes("@nanobpm/urban@0.1.0 "), "the oldest is trimmed by the cap");
+});
+
+test("#514 Defect A matchCapability surfaces `observed` on the not-ready path — a false-negative is diagnosable, not contextless", () => {
+  // Red before the fix: matchCapability returned only {ready, detail} with no observed-release context,
+  // so an escalation could not tell a genuine 'not published yet' from a transient false-negative.
+  const notReady = matchCapability(capMatch, [rel("@nanobpm/urban@0.82.0", [200])]);
+  assert(!notReady.ready);
+  assertStringIncludes(notReady.observed ?? "", "@nanobpm/urban@0.82.0 no #274");
+});
+
+test("#514 Defect A matchCapability surfaces `observed` on the ready path too (the resolving release shows as referencing the ref)", () => {
+  const ready = matchCapability(capMatch, [rel("@nanobpm/urban@0.82.0", [274])]);
+  assert(ready.ready);
+  assertStringIncludes(ready.observed ?? "", "@nanobpm/urban@0.82.0 refs #274");
+});
+
 test("cmpVersion: numeric dotted compare (0.9 < 0.54 < 0.60), matching nano-ide publish.mjs", () => {
   assert(cmpVersion("0.9.0", "0.54.0") < 0);
   assert(cmpVersion("0.54.0", "0.60.0") < 0);

package/app/readiness.ts

@@ -120,6 +120,13 @@ export interface ProbeResult {
   readonly ready: boolean;
   readonly detail: string;
   readonly bind?: Record<string, string>;
+  /** An OPTIONAL compact, human-readable summary of what the probe actually OBSERVED at poll time
+   * (issue #514 Defect A). Diagnostic-only — it is NEVER part of the gate contract, it does not gate
+   * readiness, and it carries no secret material (provenance is public). The `capability` kind
+   * populates it with {@link summariseCapabilityCandidates} so an ESCALATION (false-negative wait)
+   * surfaces the candidate releases the matcher saw and whether each referenced the ref, letting a
+   * human/agent tell a genuine "not published yet" from a transient false-negative. */
+  readonly observed?: string;
 }
 
 /** A single published GitHub Release, reduced to the two fields the capability resolver reads: the
@@ -448,6 +455,51 @@ function versionForPackage(tag: string, pkg: string): string | undefined {
   return /^\d+(\.\d+)*$/.test(v) ? v : undefined;
 }
 
+/** A compact, deterministic, BOUNDED summary of the capability candidate releases a probe observed
+ * (issue #514 Defect A). Lists the releases tagged `<match.package>@<version>` (newest first) and,
+ * for each, whether its body referenced `match.capabilityRef` — so an escalated capability gate can
+ * show a human/agent EXACTLY what the probe saw (a genuine "not published yet" vs. a transient
+ * false-negative where a matching release was live but its provenance body was momentarily empty).
+ * PURE / never throws — a malformed or empty list yields a plain "no releases observed" note.
+ * Output is capped (newest {@link CAPABILITY_SUMMARY_LIMIT}) so a repo with hundreds of releases
+ * cannot bloat the escalation form or a log line. Provenance is public — nothing here is redacted. */
+export function summariseCapabilityCandidates(
+  match: ProbeMatch | undefined,
+  releases: readonly GithubRelease[],
+): string {
+  const pkg = match?.package;
+  const ref = match?.capabilityRef;
+  if (!pkg) return "capability: no package configured";
+  const num = ref ? capabilityNumber(ref) : undefined;
+  const candidates: { version: string; refs: boolean }[] = [];
+  for (const rel of releases) {
+    if (!rel || typeof rel.tag !== "string" || typeof rel.body !== "string") continue;
+    const version = versionForPackage(rel.tag, pkg);
+    if (!version) continue;
+    candidates.push({ version, refs: num !== undefined && bodyReferences(rel.body, num) });
+  }
+  if (candidates.length === 0) return `no ${pkg} releases observed`;
+  candidates.sort((a, b) => cmpVersion(b.version, a.version)); // newest first, deterministic
+  const shown = candidates.slice(0, CAPABILITY_SUMMARY_LIMIT);
+  const more = candidates.length > shown.length ? ` (+${candidates.length - shown.length} more)` : "";
+  if (num === undefined) {
+    // No parseable ref number to test candidates against: distinguish a configured-but-unparseable ref
+    // from a genuinely absent one, and OMIT the per-candidate/aggregate "refs/no" flags — with nothing
+    // to match, every candidate would carry a meaningless "no", which is misleading rather than diagnostic.
+    const why = ref ? "(unparseable ref)" : "(no ref configured)";
+    const parts = shown.map((c) => `${pkg}@${c.version}`);
+    return `${candidates.length} ${pkg} release(s) observed ${why}: ${parts.join("; ")}${more}`;
+  }
+  const referencing = candidates.filter((c) => c.refs).length;
+  const refLabel = `#${num}`;
+  const parts = shown.map((c) => `${pkg}@${c.version} ${c.refs ? `refs ${refLabel}` : `no ${refLabel}`}`);
+  return `${candidates.length} ${pkg} release(s) observed, ${referencing} referencing ${refLabel}: ${parts.join("; ")}${more}`;
+}
+
+/** Newest-N cap on {@link summariseCapabilityCandidates} so a >100-release repo cannot bloat the
+ * escalation form or a warn log line. */
+const CAPABILITY_SUMMARY_LIMIT = 8;
+
 /** capability readiness (#274 Gap A): among GitHub Releases tagged `<match.package>@*` whose body
  * references `match.capabilityRef`, resolve the **lowest** SemVer version — that is the version that
  * *first* carries the capability (`firstVersion`). Late-binds it as `{ resolvedArtifact }` so the
@@ -457,9 +509,10 @@ function versionForPackage(tag: string, pkg: string): string | undefined {
 export function matchCapability(match: ProbeMatch | undefined, releases: readonly GithubRelease[]): ProbeResult {
   const pkg = match?.package;
   const ref = match?.capabilityRef;
-  if (!pkg || !ref) return { ready: false, detail: "capability: missing package/capabilityRef" };
+  const observed = summariseCapabilityCandidates(match, releases);
+  if (!pkg || !ref) return { ready: false, detail: "capability: missing package/capabilityRef", observed };
   const num = capabilityNumber(ref);
-  if (!num) return { ready: false, detail: "capability: unparseable capabilityRef (no #NNN)" };
+  if (!num) return { ready: false, detail: "capability: unparseable capabilityRef (no #NNN)", observed };
 
   let firstVersion: string | undefined;
   for (const rel of releases) {
@@ -469,9 +522,9 @@ export function matchCapability(match: ProbeMatch | undefined, releases: readonl
     if (!bodyReferences(rel.body, num)) continue;
     if (firstVersion === undefined || cmpVersion(version, firstVersion) < 0) firstVersion = version;
   }
-  if (firstVersion === undefined) return { ready: false, detail: `capability #${num} not published in ${pkg} yet` };
+  if (firstVersion === undefined) return { ready: false, detail: `capability #${num} not published in ${pkg} yet`, observed };
   const resolvedArtifact = `${pkg}@${firstVersion}`;
-  return { ready: true, detail: `capability #${num} carried by ${resolvedArtifact}`, bind: { resolvedArtifact } };
+  return { ready: true, detail: `capability #${num} carried by ${resolvedArtifact}`, bind: { resolvedArtifact }, observed };
 }
 
 /** The **newest** published SemVer version of `pkg` across `releases` — the target of the gated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.138.0",
+  "version": "0.138.2",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/processes/readiness-gate.bpmn

@@ -50,6 +50,7 @@
           <nano:extend name="detail" type="string" optional="true" />
           <nano:extend name="resolvedArtifact" type="string" optional="true" />
           <nano:extend name="mergedSha" type="string" optional="true" />
+          <nano:extend name="observed" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="ReadinessReady" name="readiness-ready message payload">
           <nano:extend name="ready" type="boolean" />

package/workers/readiness-probe/worker.test.ts

@@ -23,11 +23,12 @@ function execReturning(seq: Array<HttpResponse>, counts: { http: number } = { ht
 const httpProbe = (poll?: ReadinessProbe["poll"]): ReadinessProbe =>
   parseProbe({ kind: "http", target: "https://x/health?token=s3cr3t", poll });
 
-test("safeBind: strips reserved keys (ready/detail) so a bind can only ADD outputs, never shadow the payload", () => {
-  const cleaned = safeBind({ resolvedArtifact: "@nanobpm/urban@0.54.0", ready: "false", detail: "spoofed" });
+test("safeBind: strips reserved keys (ready/detail/observed) so a bind can only ADD outputs, never shadow the payload", () => {
+  const cleaned = safeBind({ resolvedArtifact: "@nanobpm/urban@0.54.0", ready: "false", detail: "spoofed", observed: "spoofed" });
   assertEquals(cleaned.resolvedArtifact, "@nanobpm/urban@0.54.0");
   assertEquals("ready" in cleaned, false, "a bound 'ready' can never override the canonical payload");
   assertEquals("detail" in cleaned, false, "a bound 'detail' can never override the canonical payload");
+  assertEquals("observed" in cleaned, false, "a bound 'observed' can never clobber the top-level diagnostic summary");
   assertEquals(Object.keys(safeBind(undefined)).length, 0, "an absent bind yields an empty object");
 });
 
@@ -121,6 +122,59 @@ test("probeSingleShot: inconclusive lastAttempt fallback surfaces its redacted d
   assert(res.detail.includes("fallback: still nothing"), "the fallback diagnostic is preserved");
 });
 
+test("#514 Defect A probeSingleShot: a not-ready capability at the boundary emits a structured WARN with the probe detail + observed releases, and threads `observed` to the return", async () => {
+  // Red before the fix: the boundary last-attempt returned a contextless "gate boundary reached" with
+  // no warn and no observed-release context, so an escalated false-negative was undiagnosable.
+  const capProbe = parseProbe({
+    kind: "capability",
+    target: "github-releases:nanobpm/nano-ide",
+    match: { package: "@nanobpm/urban", capabilityRef: "#468" },
+  });
+  // A live @nanobpm/urban release exists, but its provenance body does NOT (yet) reference #468 — the
+  // exact transient false-negative shape from the incident.
+  const releasesJson = JSON.stringify([
+    [{ tag_name: "@nanobpm/urban@0.82.0", body: "## Provenance\n- #200\n" }],
+  ]);
+  const exec: ProbeExec = {
+    async httpGet(): Promise<HttpResponse> {
+      throw new Error("unused");
+    },
+    async run(): Promise<CommandResult> {
+      return { code: 0, stdout: releasesJson, stderr: "" };
+    },
+  };
+  const warns: string[] = [];
+  let publishes = 0;
+  const res = await probeSingleShot({
+    probe: capProbe,
+    exec,
+    env: {},
+    lastAttempt: true,
+    publish: async () => {
+      publishes += 1;
+    },
+    warn: (msg) => warns.push(msg),
+  });
+  assert(!res.ready, "the boundary attempt is still not-ready");
+  assertEquals(publishes, 0, "a not-ready boundary never publishes readiness-ready");
+  assertEquals(warns.length, 1, "exactly one structured warn is emitted at the boundary last attempt");
+  assert(warns[0].includes("escalating"), "the warn says the gate is escalating");
+  assert(warns[0].includes("capability #468 not published"), "the warn carries the probe's last detail");
+  assert(warns[0].includes("@nanobpm/urban@0.82.0 no #468"), "the warn carries the observed candidate releases");
+  assert((res.observed ?? "").includes("@nanobpm/urban@0.82.0 no #468"), "the observed summary is threaded to the return for the escalation task");
+  // The return `detail` must carry the probe's actual last matcher detail — NOT a generic "gate boundary
+  // reached" string — because the wait-gate seeds `probeDetail` and the escalation context FEEL from it.
+  assert(
+    res.detail.includes("capability #468 not published"),
+    "the boundary return `detail` carries the probe's diagnostic last detail, keeping the escalation diagnostic",
+  );
+  assert(
+    !res.detail.includes("gate boundary reached"),
+    "the boundary return no longer clobbers `detail` with a generic contextless string",
+  );
+});
+
+
 test("probeSingleShot: forwards a matcher's bind through publish into the message variables (#274 Gap B)", async () => {
   const published: Array<{ detail: string; bind?: Record<string, string> }> = [];
   const payload = JSON.stringify([{ tag_name: "@nanobpm/urban@0.54.0", body: "## Provenance\n- #274\n" }]);

package/workers/readiness-probe/worker.ts

@@ -35,7 +35,7 @@ export { READINESS_READY_MESSAGE };
  * kind-agnostic emit primitive (#274 Gap B), but it flows from matcher output into both the
  * `readiness-ready` message variables and the worker output — so a matcher that binds `ready`/`detail`
  * could shadow the canonical payload and break the gate contract. */
-const RESERVED_BIND_KEYS: ReadonlySet<string> = new Set(["ready", "detail"]);
+const RESERVED_BIND_KEYS: ReadonlySet<string> = new Set(["ready", "detail", "observed"]);
 export function safeBind(bind?: Record<string, string>): Record<string, string> {
   if (!bind) return {};
   const out: Record<string, string> = {};
@@ -60,6 +60,7 @@ export async function probeSingleShot(deps: {
   lastAttempt?: boolean;
   fallback?: () => Promise<ProbeResult | null>;
   log?: (msg: string) => void;
+  warn?: (msg: string) => void;
 }): Promise<ProbeResult> {
   const label = redactTarget(deps.probe);
   const res: ProbeResult = await probeOnce(deps.probe, deps.exec, deps.env).catch((err) => ({
@@ -84,9 +85,25 @@ export async function probeSingleShot(deps: {
     await deps.publish(settled.detail, settled.bind);
     return settled;
   }
+  // Boundary last attempt and STILL not ready: this is the escalation trigger. Surface a structured
+  // warn (issue #514 Defect A) carrying the probe's last detail + what it OBSERVED, so a false-negative
+  // (a matching release was live but its provenance body was momentarily empty) is diagnosable from the
+  // logs — not just a contextless "escalated". `observed` is diagnostic-only and secret-free.
+  const failingDetail = settled ? `${res.detail} (fallback: ${settled.detail})` : res.detail;
+  const observed = settled?.observed ?? res.observed;
+  deps.warn?.(
+    `readiness gate escalating ${label}: not ready at boundary — ${failingDetail}` +
+      (observed ? `; observed: ${observed}` : ""),
+  );
+  // Return the actual failing probe detail (not a generic "gate boundary reached" string): downstream
+  // the wait-gate seeds `probeDetail` and the escalation context FEEL from `detail`, so overwriting it
+  // here would make the escalation non-diagnostic — the very defect this change fixes. The fact that the
+  // boundary/timeout was reached is already communicated by the escalation context ("exceeded its SLA …
+  // before its ReadinessProbe went green") and the structured WARN above.
   return {
     ready: false,
-    detail: settled ? `gate boundary reached (fallback: ${settled.detail})` : "gate boundary reached",
+    detail: failingDetail,
+    observed,
   };
 }
 
@@ -149,8 +166,14 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       });
     },
     log: (msg) => app.log.info(msg),
+    warn: (msg) => app.log.warn(msg),
   });
-  return { ready: result.ready, detail: result.detail, ...safeBind(result.bind) };
+  return {
+    ready: result.ready,
+    detail: result.detail,
+    ...(result.observed !== undefined ? { observed: result.observed } : {}),
+    ...safeBind(result.bind),
+  };
 };
 
 export default handler;