@nanobpm/nano-workforce 0.137.0 → 0.138.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **delivery-graphs:** split preview from stage + collapsible compose + fix example ([#517](https://github.com/nanobpm/nano-workforce/issues/517)) ([abb4a10](https://github.com/nanobpm/nano-workforce/commit/abb4a10e9a8f7f53be40488d9991a3660a9f7518)), closes [#516](https://github.com/nanobpm/nano-workforce/issues/516) [#460](https://github.com/nanobpm/nano-workforce/issues/460) [#516](https://github.com/nanobpm/nano-workforce/issues/516)
+
 ## [0.137.0](https://github.com/nanobpm/nano-workforce/compare/v0.136.0...v0.137.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/deliveryGraphTextIngress.ts

@@ -0,0 +1,94 @@
+// app/deliveryGraphTextIngress.ts — the shared PARSE → COMPILE → PROJECT pipeline behind the two
+// human-facing delivery-graph text-ingress doors (issue #516):
+//   • `previewDeliveryGraph`  — PURE preview: compile + project, NO staging.
+//   • `stageDeliveryGraph`    — compile + project + STAGE a proposal for operator dispatch.
+//
+// Splitting preview from staging means both doors run the IDENTICAL parse+compile+project step and
+// differ ONLY in whether they persist a staged proposal. That step therefore lives here ONCE
+// (derivation over duplication) rather than being copied per door — the previous single door inlined
+// it, and forking it would have created two drift-prone compile paths. Neither door dispatches; the
+// #460 boundary (dispatch is an operator action on a staged proposal) is untouched.
+
+import type { DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import { proposalReviewUrl } from "./deliveryGraphProposals.ts";
+import { parseDeliveryGraphText } from "./deliveryGraphText.ts";
+import { deliveryGraphDigest } from "./deliveryRunner.ts";
+
+type CompileResult = Awaited<ReturnType<typeof compileDeliveryGraph>>;
+type CompiledOk = Extract<CompileResult, { ok: true }>;
+type CompileErrors = Extract<CompileResult, { ok: false }>["errors"];
+
+/** A parse/validation failure, already shaped as the door's 400 response. */
+export interface TextIngressFailure {
+  ok: false;
+  status: 400;
+  body: { ok: false; error: string; errors?: CompileErrors };
+}
+
+/** A well-formed, compiled graph ready to project (and, for the stage door, to persist). */
+export interface TextIngressOk {
+  ok: true;
+  graph: unknown;
+  compiled: CompiledOk;
+  digest: string;
+  name: string | null;
+}
+
+export type TextIngressResult = TextIngressOk | TextIngressFailure;
+
+/** Parse a UI JSON-paste body (`{ graphJson }`), then run the SAME pure compiler the agent door uses.
+ * A blank/invalid paste or a graph that fails validation is returned as a ready-to-send 400; success
+ * carries the compiled graph plus its content `digest` and human `name`. Never throws / never a 500. */
+export async function parseAndCompileText(body: unknown): Promise<TextIngressResult> {
+  const parsed = parseDeliveryGraphText(body);
+  if (!parsed.ok) {
+    return { ok: false, status: 400, body: { ok: false, error: parsed.error } };
+  }
+  const compiled = await compileDeliveryGraph(parsed.graph);
+  if (!compiled.ok) {
+    return {
+      ok: false,
+      status: 400,
+      body: {
+        ok: false,
+        error: `graph failed validation: ${compiled.errors.length} error(s)`,
+        errors: compiled.errors,
+      },
+    };
+  }
+  const digest = deliveryGraphDigest(compiled.bpmn);
+  const name =
+    typeof compiled.resolved.name === "string" && compiled.resolved.name.trim() !== ""
+      ? compiled.resolved.name.trim()
+      : null;
+  return { ok: true, graph: parsed.graph, compiled, digest, name };
+}
+
+/** Project a compiled graph into the shared `DeliveryGraphTextResult` 200 body both doors return: the
+ * `digest`, node/human/side-effect counts, the mermaid `diagram`, and the full human-stop / side-effect
+ * detail the Delivery Graphs page renders (#441). `staged` records whether a proposal was persisted;
+ * `includeBpmn` attaches the compiled BPMN (with DI) so the PURE preview door can drive the host
+ * explorer's DI preview WITHOUT staging (the stage door omits it — the staged grid recompiles by
+ * digest). */
+export function buildTextPreviewBody(
+  ok: TextIngressOk,
+  opts: { staged: boolean; includeBpmn?: boolean },
+): DeliveryGraphTextResult {
+  const { compiled, digest, name } = ok;
+  return {
+    ok: true,
+    staged: opts.staged,
+    digest,
+    reviewUrl: proposalReviewUrl(digest),
+    ...(name !== null ? { title: name } : {}),
+    sideEffecting: compiled.sideEffects.length > 0,
+    nodeCount: compiled.resolved.nodes.length,
+    humanNodeCount: compiled.humanNodes.length,
+    sideEffectCount: compiled.sideEffects.length,
+    diagram: compiled.diagram,
+    humanNodes: compiled.humanNodes,
+    sideEffects: compiled.sideEffects,
+    ...(opts.includeBpmn ? { bpmn: compiled.bpmn } : {}),
+  };
+}

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