@nanobpm/nano-workforce 0.114.1 → 0.116.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.116.0](https://github.com/nanobpm/nano-workforce/compare/v0.115.0...v0.116.0) (2026-08-20)
+
+
+### Features
+
+* replace deterministic scope regex with a scope-integrity agent classifier ([#403](https://github.com/nanobpm/nano-workforce/issues/403)) ([588b869](https://github.com/nanobpm/nano-workforce/commit/588b8699ea738ff0772f23d68bc051e8ff417d49)), closes [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [398/#399](https://github.com/nanobpm/nano-workforce/issues/399) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395)
+
+# [0.115.0](https://github.com/nanobpm/nano-workforce/compare/v0.114.1...v0.115.0) (2026-08-20)
+
+
+### Features
+
+* **engine:** startup preflight + canonical engine address resolution ([#391](https://github.com/nanobpm/nano-workforce/issues/391)) ([#404](https://github.com/nanobpm/nano-workforce/issues/404)) ([16fcb71](https://github.com/nanobpm/nano-workforce/commit/16fcb711f190341f03fd84914fa66c1ee704b78c)), closes [Magikcraft/nano-bpm#940](https://github.com/Magikcraft/nano-bpm/issues/940)
+
 ## [0.114.1](https://github.com/nanobpm/nano-workforce/compare/v0.114.0...v0.114.1) (2026-08-20)
 
 

package/README.md

@@ -252,7 +252,7 @@ active epic already targets the same custom base. See
 |---|---|---|
 | `PR_REVIEW_PORT` | `3000` | app HTTP port |
 | `NANO_APP_DB_URL` | `file:./app.db` | sqlite datasource |
-| `NANOBPMN_BASE_URL` | `http://localhost:8080` | engine base URL (or set `CAMUNDA_REST_ADDRESS` to the `/v2` REST address directly) |
+| `NANOBPMN_BASE_URL` | `http://localhost:8080` | engine base URL (or set `CAMUNDA_REST_ADDRESS` to the `/v2` REST address directly). See [Engine address & the startup preflight](#engine-address--the-startup-preflight) |
 | `GITHUB_TOKEN` | — | token for the review poller / merge (or use the host `gh` CLI) |
 | `NANO_PR_GITHUB_TRANSPORT` | `auto` | how the poller reads GitHub: `gh` (host CLI), `token` (`GITHUB_TOKEN` over HTTP), or `auto` |
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
@@ -267,6 +267,49 @@ active epic already targets the same custom base. See
 | `NANO_WORKFORCE_BASE_URL` | `http://localhost:3000` | externally-reachable base URL for the capability hooks (`/app/api/hooks/*`). Must resolve from **wherever the agent runs** — set it to the app's LAN address (or console-proxy URL) for a remote fleet. See [Fleet networking](#fleet-networking-remote-workers) |
 | `NANO_AGENTIC_SECRET` | — | enables **secure mode** for the agentic visibility channel (`/agentic`): every peer must present the **same** `NANO_AGENTIC_SECRET` value (set the identical env var on the server and every worker box — Tab A → Slot A). Unset = on-by-default **LOCAL mode** — the well-known token is honoured from **any origin** (open on the trusted LAN, matching the engine's posture); exposure is governed by the server bind address, not a shared secret. Also accepts `NANO_PR_WEBHOOK_SECRET` |
 
+### Engine address & the startup preflight
+
+The app talks to one engine over the Camunda 8 REST API. The REST address is
+resolved with a fixed precedence — set **one** of:
+
+1. **`CAMUNDA_REST_ADDRESS`** — used verbatim (it already points at the `/v2`
+   REST address, e.g. `http://engine.example:8080/v2`). **Wins** if set.
+2. **`NANOBPMN_BASE_URL`** — the engine *base*; the app appends `/v2`
+   (e.g. `http://localhost:7000` → `http://localhost:7000/v2`).
+3. Neither set → the base defaults to **`http://localhost:8080`**.
+
+At boot the app **echoes the resolved address and which input it came from**,
+then probes `/v2/topology` and announces **which engine answered** — so a
+misconfigured address is obvious immediately instead of surfacing later as a
+cryptic mid-run engine error:
+
+```
+Engine address: http://localhost:8080/v2 (from default (http://localhost:8080))
+Engine: Nano engine (nanobpmn v0.114.1) — Falcon streaming at /falcon at http://localhost:8080/v2.
+```
+
+The preflight is **informational, never a gate** — Nano Workforce runs against a
+stock **Camunda 8** cluster too, so a non-Nano engine is announced
+(`Engine: Camunda 8 (gateway v8.x) — REST only …`), not rejected. If nothing
+answers, it logs a `warn` (`could not reach … features will fail to start until
+the engine is reachable`) and boot continues. On a **secured** cluster the probe
+sends `CAMUNDA_TOKEN` as a bearer credential; a `401/403` is reported as an auth
+hint (check `CAMUNDA_TOKEN`), not as an unreachable engine.
+
+> **Watch the port when launched from a console.** A console-launched app can
+> default `NANOBPMN_BASE_URL` to `http://localhost:8080`. If **another Camunda 8**
+> is already on `:8080`, the app will talk to *that* engine (it works — C8 is
+> supported), which may not be the engine you intended. Check the startup
+> `Engine:` line; to target a Nano engine on a different port, set
+> `NANOBPMN_BASE_URL` (or `CAMUNDA_REST_ADDRESS`) explicitly.
+>
+> When the app *can't* work against the reached engine you'll see a job/instance
+> decode error at first feature start — `MalformedFrameError` / `MalformedJobError`
+> (Falcon) or the Camunda REST client's own `4xx` (older versions surfaced
+> `engine response missing processInstanceKey/key`). The startup `Engine:` line
+> tells you which engine you actually reached, before any such error.
+
+
 ### Fleet networking (remote workers)
 
 `nano-workforce` can drive a **distributed worker fleet** — `senior:*` agents running on other LAN

package/app/agentic/vocab/demand-report.ts

@@ -20,6 +20,7 @@ import {
 import type { RegisteredWorker } from "@nanobpm/agentic/vocab";
 import type { Logger } from "@nanobpm/urban";
 import type { RegistryReport as WireRegistryReport } from "../../../nano-generated/api-io.d.ts";
+import { resolveEngineAddress } from "../../enginePreflight.ts";
 import { envVar } from "../../version.ts";
 import { currentPresenceRegistry } from "../families/presence.family.ts";
 import { CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
@@ -40,17 +41,14 @@ export interface RegistryReport extends DemandSupplyReport {
 }
 
 /**
- * Derive the engine's C8 v2 REST base the demand reader targets — the same precedence/derivation
- * `main.ts` uses: an explicit `CAMUNDA_REST_ADDRESS` wins, else it is derived from `NANOBPMN_BASE_URL`
- * (+ `/v2`), defaulting to `http://localhost:8080/v2`. Read through the declared env schema (ADR 0004).
- * (This reader additionally strips trailing slashes off an explicit `CAMUNDA_REST_ADDRESS`, which
- * `main.ts` does not, so the derived base is well-formed regardless of a trailing `/`.)
+ * Derive the engine's C8 v2 REST base the demand reader targets. Delegates to
+ * the canonical {@link resolveEngineAddress} (the single source of truth shared
+ * with `main.ts`) so the precedence — explicit `CAMUNDA_REST_ADDRESS` wins, else
+ * `NANOBPMN_BASE_URL` (+ `/v2`), defaulting to `http://localhost:8080/v2` — lives
+ * in one place and cannot drift between call sites.
  */
 export function engineRestAddress(): string {
-  const explicit = envVar("CAMUNDA_REST_ADDRESS")?.replace(/\/+$/, "");
-  if (explicit) return explicit;
-  const base = (envVar("NANOBPMN_BASE_URL") ?? "http://localhost:8080").replace(/\/+$/, "");
-  return `${base}/v2`;
+  return resolveEngineAddress().restAddress;
 }
 
 /** The live supply rows (`{ instance, capability }`) from the H1 presence registry, or none when unmounted. */

package/app/convergeGate.test.ts

@@ -217,15 +217,9 @@ test("pickLatestCopilotReviewBody: FAILS CLOSED (null) when the reviews read was
 async function makeUnderTest(deps: {
   readThreads: (repo: string, n: number) => Promise<ReviewThread[] | null>;
   readReviewBody: (repo: string, n: number) => Promise<string | null>;
-  readPrBody?: (repo: string, n: number) => Promise<string | null>;
-  readHeadSha?: (repo: string, n: number) => Promise<string | null>;
 }) {
   const { makeHandler } = await import("../workers/converge-gate/worker.ts");
-  // Default the scope-guard PR-body read to a verified-empty description so the comment-gate tests
-  // below exercise only the review-comment dimension; scope-guard tests pass an explicit body. The
-  // HEAD read defaults to null (unreadable) so a scope block stays blocked unless a test opts into
-  // the #395 override door with an explicit HEAD — see workers/converge-gate/worker.test.ts.
-  return makeHandler({ readPrBody: async () => "", readHeadSha: async () => null, ...deps });
+  return makeHandler(deps);
 }
 
 test("converge-gate: a clean PR is allowed to converge", async () => {
@@ -348,82 +342,6 @@ test("converge-gate: resolves repo/prNumber from the prKey when the vars are abs
   assertEquals(seen, ["o/r", 7]);
 });
 
-// ── The scope-integrity guard through the worker (#313) ─────────────────────
-
-test("converge-gate: a partial delivery that Closes a broader-scoped parent blocks convergence", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [],
-    readReviewBody: async () => "",
-    readPrBody: async () =>
-      "Delivers the nested ad-hoc half.\n\n## Scope\nEmbedded SUB_PROCESS tools remain the deferred refinement.\n\nCloses #631",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "Scope integrity blocked");
-  assertStringIncludes(out.convergeBlockReason ?? "", "#631");
-});
-
-test("converge-gate: a deferral with a filed follow-up issue and a non-closing ref converges", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [],
-    readReviewBody: async () => "",
-    readPrBody: async () =>
-      "Delivers the nested ad-hoc half.\n\n## Scope\nEmbedded SUB_PROCESS tools are deferred.\nTracked-in: #872\n\nRefs #631",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
-});
-
-test("converge-gate: a full-scope Closes PR with no deferral prose converges", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [],
-    readReviewBody: async () => "",
-    readPrBody: async () => "Implements the feature end to end.\n\nCloses #313",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
-});
-
-test("converge-gate: a scope block and a comment block are reported together", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [{ isResolved: false, path: "a.ts", bodies: ["please fix"] }],
-    readReviewBody: async () => "",
-    readPrBody: async () => "Ships one half.\n\nDeferred: the rest.\n\nCloses #631",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "unresolved review thread");
-  assertStringIncludes(out.convergeBlockReason ?? "", "Scope integrity blocked");
-});
-
-test("converge-gate: FAILS CLOSED when the PR-body read returns null (no transport)", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
-    readReviewBody: async () => "",
-    readPrBody: async () => null,
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "could not read the PR description");
-});
-
-test("converge-gate: FAILS CLOSED with the SCOPE reason when the PR-body read throws", async () => {
-  // A transport failure while reading/parsing the PR body is a scope-integrity read failure, not a
-  // review-comment verification failure: it must surface BLOCK_UNVERIFIABLE_BODY, not the generic
-  // review-comment BLOCK_UNVERIFIABLE — otherwise the human escalation is pointed at review threads
-  // when the real problem is the PR description could not be read.
-  const handler = await makeUnderTest({
-    readThreads: async () => [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
-    readReviewBody: async () => "",
-    readPrBody: async () => {
-      throw new Error("boom");
-    },
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "could not read the PR description");
-});
-
 // ── Structural guard over the committed BPMN (no engine) ─────────────────────
 
 const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
@@ -460,16 +378,108 @@ test("gw-converge-gate blocks on an explicit convergeBlocked = true condition",
   assertStringIncludes(f, "convergeBlocked = true");
 });
 
-test("gw-converge-gate default arm finalizes with no condition", () => {
+test("gw-converge-gate default arm routes to the scope classifier (not straight to finalize)", () => {
   const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-converge-gate"[^>]*>/);
   assert(gw, "gw-converge-gate gateway missing");
   assertStringIncludes(gw[0], 'default="f_convergeOk"');
   const ok = flowElement("f_convergeOk");
   assert(ok, "f_convergeOk flow missing");
+  assertStringIncludes(ok, 'targetRef="classify-scope"');
+  assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
+});
+
+// ── The scope classifier (agent task) replaces the deterministic scope regex ──
+
+test("classify-scope is an agent task servicing senior:scope-classify with a linked prompt", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="classify-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "classify-scope service task missing");
+  assertStringIncludes(task[0], 'type="senior:scope-classify"');
+  assertStringIncludes(task[0], 'resourceId="scope-classify.md"');
+  assertStringIncludes(task[0], 'linkName="prompt"');
+  // After honouring (or ignoring) the human's scope answer, it clears the one-shot
+  // scopeAnswer so a later round does not re-honour a stale decision.
+  assertStringIncludes(task[0], 'source="=null" target="scopeAnswer"');
+});
+
+// ── The scope-answer plumbing (#395 loop-defect fix) ─────────────────────────
+// review-round clears `answer` on every round, so a human's scope answer cannot reach
+// the downstream classify-scope via `answer`. A dedicated `scopeAnswer` variable, gated
+// by a `scopePending` marker, carries the decision across the review round without being
+// confused with answers to other escalation kinds.
+
+test("PrScopeClassifyIn feeds the classifier the surviving scopeAnswer, not the cleared answer", () => {
+  const shape = flat.match(/<nano:shape\b[^>]*\bid="PrScopeClassifyIn"[^>]*>.*?<\/nano:shape>/);
+  assert(shape, "PrScopeClassifyIn envelope missing");
+  assertStringIncludes(shape[0], 'name="scopeAnswer"');
+  assert(!/name="answer"/.test(shape[0]), "classifier must read scopeAnswer, not the shared answer");
+});
+
+test("PrScopeClassifyOut.scopeBlockReason is required (always emitted, empty when not blocked)", () => {
+  const shape = flat.match(/<nano:shape\b[^>]*\bid="PrScopeClassifyOut"[^>]*>.*?<\/nano:shape>/);
+  assert(shape, "PrScopeClassifyOut envelope missing");
+  assert(
+    /name="scopeBlockReason"(?![^>]*optional)/.test(shape[0]),
+    "scopeBlockReason must not be optional — the wire contract requires it always present",
+  );
+});
+
+test("persist-escalation-scope marks the open escalation as scope-kind (scopePending = true)", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="persist-escalation-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "persist-escalation-scope task missing");
+  assertStringIncludes(task[0], 'source="=true" target="scopePending"');
+});
+
+test("record-answer captures a scope answer into scopeAnswer only while scopePending", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="record-answer"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "record-answer task missing");
+  // Capture is gated on scopePending so an answer to a *different* escalation is not
+  // mis-read as a scope override; otherwise scopeAnswer is preserved.
+  assertStringIncludes(
+    task[0],
+    'source="=(if scopePending = true then answer else scopeAnswer)" target="scopeAnswer"',
+  );
+});
+
+test("review-round resets the scopePending marker after record-answer has consumed it", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="review-round"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "review-round task missing");
+  assertStringIncludes(task[0], 'source="=false" target="scopePending"');
+});
+
+test("classify-scope feeds gw-scope-gate, which blocks on scopeBlocked = true", () => {
+  const toGate = flowElement("f_toScopeGate");
+  assert(toGate, "f_toScopeGate flow missing");
+  assertStringIncludes(toGate, 'sourceRef="classify-scope"');
+  assertStringIncludes(toGate, 'targetRef="gw-scope-gate"');
+  const blocked = flowElement("f_scopeBlocked");
+  assert(blocked, "f_scopeBlocked flow missing");
+  assertStringIncludes(blocked, 'targetRef="persist-escalation-scope"');
+  assertStringIncludes(blocked, "scopeBlocked = true");
+});
+
+test("gw-scope-gate default arm finalizes (scope ok → persist-converged)", () => {
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-scope-gate"[^>]*>/);
+  assert(gw, "gw-scope-gate gateway missing");
+  assertStringIncludes(gw[0], 'default="f_scopeOk"');
+  const ok = flowElement("f_scopeOk");
+  assert(ok, "f_scopeOk flow missing");
   assertStringIncludes(ok, 'targetRef="persist-converged"');
   assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
 });
 
+test("the scope escalation routes through gw-escalated with the classifier's specific reason", () => {
+  const f = flowElement("f_scopeEscGate");
+  assert(f, "f_scopeEscGate flow missing");
+  assertStringIncludes(f, 'sourceRef="persist-escalation-scope"');
+  assertStringIncludes(f, 'targetRef="gw-escalated"');
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="persist-escalation-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "persist-escalation-scope task missing");
+  assertStringIncludes(task[0], 'type="pr.persist-escalation"');
+  assertStringIncludes(task[0], 'target="question"');
+  // The human sees the classifier's specific finding, not a generic boilerplate reason.
+  assertStringIncludes(task[0], "scopeBlockReason");
+});
+
 test("the blocked-comments escalation routes through gw-escalated toward an answerable wait-answer", () => {
   // #333: previously this flowed UNCONDITIONALLY into wait-answer, so a blank convergeBlockReason
   // (the question is mapped from that OPTIONAL variable) opened no escalation yet still parked a

package/app/enginePreflight.test.ts

@@ -0,0 +1,122 @@
+// Tests for engine address resolution + the startup preflight (nano-workforce#391).
+//
+// The resolver and the identity description are pure (an injectable env reader /
+// a plain topology body), and the preflight takes an injectable `fetch`, so none
+// of this needs a live engine or `process.env` mutation.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  announceEngine,
+  describeEngine,
+  type EngineAddress,
+  resolveEngineAddress,
+  type TopologyProbe,
+} from "./enginePreflight.ts";
+
+const reader = (vars: Record<string, string>) => (name: string): string | null => vars[name] ?? null;
+
+test("resolveEngineAddress honours an explicit CAMUNDA_REST_ADDRESS and strips trailing slashes", () => {
+  const addr = resolveEngineAddress(reader({ CAMUNDA_REST_ADDRESS: "http://engine.example:8080/v2///" }));
+  assertEquals(addr, { restAddress: "http://engine.example:8080/v2", source: "CAMUNDA_REST_ADDRESS" });
+});
+
+test("resolveEngineAddress derives /v2 from NANOBPMN_BASE_URL when no explicit address", () => {
+  const addr = resolveEngineAddress(reader({ NANOBPMN_BASE_URL: "http://engine.example:7000//" }));
+  assertEquals(addr, { restAddress: "http://engine.example:7000/v2", source: "NANOBPMN_BASE_URL" });
+});
+
+test("resolveEngineAddress defaults to localhost:8080 and labels the source as the default", () => {
+  const addr = resolveEngineAddress(reader({}));
+  assertEquals(addr, { restAddress: "http://localhost:8080/v2", source: "default (http://localhost:8080)" });
+});
+
+test("describeEngine reports a Nano engine from the `nano` marker", () => {
+  const line = describeEngine({ nano: { engine: "nanobpmn", version: "0.114.1", falconPath: "/falcon" } });
+  assert(line.includes("Nano engine (nanobpmn v0.114.1)"), "names the nano engine + version");
+  assert(line.includes("/falcon"), "mentions the Falcon path");
+});
+
+test("describeEngine reports Camunda 8 (never rejects) when the `nano` marker is absent", () => {
+  const line = describeEngine({ gatewayVersion: "8.6.0" });
+  assert(line.startsWith("Camunda 8"), "identifies Camunda 8");
+  assert(line.includes("8.6.0"), "surfaces the gateway version");
+  assert(line.includes("REST only"), "notes Falcon is unavailable");
+});
+
+test("describeEngine tolerates an empty / missing body", () => {
+  assert(describeEngine(null).startsWith("Camunda 8"), "null body degrades to Camunda 8");
+  assert(describeEngine({}).startsWith("Camunda 8"), "empty body degrades to Camunda 8");
+});
+
+// --- announceEngine (injected fetch; never throws) ---
+
+const ADDR: EngineAddress = { restAddress: "http://localhost:8080/v2", source: "default (http://localhost:8080)" };
+
+function capture() {
+  const info: string[] = [];
+  const warn: string[] = [];
+  return { log: { info: (m: string) => info.push(m), warn: (m: string) => warn.push(m) }, info, warn };
+}
+
+const okResponse = (body: TopologyProbe) =>
+  ({ ok: true, status: 200, json: () => Promise.resolve(body) }) as unknown as Response;
+
+test("announceEngine logs the resolved address + a Nano identity line", async () => {
+  const { log, info, warn } = capture();
+  let probed = "";
+  await announceEngine(ADDR, log, {
+    fetchImpl: ((url: string) => {
+      probed = url;
+      return Promise.resolve(okResponse({ nano: { engine: "nanobpmn", version: "1.2.3", falconPath: "/falcon" } }));
+    }) as unknown as typeof fetch,
+  });
+  assertEquals(probed, "http://localhost:8080/v2/topology");
+  assert(info.some((l) => l.includes("Engine address: http://localhost:8080/v2 (from default")), "echoes address+source");
+  assert(info.some((l) => l.includes("Nano engine (nanobpmn v1.2.3)")), "announces the Nano engine");
+  assertEquals(warn, []);
+});
+
+test("announceEngine announces Camunda 8 without rejecting", async () => {
+  const { log, info, warn } = capture();
+  await announceEngine(ADDR, log, {
+    fetchImpl: (() => Promise.resolve(okResponse({ gatewayVersion: "8.6.0" }))) as unknown as typeof fetch,
+  });
+  assert(info.some((l) => l.includes("Camunda 8")), "announces Camunda 8");
+  assertEquals(warn, []);
+});
+
+test("announceEngine sends CAMUNDA_TOKEN as a bearer credential on the probe", async () => {
+  const { log } = capture();
+  let sentAuth: string | undefined;
+  await announceEngine(ADDR, log, {
+    token: "secret-token",
+    fetchImpl: ((_url: string, init: { headers: Record<string, string> }) => {
+      sentAuth = init.headers.authorization;
+      return Promise.resolve(okResponse({ nano: { engine: "nanobpmn" } }));
+    }) as unknown as typeof fetch,
+  });
+  assertEquals(sentAuth, "Bearer secret-token");
+});
+
+test("announceEngine treats 401/403 as an auth hint, not an unreachable warning", async () => {
+  const { log, warn } = capture();
+  const res = { ok: false, status: 401, json: () => Promise.reject(new Error("unused")) } as unknown as Response;
+  await announceEngine(ADDR, log, { fetchImpl: (() => Promise.resolve(res)) as unknown as typeof fetch });
+  assert(warn.some((l) => l.includes("HTTP 401") && l.includes("CAMUNDA_TOKEN")), "points at the token, not unreachability");
+  assert(!warn.some((l) => l.includes("could not reach")), "does not claim the engine is unreachable");
+});
+
+test("announceEngine warns (does not throw) on a non-200 response", async () => {
+  const { log, warn } = capture();
+  const res = { ok: false, status: 503, json: () => Promise.reject(new Error("unused")) } as unknown as Response;
+  await announceEngine(ADDR, log, { fetchImpl: (() => Promise.resolve(res)) as unknown as typeof fetch });
+  assert(warn.some((l) => l.includes("HTTP 503")), "warns with the status code");
+});
+
+test("announceEngine warns (does not throw) when the engine is unreachable", async () => {
+  const { log, warn } = capture();
+  await announceEngine(ADDR, log, {
+    fetchImpl: (() => Promise.reject(new Error("ECONNREFUSED"))) as unknown as typeof fetch,
+  });
+  assert(warn.some((l) => l.includes("could not reach") && l.includes("ECONNREFUSED")), "warns with the reason");
+});

package/app/enginePreflight.ts

@@ -0,0 +1,134 @@
+// Engine address resolution + a lightweight, non-rejecting startup preflight
+// (nano-workforce#391).
+//
+// Two jobs, one source of truth:
+//   1. `resolveEngineAddress` is the CANONICAL resolver for the engine REST
+//      address. Both the engine client (`main.ts`) and the demand reader
+//      (`app/agentic/vocab/demand-report.ts`) derive from it, so the precedence
+//      lives in exactly one place instead of drifting across call sites.
+//   2. `announceEngine` probes `/v2/topology` at boot and reports which engine
+//      answered. It is DELIBERATELY informational: Nano Workforce is a
+//      first-class Camunda 8 client, so a non-Nano engine is announced, never
+//      rejected. It never throws — a boot preflight must not gate startup.
+//
+// Why: without this, pointing the app at the wrong address (classically another
+// service already on :8080) surfaces only later as a cryptic mid-run engine
+// error. Echoing the resolved address + which engine answered makes the
+// misconfiguration obvious at boot.
+
+import { envVar } from "./version.ts";
+
+/** The resolved engine REST address plus a human label for where it came from. */
+export interface EngineAddress {
+  /** The `/v2` REST base the engine client and demand reader talk to. */
+  restAddress: string;
+  /** Which input produced `restAddress`, for a legible startup line. */
+  source: string;
+}
+
+/**
+ * Canonical engine REST address resolution — the single source of truth.
+ *
+ * Precedence: an explicit `CAMUNDA_REST_ADDRESS` (already the `/v2` REST
+ * address) wins; otherwise the address is derived from `NANOBPMN_BASE_URL`
+ * (+ `/v2`), defaulting the base to `http://localhost:8080`. Trailing slashes
+ * are stripped from both inputs.
+ *
+ * `read` is injectable so the resolution is testable without mutating
+ * `process.env`; it defaults to the app's `envVar` (ADR 0004) accessor.
+ */
+export function resolveEngineAddress(
+  read: (name: string) => string | null = envVar,
+): EngineAddress {
+  const explicit = read("CAMUNDA_REST_ADDRESS")?.replace(/\/+$/, "");
+  if (explicit) return { restAddress: explicit, source: "CAMUNDA_REST_ADDRESS" };
+  const base = read("NANOBPMN_BASE_URL");
+  const normalized = (base ?? "http://localhost:8080").replace(/\/+$/, "");
+  return {
+    restAddress: `${normalized}/v2`,
+    source: base ? "NANOBPMN_BASE_URL" : "default (http://localhost:8080)",
+  };
+}
+
+/**
+ * The subset of a `/v2/topology` body we read. A nanobpmn gateway advertises a
+ * `nano` object (its own extension) so a single call distinguishes it from a
+ * stock Camunda 8 gateway, which returns the same shape without it.
+ */
+export interface TopologyProbe {
+  nano?: { engine?: string; version?: string; falconPath?: string } | null;
+  gatewayVersion?: string;
+}
+
+/**
+ * A human-readable identity line for whatever answered `/v2/topology`. Never
+ * rejects: a Camunda 8 gateway (no `nano` marker) is a supported target, so it
+ * is described, not refused.
+ */
+export function describeEngine(body: TopologyProbe | null | undefined): string {
+  const nano = body?.nano;
+  if (nano?.engine) {
+    const version = nano.version ? ` v${nano.version}` : "";
+    const falcon = nano.falconPath ?? "/falcon";
+    return `Nano engine (${nano.engine}${version}) — Falcon streaming at ${falcon}`;
+  }
+  const gateway = body?.gatewayVersion ? ` (gateway v${body.gatewayVersion})` : "";
+  return `Camunda 8${gateway} — REST only (Nano Falcon streaming unavailable)`;
+}
+
+/** The logging surface `announceEngine` needs (structurally a `Logger`). */
+export interface PreflightLog {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+/**
+ * Log the resolved engine address (and its source), then probe `/v2/topology`
+ * and announce which engine answered. Informational only — it swallows every
+ * failure into a `warn` and never throws, so a slow or absent engine cannot
+ * block boot. A missing engine is a `warn` (features will fail to start until
+ * it is reachable), not a fatal error.
+ *
+ * `opts.token` (the same `CAMUNDA_TOKEN` the engine client uses) is sent as a
+ * bearer credential so a secured cluster does not answer the probe with a
+ * misleading 401/403 while the real client is correctly configured.
+ */
+export async function announceEngine(
+  addr: EngineAddress,
+  log: PreflightLog,
+  opts: { token?: string; fetchImpl?: typeof fetch } = {},
+): Promise<void> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  log.info(`Engine address: ${addr.restAddress} (from ${addr.source})`);
+  const url = `${addr.restAddress.replace(/\/+$/, "")}/topology`;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (opts.token) headers.authorization = `Bearer ${opts.token}`;
+  try {
+    const res = await fetchImpl(url, { headers, signal: AbortSignal.timeout(3000) });
+    if (!res.ok) {
+      if (res.status === 401 || res.status === 403) {
+        // The engine is reachable but rejected the probe's credentials — the
+        // real client may still work (it authenticates independently), so this
+        // is an auth hint, not an "unreachable" warning.
+        log.warn(
+          `Engine preflight: ${url} returned HTTP ${res.status} (authentication). ` +
+            `If the engine requires a token, set CAMUNDA_TOKEN — the engine client uses it independently.`,
+        );
+        return;
+      }
+      log.warn(
+        `Engine preflight: ${url} returned HTTP ${res.status}. ` +
+          `Check CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL — features will fail to start until the engine is reachable.`,
+      );
+      return;
+    }
+    const body: TopologyProbe = await res.json();
+    log.info(`Engine: ${describeEngine(body)} at ${addr.restAddress}.`);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    log.warn(
+      `Engine preflight: could not reach ${url} (${reason}). ` +
+        `Check CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL — features will fail to start until the engine is reachable.`,
+    );
+  }
+}

package/app/persist-escalation.test.ts

@@ -212,36 +212,3 @@ test("a control-flow arm with a blank question opens nothing so gw-escalated re-
   assertEquals(inserts.escalations.length, 0, "no dead escalation is fabricated");
   assertEquals(updates.pull_requests?.length ?? 0, 0, "the PR is never flipped to escalated");
 });
-
-// The scope-integrity arm (persist-escalation-blockedcomments) binds the escalation to the reviewed
-// commit (issue #395): it stamps `head_sha` and marks `scope_block` so the converge-gate can honour
-// a same-HEAD human answer as an override instead of re-deriving the block and re-escalating forever.
-test("persist-escalation binds a scope-integrity escalation to the reviewed HEAD (head_sha + scope_block)", async () => {
-  const { app, inserts } = fakeApp();
-  const job = {
-    variables: {
-      prKey: "o/r#5",
-      round: 2,
-      status: "blocked",
-      question: "Scope integrity blocked: ...",
-      recordRound: false,
-      headSha: "HEAD1",
-      scopeBlock: true,
-    },
-  };
-  await handler(job as any, app as any);
-  assertEquals(inserts.escalations.length, 1);
-  assertEquals((inserts.escalations[0] as any).head_sha, "HEAD1", "the escalation carries the reviewed commit");
-  assertEquals((inserts.escalations[0] as any).scope_block, 1, "flagged as a scope-integrity block");
-});
-
-// Every other escalation arm (agent verdict, no-progress, max-rounds, stalled) omits the scope
-// binding: head_sha stays absent and scope_block defaults to 0, so the override door opens ONLY for
-// the block a human can actually answer.
-test("persist-escalation: a non-scope escalation records no HEAD binding and scope_block 0", async () => {
-  const { app, inserts } = fakeApp();
-  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "max rounds" } };
-  await handler(job as any, app as any);
-  assertEquals((inserts.escalations[0] as any).head_sha, undefined, "no reviewed HEAD to bind");
-  assertEquals((inserts.escalations[0] as any).scope_block, 0, "not a scope-integrity block");
-});

package/db/migrations/057_drop_escalation_head_override.sql

@@ -0,0 +1,16 @@
+-- Contract phase for the escalation scope-override columns (migration 056, issue #395).
+--
+-- Migration 056 added `escalations.head_sha` + `escalations.scope_block` to give the DETERMINISTIC
+-- scope-integrity gate a human-override door: it bound a scope escalation to the reviewed HEAD so a
+-- same-HEAD human answer could override the block instead of re-escalating forever. That whole
+-- deterministic gate has since been replaced by the `senior:scope-classify` AGENT classifier, which
+-- reads each closed issue's acceptance criteria and honours the recorded human `answer` directly —
+-- so nothing writes or reads these two columns any more. They are dead schema (a drift surface with
+-- no source of truth behind them), so drop them.
+--
+-- 056 is forward-only and immutable (its ledger row stays), so this is the standard expand→contract
+-- follow-up rather than an edit to 056. Both drops are safe: the columns were nullable/defaulted and
+-- have no remaining writer or reader. Numbered after the current highest prefix (056); the runner
+-- wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE escalations DROP COLUMN scope_block;
+ALTER TABLE escalations DROP COLUMN head_sha;

package/e2e/convergence-escalation.e2e.ts

@@ -87,6 +87,12 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
       capturedAnswer = (job.variables as Record<string, unknown>).answer;
       return { status: "converged", summary: "resolved after the human answer" };
     });
+    // `senior:scope-classify` is likewise an externalTaskType (no app worker): the converged round
+    // routes through it before finalizing. Stub it as "scope delivered" so the happy path reaches
+    // persist-converged rather than parking on an unserviced agent job.
+    await app.engine.registerWorker("senior:scope-classify", () => {
+      return { scopeBlocked: false, scopeBlockReason: "" };
+    });
   });
 
   after(async () => {