@nanobpm/nano-workforce 0.115.0 → 0.117.0

package/.github/workflows/renovate.yml

@@ -0,0 +1,72 @@
+name: Renovate
+
+# Self-hosted Renovate (issue #406). renovate.json declares the policy — auto-merge
+# non-major @nanobpm/* updates once CI is green, majors need a human — but nothing was
+# ever running it, so the config sat dormant and nwf stayed pinned to old @nanobpm/urban.
+# This workflow IS the runner: on a schedule (and on demand) it opens update PRs and, on a
+# later pass once the PR's CI is green, merges the automerge ones itself. We self-host via
+# GitHub Actions rather than the Mend hosted app so the whole capability is in-repo and
+# reproducible, with no external app-install state to drift.
+on:
+  schedule:
+    # Every 3 hours. Renovate needs to run periodically not just to DISCOVER new versions,
+    # but to COME BACK and merge automerge PRs: renovate.json sets platformAutomerge:false
+    # (main is unprotected, so GitHub-native auto-merge is unavailable), which means Renovate
+    # performs the merge itself on a subsequent run once the PR's branch status is green.
+    # A few-hourly cadence keeps that merge latency low without burning Actions minutes.
+    - cron: "0 */3 * * *"
+  # On-demand runs for immediate pickup (e.g. right after a new urban publishes) and for
+  # debugging with a raised log level.
+  workflow_dispatch:
+    inputs:
+      logLevel:
+        description: "Renovate log level"
+        default: "info"
+        type: choice
+        options:
+          - debug
+          - info
+          - warn
+  # Re-run whenever the policy or this runner itself changes, so config edits take effect
+  # without waiting for the next scheduled tick.
+  push:
+    branches: [main]
+    paths:
+      - renovate.json
+      - .github/workflows/renovate.yml
+
+# Renovate authenticates with RENOVATE_TOKEN (a PAT) for all git/PR/merge operations, so the
+# job's GITHUB_TOKEN needs no elevated scope.
+permissions:
+  contents: read
+
+# Never let two Renovate passes run concurrently — overlapping runs race on the same branches
+# and can double-open PRs. cancel-in-progress:false lets an in-flight pass (which may be mid-merge)
+# finish rather than being killed by a newer trigger.
+concurrency:
+  group: renovate
+  cancel-in-progress: false
+
+jobs:
+  renovate:
+    name: renovate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Renovate
+        uses: renovatebot/github-action@v46.2.2
+        with:
+          # A Personal Access Token (repo scope), NOT the default GITHUB_TOKEN. This is required,
+          # not a preference: PRs opened by GITHUB_TOKEN do not trigger `on: pull_request`, so CI
+          # would never run on them and the green-gated automerge in renovate.json could never fire.
+          # A PAT-authored PR triggers CI normally, which is what makes "merge when green" work.
+          token: ${{ secrets.RENOVATE_TOKEN }}
+        env:
+          # Only ever operate on this repo (no org-wide autodiscovery).
+          RENOVATE_REPOSITORIES: ${{ github.repository }}
+          RENOVATE_AUTODISCOVER: "false"
+          # Renovate reads the repo's own renovate.json as its config automatically once it
+          # clones the repo above — no global configurationFile needed.
+          LOG_LEVEL: ${{ inputs.logLevel || 'info' }}

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.117.0](https://github.com/nanobpm/nano-workforce/compare/v0.116.0...v0.117.0) (2026-08-21)
+
+
+### Features
+
+* **delivery-graph:** gated startDeliveryGraph dispatch door (ADR 0005 S5) ([#405](https://github.com/nanobpm/nano-workforce/issues/405)) ([dc7c78e](https://github.com/nanobpm/nano-workforce/commit/dc7c78e03ef1a3a8cfb70e4e51b721a4419c8962)), closes [#380](https://github.com/nanobpm/nano-workforce/issues/380)
+
+# [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)
 
 

package/README.md

@@ -441,6 +441,23 @@ returns `401` without the matching header; unset = open. The source lives in
   model, **generate** the diagram — CI enforces DI freshness), migration policy, and
   the CI gates.
 
+### Dependency updates (Renovate)
+
+First-party `@nanobpm/*` packages (notably `@nanobpm/urban`) are kept current by a
+self-hosted [Renovate](https://docs.renovatebot.com/) runner:
+[`.github/workflows/renovate.yml`](.github/workflows/renovate.yml) runs on a schedule (and
+`workflow_dispatch`), opens update PRs, and — per [`renovate.json`](renovate.json) — merges
+non-major `@nanobpm/*` bumps once CI is green while leaving majors for a human.
+
+It requires a repository secret **`RENOVATE_TOKEN`**: a Personal Access Token with `repo` +
+`workflow` scope (or a fine-grained PAT with *Contents: read & write*, *Pull requests: read &
+write*, *Issues: read & write* — the Dependency Dashboard is a GitHub Issue — and *Workflows:
+read & write*, so Renovate can update files under `.github/workflows`). A PAT is
+mandatory rather than the built-in `GITHUB_TOKEN` because PRs opened by `GITHUB_TOKEN` do not
+trigger `on: pull_request` CI — so the "merge when green" gate would never fire. Set it via
+`gh secret set RENOVATE_TOKEN --repo nanobpm/nano-workforce` (or repo → Settings → Secrets →
+Actions), then trigger a first run from the Actions tab.
+
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE).

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/deliveryGraphRun.test.ts

@@ -0,0 +1,249 @@
+// Unit coverage for the S5 dispatch-door aggregate (ADR 0005 Decision 7) — the pure decision helpers
+// (the idempotency key, the approval gate, the parked human-label map, the derived parked-node phase),
+// plus the durable at-most-once launch-claim fence (`claimRunForLaunch`) exercised against the real
+// provisioned SQLite data layer so its actual `status <> 'running'` compare-and-swap SQL is validated,
+// not just modelled. The integration test (operations/startDeliveryGraph.integration.test.ts) proves
+// the COMPOSED behaviour at the edge.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import {
+  buildDeliveryGraphRunRow,
+  buildHumanLabels,
+  claimRunForLaunch,
+  computeRunKey,
+  deriveDeliveryPhase,
+  DELIVERY_PHASE,
+  deliveryGraphRuns,
+  humanTaskElementId,
+  isDeliveryGraphApproved,
+  parkRunFencedAgainstLaunch,
+  parseHumanLabels,
+} from "./deliveryGraphRun.ts";
+import { pollDeliveryGraphPhase } from "./service.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+/** Boot an app purely for its provisioned data layer (migration 058 applied), run `fn`, tear down. */
+async function withData(fn: (data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dgrun-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    await fn(app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const claimRow = (status: "awaiting-approval" | "running") =>
+  buildDeliveryGraphRunRow({
+    runKey: "rk",
+    digest: "d",
+    status,
+    sideEffecting: true,
+    nodeCount: 1,
+    humanNodeCount: 0,
+    sideEffectCount: 1,
+    title: "t",
+    phase: status === "running" ? DELIVERY_PHASE.RUNNING : DELIVERY_PHASE.AWAITING_APPROVAL,
+    processKey: null,
+  });
+
+test("claimRunForLaunch: an empty slot is won by INSERT; a second racer that also read empty loses the run_key PK fence", async () => {
+  await withData(async (data) => {
+    const claim = claimRow("running");
+    assertEquals(await claimRunForLaunch(data, false, claim), true); // inserted the claim → this caller launches
+    assertEquals(await claimRunForLaunch(data, false, claim), false); // the row now exists → PK fence, no second launch
+    assertEquals((await deliveryGraphRuns(data).get("rk"))?.status, "running");
+  });
+});
+
+test("claimRunForLaunch: a parked awaiting-approval row is claimed by ONE compare-and-swap — a second approved racer loses the `status <> 'running'` guard, so a graph launches at most once", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    await runs.insert(claimRow("awaiting-approval")); // a prior unapproved POST parked this run
+    const claim = claimRow("running");
+    assertEquals(await claimRunForLaunch(data, true, claim), true); // CAS flips awaiting-approval → running
+    assertEquals(await claimRunForLaunch(data, true, claim), false); // already running → guard blocks the double-launch
+    assertEquals((await runs.get("rk"))?.status, "running");
+  });
+});
+
+test("claimRunForLaunch: a TERMINAL row re-runs — the CAS flips it to running, and a concurrent re-run racer loses the guard", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    await runs.insert({ ...claimRow("running"), status: "failed" }); // a completed/terminal prior run
+    const claim = claimRow("running");
+    assertEquals(await claimRunForLaunch(data, true, claim), true); // re-run: failed <> running → flips
+    assertEquals(await claimRunForLaunch(data, true, claim), false); // now running → no second launch
+    assertEquals((await runs.get("rk"))?.status, "running");
+  });
+});
+
+test("claimRunForLaunch: re-running a terminal row clears the PRIOR instance key in the SAME atomic flip — a claimed `running` row is never visible pointing at a stale process_key", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    // A terminal prior run still carrying its old instance key + parked-node projection.
+    await runs.insert({
+      ...claimRow("running"),
+      status: "failed",
+      process_key: "OLD-PI",
+      process_definition_id: "OLD-DEF",
+      phase: "Parked on human node: publish",
+      phase_node_id: "delivery-human-task__n1",
+    });
+    // The fresh launch claim carries no instance key yet (processKey: null).
+    assertEquals(await claimRunForLaunch(data, true, claimRow("running")), true);
+    const row = await runs.get("rk");
+    assertEquals(row?.status, "running");
+    assertEquals(row?.process_key, null); // stale key cleared atomically with the flip — not left as "OLD-PI"
+    assertEquals(row?.process_definition_id, null);
+    assertEquals(row?.phase_node_id, null);
+    assertEquals(row?.phase, DELIVERY_PHASE.RUNNING);
+  });
+});
+
+// ── pollDeliveryGraphPhase: engine-key coercion ───────────────────────────────
+test("pollDeliveryGraphPhase: a numeric engine processInstanceKey still matches the string process_key, so a COMPLETED instance reconciles to done", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    await runs.insert({ ...claimRow("running"), process_key: "12345" });
+    // The engine can yield a NUMERIC key; the poller compares against the string process_key.
+    const engine = {
+      searchProcessInstances: async () => [{ processInstanceKey: 12345, state: "COMPLETED" }],
+      searchUserTasks: async () => [],
+    };
+    await pollDeliveryGraphPhase(data, engine as never);
+    assertEquals((await runs.get("rk"))?.status, "done");
+  });
+});
+
+// ── parkRunFencedAgainstLaunch: the approval-park write never clobbers a launched claim ────────────
+test("parkRunFencedAgainstLaunch: an approval-park write onto a launched `running` claim is a no-op — the at-most-once dispatch fence survives (no clobber back to awaiting-approval, no nulled process_key)", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    // A concurrent APPROVED submit already launched: the row is `running` with a live instance key.
+    await runs.insert({ ...claimRow("running"), process_key: "PI-1" });
+    // A racing UNAPPROVED submit that read the pre-launch row now tries to (re-)park it. The guarded
+    // write must refuse to overwrite the launched claim — otherwise a later re-submit double-launches.
+    await parkRunFencedAgainstLaunch(data, true, claimRow("awaiting-approval"));
+    const row = await runs.get("rk");
+    assertEquals(row?.status, "running"); // NOT clobbered back to awaiting-approval
+    assertEquals(row?.process_key, "PI-1"); // instance key preserved
+  });
+});
+
+test("parkRunFencedAgainstLaunch: a first park INSERTs the row; a park onto a still-parked row idempotently re-parks it (metadata refreshed, status stays awaiting-approval)", async () => {
+  await withData(async (data) => {
+    const runs = deliveryGraphRuns(data);
+    // First unapproved submit: no row yet → INSERT.
+    await parkRunFencedAgainstLaunch(data, false, claimRow("awaiting-approval"));
+    assertEquals((await runs.get("rk"))?.status, "awaiting-approval");
+    // A second unapproved submit onto the existing parked row: guarded UPDATE re-parks it (status is
+    // not `running`, so it applies) without duplicating the row.
+    await parkRunFencedAgainstLaunch(data, true, { ...claimRow("awaiting-approval"), digest: "d2" });
+    const row = await runs.get("rk");
+    assertEquals(row?.status, "awaiting-approval");
+    assertEquals(row?.digest, "d2");
+  });
+});
+
+// ── computeRunKey ─────────────────────────────────────────────────────────────
+test("computeRunKey: a non-blank caller key wins; a blank/absent key falls back to the digest", () => {
+  assertEquals(computeRunKey("run-1", "digestX"), "run-1");
+  assertEquals(computeRunKey("  run-2  ", "digestX"), "run-2"); // trimmed
+  assertEquals(computeRunKey("", "digestX"), "digestX");
+  assertEquals(computeRunKey("   ", "digestX"), "digestX");
+  assertEquals(computeRunKey(null, "digestX"), "digestX");
+  assertEquals(computeRunKey(undefined, "digestX"), "digestX");
+});
+
+// ── isDeliveryGraphApproved ───────────────────────────────────────────────────
+test("isDeliveryGraphApproved: a non-side-effecting graph needs no approval", () => {
+  assertEquals(isDeliveryGraphApproved(false, null, "d"), true);
+  assertEquals(isDeliveryGraphApproved(false, "wrong", "d"), true);
+});
+
+test("isDeliveryGraphApproved: a side-effecting graph dispatches ONLY with the matching content token", () => {
+  assertEquals(isDeliveryGraphApproved(true, "d", "d"), true);
+  assertEquals(isDeliveryGraphApproved(true, "  d  ", "d"), true); // trimmed
+  assertEquals(isDeliveryGraphApproved(true, "wrong", "d"), false);
+  assertEquals(isDeliveryGraphApproved(true, null, "d"), false);
+  assertEquals(isDeliveryGraphApproved(true, "", "d"), false);
+});
+
+// ── buildHumanLabels / parseHumanLabels ───────────────────────────────────────
+test("buildHumanLabels: maps each human node's compiled user-task element id → its instruction label", () => {
+  const graph = {
+    nodes: [
+      { id: "open-b", kind: "agent", agent: { jobType: "j" } },
+      { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish\nsecond line" } },
+      { id: "ack", kind: "human" }, // no prompt → falls back to the node id
+    ],
+    edges: [{ from: "open-b", to: "publish" }, { from: "publish", to: "ack" }],
+  };
+  const compiled = compileDeliveryGraph(graph);
+  assertEquals(compiled.ok, true);
+  if (!compiled.ok) return;
+  const labels = buildHumanLabels(compiled);
+  const publishEl = compiled.resolved.nodes.find((n) => n.id === "publish")?.element ?? "";
+  const ackEl = compiled.resolved.nodes.find((n) => n.id === "ack")?.element ?? "";
+  assertEquals(labels[humanTaskElementId(publishEl)], "run the manual OTP publish"); // first line only
+  assertEquals(labels[humanTaskElementId(ackEl)], "ack"); // fallback to node id
+});
+
+test("parseHumanLabels: round-trips a stored map and tolerates null/blank/corrupt", () => {
+  assertEquals(parseHumanLabels(JSON.stringify({ a: "x" })), { a: "x" });
+  assertEquals(parseHumanLabels(null), {});
+  assertEquals(parseHumanLabels(""), {});
+  assertEquals(parseHumanLabels("  "), {});
+  assertEquals(parseHumanLabels("{not json"), {});
+  assertEquals(parseHumanLabels(JSON.stringify(["a"])), {}); // non-object
+  assertEquals(parseHumanLabels(JSON.stringify({ a: 1, b: "y" })), { b: "y" }); // drops non-string values
+});
+
+// ── deriveDeliveryPhase ───────────────────────────────────────────────────────
+test("deriveDeliveryPhase: COMPLETED → done, TERMINATED → failed", () => {
+  assertEquals(deriveDeliveryPhase("COMPLETED", [], {}), { status: "done", phase: DELIVERY_PHASE.COMPLETED, phase_node_id: null });
+  assertEquals(deriveDeliveryPhase("TERMINATED", [], {}), { status: "failed", phase: DELIVERY_PHASE.FAILED, phase_node_id: null });
+});
+
+test("deriveDeliveryPhase: ACTIVE with an open human task → parked on that node with its label", () => {
+  const el = humanTaskElementId("n2");
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: el }], { [el]: "manual OTP publish" });
+  assertEquals(p.status, "running");
+  assertEquals(p.phase, "Parked on human node: manual OTP publish");
+  assertEquals(p.phase_node_id, el);
+});
+
+test("deriveDeliveryPhase: a parked node with no stored label falls back to the element id", () => {
+  const el = humanTaskElementId("n5");
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: el }], {});
+  assertEquals(p.phase, `Parked on human node: ${el}`);
+  assertEquals(p.phase_node_id, el);
+});
+
+test("deriveDeliveryPhase: ACTIVE with only a non-human open task (or none) → a bare Running", () => {
+  assertEquals(deriveDeliveryPhase("ACTIVE", [], {}), { status: "running", phase: DELIVERY_PHASE.RUNNING, phase_node_id: null });
+  assertEquals(deriveDeliveryPhase("ACTIVE", [{ elementId: "some-service-task" }], {}), {
+    status: "running",
+    phase: DELIVERY_PHASE.RUNNING,
+    phase_node_id: null,
+  });
+  // A null state (instance not found this pass) is treated as still-running, never a false terminal.
+  assertEquals(deriveDeliveryPhase(null, [], {}), { status: "running", phase: DELIVERY_PHASE.RUNNING, phase_node_id: null });
+});
+
+test("deriveDeliveryPhase: multiple open human tasks pick the lowest element id deterministically", () => {
+  const a = humanTaskElementId("n1");
+  const b = humanTaskElementId("n3");
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: b }, { elementId: a }], { [a]: "first", [b]: "second" });
+  assertEquals(p.phase, "Parked on human node: first");
+  assertEquals(p.phase_node_id, a);
+});