@nanobpm/nano-workforce 0.186.0 → 0.186.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.186.2](https://github.com/nanobpm/nano-workforce/compare/v0.186.1...v0.186.2) (2026-09-11)
+
+### Bug Fixes
+
+* **merge-loop:** re-poll a 'waiting' mergeability verdict instead of escalating ([#775](https://github.com/nanobpm/nano-workforce/issues/775)) ([4812fe9](https://github.com/nanobpm/nano-workforce/commit/4812fe9689088f21e41ef50ba8f1dbec2093fb23)), closes [#774](https://github.com/nanobpm/nano-workforce/issues/774) [#774](https://github.com/nanobpm/nano-workforce/issues/774) [#774](https://github.com/nanobpm/nano-workforce/issues/774)
+
+## [0.186.1](https://github.com/nanobpm/nano-workforce/compare/v0.186.0...v0.186.1) (2026-09-11)
+
+### Bug Fixes
+
+* delivery-graph human-node Tasks form renders context-free ([#773](https://github.com/nanobpm/nano-workforce/issues/773)) ([91a8065](https://github.com/nanobpm/nano-workforce/commit/91a806566e157257cc264310e18d7df0bba3e350)), closes [#772](https://github.com/nanobpm/nano-workforce/issues/772) [#772](https://github.com/nanobpm/nano-workforce/issues/772)
+
 ## [0.186.0](https://github.com/nanobpm/nano-workforce/compare/v0.185.1...v0.186.0) (2026-09-08)
 
 ### Features

package/SPEC.md

@@ -216,7 +216,7 @@ Consequences the prompt (`resources/prompts/review-round.md`) encodes:
 | `pr-submitted` | — (start) | submit route/webhook | `{repo, prNumber, prUrl, prKey}` |
 | `readiness-ready` | `prKey` | **poller** | `{ready, detail?}` (ADR 0001 §2 wait-gate; the review-ready wait, re-expressed on the ReadinessProbe gate — #259) |
 | `deps-cleared` | `prKey` | **poller** (merge) | — (all `Depends-on` PRs merged) |
-| `merge-ready` | `prKey` | **poller** (merge) | `{mergeState}` (`ready` \| `conflict` \| `blocked`); when `blocked`, also `{failingChecks, failingChecksList}` for the `senior:fix-ci` branch |
+| `merge-ready` | `prKey` | **poller** (merge) | `{mergeState}` (`ready` \| `conflict` \| `blocked` \| `draft`); when `blocked`, also `{failingChecks, failingChecksList}` for the `senior:fix-ci` branch. A transient `UNKNOWN`/`waiting` verdict is NOT published — the poller keeps polling (fast self-heal); the merge loop's `gw-mergeable` sees `waiting` only via the dead-poller stall-probe re-derivation, where it re-polls (bounded, #774) instead of escalating |
 | `merge-landed` | `prKey` | **poller** (merge) | — (queued PR merged, or merged out-of-band) |
 
 The `escalation-answered` message was retired (#256): the merge-loop escalation is
@@ -466,10 +466,21 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   time** by a `fix-ci`/`rebase` agent (`status: "waiting-on-pr"`, above). `merge-loop`
   parks at *wait: deps merged*; the poller checks each dependency (own tracked row
   first, else GitHub `merged` state) and publishes `deps-cleared` once all have landed.
-- **Mergeability** — the poller classifies GitHub's `mergeStateStatus`:
+- **Mergeability** — the poller classifies GitHub's `mergeStateStatus`, but a
+  first-class `isDraft` guard runs *first* (`classifyMergeability`, `app/github.ts`):
+  a draft PR is `draft` regardless of `mergeStateStatus`. Otherwise, by status:
   `CLEAN`/`HAS_HOOKS`/`UNSTABLE`/`BEHIND` → `ready`; `DIRTY` → `conflict`;
   `BLOCKED` → `blocked` if a required check is failing, else keep waiting;
-  `DRAFT`/`UNKNOWN`/empty → keep waiting. It publishes `merge-ready {mergeState}`.
+  `UNKNOWN`/empty (and any other status, including `DRAFT`) → keep polling (GitHub
+  still computing). It
+  publishes `merge-ready {mergeState}` for the settled verdicts. When the live
+  poller is dead the `wait-mergeable-timeout` backstop's stall-probe re-derives
+  mergeability; a still-unsettled `UNKNOWN`/`waiting` verdict then routes to a
+  **bounded re-poll** (`wait-mergeable-repoll`, `NANO_PR_MERGEABLE_REPOLL_INTERVAL`)
+  rather than escalating (bounded by `NANO_PR_MAX_MERGE_STALL_ROUNDS`), and an
+  unclassified/default verdict routes to auto-rebase (`gw-rebase`, bounded by its
+  own `NANO_PR_MAX_REBASE_ROUNDS` budget); once either budget is exhausted the loop
+  escalates to a human (#774).
 - **Merge** — `pr.merge` attempts the merge (`NANO_PR_MERGE_METHOD`, default
   `squash`). GitHub auto-enqueues on merge-queue-required branches → the process
   waits for `merge-landed` (poller detects the landed PR). Every attempt is

package/app/contracts.ts

@@ -137,7 +137,7 @@ export const ENV_CONTRACTS = {
     name: "NANO_PR_MAX_MERGE_STALL_ROUNDS",
     owner: "app/service.ts",
     semantics:
-      "Maximum mergeable-wait-timeout stall-probe re-derivations (dead-poller backstop, #636) before escalating; 0 escalates on the first stall.",
+      "Maximum mergeable-wait-timeout stall-probe re-derivations (dead-poller backstop, #636) AND `waiting`-verdict re-poll probes (#774) before escalating; 0 escalates on the first stall.",
     default: "3",
   },
   NANO_PR_REVIEW_WAIT_TIMEOUT: {
@@ -166,6 +166,13 @@ export const ENV_CONTRACTS = {
     semantics:
       "How long the merge loop waits for the poller's `merge-ready` before the stall-probe timer arm fires (dead-poller backstop, #636; FEEL/ISO-8601 duration).",
   },
+  NANO_PR_MERGEABLE_REPOLL_INTERVAL: {
+    category: "env",
+    name: "NANO_PR_MERGEABLE_REPOLL_INTERVAL",
+    owner: "app/service.ts",
+    semantics:
+      "How long the merge loop waits before re-deriving mergeability when `gw-mergeable` sees an async-`UNKNOWN` `\"waiting\"` verdict, instead of escalating to a human (#774; bounded by `NANO_PR_MAX_MERGE_STALL_ROUNDS`; FEEL/ISO-8601 duration).",
+  },
   NANO_PR_AUTO_MERGE: {
     category: "env",
     name: "NANO_PR_AUTO_MERGE",

package/app/deliveryHuman.test.ts

@@ -10,6 +10,7 @@ import type { DeliveryFact } from "../nano-generated/api-io.d.ts";
 import {
   bindHumanEmits,
   DELIVERY_HUMAN_ELEMENT,
+  deliveryHumanContextQuestion,
   deriveHumanCategory,
   GENERIC_HUMAN_FORM,
   HUMAN_ACK_FORM,
@@ -304,3 +305,125 @@ test("drift guard: the human element is completer-answerable and surfaces on the
     "USER_TASK_KIND_LABELS must label the delivery human node",
   );
 });
+
+// ── issue #772: Tasks-inbox "Decision context" for a parked delivery-graph human node ─────────────
+
+test("deliveryHumanContextQuestion: derives the node instruction from human_labels (base + __esc twin)", () => {
+  const labels = { "delivery-human-task__n7": "Run the manual OTP publish for @nanobpm/urban" };
+  // The parked base task looks up its own id.
+  assertEquals(
+    deliveryHumanContextQuestion(labels, "delivery-human-task__n7"),
+    "Run the manual OTP publish for @nanobpm/urban",
+  );
+  // The bounded-timeout escalation twin parks on `…__esc`; strip it to find the same stamped label.
+  assertEquals(
+    deliveryHumanContextQuestion(labels, "delivery-human-task__n7__esc"),
+    "Run the manual OTP publish for @nanobpm/urban",
+  );
+});
+
+test("deliveryHumanContextQuestion: falls back to a static message when no label is stored", () => {
+  // A parked human step must never render a blank Decision context — an untracked/absent label still
+  // yields actionable guidance rather than null (which would leave the panel empty, issue #772).
+  assertEquals(
+    deliveryHumanContextQuestion({}, "delivery-human-task__n1"),
+    "A scheduled delivery-graph step is waiting to be completed.",
+  );
+  assertEquals(
+    deliveryHumanContextQuestion(undefined, "delivery-human-task__n1"),
+    "A scheduled delivery-graph step is waiting to be completed.",
+  );
+});
+
+test("deliveryHumanContextQuestion: a non-human node's escalation twin (no stored label) gets the node-NEUTRAL fallback, not a 'human step' claim", () => {
+  // `isDeliveryHumanElement` also matches the `__esc`/`__contract` escalation twins that bounded
+  // `agent`/`wait`/`connector` nodes schedule; those carry NO stored human label. The fallback must
+  // not mislabel them as a "human step" (issue #772 review, comment on service.ts contextFor arm).
+  const humanLabels = { "delivery-human-task__n7": "Run the manual OTP publish" };
+  assertEquals(
+    deliveryHumanContextQuestion(humanLabels, "delivery-human-task__agent5__esc"),
+    "A scheduled delivery-graph step is waiting to be completed.",
+  );
+  assertEquals(
+    deliveryHumanContextQuestion(humanLabels, "delivery-human-task__agent5__contract"),
+    "A scheduled delivery-graph step is waiting to be completed.",
+  );
+  // A real human node's own `__esc` timeout twin still resolves the base label.
+  assertEquals(
+    deliveryHumanContextQuestion(humanLabels, "delivery-human-task__n7__esc"),
+    "Run the manual OTP publish",
+  );
+});
+
+test("deliveryHumanContextQuestion: a human node whose id itself ends in __esc resolves its EXACT label, not a sibling's", () => {
+  // Node ids may legitimately end in `__esc` (`deliveryGraph.ts` NODE_ID_PATTERN), so such a node is
+  // stamped under the exact key `delivery-human-task__<id>` (…__esc). The exact lookup must win over
+  // the `__esc`-stripped base, otherwise a sibling `n7` node's label would shadow real node `n7__esc`.
+  const labels = {
+    "delivery-human-task__n7": "Sibling n7 label",
+    "delivery-human-task__n7__esc": "The real n7__esc node label",
+  };
+  assertEquals(
+    deliveryHumanContextQuestion(labels, "delivery-human-task__n7__esc"),
+    "The real n7__esc node label",
+  );
+});
+
+// ── issue #772: the generic form must be static / input-only on the Tasks surface ─────────────────
+
+const genericForm = readFileSync("resources/forms/delivery-human-generic.form", "utf8");
+
+test("form-structure guard: delivery-human-generic.form uses node-neutral wording", () => {
+  // This shared form is also attached to the `__esc`/`__contract` escalation tasks that bounded
+  // agent/wait/connector nodes create (`app/deliveryGraphCompiler.ts`), not only scheduled `human`
+  // nodes. Copy that calls the task a "scheduled human step" is inaccurate for the escalation family
+  // and can obscure that the task is an escalation, so the static text must stay node-neutral.
+  assert(
+    !/scheduled human step/i.test(genericForm),
+    "the shared generic form must use node-neutral wording (it also serves escalation tasks)",
+  );
+});
+
+test("form-structure guard: delivery-human-generic.form carries no {{…}} tokens", () => {
+  // The Tasks surface (`engineForm`) seeds NO form variables, so any `{{token}}` renders literally and
+  // any data-dependent `conditional` mis-fires. Deploy-time `{{token}}` templating is removed too, so
+  // such a token could never resolve. Assert the surface stays context-free-safe (issue #772).
+  assert(!genericForm.includes("{{"), "the generic delivery-human form must not carry {{…}} tokens");
+});
+
+test("form-structure guard: delivery-human-generic.form has no data-dependent conditional and an OPTIONAL value", () => {
+  const parsed = JSON.parse(genericForm) as {
+    components: { key?: string; conditional?: unknown; validate?: { required?: boolean } }[];
+  };
+  // No component may gate on form data — those blurbs render contradictorily against empty data.
+  for (const c of parsed.components) {
+    assert(c.conditional === undefined, "no component may carry a data-dependent conditional");
+  }
+  // `value` must be OPTIONAL — a no-emit ("click done") node completes without entering a value. This
+  // S3 generic surface deploys a single static default form and cannot know per-node whether a fact is
+  // required, so it must not client-require `value`; per-node typed-emit binding is the S4 form-
+  // selection path's job (`bindHumanEmits`), not a client-required field on this generic surface.
+  const value = parsed.components.find((c) => c.key === "value");
+  assert(value, "the generic form must keep a single `value` field");
+  assert(value!.validate?.required !== true, "`value` must be optional on this surface");
+});
+
+test("form-structure guard: delivery-human-generic.form has no task-variable-dependent readonly input", () => {
+  // The Tasks surface (`engineForm`) seeds NO task-local variables, so a readonly INPUT component
+  // (e.g. the old `prompt` textarea) renders permanently blank — a confusing empty "Now do this".
+  // The instruction reaches the operator through the read-model Decision context column instead, so
+  // the surface must carry no keyed readonly control; a static keyless `text` block may point to it.
+  const parsed = JSON.parse(genericForm) as {
+    components: { type?: string; key?: string; readonly?: boolean }[];
+  };
+  for (const c of parsed.components) {
+    assert(
+      !(c.readonly === true && typeof c.key === "string"),
+      `keyed readonly input '${c.key}' renders blank on the variable-free Tasks surface`,
+    );
+  }
+  assert(
+    !parsed.components.some((c) => c.key === "prompt"),
+    "the never-seeded readonly `prompt` control must not reappear on the Tasks surface",
+  );
+});

package/app/deliveryHuman.ts

@@ -54,6 +54,35 @@ export function isDeliveryHumanElement(elementId: string): boolean {
   return elementId === DELIVERY_HUMAN_ELEMENT || elementId.startsWith(`${DELIVERY_HUMAN_ELEMENT}__`);
 }
 
+/** 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
+ *  arrive through the read-model `question` column, exactly like every other escalation kind. The run
+ *  row already stamps each human node's instruction label in `human_labels` (`buildHumanLabels`), keyed
+ *  by the node's base user-task element id (`delivery-human-task__<node>`); the bounded-timeout
+ *  escalation twin parks on the `…__esc` variant. A node id may itself legitimately END in `__esc`
+ *  (`deliveryGraph.ts` NODE_ID_PATTERN allows it), so the twin-suffix strip is a FALLBACK, not the
+ *  first probe: look up the EXACT reported element id first (a real `…__esc` human node stores its
+ *  label under that exact key), and only then the `__esc`-stripped base (the bounded-timeout twin,
+ *  whose exact id is never stamped, resolves to its real node's label). Returns a static fallback when
+ *  no label is stored so a parked step is never left with a blank panel.
+ *
+ *  The fallback is deliberately node-NEUTRAL ("…delivery-graph step…", not "…human step…"): only
+ *  real `human` nodes are stamped into `human_labels`, but `isDeliveryHumanElement` (and hence this
+ *  helper's caller) also matches the `__esc`/`__contract` escalation twins that BOUNDED `agent`/`wait`/
+ *  `connector` nodes schedule — those carry no stored label and would otherwise be mislabeled as a
+ *  "human step". A found label is always a real human node's instruction; the fallback must read true
+ *  for both an untracked human run AND a non-human escalation twin. */
+export function deliveryHumanContextQuestion(
+  humanLabels: Record<string, string> | undefined,
+  elementId: string,
+): string {
+  const labels = humanLabels ?? {};
+  const base = elementId.replace(/__esc$/, "");
+  const label = (labels[elementId] ?? labels[base] ?? "").trim();
+  return label || "A scheduled delivery-graph step is waiting to be completed.";
+}
+
 /** The GENERIC fallback form (Decision 4, step 3): captures ONE typed value into the node's single
  *  declared emitted fact, so a human node with no explicit/category form can STILL emit downstream. */
 export const GENERIC_HUMAN_FORM = "delivery-human-generic";

package/app/mergeLoopBehaviour.test.ts

@@ -43,6 +43,7 @@ const MODEL = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
 const AGENT_SLA_MS = 30 * 60 * 1000; // matches the PT30M we start instances with
 const LANDED_WAIT_MS = 30 * 60 * 1000; // matches the PT30M landedWaitTimeout we start instances with
 const MERGEABLE_WAIT_MS = 30 * 60 * 1000; // matches the PT30M mergeableWaitTimeout we start instances with
+const MERGEABLE_REPOLL_MS = 2 * 60 * 1000; // matches the PT2M mergeableRepollInterval we start instances with
 
 type Output = Record<string, unknown>;
 type Responder = Output | Output[] | ((job: { variables: Record<string, unknown> }) => Output);
@@ -85,6 +86,7 @@ const DEFAULT_VARS: Record<string, unknown> = {
   agentSlaTimeout: "PT30M",
   landedWaitTimeout: "PT30M",
   mergeableWaitTimeout: "PT30M",
+  mergeableRepollInterval: "PT2M",
   mergeStallRounds: 0,
   mergeStallMax: 3,
   abandonBrief: null,
@@ -349,6 +351,94 @@ test("the stall-round cap escalates to a human instead of looping forever (#636)
   assert(!completedElementIds(engine).has("mark-merged"), "an exhausted stall must not mark-merged");
 });
 
+// ---------------------------------------------------------------------------
+// Async-UNKNOWN "waiting" verdict → bounded re-poll, NOT a human (issue #774)
+// ---------------------------------------------------------------------------
+// GitHub returns `mergeable=UNKNOWN` transiently while it computes mergeability in the background,
+// which `classifyMergeability` maps to `"waiting"`. Before the fix, a `"waiting"` verdict at
+// `gw-mergeable` hit the DEFAULT arm and escalated straight to the `wait-merge-answer` human task —
+// so a PR whose real state was still settling (e.g. to `"conflict"`, which would auto-fire
+// `senior:rebase`) paged a human instead of self-healing. The fix routes `"waiting"` to a bounded
+// re-poll (`wait-mergeable-repoll` timer → `merge-stall-probe` → the existing `gw-mergeable` arms),
+// bounded by the shared `mergeStallMax` budget, and routes the true DEFAULT to auto-rebase.
+
+test("a 'waiting' (async UNKNOWN) verdict re-polls instead of escalating to a human (#774)", async () => {
+  // RED (before the fix): `waiting` → DEFAULT → `merge-esc-conflict` → `wait-merge-answer`. GREEN:
+  // `waiting` parks on the re-poll timer; when it fires, `merge-stall-probe` re-derives `ready` and
+  // the PR merges — no human ever touched.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
+      "pr.merge": { mergeStatus: "merged" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "waiting" } });
+  // Parks on the bounded re-poll timer — NOT on a human task, NOT escalated.
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable-repoll");
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "a waiting verdict must NOT escalate to a human");
+  const openTasks = await engine.searchUserTasks({});
+  assert(!openTasks.some((t) => t.elementId === "wait-merge-answer"), "a waiting verdict must not park a user task");
+  // The timer fires → the probe re-derives ground truth (`ready`) → the PR merges.
+  await engine.advanceTime(MERGEABLE_REPOLL_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .hasCompleted()
+    .hasNoIncident()
+    .hasCompletedElements("wait-mergeable-repoll", "merge-stall-probe", "attempt-merge", "mark-merged");
+});
+
+test("a 'waiting' verdict that settles to conflict on re-poll reaches the rebase arm (#774)", async () => {
+  // The incident (Magikcraft/nano-bpm#1166): the PR was really CONFLICTING, but GitHub reported
+  // UNKNOWN transiently. The re-poll must let it settle to `conflict` → `senior:rebase`, the arm that
+  // would have fixed it, rather than paging a human on the transient UNKNOWN.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+      "senior:rebase": { status: "rebased" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "waiting" } });
+  await engine.advanceTime(MERGEABLE_REPOLL_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("wait-mergeable-repoll", "merge-stall-probe", "rebase")
+    .hasVariable("rebaseRound", 1);
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "settling to conflict must rebase, not escalate");
+});
+
+test("the 'waiting' re-poll is bounded — exhausting mergeStallMax escalates to a human (#774)", async () => {
+  // A permanently-UNKNOWN PR cannot re-poll forever: the re-poll shares the `mergeStallMax` budget.
+  // `mergeStallMax: 0` — escalate on the first re-poll. The probe runs once, `gw-merge-stall` finds
+  // the budget exhausted, and routes to the human `wait-merge-answer` (last resort, not first).
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", failingChecks: 0, failingChecksList: "" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "waiting" } });
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "must re-poll before ever escalating");
+  await engine.advanceTime(MERGEABLE_REPOLL_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("wait-mergeable-repoll", "merge-stall-probe", "merge-esc-conflict");
+});
+
+test("an unclassified verdict routes to auto-rebase (DEFAULT), not to a human (#774)", async () => {
+  // The DEFAULT arm is a last-resort self-heal, not a page: an unexpected/garbage `mergeState` routes
+  // to the bounded rebase agent (which reconciles from ground truth), never straight to a human.
+  const engine = await boot({ responses: { "senior:rebase": { status: "rebased" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "bogus" } });
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("rebase")
+    .hasVariable("rebaseRound", 1);
+  const openTasks = await engine.searchUserTasks({});
+  assert(!openTasks.some((t) => t.elementId === "wait-merge-answer"), "the default arm must not page a human");
+});
+
 test("an evicted queued merge re-arms the poller rather than completing", async () => {
   const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
   await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });

package/app/mergeableWait.test.ts

@@ -6,7 +6,8 @@
 
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { DEFAULT_MERGEABLE_WAIT_TIMEOUT, mergeableWaitTimeout } from "./mergeableWait.ts";
+import { DEFAULT_MERGEABLE_REPOLL_INTERVAL, DEFAULT_MERGEABLE_WAIT_TIMEOUT, mergeableRepollInterval, mergeableWaitTimeout } from "./mergeableWait.ts";
+import { isoDurationToMs } from "./reviewWait.ts";
 
 test("mergeableWaitTimeout: blank / absent / malformed → default", () => {
   assert.equal(mergeableWaitTimeout(undefined), DEFAULT_MERGEABLE_WAIT_TIMEOUT);
@@ -37,3 +38,43 @@ test("the default is itself a well-formed ISO-8601 duration (never an uninterpre
   assert.notEqual(DEFAULT_MERGEABLE_WAIT_TIMEOUT, sentinel);
   assert.equal(mergeableWaitTimeout(DEFAULT_MERGEABLE_WAIT_TIMEOUT, sentinel), DEFAULT_MERGEABLE_WAIT_TIMEOUT);
 });
+
+// --- Mergeability re-poll interval (issue #774) -----------------------------------------------
+// Baked into every merge-loop instance's `mergeableRepollInterval` process variable and evaluated by
+// the `wait-mergeable-repoll` timer catch, which bounds the `"waiting"` (async UNKNOWN) verdict's
+// re-poll before it re-derives mergeability from ground truth — so a malformed operator env must
+// never deploy an uninterpretable `<bpmn:timeDuration>`.
+
+test("mergeableRepollInterval: blank / absent / malformed → default", () => {
+  assert.equal(mergeableRepollInterval(undefined), DEFAULT_MERGEABLE_REPOLL_INTERVAL);
+  assert.equal(mergeableRepollInterval(""), DEFAULT_MERGEABLE_REPOLL_INTERVAL);
+  assert.equal(mergeableRepollInterval("   "), DEFAULT_MERGEABLE_REPOLL_INTERVAL);
+  assert.equal(mergeableRepollInterval("2m"), DEFAULT_MERGEABLE_REPOLL_INTERVAL); // missing leading P/T
+  assert.equal(mergeableRepollInterval("garbage"), DEFAULT_MERGEABLE_REPOLL_INTERVAL);
+});
+
+test("mergeableRepollInterval: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assert.equal(mergeableRepollInterval("PT2M"), "PT2M");
+  assert.equal(mergeableRepollInterval("pt90s"), "PT90S");
+  assert.equal(mergeableRepollInterval("  pt5m  "), "PT5M");
+});
+
+test("mergeableRepollInterval: the re-poll interval is shorter than the poller-death backstop", () => {
+  // The re-poll (GitHub settling UNKNOWN, ~seconds) must fire far sooner than the 30-minute
+  // dead-poller backstop, so a transient UNKNOWN self-heals briskly rather than parking for tens of
+  // minutes per round.
+  assert.equal(DEFAULT_MERGEABLE_REPOLL_INTERVAL, "PT2M");
+  // `notEqual` only proves the values differ — a future `PT1H` would pass despite being LONGER than
+  // the backstop. Assert the actual ordering invariant on parsed durations via the canonical helper.
+  assert.ok(
+    isoDurationToMs(DEFAULT_MERGEABLE_REPOLL_INTERVAL, "PT0S") <
+      isoDurationToMs(DEFAULT_MERGEABLE_WAIT_TIMEOUT, "PT0S"),
+    "the re-poll interval must be strictly shorter than the poller-death backstop",
+  );
+});
+
+test("mergeableRepollInterval: the default is itself a well-formed ISO-8601 duration", () => {
+  const sentinel = "PT1S";
+  assert.notEqual(DEFAULT_MERGEABLE_REPOLL_INTERVAL, sentinel);
+  assert.equal(mergeableRepollInterval(DEFAULT_MERGEABLE_REPOLL_INTERVAL, sentinel), DEFAULT_MERGEABLE_REPOLL_INTERVAL);
+});

package/app/mergeableWait.ts

@@ -36,3 +36,26 @@ export function mergeableWaitTimeout(
 ): string {
   return isoDuration(raw, def);
 }
+
+/** Default mergeability re-poll interval (ISO-8601 duration): how long the merge loop waits before
+ * re-deriving mergeability from ground truth when `gw-mergeable` sees an async-`UNKNOWN` `"waiting"`
+ * verdict (issue #774). GitHub returns `mergeable=UNKNOWN` transiently while it computes mergeability
+ * in the background; a `"waiting"` verdict must therefore route to a *bounded re-poll* — not straight
+ * to a human — so the loop self-heals once GitHub settles (to `"conflict"` → `senior:rebase`, etc.).
+ * Deliberately SHORT (unlike the 30-minute {@link DEFAULT_MERGEABLE_WAIT_TIMEOUT} poller-death
+ * backstop): GitHub usually settles UNKNOWN within seconds, so re-poll briskly rather than parking
+ * the PR for tens of minutes per round. The re-poll is bounded by the shared `mergeStallMax` budget
+ * (`NANO_PR_MAX_MERGE_STALL_ROUNDS`): once exhausted, `gw-merge-stall` escalates to a human. */
+export const DEFAULT_MERGEABLE_REPOLL_INTERVAL = "PT2M";
+
+/** Validate the operator-supplied mergeability re-poll interval (env
+ * `NANO_PR_MERGEABLE_REPOLL_INTERVAL`, ISO-8601 duration), falling back to
+ * {@link DEFAULT_MERGEABLE_REPOLL_INTERVAL} when absent, blank, or malformed — a bad env value must
+ * never deploy an uninterpretable timer expression. Derives its validation from the single canonical
+ * {@link isoDuration}. */
+export function mergeableRepollInterval(
+  raw: string | undefined,
+  def: string = DEFAULT_MERGEABLE_REPOLL_INTERVAL,
+): string {
+  return isoDuration(raw, def);
+}

package/app/pollUserTasks.test.ts

@@ -661,6 +661,62 @@ test("pollUserTasks (engine-first): surfaces an inlined delivery-graph human tas
   assertEquals(byKey["35002"].subject_title, "release runbook");
 });
 
+test("pollUserTasks: a parked delivery-human node carries its instruction as `question` (Decision context, issue #772)", async () => {
+  // The Tasks surface seeds no form variables, so a delivery-graph `human` node's instruction can only
+  // reach the operator through the read-model `question` (rendered as "Decision context"). Source it
+  // from the run's stamped `human_labels`, keyed by the parked user-task element id — else the panel is
+  // blank and the human has no idea what the run is waiting on.
+  const { data, stores } = memData({
+    delivery_graph_runs: [
+      {
+        run_key: "delivery-graph-403eb22e",
+        process_key: "dg-1",
+        status: "running",
+        title: "release runbook",
+        human_labels: JSON.stringify({
+          "delivery-human-task__n7": "Run the manual OTP publish for @nanobpm/urban",
+        }),
+      },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "20411", elementId: "delivery-human-task__n7", processInstanceKey: "dg-1", state: "CREATED" },
+    // the bounded-timeout escalation twin parks on the `…__esc` id but resolves the same base label
+    { userTaskKey: "20412", elementId: "delivery-human-task__n7__esc", processInstanceKey: "dg-1", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(byKey["20411"].question, "Run the manual OTP publish for @nanobpm/urban");
+  assertEquals(byKey["20412"].question, "Run the manual OTP publish for @nanobpm/urban");
+});
+
+test("pollUserTasks: a delivery-human node with no stored label still gets a non-blank Decision context (issue #772)", async () => {
+  // An untracked run (or a run whose label wasn't stamped) must not leave the panel blank — a static,
+  // node-NEUTRAL fallback still tells the operator a delivery-graph step is waiting. It must read true
+  // for a non-human escalation twin too, so it must not claim "human step".
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "20411", elementId: "delivery-human-task__n1", processInstanceKey: "dg-9", state: "CREATED" },
+    // a bounded `agent`/`wait`/`connector` node's escalation twin: `isDeliveryHumanElement` matches it,
+    // but it carries no stored human label, so it gets the neutral fallback, not a "human step" claim.
+    { userTaskKey: "20499", elementId: "delivery-human-task__agent5__esc", processInstanceKey: "dg-9", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(byKey["20411"].question, "A scheduled delivery-graph step is waiting to be completed.");
+  assertEquals(byKey["20499"].question, "A scheduled delivery-graph step is waiting to be completed.");
+});
+
 test("pollUserTasks (engine-first): a delivery-human task on an UNTRACKED run still surfaces (bucketed `delivery`, instance fallback) (issue #442)", async () => {
   // Even with no `delivery_graph_runs` row referencing the instance, the kind implies its aggregate, so
   // the row renders and stays answerable — mirroring the orphaned-escalation guarantee (#358).

package/app/service.ts

@@ -30,7 +30,7 @@ import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
-import { isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { deliveryHumanContextQuestion, isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
 import { deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
@@ -53,7 +53,7 @@ import {
 } from "./github.ts";
 import { activeStatusesFor, derivedTrackingTable } from "./instanceTracking.ts";
 import { pollLineage } from "./lineage.ts";
-import { mergeableWaitTimeout } from "./mergeableWait.ts";
+import { mergeableRepollInterval, mergeableWaitTimeout } from "./mergeableWait.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { mergeLandedWaitTimeout } from "./mergeLandedWait.ts";
 import {
@@ -206,6 +206,19 @@ export const MERGEABLE_WAIT_TIMEOUT = mergeableWaitTimeout(
   process.env.NANO_PR_MERGEABLE_WAIT_TIMEOUT,
 );
 
+/** How long the merge loop waits before re-deriving mergeability from ground truth when
+ * `gw-mergeable` sees an async-`UNKNOWN` `"waiting"` verdict (issue #774). Seeded as the
+ * `mergeableRepollInterval` process variable at merge start and evaluated by the merge-loop's
+ * `wait-mergeable-repoll` timer catch. A `"waiting"` verdict means GitHub is still computing
+ * mergeability in the background — so route it to a *bounded re-poll* (this timer → `merge-stall-probe`
+ * → the existing `gw-mergeable` arms), not to a human. The re-poll shares the `mergeStallMax` budget
+ * (`NANO_PR_MAX_MERGE_STALL_ROUNDS`) with the dead-poller stall backstop; once exhausted,
+ * `gw-merge-stall` escalates. ISO-8601 duration; a malformed `NANO_PR_MERGEABLE_REPOLL_INTERVAL`
+ * falls back to the default so an uninterpretable timer is never deployed. */
+export const MERGEABLE_REPOLL_INTERVAL = mergeableRepollInterval(
+  process.env.NANO_PR_MERGEABLE_REPOLL_INTERVAL,
+);
+
 /** Cooldown (ms) between the poller's automatic Copilot re-request nudges for a single waiting PR.
  * Copilot dismisses re-requests, so the poller retries — but not on every tick; this throttles it
  * to one attempt per window. Set via `NANO_PR_REVIEW_NUDGE_MINUTES` (minutes). */
@@ -678,6 +691,7 @@ export async function startMerge(
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
       landedWaitTimeout: MERGE_LANDED_WAIT_TIMEOUT,
       mergeableWaitTimeout: MERGEABLE_WAIT_TIMEOUT,
+      mergeableRepollInterval: MERGEABLE_REPOLL_INTERVAL,
       mergeStallRounds: 0,
       mergeStallMax: MAX_MERGE_STALL_ROUNDS,
       // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
@@ -2613,6 +2627,10 @@ export async function pollUserTasks(
     url?: string | null;
     deliveryLabel?: string | null;
     conformanceSummary?: string | null;
+    /** The parked human-node instruction labels for a delivery run, keyed by user-task element id
+     *  (`delivery-human-task__<node>`) — the run row's stamped `human_labels`, denormalised so the
+     *  Tasks-inbox "Decision context" can explain a parked delivery-graph `human` node (issue #772). */
+    humanLabels?: Record<string, string>;
     /** The subject's at-a-glance "waiting on <capability> · …" rollup, denormalised for the readiness
      *  escalation question (issue #674): the wait-gate projection on `plans.wait_gate_label`, or the
      *  feature run's `delivery_label` for the inline preflight. */
@@ -2640,7 +2658,7 @@ export async function pollUserTasks(
   // feature/plan/pr enrichment. The row's inlined `delivery-human-task__<node>` id is recognised by
   // the shared `userTaskKindLabel` predicate, and buckets as `delivery` (below).
   for (const run of await deliveryGraphRuns(data).all()) {
-    if (run.process_key) subjectByInstance.set(run.process_key, { type: "delivery", key: run.run_key, title: run.title, url: null });
+    if (run.process_key) subjectByInstance.set(run.process_key, { type: "delivery", key: run.run_key, title: run.title, url: null, humanLabels: parseHumanLabels(run.human_labels) });
   }
 
   // Per-element subject type for an ORPHANED task (no subject row) — the kind implies its aggregate even
@@ -2719,6 +2737,13 @@ export async function pollUserTasks(
         question = readinessEscalationQuestion(subj?.waitGateLabel ?? null);
         break;
     }
+    // A delivery-graph `human` node's user-task id is inlined per node (`delivery-human-task__<node>`
+    // and its `…__esc` twin), so it can't be a static `case` above (issue #772). Fill its "Decision
+    // context" from the run's stamped `human_labels` — otherwise the panel is blank and, because this
+    // surface seeds no form variables, the operator has no idea what the run is waiting on.
+    if (question === null && isDeliveryHumanElement(elementId)) {
+      question = deliveryHumanContextQuestion(subj?.humanLabels, elementId);
+    }
     return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? null, question, processKey: processInstanceKey, formKey: resolvedFormKey };
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.186.0",
+  "version": "0.186.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/forms/delivery-human-generic.form

@@ -5,43 +5,14 @@
   "components": [
     {
       "type": "text",
-      "text": "### Delivery graph — node `{{nodeId}}`",
-      "conditional": {
-        "hide": "=(nodeId = null) or (nodeId = \"\")"
-      }
-    },
-    {
-      "type": "textarea",
-      "key": "prompt",
       "label": "Now do this",
-      "description": "The scheduled human step this delivery graph is waiting on.",
-      "readonly": true
-    },
-    {
-      "type": "text",
-      "text": "**Emits:** {{emitLabel}} — enter its typed value below (validated against the node's declared fact).",
-      "conditional": {
-        "hide": "=emitMode != \"typed\""
-      }
+      "text": "This task's instruction is shown in the Decision context above."
     },
     {
       "type": "textfield",
       "key": "value",
-      "label": "Emitted value",
-      "description": "The typed value this step hands forward to its downstream dependents. Validated against the node's declared emitted fact.",
-      "conditional": {
-        "hide": "=emitMode != \"typed\""
-      },
-      "validate": {
-        "required": true
-      }
-    },
-    {
-      "type": "text",
-      "text": "_This step emits no typed fact (N/A) — just complete it to unblock its dependents._",
-      "conditional": {
-        "hide": "=emitMode = \"typed\""
-      }
+      "label": "Emitted value (only if this step emits a fact)",
+      "description": "The typed value this step hands forward to its downstream dependents. Leave blank for a click-done step that emits nothing."
     },
     {
       "type": "textarea",