@nanobpm/nano-workforce 0.40.1 → 0.41.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.41.0](https://github.com/nanobpm/nano-workforce/compare/v0.40.2...v0.41.0) (2026-08-11)
+
+
+### Features
+
+* **api:** serve an agent operator guide at GET /app/api/agent ([#118](https://github.com/nanobpm/nano-workforce/issues/118)) ([6768407](https://github.com/nanobpm/nano-workforce/commit/67684075cfe4706db7dfc63f8c536990254a7480))
+
+## [0.40.2](https://github.com/nanobpm/nano-workforce/compare/v0.40.1...v0.40.2) (2026-08-11)
+
+
+### Bug Fixes
+
+* **merge-loop:** escape wait-landed when a queued PR is evicted on conflict ([#117](https://github.com/nanobpm/nano-workforce/issues/117)) ([df7f850](https://github.com/nanobpm/nano-workforce/commit/df7f85050624f11490d715c90e054a5c7fb6d0fa)), closes [Magikcraft/nano-bpm#727](https://github.com/Magikcraft/nano-bpm/issues/727)
+
 ## [0.40.1](https://github.com/nanobpm/nano-workforce/compare/v0.40.0...v0.40.1) (2026-08-11)
 
 

package/README.md

@@ -279,6 +279,26 @@ per-instance context (e.g. a human's escalation answer) is appended by the harne
 
 ---
 
+## Point an agent at it (self-serve guide)
+
+The running app serves a live **agent operator guide** at
+`GET /app/api/agent` — how to submit PRs (review-only vs. merge), hand over an epic,
+answer escalations, and **debug** the system (find engine instances, relate them to
+PRs, inspect the models/prompts, unstick stuck processes, and raise issues/PRs). Its
+examples are keyed to the instance you fetched it from, so a coding agent can drive
+**and** debug the workforce with no extra context:
+
+```bash
+curl -sS http://localhost:3000/app/api/agent | jq -r .instructions
+```
+
+Like `/version` and `/status`, this endpoint honours the optional
+`NANO_PR_WEBHOOK_SECRET` guard (`X-Hook-Secret` header): when that secret is set it
+returns `401` without the matching header; unset = open. The source lives in
+`resources/agent-guide.md`.
+
+---
+
 ## Architecture & contributing
 
 - **[SPEC.md](SPEC.md)** — the behavioural source of truth for the processes.

package/app/agentGuide.ts

@@ -0,0 +1,64 @@
+// The agent operator guide served by GET /app/api/agent (operationId `getAgentInstructions`).
+//
+// The guide itself is authored as plain markdown in `resources/agent-guide.md` (kept out of
+// `prompts/` so it is NOT treated as a deployable agent template) and read from the checkout at
+// module load — same "run the .ts sources directly, inspect the working tree at runtime" approach
+// as version.ts. Two placeholders are substituted per request/deployment so the embedded examples
+// are copy-pasteable against THIS instance:
+//   • __BASE__   → the app control-API base the caller reached us on (e.g. https://host/app/api)
+//   • __ENGINE__ → the engine's Camunda-8 v2 REST base this app is configured to talk to
+//
+// Reading is best-effort: a missing file yields a short built-in fallback rather than throwing, so
+// the endpoint never 500s just because the doc is absent from a stripped-down deploy.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const GUIDE_PATH = join(REPO_ROOT, "resources", "agent-guide.md");
+
+// Read the raw guide once, at module load. Frozen for the life of the process.
+const RAW_GUIDE: string = (() => {
+  try {
+    return readFileSync(GUIDE_PATH, "utf8");
+  } catch {
+    return [
+      "# Nano Workforce — agent operator guide",
+      "",
+      "The full guide document could not be read from this deployment.",
+      "",
+      "Key endpoints (under the app control-API base `__BASE__`):",
+      "- `GET /status` — every PR in flight, with its engine `processKey` and any open escalation.",
+      "- `GET /version` — which code is live.",
+      "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
+      "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue }`).",
+      "- `POST /actions/message` — answer an escalation (`escalation-answered`, correlate by PR key).",
+      "",
+      "Engine (Camunda-8 v2 REST) base for debugging: `__ENGINE__`.",
+      "Source repository: `nanobpm/nano-workforce`.",
+      "",
+    ].join("\n");
+  }
+})();
+
+/**
+ * The engine's Camunda-8 v2 REST base this app talks to, resolved exactly as `main.ts` does:
+ * an explicit `CAMUNDA_REST_ADDRESS` wins, else `${NANOBPMN_BASE_URL}/v2` (default localhost:8080).
+ * Trailing slashes are trimmed so the guide's `__ENGINE__/jobs/search` examples are well-formed.
+ */
+export function resolveEngineBase(): string {
+  const explicit = process.env.CAMUNDA_REST_ADDRESS;
+  const base = explicit?.trim()
+    ? explicit.trim()
+    : `${(process.env.NANOBPMN_BASE_URL ?? "http://localhost:8080").replace(/\/+$/, "")}/v2`;
+  return base.replace(/\/+$/, "");
+}
+
+/**
+ * Render the guide for a given app control-API base (e.g. "https://host/app/api"). The engine base
+ * is resolved from the environment. Substitutes every `__BASE__`/`__ENGINE__` occurrence.
+ */
+export function renderAgentGuide(apiBase: string): string {
+  const base = apiBase.replace(/\/+$/, "");
+  return RAW_GUIDE.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
+}

package/app/queuedVerdict.test.ts

@@ -0,0 +1,40 @@
+// The merge-loop enqueues a "ready" PR (mergeStatus="queued") and parks at `wait-landed`. This
+// decision drives what the poller does next from the PR's live GitHub state. The regression it
+// guards: a PR that develops a merge CONFLICT after being enqueued (#727/instance 729) must be
+// EVICTED back to the mergeable gate, not left waiting forever — while a PR still legitimately in
+// the queue (reported BLOCKED/UNSTABLE by GitHub) must keep waiting, never be falsely evicted.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { PrState } from "./github.ts";
+import { queuedVerdict } from "./service.ts";
+
+function st(over: Partial<PrState>): PrState {
+  return {
+    merged: false,
+    mergeStateStatus: "CLEAN",
+    failingChecks: 0,
+    failingCheckNames: [],
+    presentCheckNames: [],
+    totalChecks: 0,
+    isDraft: false,
+    headRefOid: null,
+    ...over,
+  };
+}
+
+test("a landed PR advances (merge-landed)", () => {
+  assertEquals(queuedVerdict(st({ merged: true, mergeStateStatus: "CLEAN" })), "landed");
+  // `merged` wins even if a stale mergeStateStatus lags.
+  assertEquals(queuedVerdict(st({ merged: true, mergeStateStatus: "DIRTY" })), "landed");
+});
+
+test("a DIRTY (conflicting) PR is evicted — this is the #727 wedge", () => {
+  assertEquals(queuedVerdict(st({ merged: false, mergeStateStatus: "DIRTY" })), "evicted");
+});
+
+test("a PR still legitimately in the queue keeps waiting (never falsely evicted)", () => {
+  // Queuing PRs commonly report these; none is a conflict, so none may evict.
+  for (const s of ["CLEAN", "BLOCKED", "UNSTABLE", "BEHIND", "HAS_HOOKS", "UNKNOWN", "DRAFT"]) {
+    assertEquals(queuedVerdict(st({ merged: false, mergeStateStatus: s })), "waiting", s);
+  }
+});

package/app/service.ts

@@ -17,6 +17,7 @@ import {
   fetchPrState,
   hasPendingCopilotReviewer,
   type MergeMethod,
+  type PrState,
   requestCopilotReview,
 } from "./github.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
@@ -637,7 +638,7 @@ async function mirrorTaskStatusForPr(data: DataLayer, prKey: string, status: "op
  *   • waiting_deps  → every declared dependency has merged        → `deps-cleared`
  *   • waiting_merge → GitHub settled the PR as mergeable/blocked  → `merge-ready` {mergeState}
  *   • waiting_lane  → predecessor in same exclusion lane merged    → re-arm `waiting_merge`
- *   • queued        → the queued PR has landed on GitHub          → `merge-landed`
+ *   • queued        → the queued PR landed → `merge-landed`; or it conflicts (DIRTY) → `merge-evicted`
  * On publish we flip status to the transient `merging` (which no branch scans) so a slow pass
  * can't double-signal, exactly as `pollReviews` flips to `converging`; `flipToMergingThenPublish`
  * reverts the flip if the publish fails so a failed handoff can't wedge the PR. */
@@ -756,25 +757,60 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
     }
   }
 
-  // 4) Queued PR landed?
+  // 4) Queued PR landed — or fell out of the merge queue?
+  //
+  // A PR enqueued by `attempt-merge` (mergeStatus="queued") parks the process at `wait-landed`.
+  // Two things can end that wait: the queue lands the PR (→ `merge-landed`), or the PR is EVICTED
+  // from the queue because its base moved under it and it now conflicts (`DIRTY`). Without the
+  // eviction path a conflicted-after-enqueue PR waits forever (nothing ever publishes
+  // `merge-landed`), which is exactly how #727/instance 729 wedged. We must NOT treat a merely
+  // "not yet landed" PR as evicted: while it is legitimately queuing GitHub often reports it as
+  // BLOCKED (a pending queue check) or UNSTABLE, which `classifyMergeability` calls not-ready. Only
+  // a genuine merge CONFLICT (`DIRTY`) means it has dropped out — evict on that alone and re-arm the
+  // merge poller (`merge-evicted` → `arm-merge`), which re-runs the mergeable gate so the existing
+  // auto-rebase / escalate machinery resolves the conflict.
   for (const pr of await prs(data).find({ status: "queued" })) {
     const { repo, number, pr_key: prKey } = pr;
     try {
       const st = await fetchPrState(repo, number, token);
       if (st === null) continue; // no transport → skip this PR (others may still advance)
-      if (!st.merged) continue; // still in the queue
-      await flipToMergingThenPublish(data, engine, prKey, "queued", {
-        name: "merge-landed",
-        correlationKey: prKey,
-        variables: {},
-      });
-      console.log(`[poller] queued PR landed -> ${prKey}`);
+      const verdict = queuedVerdict(st);
+      if (verdict === "landed") {
+        await flipToMergingThenPublish(data, engine, prKey, "queued", {
+          name: "merge-landed",
+          correlationKey: prKey,
+          variables: {},
+        });
+        console.log(`[poller] queued PR landed -> ${prKey}`);
+      } else if (verdict === "evicted") {
+        await flipToMergingThenPublish(data, engine, prKey, "queued", {
+          name: "merge-evicted",
+          correlationKey: prKey,
+          variables: {},
+        });
+        console.log(`[poller] queued PR evicted (conflict) -> ${prKey}`);
+      }
+      // otherwise: still legitimately in the queue — keep waiting.
     } catch (err) {
       console.error(`[poller] queued ${prKey}: ${err}`);
     }
   }
 }
 
+/** Decide what to do with a PR the process enqueued (parked at `wait-landed`), from its current
+ *  GitHub merge state:
+ *   • `landed`  — the queue merged it → publish `merge-landed` (advance to mark-merged).
+ *   • `evicted` — it fell out of the queue with a real merge CONFLICT (`DIRTY`) → publish
+ *     `merge-evicted` so the process re-arms the merge poller and the mergeable gate re-runs
+ *     (auto-rebase / escalate). Without this a conflicted-after-enqueue PR waits forever.
+ *   • `waiting` — still legitimately in the queue. Crucially, a queuing PR is frequently reported
+ *     BLOCKED/UNSTABLE (a pending queue check), which is NOT eviction — only `DIRTY` is. */
+export function queuedVerdict(st: PrState): "landed" | "evicted" | "waiting" {
+  if (st.merged) return "landed";
+  if (st.mergeStateStatus === "DIRTY") return "evicted";
+  return "waiting";
+}
+
 /** The subset of a Camunda-8 `/v2/jobs/search` result item this app reads. `worker` is the
  * leasing worker's name (empty/absent until an agent activates the job); `deadline` is the
  * activation lock's expiry (ISO ts). */

package/openapi.yaml

@@ -137,6 +137,42 @@ components:
           type: string
         uptimeSeconds:
           type: integer
+    AgentInstructions:
+      type: object
+      description: The agent operator guide — how to drive (submit PRs/epics, answer escalations)
+        and debug (find engine instances, relate them to PRs, inspect models/prompts, unstick stuck
+        processes, raise issues/PRs) this Nano Workforce instance. The `instructions` markdown has
+        its example commands keyed to this instance's `baseUrl`/`engineBase`.
+      additionalProperties: false
+      required:
+        - format
+        - appVersion
+        - generatedAt
+        - baseUrl
+        - engineBase
+        - instructions
+      properties:
+        format:
+          type: string
+          description: The `instructions` media format. Always "markdown".
+          enum:
+            - markdown
+        appVersion:
+          type: string
+          nullable: true
+          description: The running app version this guide matches (null when unreadable).
+        generatedAt:
+          type: string
+          description: When this response was rendered (ISO-8601).
+        baseUrl:
+          type: string
+          description: The app control-API base the examples target (e.g. https://host/app/api).
+        engineBase:
+          type: string
+          description: The engine's Camunda-8 v2 REST base this app talks to, for debugging queries.
+        instructions:
+          type: string
+          description: The full operator guide as markdown.
     SubmitResult:
       type: object
       required:
@@ -387,6 +423,27 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agent:
+    get:
+      operationId: getAgentInstructions
+      summary: The agent operator guide (markdown) — how to submit PRs/epics, answer escalations, and
+        debug this instance. Point a coding agent at this URL to drive and debug the workforce.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The operator guide, with examples keyed to this instance.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentInstructions"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/convergence-loop:
     post:
       operationId: startConvergenceLoop

package/operations/getAgentInstructions.test.ts

@@ -0,0 +1,100 @@
+// Tests for GET /app/api/agent → operation `getAgentInstructions` (ADR 0058 OpenAPI surface).
+// The guide markdown is served as the `instructions` field with its examples keyed to the request's
+// control-API base + the configured engine base. Mirrors the getVersion test's request shape and
+// shared-secret guard pattern.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import handler from "./getAgentInstructions.ts";
+
+const app = {} as any as AppApi;
+
+function input(headers: Record<string, string> = {}, path = "/app/api/agent") {
+  return {
+    req: {
+      method: "GET",
+      path,
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+test("returns 200 with the markdown guide and metadata", async () => {
+  const r = (await handler(input(), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.format, "markdown");
+  assert("appVersion" in r.body); // nullable, but always present
+  assert(typeof r.body.generatedAt === "string" && r.body.generatedAt.length > 0);
+  assert(typeof r.body.baseUrl === "string" && r.body.baseUrl.length > 0);
+  assert(typeof r.body.engineBase === "string" && r.body.engineBase.length > 0);
+  assert(typeof r.body.instructions === "string" && r.body.instructions.length > 200);
+});
+
+test("the guide covers every capability the endpoint promises", async () => {
+  const md = ((await handler(input(), app)) as any).body.instructions as string;
+  // Submit a PR (converge vs. merge), submit an epic, answer escalations…
+  assert(md.includes("start/convergence-loop"), "covers submitting a PR for convergence");
+  assert(md.includes("convergeOnly"), "documents review-only vs. merge");
+  assert(md.includes("start/plan-fanout"), "covers submitting an epic");
+  assert(md.includes("escalation-answered"), "covers answering escalations");
+  // …debug the system.
+  assert(md.includes("/jobs/search") && md.includes("/incidents/search"), "covers engine REST debugging");
+  assert(md.includes("processKey") || md.includes("process_key"), "relates instances to PRs");
+  assert(md.includes("resources/processes") && md.includes("prompts/"), "covers debugging models + prompts");
+  assert(md.includes("nanobpm/nano-workforce"), "covers raising issues/PRs against the repo");
+});
+
+test("examples are keyed to the request's control-API base and leave no placeholders", async () => {
+  const forwarded = input({ host: "wf.example.com", "x-forwarded-proto": "https" });
+  const md = ((await handler(forwarded, app)) as any).body.instructions as string;
+  const body = (await handler(forwarded, app)) as any;
+  assertEquals(body.body.baseUrl, "https://wf.example.com/app/api");
+  assert(md.includes("https://wf.example.com/app/api/version"), "base URL substituted into examples");
+  assert(!md.includes("__BASE__"), "no unsubstituted __BASE__ placeholder");
+  assert(!md.includes("__ENGINE__"), "no unsubstituted __ENGINE__ placeholder");
+});
+
+test("x-forwarded-proto is restricted to http/https", async () => {
+  const spoofed = input({ host: "wf.example.com", "x-forwarded-proto": "javascript" });
+  const body = (await handler(spoofed, app)) as any;
+  assertEquals(body.body.baseUrl, "http://wf.example.com/app/api", "unsafe scheme falls back to http");
+});
+
+test("engine base follows CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL", async () => {
+  const prevCamunda = process.env["CAMUNDA_REST_ADDRESS"];
+  const prevBase = process.env["NANOBPMN_BASE_URL"];
+  try {
+    delete process.env["CAMUNDA_REST_ADDRESS"];
+    process.env["NANOBPMN_BASE_URL"] = "http://engine.internal:8080";
+    const r = (await handler(input(), app)) as any;
+    assertEquals(r.body.engineBase, "http://engine.internal:8080/v2");
+    assert(r.body.instructions.includes("http://engine.internal:8080/v2/jobs/search"));
+  } finally {
+    if (prevCamunda === undefined) delete process.env["CAMUNDA_REST_ADDRESS"];
+    else process.env["CAMUNDA_REST_ADDRESS"] = prevCamunda;
+    if (prevBase === undefined) delete process.env["NANOBPMN_BASE_URL"];
+    else process.env["NANOBPMN_BASE_URL"] = prevBase;
+  }
+});
+
+test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    // SECRET is bound at import time, so import a cache-busted copy to observe the guard.
+    const mod = await import(`./getAgentInstructions.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getAgentInstructions.ts

@@ -0,0 +1,52 @@
+// GET /app/api/agent → operationId `getAgentInstructions` (ADR 0058/0059 OpenAPI surface, base
+// /app/api). Serves the agent operator guide: how to submit a PR for convergence (review-only vs.
+// merge), submit an epic, answer escalations, and debug the system (find engine instances, relate
+// them to PRs, inspect the models/prompts, unstick stuck processes, and raise issues/PRs). A user
+// can point their coding agent at this URL and it can drive AND debug the workforce.
+//
+// The runtime serializes an operation body as JSON, so the markdown guide is returned as the
+// `instructions` string field (alongside the app version + the base URLs the examples are keyed
+// to), rather than as a raw text/markdown body. The embedded examples are rewritten to THIS
+// instance's control-API base (derived from the request) and engine base (from the environment).
+//
+// Read-only. The optional shared-secret guard mirrors /version: enforced HERE only when
+// NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
+
+import { renderAgentGuide, resolveEngineBase } from "../app/agentGuide.ts";
+import { buildVersionInfo, envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+/**
+ * Reconstruct the app control-API base the caller reached us on (e.g. "https://host/app/api"), so
+ * the guide's example commands are copy-pasteable. Honour reverse-proxy forwarding headers; fall
+ * back to a localhost default when the Host header is absent (e.g. a raw unit-test request).
+ */
+function resolveApiBase(req: { path: string; headers: Headers }): 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 op is mounted at "<base>/agent"; strip the trailing segment to recover the base path.
+  const basePath = req.path.replace(/\/agent\/?$/, "") || "/app/api";
+  return host ? `${proto}://${host}${basePath}` : `http://localhost:3000${basePath}`;
+}
+
+export default defineOperation("getAgentInstructions", ({ req }) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const baseUrl = resolveApiBase(req);
+  return {
+    status: 200,
+    body: {
+      format: "markdown",
+      appVersion: buildVersionInfo().version,
+      generatedAt: new Date().toISOString(),
+      baseUrl,
+      engineBase: resolveEngineBase(),
+      instructions: renderAgentGuide(baseUrl),
+    },
+  };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.40.1",
+  "version": "0.41.0",
   "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/agent-guide.md

@@ -0,0 +1,302 @@
+# Nano Workforce — agent operator guide
+
+You are an AI assistant helping a human operate a running **Nano Workforce**
+instance. Nano Workforce is a durable orchestration app (a [Nano](https://nanobpm.io)
+Urban app) that drives pull requests to **review convergence** against an automated
+reviewer, then **merges** them, and can take a whole issue and **plan → implement →
+converge** it across a fleet of coding agents.
+
+This document is served live by the running app so you always match the deployed
+version. Use it to **drive** the workforce (submit work, answer escalations) and to
+**debug** it (find stuck instances, relate them to PRs, inspect the models/prompts,
+and unstick or report problems).
+
+- **App control API base:** `__BASE__`
+- **Engine (Nano/Camunda-8 v2 REST) base:** `__ENGINE__`
+- **Source repository:** `nanobpm/nano-workforce`
+
+Everything below assumes the app control API is reachable at `__BASE__`. Most app
+endpoints are mounted under that base (ADR 0059), but a few siblings sit outside it —
+notably the interactive docs (Swagger UI) at `__BASE__/../api-docs` and the action
+endpoints (e.g. the cancel action at `/app/actions/cancel`). Paths below are written
+in full so you can tell which are under the control-API base and which are not.
+
+---
+
+## 0. Orient yourself first
+
+Before acting, confirm what is running and what is in flight:
+
+```bash
+# Which code is live (app version, urban version, git sha/branch, uptime):
+curl -sS __BASE__/version | jq
+
+# Every PR currently in flight (not converged/abandoned), with its engine
+# process key, status, round, and any open escalation:
+curl -sS __BASE__/status | jq
+```
+
+`/status` is your primary situational-awareness endpoint. Each entry carries:
+`prKey` (`owner/repo#123`), `status`, `round`, `processKey` (the **engine process
+instance key** — the bridge to the engine REST API, §5), `openEscalation`,
+`activeWorker`/`leaseUntil` (is an agent actually working the round, or is the job
+just queued), and `updatedAt`.
+
+---
+
+## 1. Submit a PR for review convergence
+
+One PR → one durable `convergence-loop`. Each round dispatches a `senior:pr-review`
+agent; between rounds the process parks on a durable message-catch, so review latency
+never holds an agent slot. The app's poller watches GitHub and republishes
+`review-ready` when a new review lands.
+
+```bash
+# Minimal: converge, then merge (if NANO_PR_AUTO_MERGE is on — the default).
+curl -sS -X POST __BASE__/actions/start/convergence-loop \
+  -H 'content-type: application/json' \
+  -d '{ "pr": "owner/repo#123" }'
+```
+
+The body is flat. Fields:
+
+| field | type | meaning |
+|---|---|---|
+| `pr` (or `url`) | string | the PR — `owner/repo#123` or a full PR URL. Required. |
+| `convergeOnly` | boolean | **`true` = review only.** The PR stops at `converged` and is **never** handed to the merge loop, even when `NANO_PR_AUTO_MERGE` is on. Omit / `false` = converge **then merge**. |
+| `maxRounds` | integer | per-submit cap before escalating (clamped 1–100; default from `NANO_PR_MAX_ROUNDS`, 20). |
+| `dependsOn` | string[] | other `prKey`s that must land before this one merges (merge-loop barrier). |
+
+**Converge-only vs. converge-and-merge — choose deliberately:**
+
+```bash
+# Review only — do NOT merge (use when the human wants to merge by hand,
+# or is only after a review pass):
+curl -sS -X POST __BASE__/actions/start/convergence-loop \
+  -H 'content-type: application/json' \
+  -d '{ "pr": "owner/repo#123", "convergeOnly": true }'
+
+# Converge then merge, with a dependency barrier and a tighter round cap:
+curl -sS -X POST __BASE__/actions/start/convergence-loop \
+  -H 'content-type: application/json' \
+  -d '{ "pr": "owner/repo#42", "maxRounds": 8, "dependsOn": ["owner/repo#40"] }'
+```
+
+Submitting is **idempotent on the PR key** — re-POSTing the same PR refreshes the
+aggregate rather than starting a duplicate loop. The response (202) echoes the
+`prKey` and the engine `processKey`.
+
+---
+
+## 2. Submit an epic (plan → implement → converge)
+
+Hand the fleet a whole issue. A planning agent decomposes it into levelized tasks; a
+parallel fan-out drives one implementation agent per task (one PR each); every opened
+PR is then enrolled into its own convergence loop (§1).
+
+```bash
+curl -sS -X POST __BASE__/actions/start/plan-fanout \
+  -H 'content-type: application/json' \
+  -d '{ "issue": "owner/repo#123" }'
+```
+
+The body is flat: `issue` (or `url`) — `owner/repo#123` or an issue URL. Starting a
+plan is idempotent on the plan key; an already-running plan short-circuits. The
+response (202) echoes the `planKey` and engine `processKey`.
+
+Track a plan the same way you track PRs — its `process_key` is an engine instance you
+can inspect in §5, and the PRs it opens show up in `/status` as ordinary convergence
+loops.
+
+---
+
+## 3. Answer escalations (unblock a human-in-the-loop wait)
+
+A loop escalates only when an agent returns `needs_input`/`blocked`, or a safety net
+fires (round cap, a review that never arrives, a merge conflict, an unfixable CI
+failure). The parked process waits for a human answer.
+
+Find the open escalations, then answer them:
+
+```bash
+# Which in-flight PRs have an open escalation waiting for a human?
+curl -sS __BASE__/status | jq '.prs[] | select(.openEscalation != null)
+  | { prKey, status, round, openEscalation }'
+```
+
+**Answer a PR/merge escalation** (convergence-loop or merge-loop). Use the message
+name `escalation-answered`; correlate by the PR key:
+
+```bash
+curl -sS -X POST __BASE__/actions/message \
+  -H 'content-type: application/json' \
+  -d '{
+        "name": "escalation-answered",
+        "correlationKey": "owner/repo#123",
+        "variables": { "answer": "Yes — cap the retries at 5 and proceed." }
+      }'
+```
+
+The answer is delivered to the agent as the `answer` variable on its next round, and
+the loop resumes.
+
+**Answer an implementation-phase (feature) task escalation** raised during a
+plan fan-out — a dedicated webhook operation:
+
+```bash
+curl -sS -X POST __BASE__/hooks/feature-answer \
+  -H 'content-type: application/json' \
+  -d '{ "correlationKey": "<task-or-pr-key>", "answer": "…" }'
+```
+
+If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
+
+Guidance for the human you assist: read the escalation `question` first (it is the
+exact blocker text the agent surfaced), decide the smallest unblocking answer, and
+answer it precisely — the answer becomes the agent's next-round context.
+
+---
+
+## 4. The lifecycle & statuses (so you can reason about state)
+
+```
+ submit ──► convergence-loop
+   round (senior:pr-review) ──► addressed ──► wait review-ready ─┐
+                             ├─ converged  ──► finalize ──► merge-loop (unless convergeOnly)
+                             └─ needs_input/blocked ──► escalate ──► wait escalation-answered
+ merge-loop: wait deps ─► arm merge ─► (queue-aware) merge / land
+             blocked (CI red) ─► senior:fix-ci ─► retry     conflict ─► senior:rebase ─► retry
+```
+
+PR `status` values you will see in `/status`:
+`converging` (a review round is live), `waiting_review` (parked for a fresh review),
+`escalated` (waiting on a human answer), `converged`, `waiting_deps` / `waiting_merge`
+/ `queued` / `merging` (merge stage), `merged`, `abandoned`. A separate
+`incident` signal (§5) can overlay any live status when the engine parks the token on
+a technical fault.
+
+---
+
+## 5. Debug: find engine instances and relate them to PRs
+
+The app stores each PR/plan's engine **process instance key** in its `process_key`
+column and surfaces it as `processKey` in `/status`. That key is the join between the
+app's business view and the engine's execution view.
+
+**Find the instance for a PR:** take `processKey` from `/status`, then query the
+engine's Camunda-8 v2 REST API:
+
+```bash
+PK=<processKey-from-status>
+
+# The instance itself (state, the BPMN process it is running, start time):
+curl -sS -X POST __ENGINE__/process-instances/search \
+  -H 'content-type: application/json' \
+  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\" } }" | jq
+
+# Where is it parked? — active jobs on the instance (a CREATED senior:pr-review job
+# with a `worker` set means an agent has leased the round; none means it is queued):
+curl -sS -X POST __ENGINE__/jobs/search \
+  -H 'content-type: application/json' \
+  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\", \"state\": \"CREATED\" } }" | jq
+
+# Is it dead-in-the-water on a technical fault? — active incidents:
+curl -sS -X POST __ENGINE__/incidents/search \
+  -H 'content-type: application/json' \
+  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\", \"state\": \"ACTIVE\" } }" | jq
+
+# What are the element/flow-node instances (which BPMN element is it sitting on)?
+curl -sS -X POST __ENGINE__/element-instances/search \
+  -H 'content-type: application/json' \
+  -d "{ \"filter\": { \"processInstanceKey\": \"$PK\" } }" | jq
+```
+
+The app already mirrors an ACTIVE incident onto the PR row (`incident`/incident
+message), so a PR that shows an incident in the UI is parked on an engine fault —
+inspect it with `incidents/search` above. If the engine is not at the default, the
+deployment's engine base is `__ENGINE__` (set via `NANOBPMN_BASE_URL` or
+`CAMUNDA_REST_ADDRESS`).
+
+**Relate an instance back to a PR:** if you have a `processKey` but not the PR, match
+it against `/status` (`.prs[] | select(.processKey == "<PK>")`). A terminal PR is no
+longer in `/status`; its instance has already completed or been cancelled.
+
+---
+
+## 6. Debug the models and the prompts
+
+The behaviour is defined by durable BPMN processes and model-authored agent prompts —
+both live in the source repo, not in the job payload.
+
+- **Processes:** `resources/processes/*.bpmn` — `convergence-loop.bpmn` (review),
+  `merge-loop.bpmn` (merge/CI-fix/rebase), `plan-fanout.bpmn` (planning),
+  `retro.bpmn`. These are the source of truth for routing. To understand *why* an
+  instance went where it did, read the gateway conditions (FEEL expressions on the
+  sequence flows) for the element it is parked on (§5).
+- **Prompts (agent base instructions):** `prompts/*.md` — `review-round.md`,
+  `plan.md`, `feature.md`, `fix-ci.md`, `rebase.md`, `trial-merge.md`, etc. An
+  agent's base prompt is **not** a job variable: it is delivered as a model
+  **template header** (`{{review-round}}`, `{{plan}}`, …) substituted from these files
+  at deploy time. If an agent misbehaves systematically, the prompt is the first thing
+  to inspect/fix.
+- **Job contract:** `senior:pr-review` receives `{ prUrl, repo, prNumber, round,
+  answer? }` and must return a flat result `{ status, summary, question? }` with
+  `status ∈ { converged, addressed, waiting, needs_input, blocked }`. A round that
+  pushes anything (including a rebase/force-push) is `addressed`; a round with an
+  unknown/empty result is treated as a safe `addressed` and re-enters the review wait
+  rather than escalating.
+
+To validate a model/prompt change locally: `npm run layout:check` (BPMN diagram
+freshness), `npm run check:prompts` (every template resolves), `npm run check`
+(manifest), `npm run typecheck`, `npm run lint`, `npm test`.
+
+---
+
+## 7. Unstick a stuck process
+
+Work through this order:
+
+1. **Confirm it is actually stuck.** From `/status`, a PR `converging` with an
+   `activeWorker` set is *working*, not stuck — an agent holds the round. No worker
+   for a long time means the job is queued: is a fleet `c8ctl nano work` daemon
+   running and subscribed to the `senior:*` task types?
+2. **Check for an incident** (§5). An ACTIVE incident parks the token; the underlying
+   fault must be resolved (or the instance cancelled and the work resubmitted). The
+   app surfaces the incident message on the PR row.
+3. **Check for an open escalation** (§3) — the process may simply be waiting for a
+   human answer. Answer it.
+4. **A review that never arrives** escalates on its own after
+   `NANO_PR_REVIEW_WAIT_TIMEOUT` (default `PT20M`); the poller also re-nudges the
+   reviewer periodically. If the reviewer bot is not provisioned on the repo, no
+   review will ever land — that is a repo-config problem, not an app bug.
+5. **Cancel + resubmit** as a last resort. Cancel the instance via the app (the UI's
+   per-row Cancel, `POST /app/actions/cancel { "processInstanceKey": "<PK>" }`), which
+   marks the PR `abandoned`, then re-submit the PR (§1) to start a fresh loop. Do not
+   cancel a raw engine instance out from under the app — go through the app so its
+   record state stays consistent.
+
+---
+
+## 8. Raise an issue or a PR against nano-workforce
+
+When you find a genuine bug or a missing capability in the orchestration itself
+(not a transient repo/agent problem), help the human file it against
+`nanobpm/nano-workforce`:
+
+- **Every change needs a tracked issue or PR** — no silent fixes. Open an issue
+  first if one does not exist.
+- **DCO is enforced:** every commit needs a `Signed-off-by` trailer — commit with
+  `git commit -s` (or `git rebase --signoff`).
+- **Work in a git worktree** off `origin/main`, on a `feat/*` or `fix/*` branch.
+- **Author the BPMN semantics, generate the diagram.** Never hand-edit the
+  `bpmndi:BPMNDiagram`; run `npm run layout <file.bpmn>` and commit the result. CI
+  fails on stale DI.
+- **Match the CI gates locally before pushing:** `npm run lint`, `npm run typecheck`,
+  `npm run check`, `npm run layout:check`, `npm run check:prompts`, `npm test`.
+- **Copilot code review is provisioned** — drive the PR to convergence against it.
+- Read `AGENTS.md` (engineering principles + gates) and `SPEC.md` (behavioural source
+  of truth) before proposing a change to a process.
+
+When describing the bug, include the concrete evidence you gathered here: the
+`prKey`, the engine `processKey`, the parked element / incident message (§5), and the
+BPMN/prompt file you believe is responsible (§6).

package/resources/processes/merge-loop.bpmn

@@ -18,6 +18,11 @@
       <zeebe:subscription correlationKey="=prKey" />
     </bpmn:extensionElements>
   </bpmn:message>
+  <bpmn:message id="Message_mergeEvicted" name="merge-evicted">
+    <bpmn:extensionElements>
+      <zeebe:subscription correlationKey="=prKey" />
+    </bpmn:extensionElements>
+  </bpmn:message>
   <bpmn:message id="Message_mergeEscAnswered" name="escalation-answered">
     <bpmn:extensionElements>
       <zeebe:subscription correlationKey="=prKey" />
@@ -109,6 +114,7 @@
       <bpmn:incoming>f_m_answer</bpmn:incoming>
       <bpmn:incoming>f_ci_fixed</bpmn:incoming>
       <bpmn:incoming>f_reb_rebased</bpmn:incoming>
+      <bpmn:incoming>f_m_evicted</bpmn:incoming>
       <bpmn:outgoing>f_m_arm</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:intermediateCatchEvent id="wait-mergeable" name="Wait: mergeable">
@@ -140,11 +146,21 @@
       <bpmn:outgoing>f_m_gQueued</bpmn:outgoing>
       <bpmn:outgoing>f_m_gBlocked</bpmn:outgoing>
     </bpmn:exclusiveGateway>
-    <bpmn:intermediateCatchEvent id="wait-landed" name="Wait: merge queue landed">
+    <bpmn:eventBasedGateway id="eg-landed" name="landed or evicted?">
       <bpmn:incoming>f_m_gQueued</bpmn:incoming>
+      <bpmn:outgoing>f_eg_landed</bpmn:outgoing>
+      <bpmn:outgoing>f_eg_evicted</bpmn:outgoing>
+    </bpmn:eventBasedGateway>
+    <bpmn:intermediateCatchEvent id="wait-landed" name="Wait: merge queue landed">
+      <bpmn:incoming>f_eg_landed</bpmn:incoming>
       <bpmn:outgoing>f_m_landed</bpmn:outgoing>
       <bpmn:messageEventDefinition id="med_mergeLanded" messageRef="Message_mergeLanded" />
     </bpmn:intermediateCatchEvent>
+    <bpmn:intermediateCatchEvent id="wait-evicted" name="Wait: evicted from queue">
+      <bpmn:incoming>f_eg_evicted</bpmn:incoming>
+      <bpmn:outgoing>f_m_evicted</bpmn:outgoing>
+      <bpmn:messageEventDefinition id="med_mergeEvicted" messageRef="Message_mergeEvicted" />
+    </bpmn:intermediateCatchEvent>
     <bpmn:serviceTask id="mark-merged" name="Mark merged">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.mark-merged" />
@@ -287,9 +303,12 @@
     <bpmn:sequenceFlow id="f_m_gMerged" name="merged" sourceRef="gw-merge" targetRef="mark-merged">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStatus = "merged"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
-    <bpmn:sequenceFlow id="f_m_gQueued" name="queued" sourceRef="gw-merge" targetRef="wait-landed">
+    <bpmn:sequenceFlow id="f_m_gQueued" name="queued" sourceRef="gw-merge" targetRef="eg-landed">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStatus = "queued"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_eg_landed" sourceRef="eg-landed" targetRef="wait-landed" />
+    <bpmn:sequenceFlow id="f_eg_evicted" sourceRef="eg-landed" targetRef="wait-evicted" />
+    <bpmn:sequenceFlow id="f_m_evicted" sourceRef="wait-evicted" targetRef="arm-merge" />
     <bpmn:sequenceFlow id="f_m_gBlocked" name="blocked" sourceRef="gw-merge" targetRef="merge-esc-attempt" />
     <bpmn:sequenceFlow id="f_m_landed" sourceRef="wait-landed" targetRef="mark-merged" />
     <bpmn:sequenceFlow id="f_m_done" sourceRef="mark-merged" targetRef="MergeEnd" />
@@ -332,49 +351,61 @@
       <bpmndi:BPMNShape id="BPMNShape_gw-merge" bpmnElement="gw-merge" isMarkerVisible="true">
         <dc:Bounds x="1063" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1062" y="62" width="53" height="28" />
+          <dc:Bounds x="1022" y="150" width="53" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_eg-landed" bpmnElement="eg-landed" isMarkerVisible="true">
+        <dc:Bounds x="1238" y="255" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1231" y="222" width="64" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-landed" bpmnElement="wait-landed">
-        <dc:Bounds x="1245" y="262" width="36" height="36" />
+        <dc:Bounds x="1420" y="262" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1221" y="229" width="85" height="28" />
+          <dc:Bounds x="1396" y="303" width="85" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_wait-evicted" bpmnElement="wait-evicted">
+        <dc:Bounds x="1420" y="422" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1394" y="375" width="88" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_mark-merged" bpmnElement="mark-merged">
-        <dc:Bounds x="1388" y="80" width="100" height="80" />
+        <dc:Bounds x="1588" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_MergeEnd" bpmnElement="MergeEnd">
-        <dc:Bounds x="1588" y="102" width="36" height="36" />
+        <dc:Bounds x="1788" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1581" y="143" width="50" height="14" />
+          <dc:Bounds x="1781" y="143" width="50" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-conflict" bpmnElement="merge-esc-conflict">
-        <dc:Bounds x="1038" y="560" width="100" height="80" />
+        <dc:Bounds x="1038" y="720" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-attempt" bpmnElement="merge-esc-attempt">
-        <dc:Bounds x="1388" y="400" width="100" height="80" />
+        <dc:Bounds x="1388" y="560" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-merge-answer" bpmnElement="wait-merge-answer">
-        <dc:Bounds x="1588" y="422" width="36" height="36" />
+        <dc:Bounds x="1620" y="582" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1649" y="463" width="74" height="42" />
+          <dc:Bounds x="1661" y="579" width="74" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-ci-fix" bpmnElement="gw-ci-fix" isMarkerVisible="true">
-        <dc:Bounds x="863" y="575" width="50" height="50" />
+        <dc:Bounds x="863" y="735" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="844" y="556" width="89" height="14" />
+          <dc:Bounds x="844" y="716" width="89" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_fix-ci" bpmnElement="fix-ci">
-        <dc:Bounds x="1038" y="720" width="100" height="80" />
+        <dc:Bounds x="1038" y="880" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-ci-result" bpmnElement="gw-ci-result" isMarkerVisible="true">
-        <dc:Bounds x="1238" y="735" width="50" height="50" />
+        <dc:Bounds x="1238" y="895" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1240" y="716" width="46" height="14" />
+          <dc:Bounds x="1240" y="876" width="46" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-rebase" bpmnElement="gw-rebase" isMarkerVisible="true">
@@ -384,12 +415,12 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_rebase" bpmnElement="rebase">
-        <dc:Bounds x="1038" y="880" width="100" height="80" />
+        <dc:Bounds x="1038" y="1040" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-rebase-result" bpmnElement="gw-rebase-result" isMarkerVisible="true">
-        <dc:Bounds x="1238" y="895" width="50" height="50" />
+        <dc:Bounds x="1238" y="1055" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1233" y="876" width="60" height="14" />
+          <dc:Bounds x="1233" y="1036" width="60" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_start" bpmnElement="f_m_start">
@@ -421,69 +452,78 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_gMerged" bpmnElement="f_m_gMerged">
         <di:waypoint x="1113" y="120" />
-        <di:waypoint x="1388" y="120" />
+        <di:waypoint x="1588" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1216" y="98" width="49" height="14" />
+          <dc:Bounds x="1326" y="98" width="49" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_done" bpmnElement="f_m_done">
-        <di:waypoint x="1488" y="120" />
-        <di:waypoint x="1588" y="120" />
+        <di:waypoint x="1688" y="120" />
+        <di:waypoint x="1788" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_giveup" bpmnElement="f_ci_giveup">
-        <di:waypoint x="913" y="600" />
-        <di:waypoint x="1038" y="600" />
+        <di:waypoint x="913" y="760" />
+        <di:waypoint x="1038" y="760" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="942" y="605" width="67" height="28" />
+          <dc:Bounds x="942" y="765" width="67" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_blocked" bpmnElement="f_ci_blocked">
-        <di:waypoint x="1288" y="760" />
-        <di:waypoint x="1438" y="760" />
-        <di:waypoint x="1438" y="480" />
+        <di:waypoint x="1288" y="920" />
+        <di:waypoint x="1438" y="920" />
+        <di:waypoint x="1438" y="640" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1319" y="738" width="89" height="14" />
+          <dc:Bounds x="1319" y="898" width="89" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_giveup" bpmnElement="f_reb_giveup">
         <di:waypoint x="913" y="280" />
         <di:waypoint x="1088" y="280" />
-        <di:waypoint x="1088" y="560" />
+        <di:waypoint x="1088" y="720" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="977" y="247" width="67" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_blocked" bpmnElement="f_reb_blocked">
-        <di:waypoint x="1288" y="920" />
-        <di:waypoint x="1438" y="920" />
-        <di:waypoint x="1438" y="480" />
+        <di:waypoint x="1288" y="1080" />
+        <di:waypoint x="1438" y="1080" />
+        <di:waypoint x="1438" y="640" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1331" y="887" width="64" height="28" />
+          <dc:Bounds x="1331" y="1047" width="64" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_eg_landed" bpmnElement="f_eg_landed">
+        <di:waypoint x="1288" y="280" />
+        <di:waypoint x="1420" y="280" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_landed" bpmnElement="f_m_landed">
+        <di:waypoint x="1456" y="280" />
+        <di:waypoint x="1638" y="280" />
+        <di:waypoint x="1638" y="160" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escC" bpmnElement="f_m_escC">
-        <di:waypoint x="1138" y="580" />
-        <di:waypoint x="1158" y="580" />
-        <di:waypoint x="1158" y="380" />
-        <di:waypoint x="1606" y="380" />
-        <di:waypoint x="1606" y="422" />
+        <di:waypoint x="1138" y="740" />
+        <di:waypoint x="1158" y="740" />
+        <di:waypoint x="1158" y="540" />
+        <di:waypoint x="1638" y="540" />
+        <di:waypoint x="1638" y="582" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escA" bpmnElement="f_m_escA">
-        <di:waypoint x="1488" y="440" />
-        <di:waypoint x="1588" y="440" />
+        <di:waypoint x="1488" y="600" />
+        <di:waypoint x="1620" y="600" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_answer" bpmnElement="f_m_answer">
-        <di:waypoint x="1606" y="458" />
-        <di:waypoint x="1606" y="500" />
-        <di:waypoint x="402" y="500" />
+        <di:waypoint x="1638" y="618" />
+        <di:waypoint x="1638" y="660" />
+        <di:waypoint x="402" y="660" />
         <di:waypoint x="402" y="160" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_mCiFix" bpmnElement="f_m_mCiFix">
         <di:waypoint x="713" y="145" />
-        <di:waypoint x="713" y="600" />
-        <di:waypoint x="863" y="600" />
+        <di:waypoint x="713" y="760" />
+        <di:waypoint x="863" y="760" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="718" y="438" width="60" height="42" />
+          <dc:Bounds x="718" y="518" width="60" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_mRebase" bpmnElement="f_m_mRebase">
@@ -498,18 +538,18 @@
         <di:waypoint x="713" y="145" />
         <di:waypoint x="713" y="318" />
         <di:waypoint x="1018" y="318" />
-        <di:waypoint x="1018" y="580" />
-        <di:waypoint x="1038" y="580" />
+        <di:waypoint x="1018" y="740" />
+        <di:waypoint x="1038" y="740" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="823" y="326" width="85" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_go" bpmnElement="f_ci_go">
-        <di:waypoint x="888" y="625" />
-        <di:waypoint x="888" y="760" />
-        <di:waypoint x="1038" y="760" />
+        <di:waypoint x="888" y="785" />
+        <di:waypoint x="888" y="920" />
+        <di:waypoint x="1038" y="920" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="893" y="679" width="49" height="28" />
+          <dc:Bounds x="893" y="839" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_go" bpmnElement="f_reb_go">
@@ -517,8 +557,8 @@
         <di:waypoint x="933" y="280" />
         <di:waypoint x="933" y="305" />
         <di:waypoint x="1158" y="305" />
-        <di:waypoint x="1158" y="920" />
-        <di:waypoint x="1138" y="920" />
+        <di:waypoint x="1158" y="1080" />
+        <di:waypoint x="1138" y="1080" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="1101" y="310" width="49" height="28" />
         </bpmndi:BPMNLabel>
@@ -526,60 +566,64 @@
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_gQueued" bpmnElement="f_m_gQueued">
         <di:waypoint x="1088" y="145" />
         <di:waypoint x="1088" y="280" />
-        <di:waypoint x="1245" y="280" />
+        <di:waypoint x="1238" y="280" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="1093" y="206" width="46" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_eg_evicted" bpmnElement="f_eg_evicted">
+        <di:waypoint x="1263" y="305" />
+        <di:waypoint x="1263" y="440" />
+        <di:waypoint x="1420" y="440" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_gBlocked" bpmnElement="f_m_gBlocked">
-        <di:waypoint x="1113" y="120" />
-        <di:waypoint x="1368" y="120" />
-        <di:waypoint x="1368" y="440" />
-        <di:waypoint x="1388" y="440" />
+        <di:waypoint x="1088" y="95" />
+        <di:waypoint x="1088" y="75" />
+        <di:waypoint x="1844" y="75" />
+        <di:waypoint x="1844" y="478" />
+        <di:waypoint x="1368" y="478" />
+        <di:waypoint x="1368" y="580" />
+        <di:waypoint x="1388" y="580" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1373" y="273" width="53" height="14" />
+          <dc:Bounds x="1849" y="270" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_done" bpmnElement="f_ci_done">
-        <di:waypoint x="1138" y="760" />
-        <di:waypoint x="1238" y="760" />
+        <di:waypoint x="1138" y="920" />
+        <di:waypoint x="1238" y="920" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_done" bpmnElement="f_reb_done">
-        <di:waypoint x="1138" y="940" />
-        <di:waypoint x="1158" y="940" />
-        <di:waypoint x="1158" y="965" />
-        <di:waypoint x="1238" y="965" />
-        <di:waypoint x="1263" y="965" />
-        <di:waypoint x="1263" y="945" />
-      </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_m_landed" bpmnElement="f_m_landed">
-        <di:waypoint x="1263" y="298" />
-        <di:waypoint x="1263" y="318" />
-        <di:waypoint x="1281" y="318" />
-        <di:waypoint x="1281" y="540" />
-        <di:waypoint x="1644" y="540" />
-        <di:waypoint x="1644" y="180" />
-        <di:waypoint x="1468" y="180" />
-        <di:waypoint x="1468" y="160" />
+        <di:waypoint x="1138" y="1100" />
+        <di:waypoint x="1158" y="1100" />
+        <di:waypoint x="1158" y="1125" />
+        <di:waypoint x="1238" y="1125" />
+        <di:waypoint x="1263" y="1125" />
+        <di:waypoint x="1263" y="1105" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_fixed" bpmnElement="f_ci_fixed">
-        <di:waypoint x="1263" y="785" />
-        <di:waypoint x="1263" y="820" />
-        <di:waypoint x="402" y="820" />
+        <di:waypoint x="1263" y="945" />
+        <di:waypoint x="1263" y="980" />
+        <di:waypoint x="402" y="980" />
         <di:waypoint x="402" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="813" y="798" width="39" height="14" />
+          <dc:Bounds x="813" y="958" width="39" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_rebased" bpmnElement="f_reb_rebased">
-        <di:waypoint x="1263" y="945" />
-        <di:waypoint x="1263" y="980" />
-        <di:waypoint x="402" y="980" />
+        <di:waypoint x="1263" y="1105" />
+        <di:waypoint x="1263" y="1140" />
+        <di:waypoint x="402" y="1140" />
         <di:waypoint x="402" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="806" y="958" width="53" height="14" />
+          <dc:Bounds x="806" y="1118" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_evicted" bpmnElement="f_m_evicted">
+        <di:waypoint x="1438" y="458" />
+        <di:waypoint x="1438" y="478" />
+        <di:waypoint x="402" y="478" />
+        <di:waypoint x="402" y="160" />
+      </bpmndi:BPMNEdge>
     </bpmndi:BPMNPlane>
   </bpmndi:BPMNDiagram>
 </bpmn:definitions>