@nanobpm/nano-workforce 0.150.2 → 0.150.4

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.150.4](https://github.com/nanobpm/nano-workforce/compare/v0.150.3...v0.150.4) (2026-08-28)
+
+### Documentation
+
+* **agent guide:** document the PT30M wait-gate default and poll bounds in §9 ([#585](https://github.com/nanobpm/nano-workforce/issues/585)) ([3092ae9](https://github.com/nanobpm/nano-workforce/commit/3092ae9c1448c8b540aa62abf58b268e14f3f0ee)), closes [nanobpm/nano-workforce#584](https://github.com/nanobpm/nano-workforce/issues/584)
+
+## [0.150.3](https://github.com/nanobpm/nano-workforce/compare/v0.150.2...v0.150.3) (2026-08-28)
+
+### Bug Fixes
+
+* **compileDeliveryGraph:** key reviewUrl to the request origin ([#577](https://github.com/nanobpm/nano-workforce/issues/577)) ([#581](https://github.com/nanobpm/nano-workforce/issues/581)) ([8c04c95](https://github.com/nanobpm/nano-workforce/commit/8c04c95b9d3617b3d71d28e54a7f24cae54c6e2c))
+
 ## [0.150.2](https://github.com/nanobpm/nano-workforce/compare/v0.150.1...v0.150.2) (2026-08-28)
 
 ### Bug Fixes

package/app/deliveryGraphProposals.test.ts

@@ -25,6 +25,7 @@ import {
   stageProposal,
   sweepExpiredProposals,
 } from "./deliveryGraphProposals.ts";
+import { publicBaseUrl } from "./blackboard.ts";
 
 const APP_ROOT = resolve(import.meta.dirname, "..");
 
@@ -87,6 +88,12 @@ test("proposalReviewUrl: a navigational deep-link to the cockpit page — NOT a
   assert(!/\/actions\//.test(url), "reviewUrl points at a page, never an API action");
 });
 
+test("proposalReviewUrl: with no base falls back to publicBaseUrl() — the text-ingress (no request) path (#577)", () => {
+  // The staging text-ingress path has no HTTP request to derive an origin from, so the default base
+  // must stay the deployment-wide NANO_WORKFORCE_BASE_URL via publicBaseUrl().
+  assertEquals(proposalReviewUrl("abc123"), `${publicBaseUrl()}/app/pages/delivery-graphs#proposal-abc123`);
+});
+
 test("buildProposalRow: stamps status staged, boolean→0/1, and TTL from createdAt", () => {
   const r = row({ sideEffecting: true, createdAt: "2024-01-01T00:00:00.000Z" });
   assertEquals(r.status, "staged");

package/app/resolveApiBase.test.ts

@@ -1,9 +1,10 @@
 // Tests for app/resolveApiBase.ts — the single canonical control-API base reconstruction shared by
-// getAgentInstructions and getAgentSkill. Covers proxy-header handling, scheme restriction,
+// getAgentInstructions and getAgentSkill, plus the human-facing resolvePublicOrigin (#577). Covers
+// proxy-header handling, scheme restriction, host sanitisation, x-forwarded-prefix sanitisation,
 // host-absent fallback, and mount-suffix stripping for both mount depths.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { resolveApiBase } from "./resolveApiBase.ts";
+import { resolveApiBase, resolvePublicOrigin } from "./resolveApiBase.ts";
 
 function req(headers: Record<string, string>, path: string) {
   return { path, headers: new Headers(headers) };
@@ -42,6 +43,7 @@ test("strips multiple trailing slashes after the mount suffix", () => {
   assertEquals(resolveApiBase(req({ host: "h" }, "/app/api/agent/skill///"), "agent/skill"), "http://h/app/api");
 });
 
+// ── resolveApiBase: x-forwarded-prefix sanitisation (#580) via the shared sanitiseForwardedPrefix ──
 test("prepends a validated x-forwarded-prefix to the reconstructed base", () => {
   const r = req(
     { host: "nano.ngrok-free.dev", "x-forwarded-prefix": "/console/app-view/Workforce" },
@@ -97,3 +99,79 @@ test("prefix composes with x-forwarded-proto and x-forwarded-host", () => {
   );
   assertEquals(resolveApiBase(r, "agent/skill"), "https://nano.ngrok-free.dev/console/app-view/Workforce/app/api");
 });
+
+// ── resolvePublicOrigin: the human-facing ORIGIN (+ proxy prefix), no /app/api suffix (#577) ──
+// Shares sanitiseForwardedPrefix with resolveApiBase, so the prefix policy (absolute-only, reject
+// scheme/authority/traversal entirely, percent-aware) is identical on both surfaces — no drift.
+test("resolvePublicOrigin: bare origin from the host header", () => {
+  assertEquals(resolvePublicOrigin(req({ host: "wf.example.com" }, "/app/api/actions/compile-delivery-graph")), "http://wf.example.com");
+});
+
+test("resolvePublicOrigin: honours x-forwarded-proto and x-forwarded-host", () => {
+  const r = req({ host: "internal", "x-forwarded-host": "example.test", "x-forwarded-proto": "https" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "https://example.test");
+});
+
+test("resolvePublicOrigin: restricts x-forwarded-proto to http/https", () => {
+  const r = req({ host: "wf.example.com", "x-forwarded-proto": "javascript" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://wf.example.com");
+});
+
+test("resolvePublicOrigin: appends the reverse-proxy x-forwarded-prefix", () => {
+  const r = req(
+    { "x-forwarded-host": "nano.ngrok-free.dev", "x-forwarded-proto": "https", "x-forwarded-prefix": "/console/app-view/Workforce" },
+    "/app/api/actions/compile-delivery-graph",
+  );
+  assertEquals(resolvePublicOrigin(r), "https://nano.ngrok-free.dev/console/app-view/Workforce");
+});
+
+test("resolvePublicOrigin: normalises a trailing slash on x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/console/app-view/Workforce/" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h/console/app-view/Workforce");
+});
+
+test("resolvePublicOrigin: treats a slash-only x-forwarded-prefix as empty (no double slash)", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "///" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: rejects a path-traversal x-forwarded-prefix entirely", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/console/../../etc" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: rejects a scheme/authority x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "https://evil.example/hijack" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: rejects a relative (non-absolute) x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "@evil.example" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: falls back to a localhost origin when the Host header is absent", () => {
+  assertEquals(resolvePublicOrigin(req({}, "/app/api/actions/compile-delivery-graph")), "http://localhost:3000");
+});
+
+// ── host sanitisation: the untrusted x-forwarded-host/host authority is reflected into the URL ──
+test("rejects a userinfo-injecting host (falls back to localhost)", () => {
+  const r = req({ "x-forwarded-host": "evil.com@real.example" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://localhost:3000");
+  assertEquals(resolveApiBase(req({ "x-forwarded-host": "evil.com@real.example" }, "/app/api/agent"), "agent"), "http://localhost:3000/app/api");
+});
+
+test("rejects a path-injecting host (falls back to localhost)", () => {
+  const r = req({ "x-forwarded-host": "real.example/extra-path" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://localhost:3000");
+});
+
+test("accepts a host:port authority", () => {
+  const r = req({ "x-forwarded-host": "wf.example.com:8443", "x-forwarded-proto": "https" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "https://wf.example.com:8443");
+});
+
+test("accepts a bracketed IPv6 host authority", () => {
+  const r = req({ "x-forwarded-host": "[2001:db8::1]:3000" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://[2001:db8::1]:3000");
+});

package/app/resolveApiBase.ts

@@ -17,33 +17,72 @@
  *                    "/app/api" when the path is nothing but the suffix.
  */
 export function resolveApiBase(req: { path: string; headers: Headers }, mountSuffix: string): string {
-  const rawProto = (req.headers.get("x-forwarded-proto") ?? "http").split(",")[0].trim().toLowerCase();
-  // x-forwarded-proto is user-controlled behind some proxies; only trust http/https.
-  const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
-  const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
-  // The external path prefix stripped by a reverse proxy (e.g. the console app-view proxy mounts us
-  // under "/console/app-view/{project}"). X-Forwarded-Prefix is the de-facto standard header for it.
-  // It is untrusted, proxy-supplied input that ends up in a URL handed to an agent, so validate it as
-  // strictly as x-forwarded-proto above: accept only an absolute path of URL-safe path characters —
-  // rejecting anything with a scheme, an authority ("//host"), or a "."/".." traversal segment — then
-  // drop trailing slashes so it composes cleanly with the base path. Anything else falls back to an
-  // empty prefix, i.e. today's behaviour.
-  //
-  // Percent-encoding can smuggle those forms past a literal check: "%2e%2e" decodes to "..", and
-  // "%2f%2f" decodes to an authority-introducing "//". So normalise the common encoded spellings of
-  // "." and "/" (case-insensitively) before rejecting dot-segments and "//"; the still-encoded raw
-  // value is what we reflect once it validates.
-  const rawPrefix = (req.headers.get("x-forwarded-prefix") ?? "").split(",")[0].trim();
-  const decodedPrefix = rawPrefix.replace(/%2e/gi, ".").replace(/%2f/gi, "/");
-  const prefix =
-    /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/.test(rawPrefix) &&
-    !decodedPrefix.includes("//") &&
-    !/(^|\/)\.\.?(\/|$)/.test(decodedPrefix)
-      ? rawPrefix.replace(/\/+$/, "")
-      : "";
+  const { proto, host } = requestProtoHost(req);
+  const prefix = sanitiseForwardedPrefix(req.headers.get("x-forwarded-prefix"));
   // The op is mounted at "<base>/<mountSuffix>"; strip the trailing segments to recover the base path.
   const suffix = mountSuffix.replace(/^\/+/, "").replace(/\/+$/, "");
   const stripRe = new RegExp(`/${suffix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/*$`);
   const basePath = req.path.replace(stripRe, "") || "/app/api";
   return host ? `${proto}://${host}${prefix}${basePath}` : `http://localhost:3000${prefix}${basePath}`;
 }
+
+/** The public ORIGIN (+ proxy prefix) this request arrived on — the base for a navigational link
+ * handed back to the caller (e.g. a cockpit deep-link), WITHOUT the `/app/api` mount suffix that
+ * {@link resolveApiBase} keeps. Where `resolveApiBase` reconstructs the control-API base an *agent*
+ * calls back on, this reconstructs the human-facing origin: proto + host (same proxy-header trust as
+ * `resolveApiBase`) plus any reverse-proxy path prefix advertised via `x-forwarded-prefix`, so a
+ * link built as `${resolvePublicOrigin(req)}/app/pages/…` opens on the exact origin the operator is
+ * driving this app from (e.g. a tunnel), not a static deployment-wide base. Falls back to a
+ * localhost origin when the Host header is absent (a raw unit-test request). */
+export function resolvePublicOrigin(req: { path: string; headers: Headers }): string {
+  const { proto, host } = requestProtoHost(req);
+  const prefix = sanitiseForwardedPrefix(req.headers.get("x-forwarded-prefix"));
+  return host ? `${proto}://${host}${prefix}` : `http://localhost:3000${prefix}`;
+}
+
+/** Sanitise the untrusted, proxy/user-controlled `x-forwarded-prefix` into a safe leading-slash,
+ * no-trailing-slash path segment (or ""). The ONE canonical prefix sanitiser shared by
+ * {@link resolveApiBase} and {@link resolvePublicOrigin} (AGENTS.md "derivation over duplication") —
+ * the prefix is the reverse-proxy path the public URL was mounted under (e.g.
+ * "/console/app-view/Workforce") and is reflected into a caller-facing URL, so it must not smuggle a
+ * scheme, an authority ("//host"), or a "."/".." traversal segment into the URL. Accept only an
+ * absolute path of URL-safe path characters, then drop trailing slashes so it composes cleanly with
+ * the base path; anything else falls back to an empty prefix. Percent-encoding can smuggle those
+ * forms past a literal check ("%2e%2e" decodes to "..", "%2f%2f" to an authority-introducing "//"),
+ * so normalise the common encoded spellings of "." and "/" (case-insensitively) before rejecting
+ * dot-segments and "//"; the still-encoded raw value is what we reflect once it validates. Because
+ * the return is always either "" or a leading-"/" path, it can never alter the `${proto}://${host}`
+ * authority. */
+function sanitiseForwardedPrefix(raw: string | null): string {
+  const rawPrefix = (raw ?? "").split(",")[0].trim();
+  const decodedPrefix = rawPrefix.replace(/%2e/gi, ".").replace(/%2f/gi, "/");
+  return /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/.test(rawPrefix) &&
+    !decodedPrefix.includes("//") &&
+    !/(^|\/)\.\.?(\/|$)/.test(decodedPrefix)
+    ? rawPrefix.replace(/\/+$/, "")
+    : "";
+}
+
+/** The trusted (proto, host) pair for a request — the ONE place proxy-header handling lives so
+ * `resolveApiBase` and `resolvePublicOrigin` can't drift (AGENTS.md "derivation over duplication").
+ * Only `http`/`https` are trusted from the user-controlled `x-forwarded-proto`; the host prefers
+ * `x-forwarded-host` over `host`. `host` is "" when neither header is present or the advertised host
+ * is not a valid authority (see {@link sanitiseHost}). */
+function requestProtoHost(req: { headers: Headers }): { proto: string; host: string } {
+  const rawProto = (req.headers.get("x-forwarded-proto") ?? "http").split(",")[0].trim().toLowerCase();
+  const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
+  const rawHost = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
+  return { proto, host: sanitiseHost(rawHost) };
+}
+
+/** Sanitise the untrusted, proxy/user-controlled host (`x-forwarded-host`/`host`) into a bare
+ * authority — a registered name or IPv4 with an optional `:port`, or a bracketed IPv6 literal with
+ * an optional `:port` — or "" when it carries anything else. The host is reflected verbatim into the
+ * `${proto}://${host}` authority of a caller-facing URL, so a hostile value like
+ * `evil.com@real.example` (userinfo injection) or `real.example/extra-path` (path injection) must be
+ * rejected outright rather than smuggled through. */
+function sanitiseHost(host: string): string {
+  if (!host) return "";
+  const valid = /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\])(?::\d+)?$/.test(host);
+  return valid ? host : "";
+}

package/docs/agent-guide.md

@@ -180,6 +180,12 @@ curl -sS __BASE__/../../tasks/api/tasks \
 The inbox UI is also served at `__BASE__/../../tasks` for a human to browse, filter, and
 answer (assignee/candidate-group and age surface on each task once assignment lands).
 
+> **`wait`-gate escalations are different — completing one does NOT re-arm the gate.** The
+> escalation kinds above resume a loop with your answer. A **delivery-graph `wait` node**
+> (§9) that elapses its bound also parks a task, but completing *that* one releases the token
+> **as not-ready** and the graph proceeds **past the gate** — the downstream side-effecting
+> node then runs against the unmet dependency. See §9.2 before clearing one.
+
 **Answer a task** by completing it with the typed variables its form expects — the
 completion resumes the parked process:
 
@@ -438,7 +444,20 @@ layer schedules, it does not re-implement execution):
 | `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Two **real targets** ship today — **`converge`** and **`converge-merge`** (§9.4); other targets are a forward-declared stub. | yes |
 
 A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
-intake uses): `{ kind, target, onTimeout?, match?, poll? }`. The **`pr` kind** watches an
+intake uses): `{ kind, target, onTimeout?, match?, poll? }`, where `poll` is
+`{ everyMs?, timeoutMs?, backoff? }` — `everyMs` is the re-probe cadence, `timeoutMs` the
+total bounded budget, and `backoff ∈ fixed|exponential`.
+
+> **The bound is invisible unless you set it.** When `poll` (or `poll.timeoutMs`) is
+> **omitted**, the gate inherits the built-in default budget of **`PT30M` (30 minutes),
+> re-probing every 15s** (`DEFAULT_READINESS_TIMEOUT` / `DEFAULT_EVERY_MS`,
+> `app/readiness.ts`). That default is right for *"is the package published yet"* and badly
+> wrong for `wait[pr, merged]` / `wait[epic]`, which routinely wait **hours or days** — an
+> unpopulated `poll` on such a gate escalates after 30 minutes for no visible reason. Neither
+> `compile` nor `preview` surfaces the effective bound, so **set `poll.timeoutMs` explicitly**
+> on any gate that waits on a merge or an epic (see §9.4 / §9.5).
+
+The **`pr` kind** watches an
 in-flight PR — `target: "owner/repo#123"`, `match.prState ∈ ready|merged|mergeable|checks-green`
 (default `merged`) — and on a merged match binds `mergedSha` as an output fact. The **`epic`
 kind** (issue #568) gates on an **nwf plan-fanout epic reaching "fully merged"** — `target:
@@ -526,6 +545,18 @@ Graphs** grid (e.g. *"parked on human node: manual OTP publish"*). A `human` nod
 **Tasks** inbox and is answered exactly as an escalation is (§3) — its completion emits any
 declared facts, which downstream edges bind.
 
+> **Completing a `wait` escalation proceeds *as not-ready* — it does NOT re-arm the gate.**
+> A `wait` node with `onTimeout: "escalate"` (the default) that elapses its bound parks a
+> human-completable escalation task on the Tasks inbox. **Completing that task does not retry
+> the probe or wait for readiness** — it releases the token **as not-ready** and the graph
+> proceeds **past the gate**, so the downstream side-effecting node then runs *against the
+> unmet dependency* (`waitBodyLines`, `app/deliveryGraphCompiler.ts`). An operator clearing
+> what looks like a stuck task therefore *launches the very work the gate was holding back*.
+> If the dependency genuinely is not ready, do **not** complete the escalation to "unstick"
+> it — extend the gate's `poll.timeoutMs` and re-dispatch, or abandon the run. (Same for
+> `onTimeout: "continue"`, which proceeds past the gate as not-ready with **no** human stop
+> at all.)
+
 > **Why the split?** Making the compile door the end of the agent surface closes a
 > self-approval hole: the old flow handed the same caller a content-addressed approval token
 > to re-submit with, so any holder of the API credential approved its own graph. Removing the
@@ -544,7 +575,8 @@ publish and records the version → open+merge PR #303 (repo 3) consuming that v
   "name": "cross-repo release: merge #101 → un-draft+merge #202 → manual OTP publish → consume in #303",
   "nodes": [
     { "id": "merge-a", "kind": "wait",
-      "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" }, "onTimeout": "escalate" } },
+      "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" },
+                "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } },
     { "id": "undraft-merge-b", "kind": "agent",
       "agent": { "jobType": "senior:merge", "prompt": "Take draft PR acme/repo-2#202 out of draft and merge it once its required checks are green." } },
     { "id": "manual-publish", "kind": "human",
@@ -553,7 +585,8 @@ publish and records the version → open+merge PR #303 (repo 3) consuming that v
     { "id": "open-pr-c", "kind": "agent",
       "agent": { "jobType": "senior:feature", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
     { "id": "merge-c", "kind": "wait",
-      "wait": { "kind": "pr", "target": "acme/repo-3#303", "match": { "prState": "merged" }, "onTimeout": "escalate" } }
+      "wait": { "kind": "pr", "target": "acme/repo-3#303", "match": { "prState": "merged" },
+                "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } }
   ],
   "edges": [
     { "from": "merge-a", "to": "undraft-merge-b" },
@@ -622,7 +655,8 @@ author never knows the PR number at compose time, so reference it by fact:
     { "id": "land", "kind": "connector",
       "connector": { "target": "converge-merge", "payload": { "pr": "open.pr" } } },
     { "id": "merged", "kind": "wait",
-      "wait": { "kind": "pr", "target": "open.pr", "match": { "prState": "merged" }, "onTimeout": "escalate" } }
+      "wait": { "kind": "pr", "target": "open.pr", "match": { "prState": "merged" },
+                "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } }
   ],
   "edges": [
     { "from": "open.pr", "to": "land" },
@@ -631,6 +665,11 @@ author never knows the PR number at compose time, so reference it by fact:
 }
 ```
 
+The `merged` gate carries an explicit **`poll`** (re-probe every 5 minutes, budget 3 days:
+`timeoutMs: 259200000`) because a `wait[pr, merged]` waits on a human-paced merge — **omitting
+`poll` inherits the 30-minute default** (§9.1) and escalates mid-review. Set `poll.timeoutMs`
+to a realistic budget on any merge/epic gate.
+
 The `pr` fact is threaded along the **fact-qualified edges** (`open.pr → land`, `open.pr → merged`) —
 those edges are what carry the observed PR into each consumer, so they are **required** when you
 reference `open.pr` (the validator rejects a reference with no threading edge, `unbound-pr`). Three
@@ -661,7 +700,9 @@ babysitting a `confirm` gate.
   "nodes": [
     { "id": "gate-epic", "kind": "wait",
       "wait": { "kind": "epic", "target": "nanobpm/nano-ide#488",
-                "match": { "epicState": "merged" }, "onTimeout": "escalate" },
+                "match": { "epicState": "merged" },
+                "poll": { "everyMs": 300000, "timeoutMs": 259200000 },
+                "onTimeout": "escalate" },
       "emits": [ { "name": "prCount", "type": "number" } ] },
     { "id": "start-b", "kind": "agent",
       "agent": { "jobType": "senior:feature", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
@@ -680,5 +721,11 @@ Semantics:
 - **A failed/abandoned/mixed epic never reports merged**, so it never falsely releases the
   gate; the **bounded** wait elapses and routes via **`onTimeout`** (`escalate`/`continue`) —
   it does **not** hang.
+- **Set `poll.timeoutMs` to a realistic budget.** An epic reaching "fully merged" is a
+  multi-day, human-paced event, so the example gives it `poll: { everyMs: 300000, timeoutMs:
+  259200000 }` (re-probe every 5 minutes, budget 3 days). **Omitting `poll` inherits the
+  30-minute default** (§9.1) — the gate would escalate long before the epic lands, and (per
+  §9.2) completing that escalation would release `start-b` **as not-ready**, launching feature
+  B before its dependency merged. Size `timeoutMs` to how long the epic realistically takes.
 - On a fully-merged match it binds **`prCount`** (how many slice PRs the epic landed) as an
   output fact, so a downstream node can consume it (parity with the `pr` kind's `mergedSha`).

package/operations/compileDeliveryGraph.test.ts

@@ -30,8 +30,9 @@ async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Pro
   }
 }
 
-async function call(app: AppApi, body: unknown) {
-  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+async function call(app: AppApi, body: unknown, headers: Record<string, string> = {}) {
+  const req = { path: "/app/api/actions/compile-delivery-graph", headers: new Headers(headers) };
+  return (await handler({ req: req as any, params: {}, query: {}, body } as any, app)) as any;
 }
 
 const GOOD = {
@@ -79,6 +80,33 @@ test("compile-delivery-graph: the response exposes NO dispatch handle — no run
   });
 });
 
+// ── #577: reviewUrl is a caller-facing link → keyed to the request origin, not the static base ──
+test("compile-delivery-graph: reviewUrl is on the request's forwarded origin, not NANO_WORKFORCE_BASE_URL", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, GOOD, { "x-forwarded-proto": "https", "x-forwarded-host": "example.test" });
+    assertEquals(res.status, 200);
+    assertEquals(
+      res.body.reviewUrl,
+      `https://example.test/app/pages/delivery-graphs#proposal-${res.body.digest}`,
+    );
+  });
+});
+
+test("compile-delivery-graph: reviewUrl honours the reverse-proxy x-forwarded-prefix", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, GOOD, {
+      "x-forwarded-proto": "https",
+      "x-forwarded-host": "nano.ngrok-free.dev",
+      "x-forwarded-prefix": "/console/app-view/Workforce",
+    });
+    assertEquals(res.status, 200);
+    assertEquals(
+      res.body.reviewUrl,
+      `https://nano.ngrok-free.dev/console/app-view/Workforce/app/pages/delivery-graphs#proposal-${res.body.digest}`,
+    );
+  });
+});
+
 test("compile-delivery-graph: re-compiling the same graph is idempotent — one staged proposal, TTL anchored to the first stage", async () => {
   await withApp(async (app, data) => {
     const first = await call(app, GOOD);

package/operations/compileDeliveryGraph.ts

@@ -21,12 +21,13 @@ import {
   stageProposal,
 } from "../app/deliveryGraphProposals.ts";
 import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import { resolvePublicOrigin } from "../app/resolveApiBase.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const STAGED_MESSAGE =
   "The graph compiled and is staged for operator review. Ask the operator to preview and approve — or request modifications — in the cockpit. Dispatch is an operator action; there is no start endpoint.";
 
-export default defineOperation("compileDeliveryGraph", async ({ body }, app) => {
+export default defineOperation("compileDeliveryGraph", async ({ body, req }, app) => {
   // The runtime validates the body's SHAPE against `DeliveryGraph` before we run; the compiler adds
   // the SEMANTIC checks (acyclicity, edge integrity, fact resolution). A directly-invoked delegate
   // could still pass `undefined` — the compiler reads its input as `unknown` and maps that to a clean
@@ -75,7 +76,10 @@ export default defineOperation("compileDeliveryGraph", async ({ body }, app) =>
       message: STAGED_MESSAGE,
       digest,
       preview,
-      reviewUrl: proposalReviewUrl(digest),
+      // Navigational, human-facing link → keyed to the ORIGIN this request arrived on (tunnel,
+      // proxy prefix, …), not the static deployment-wide NANO_WORKFORCE_BASE_URL, so the operator
+      // driving this instance can actually open it (#577).
+      reviewUrl: proposalReviewUrl(digest, resolvePublicOrigin(req)),
     },
   };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.150.2",
+  "version": "0.150.4",
   "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",