@nanobpm/nano-workforce 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.43.0](https://github.com/nanobpm/nano-workforce/compare/v0.42.0...v0.43.0) (2026-08-11)
+
+
+### Features
+
+* **api:** oneOf request bodies + structured logging (urban 0.42.0) ([#120](https://github.com/nanobpm/nano-workforce/issues/120)) ([ea7549b](https://github.com/nanobpm/nano-workforce/commit/ea7549bd4acb7cdd874fde0a8ccccbf1563b8e53)), closes [#119](https://github.com/nanobpm/nano-workforce/issues/119)
+
 # [0.42.0](https://github.com/nanobpm/nano-workforce/compare/v0.41.0...v0.42.0) (2026-08-11)
 
 

package/app/retro.ts

@@ -13,7 +13,7 @@
 //
 // Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
 // app/plan.ts, app/blackboard.ts, and app/taskDelta.ts.
-import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import type { DataLayer, EngineClient, Logger } from "@nanobpm/urban";
 import { isUniqueViolation, readBlackboard } from "./blackboard.ts";
 import { planReviews, planTasks } from "./plan.ts";
 import { TERMINAL_STATUSES } from "./service.ts";
@@ -296,7 +296,7 @@ export async function maybeStartRetro(
   data: DataLayer,
   engine: EngineClient,
   prKey: string,
-  log?: (level: "info" | "warn" | "error", msg: string, meta?: Record<string, unknown>) => void,
+  log?: Logger,
 ): Promise<{ started: boolean; planKey?: string; reason?: string }> {
   if (!autoRetroEnabled()) return { started: false, reason: "disabled" };
   try {
@@ -340,7 +340,7 @@ export async function maybeStartRetro(
       // record, the epic surface would show a plan that "started a retro" with nothing to show and
       // no way to retry. Persist a `blocked` retro instead so the failure stays visible and the
       // system state is consistent. Recording must not mask the original error in the log.
-      log?.("error", `retro: could not start process for epic ${planKey}`, { err: String(err) });
+      log?.error(`retro: could not start process for epic ${planKey}`, { err: String(err) });
       // Persisting the blocked record is best-effort: recordRetro rethrows non-unique DB errors, and
       // if that escaped here it would fall through to the outer catch and return `error` instead of
       // `start-failed` — reintroducing the very silent-gap failure this path guards against (guard
@@ -352,16 +352,16 @@ export async function maybeStartRetro(
           summary: `Retro process could not be started: ${String(err)}`,
         });
       } catch (persistErr) {
-        log?.("error", `retro: could not persist blocked retro for epic ${planKey}`, {
+        log?.error(`retro: could not persist blocked retro for epic ${planKey}`, {
           err: String(persistErr),
         });
       }
       return { started: false, planKey, reason: "start-failed" };
     }
-    log?.("info", `retro: started for epic ${planKey}`, { processInstanceKey, learnings: digest.counts.learnings });
+    log?.info(`retro: started for epic ${planKey}`, { processInstanceKey, learnings: digest.counts.learnings });
     return { started: true, planKey };
   } catch (err) {
-    log?.("error", `retro: could not start for PR ${prKey}`, { err: String(err) });
+    log?.error(`retro: could not start for PR ${prKey}`, { err: String(err) });
     return { started: false, reason: "error" };
   }
 }

package/openapi.yaml

@@ -201,22 +201,46 @@ components:
         alreadyRunning:
           type: boolean
           description: True when a non-terminal plan for this issue already exists; no new instance was started.
-    StartVariables:
+    ConvergenceStart:
+      description: The start-convergence request body. Names the target PR by EXACTLY ONE of `pr`
+        (an `owner/repo#123` reference) or `url` (a bare PR URL) — never both, never neither — with
+        the optional convergence knobs. Modeled as `oneOf` named variants (ADR — Camunda REST v2
+        pattern) so the runtime rejects an ambiguous or empty target at the edge with a 400 that
+        names the allowed shapes, rather than the delegate silently coalescing `pr ?? url`.
+      oneOf:
+        - $ref: "#/components/schemas/ConvergenceStartByPr"
+        - $ref: "#/components/schemas/ConvergenceStartByUrl"
+    ConvergenceStartByPr:
       type: object
-      description: The start request body. `pr`/`url` (convergence) or `issue`/`url` (planning) name the
-        target. Only the fields below are read by the delegate; any extra keys are accepted but
-        ignored (they are NOT forwarded to the engine as process variables).
-      additionalProperties: true
+      additionalProperties: false
+      required:
+        - pr
       properties:
         pr:
           type: string
-          description: "PR reference: owner/repo#123 or a PR URL."
-        issue:
-          type: string
-          description: "Issue reference: owner/repo#123 or an issue URL."
+          description: "PR reference: owner/repo#123."
+        dependsOn:
+          type: array
+          items:
+            type: string
+        maxRounds:
+          type: integer
+          minimum: 1
+          description: Values above 100 are accepted and clamped to 100 by the delegate.
+        convergeOnly:
+          type: boolean
+          description: When true, run convergence only and stop at `converged` — the PR is never
+            handed to the merge-loop even if auto-merge is on globally (`NANO_PR_AUTO_MERGE`). A
+            per-request review-only override; defaults to false (the global auto-merge default applies).
+    ConvergenceStartByUrl:
+      type: object
+      additionalProperties: false
+      required:
+        - url
+      properties:
         url:
           type: string
-          description: Alias for pr/issue when a bare URL is supplied.
+          description: A bare PR URL, when no `owner/repo#123` reference is supplied.
         dependsOn:
           type: array
           items:
@@ -230,6 +254,32 @@ components:
           description: When true, run convergence only and stop at `converged` — the PR is never
             handed to the merge-loop even if auto-merge is on globally (`NANO_PR_AUTO_MERGE`). A
             per-request review-only override; defaults to false (the global auto-merge default applies).
+    PlanStart:
+      description: The start-plan-fanout request body. Names the target issue by EXACTLY ONE of
+        `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL). Modeled as `oneOf`
+        named variants (Camunda REST v2 pattern) so an ambiguous or empty target is a 400 at the
+        edge, not a silent `issue ?? url` coalesce in the delegate.
+      oneOf:
+        - $ref: "#/components/schemas/PlanStartByIssue"
+        - $ref: "#/components/schemas/PlanStartByUrl"
+    PlanStartByIssue:
+      type: object
+      additionalProperties: false
+      required:
+        - issue
+      properties:
+        issue:
+          type: string
+          description: "Issue reference: owner/repo#123."
+    PlanStartByUrl:
+      type: object
+      additionalProperties: false
+      required:
+        - url
+      properties:
+        url:
+          type: string
+          description: A bare issue URL, when no `owner/repo#123` reference is supplied.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message
@@ -241,15 +291,36 @@ components:
         ok:
           type: boolean
     FeatureAnswerRequest:
+      description: "Answer an implementation-phase task escalation (issue #25). Supply the target by
+        EXACTLY ONE of `corrKey`, or the `plan`+`task` pair the delegate derives it from; `answer`
+        is always required. Modeled as `oneOf` named variants (Camunda REST v2 pattern) so a body
+        that supplies neither addressing form — or mixes them — is a 400 at the edge that names the
+        allowed shapes, instead of the delegate re-deriving the precedence by hand."
+      oneOf:
+        - $ref: "#/components/schemas/FeatureAnswerByCorrKey"
+        - $ref: "#/components/schemas/FeatureAnswerByPlanTask"
+    FeatureAnswerByCorrKey:
       type: object
-      description: "Answer an implementation-phase task escalation (issue #25). Supply either `corrKey`,
-        or both `plan` and `task`; `answer` is always required."
+      additionalProperties: false
       required:
+        - corrKey
         - answer
       properties:
         corrKey:
           type: string
           description: The task correlation key, `<plan_key>:<task_id>` (e.g. owner/repo#12:task-3).
+        answer:
+          type: string
+          minLength: 1
+          description: The operator's answer that resumes the parked implementation agent.
+    FeatureAnswerByPlanTask:
+      type: object
+      additionalProperties: false
+      required:
+        - plan
+        - task
+        - answer
+      properties:
         plan:
           type: string
           description: Plan reference (owner/repo#N); combined with `task` to derive the corrKey.
@@ -453,7 +524,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/StartVariables"
+              $ref: "#/components/schemas/ConvergenceStart"
       responses:
         "202":
           description: The loop was started (or refreshed).
@@ -476,7 +547,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/StartVariables"
+              $ref: "#/components/schemas/PlanStart"
       responses:
         "202":
           description: The plan fan-out was started (or was already running).

package/operations/answerFeatureEscalation.test.ts

@@ -1,6 +1,7 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
 
 const hadSecret = Object.prototype.hasOwnProperty.call(process.env, "NANO_PR_WEBHOOK_SECRET");
 const previousSecret = process.env.NANO_PR_WEBHOOK_SECRET;
@@ -42,6 +43,7 @@ function memApp(escalations: any[] = []) {
         return Promise.resolve();
       },
     },
+    log: noopLog(),
   } as any as AppApi;
   return { app, published };
 }
@@ -98,3 +100,13 @@ test("maps an unmatched corrKey to 404", async () => {
   assertEquals(result.status, 404);
   assertEquals(result.body.ok, false);
 });
+
+test("rejects a missing request body with 400 (not 500)", async () => {
+  const { app } = memApp();
+  const result = await answerFeatureEscalation(
+    { ...input({}, "test-secret"), body: undefined },
+    app,
+  ) as any;
+  assertEquals(result.status, 400);
+  assertEquals(result.body.ok, false);
+});

package/operations/answerFeatureEscalation.ts

@@ -5,9 +5,11 @@
 // external system (a chat relay, a CI job, a human via curl) resume a parked implementation agent
 // without the page. Same idempotent `answerTaskEscalation` path the page's answer form uses.
 //
-// The runtime validates the body shape against openapi.yaml; this delegate keeps the semantic
-// checks (an answer is required; a correlation key must be resolvable) and the shared-secret guard.
-// Body accepts either the raw correlation key or a plan+task pair:
+// The runtime validates the body shape against openapi.yaml — a `oneOf` of EXACTLY ONE addressing
+// form (`{ corrKey, answer }` OR `{ plan, task, answer }`), so a body that supplies neither form (or
+// mixes them) is rejected at the edge with a 400 that names the allowed shapes. This delegate narrows
+// the validated variant and keeps the semantic normalization the schema can't express (an answer /
+// correlation key that is present but blank-after-trim) plus the shared-secret guard.
 //   { "corrKey": "owner/repo#12:task-3", "answer": "…" }
 //   { "plan": "owner/repo#12", "task": "task-3", "answer": "…" }
 
@@ -21,14 +23,28 @@ const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
 
 export default defineOperation("answerFeatureEscalation", async ({ req, body }, app) => {
   if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
+    app.log.warn("feature-answer rejected: missing/invalid shared secret");
     return { status: 401, body: { ok: false, error: "unauthorized" } };
   }
-  const b = body ?? {};
-  const answer = str(b.answer);
-  if (!answer) return { status: 400, body: { ok: false, error: "answer is required" } };
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate
+  // (or a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500.
+  if (!body || typeof body !== "object") {
+    app.log.warn("feature-answer rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "answer is required" } };
+  }
+  const answer = str(body.answer);
+  if (!answer) {
+    app.log.warn("feature-answer rejected: blank answer");
+    return { status: 400, body: { ok: false, error: "answer is required" } };
+  }
 
-  const corrKey = str(b.corrKey) || (str(b.plan) && str(b.task) ? featureCorrKey(str(b.plan), str(b.task)) : "");
+  const corrKey = "corrKey" in body
+    ? str(body.corrKey)
+    : str(body.plan) && str(body.task)
+      ? featureCorrKey(str(body.plan), str(body.task))
+      : "";
   if (!corrKey) {
+    app.log.warn("feature-answer rejected: unresolvable correlation key");
     return {
       status: 400,
       body: { ok: false, error: "provide corrKey, or both plan (owner/repo#N) and task" },
@@ -36,5 +52,7 @@ export default defineOperation("answerFeatureEscalation", async ({ req, body },
   }
 
   const r = await answerTaskEscalation(app.data, app.engine, corrKey, answer);
+  if (r.ok) app.log.info("feature escalation answered", { corrKey });
+  else app.log.warn("feature-answer: no open escalation to answer", { corrKey });
   return { status: r.ok ? 200 : 404, body: r };
 });

package/operations/appendBlackboard.ts

@@ -20,7 +20,10 @@ export default defineOperation("appendBlackboard", async ({ req, body }, app) =>
   const token = (req.query.get("token") ?? req.headers.get("x-blackboard-token") ?? "").trim();
   if (!token) return { status: 400, body: { error: "missing blackboard token" } };
   const planKey = await planKeyForToken(app.data, token);
-  if (!planKey) return { status: 404, body: { error: "unknown blackboard token" } };
+  if (!planKey) {
+    app.log.warn("appendBlackboard: unknown blackboard token");
+    return { status: 404, body: { error: "unknown blackboard token" } };
+  }
 
   const b = body ?? {};
   const text = typeof b.body === "string" ? b.body.trim() : "";
@@ -51,6 +54,12 @@ export default defineOperation("appendBlackboard", async ({ req, body }, app) =>
       beforeId: Number(res.id),
     })
     : [];
+  app.log.info("blackboard entry appended", {
+    planKey,
+    kind,
+    inserted: res.inserted,
+    conflicts: conflicts.length,
+  });
   return {
     status: res.inserted ? 201 : 200,
     body: { id: Number(res.id), inserted: res.inserted, conflicts },

package/operations/blackboard.test.ts

@@ -3,6 +3,7 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
 import readBlackboard from "./readBlackboard.ts";
 import appendBlackboard from "./appendBlackboard.ts";
 
@@ -29,7 +30,7 @@ function memApp(): { app: AppApi; stores: Record<string, any[]> } {
       },
     };
   }
-  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) } } as any as AppApi;
+  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) }, log: noopLog() } as any as AppApi;
   return { app, stores };
 }
 

package/operations/checkAbandon.test.ts

@@ -2,6 +2,7 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
 import handler from "./checkAbandon.ts";
 
 function memApp(): { app: AppApi } {
@@ -18,7 +19,7 @@ function memApp(): { app: AppApi } {
       },
     };
   }
-  const app = { data: { table: (n: string) => tbl(n) } } as any as AppApi;
+  const app = { data: { table: (n: string) => tbl(n) }, log: noopLog() } as any as AppApi;
   return { app };
 }
 

package/operations/checkAbandon.ts

@@ -17,6 +17,9 @@ export default defineOperation("checkAbandon", async ({ req }, app) => {
   const token = (req.query.get("token") ?? req.headers.get("x-abandon-token") ?? "").trim();
   if (!token) return { status: 400, body: { error: "missing abandon token" } };
   const state = await abandonStatusForToken(app.data, token);
-  if (!state) return { status: 404, body: { error: "unknown abandon token" } };
+  if (!state) {
+    app.log.warn("checkAbandon: unknown abandon token");
+    return { status: 404, body: { error: "unknown abandon token" } };
+  }
   return { status: 200, body: state };
 });

package/operations/getAgentInstructions.test.ts

@@ -5,9 +5,10 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
 import handler from "./getAgentInstructions.ts";
 
-const app = {} as any as AppApi;
+const app = { log: noopLog() } as any as AppApi;
 
 function input(headers: Record<string, string> = {}, path = "/app/api/agent") {
   return {

package/operations/getAgentInstructions.ts

@@ -33,8 +33,9 @@ function resolveApiBase(req: { path: string; headers: Headers }): string {
   return host ? `${proto}://${host}${basePath}` : `http://localhost:3000${basePath}`;
 }
 
-export default defineOperation("getAgentInstructions", ({ req }) => {
+export default defineOperation("getAgentInstructions", ({ req }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgentInstructions rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
   }
   const baseUrl = resolveApiBase(req);

package/operations/getVersion.test.ts

@@ -4,9 +4,10 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
 import handler from "./getVersion.ts";
 
-const app = {} as any as AppApi;
+const app = { log: noopLog() } as any as AppApi;
 
 function input(headers: Record<string, string> = {}) {
   return {

package/operations/getVersion.ts

@@ -14,8 +14,9 @@ import { defineOperation } from "../nano-generated/operations.ts";
 // the x-hook-secret header. Captured once, at module load.
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
-export default defineOperation("getVersion", ({ req }) => {
+export default defineOperation("getVersion", ({ req }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getVersion rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
   }
   return { status: 200, body: buildVersionInfo() };

package/operations/listActivePrs.test.ts

@@ -4,6 +4,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
 import handler from "./listActivePrs.ts";
 
 function memApp(rows: any[]): AppApi {
@@ -12,7 +13,7 @@ function memApp(rows: any[]): AppApi {
       return rows;
     },
   };
-  return { data: { table: () => tbl } } as any as AppApi;
+  return { data: { table: () => tbl }, log: noopLog() } as any as AppApi;
 }
 
 function input(headers: Record<string, string> = {}) {

package/operations/listActivePrs.ts

@@ -17,6 +17,7 @@ const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
 export default defineOperation("listActivePrs", async ({ req }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listActivePrs rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
   }
   const prs = await activePrs(app.data);

package/operations/postMessage.ts

@@ -16,7 +16,10 @@ import { defineOperation } from "../nano-generated/operations.ts";
 export default defineOperation("postMessage", async ({ body }, app) => {
   const b = body ?? {};
   const name = String(b.name ?? "");
-  if (!name) return { status: 400, body: { error: "name is required" } };
+  if (!name) {
+    app.log.warn("postMessage rejected: missing name");
+    return { status: 400, body: { error: "name is required" } };
+  }
 
   if (name === "escalation-answered") {
     const prKey = String(b.correlationKey ?? "");
@@ -24,6 +27,8 @@ export default defineOperation("postMessage", async ({ body }, app) => {
     if (!prKey) return { status: 400, body: { error: "correlationKey is required" } };
     if (!answer) return { status: 400, body: { error: "answer is required" } };
     const r = await answerEscalation(app.data, app.engine, prKey, answer);
+    if (r.ok) app.log.info("review escalation answered", { name, prKey });
+    else app.log.warn("postMessage: no open review escalation to answer", { name, prKey });
     return { status: r.ok ? 200 : 404, body: r };
   }
 
@@ -36,6 +41,8 @@ export default defineOperation("postMessage", async ({ body }, app) => {
     if (!corrKey) return { status: 400, body: { error: "correlationKey is required" } };
     if (!answer) return { status: 400, body: { error: "answer is required" } };
     const r = await answerTaskEscalation(app.data, app.engine, corrKey, answer);
+    if (r.ok) app.log.info("feature escalation answered", { name, corrKey });
+    else app.log.warn("postMessage: no open feature escalation to answer", { name, corrKey });
     return { status: r.ok ? 200 : 404, body: r };
   }
 
@@ -44,5 +51,6 @@ export default defineOperation("postMessage", async ({ body }, app) => {
     correlationKey: b.correlationKey != null ? String(b.correlationKey) : undefined,
     variables: b.variables,
   });
+  app.log.info("message published", { name });
   return { status: 200, body: { ok: true } };
 });

package/operations/readBlackboard.ts

@@ -17,7 +17,10 @@ export default defineOperation("readBlackboard", async ({ req }, app) => {
   const token = (req.query.get("token") ?? req.headers.get("x-blackboard-token") ?? "").trim();
   if (!token) return { status: 400, body: { error: "missing blackboard token" } };
   const planKey = await planKeyForToken(app.data, token);
-  if (!planKey) return { status: 404, body: { error: "unknown blackboard token" } };
+  if (!planKey) {
+    app.log.warn("readBlackboard: unknown blackboard token");
+    return { status: 404, body: { error: "unknown blackboard token" } };
+  }
 
   const rawSince = req.query.get("since");
   const since = rawSince != null && /^\d+$/.test(rawSince) ? Number(rawSince) : undefined;

package/operations/startAndMessage.test.ts

@@ -1,17 +1,19 @@
 // Tests for the start/message operation delegates (ADR 0058 OpenAPI surface).
-// These cover the app-logic guards the JSON schema can't express (reference parsing, message-name
-// dispatch). The delegates reject an unparseable/blank `pr`/`issue` with a 400 (the schema itself
-// marks neither required, since `StartVariables` is shared across convergence and planning); the
-// runtime's schema-level validation (e.g. `postMessage`'s required `name`) is exercised by urban's
-// own api runtime tests.
+// These cover the app-logic guards the JSON schema can't express (reference FORMAT parsing,
+// message-name dispatch) and the derived-union narrowing. The start bodies are now `oneOf` shapes
+// (`ConvergenceStart` = pr | url, `PlanStart` = issue | url) — exactly-one-of enforcement and
+// extra-key rejection are the runtime's job (exercised by urban's own api runtime tests); here we
+// drive the delegate directly with each validated variant and assert it narrows correctly, still
+// rejecting an unparseable reference with a 400.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
 import startConvergenceLoop from "./startConvergenceLoop.ts";
 import startPlanFanout from "./startPlanFanout.ts";
 import postMessage from "./postMessage.ts";
 
-const app = {} as any as AppApi;
+const app = { log: noopLog() } as any as AppApi;
 
 function input(body: any) {
   return {
@@ -62,7 +64,7 @@ function captureApp() {
       return Promise.resolve({ processInstanceKey: "PI-1" });
     },
   };
-  return { app: { data, engine } as any as AppApi, get: () => captured };
+  return { app: { data, engine, log: noopLog() } as any as AppApi, get: () => captured };
 }
 
 function withGithubOff(run: () => Promise<void>): Promise<void> {
@@ -77,6 +79,13 @@ function withGithubOff(run: () => Promise<void>): Promise<void> {
   });
 }
 
+test("startConvergenceLoop → 400 (not 500) on a missing request body", async () => {
+  const res = await startConvergenceLoop(input(undefined), app);
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
 test("startConvergenceLoop forwards convergeOnly:true to the loop", async () => {
   await withGithubOff(async () => {
     const { app: capApp, get } = captureApp();
@@ -105,6 +114,29 @@ test("startPlanFanout → 400 on an unparseable issue reference", async () => {
   assertEquals(typeof r.body.error, "string");
 });
 
+test("startPlanFanout → 400 (not 500) on a missing request body", async () => {
+  const res = await startPlanFanout(input(undefined), app);
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
+test("startConvergenceLoop narrows the `url` variant (no `pr` key)", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp } = captureApp();
+    const res = await startConvergenceLoop(input({ url: "https://github.com/owner/repo/pull/11" }), capApp);
+    assertEquals((res as any).status, 202);
+  });
+});
+
+test("startPlanFanout narrows the `url` variant (no `issue` key)", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp } = captureApp();
+    const res = await startPlanFanout(input({ url: "https://github.com/owner/repo/issues/12" }), capApp);
+    assertEquals((res as any).status, 202);
+  });
+});
+
 test("postMessage → 400 when name is blank", async () => {
   const res = await postMessage(input({ name: "" }), app);
   const r = res as any;

package/operations/startConvergenceLoop.ts

@@ -5,28 +5,40 @@
 //
 // The request body is FLAT (`{ pr | url, dependsOn?, maxRounds?, convergeOnly? }`), not wrapped in a
 // `variables` envelope: this is a purpose-built operation, not a generic engine "start process" call,
-// so it does not leak the engine's variable-map concept to callers. The runtime validates the body
-// against openapi.yaml; this delegate keeps the PR-parse guard because the reference format
-// (owner/repo#123 or a URL) is app logic, not something the JSON schema can express — an unparseable
-// reference is a 400.
+// so it does not leak the engine's variable-map concept to callers. The body is a `oneOf` — EXACTLY
+// ONE of `pr` or `url` — so the runtime rejects an empty or ambiguous target at the edge (a 400 that
+// names the allowed shapes); this delegate no longer coalesces `pr ?? url`, it just narrows the
+// validated variant. It keeps the PR-parse guard because the reference FORMAT (owner/repo#123 or a
+// URL) is app logic the JSON schema can't express — an unparseable reference is a 400.
 
 import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startConvergenceLoop", async ({ body }, app) => {
-  const b = body ?? {};
-  const raw = String(b.pr ?? b.url ?? "").trim();
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate
+  // (or a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500 from `in`.
+  if (!body || typeof body !== "object") {
+    app.log.warn("start-convergence rejected: missing request body");
+    return { status: 400, body: { error: "request body is required (owner/repo#123 or a PR URL)" } };
+  }
+  const raw = ("pr" in body ? body.pr : body.url).trim();
   const parsed = parsePr(raw);
   if (!parsed) {
+    app.log.warn("start-convergence rejected: unparseable PR reference", { raw });
     return { status: 400, body: { error: "could not parse PR (use owner/repo#123 or a PR URL)" } };
   }
-  const dependsOn = Array.isArray(b.dependsOn) ? b.dependsOn.map((d) => String(d)) : [];
-  const maxRounds = clampRounds(b.maxRounds, MAX_ROUNDS);
+  const dependsOn = body.dependsOn ?? [];
+  const maxRounds = clampRounds(body.maxRounds, MAX_ROUNDS);
   // Per-request review-only override: when true the PR stops at `converged` and is never
   // handed to the merge-loop, regardless of the global NANO_PR_AUTO_MERGE default.
-  const convergeOnly = b.convergeOnly === true;
-  return {
-    status: 202,
-    body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly),
-  };
+  const convergeOnly = body.convergeOnly === true;
+  const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly);
+  app.log.info("convergence loop started", {
+    prKey: parsed.prKey,
+    alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
+    dependsOn: dependsOn.length,
+    maxRounds,
+    convergeOnly,
+  });
+  return { status: 202, body: result };
 });

package/operations/startPlanFanout.ts

@@ -6,17 +6,30 @@
 // short-circuits.
 //
 // The request body is FLAT (`{ issue | url }`), not wrapped in a `variables` envelope — this is a
-// purpose-built operation, not a generic engine "start process" call.
+// purpose-built operation, not a generic engine "start process" call. The body is a `oneOf` — EXACTLY
+// ONE of `issue` or `url` — so an empty or ambiguous target is a 400 at the edge; this delegate just
+// narrows the validated variant and keeps the issue-FORMAT parse guard (schema can't express it).
 
 import { parseIssue, startPlan } from "../app/plan.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startPlanFanout", async ({ body }, app) => {
-  const b = body ?? {};
-  const raw = String(b.issue ?? b.url ?? "").trim();
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate
+  // (or a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500 from `in`.
+  if (!body || typeof body !== "object") {
+    app.log.warn("start-plan rejected: missing request body");
+    return { status: 400, body: { error: "request body is required (owner/repo#123 or an issue URL)" } };
+  }
+  const raw = ("issue" in body ? body.issue : body.url).trim();
   const parsed = parseIssue(raw);
   if (!parsed) {
+    app.log.warn("start-plan rejected: unparseable issue reference", { raw });
     return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
   }
-  return { status: 202, body: await startPlan(app.data, app.engine, parsed) };
+  const result = await startPlan(app.data, app.engine, parsed);
+  app.log.info("plan fan-out started", {
+    planKey: parsed.planKey,
+    alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
+  });
+  return { status: 202, body: result };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.42.0",
+  "version": "0.43.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/test/log.ts

@@ -0,0 +1,12 @@
+// A no-op `Logger` for test doubles. The runtime injects `app.log` into every operation delegate
+// and worker handler, but the in-memory `app` fakes the suite builds don't carry one — so a
+// delegate that logs on a covered path would throw on `app.log.info(...)`. `createLogger` (exported
+// from urban's runtime barrel since 0.42.0) builds a spec-correct Logger over a discarding sink, so
+// tests exercise the logging code paths without asserting on them and stay correct if the Logger
+// interface grows. Spread into the fake `app`: `{ ...data, log: noopLog() } as unknown as AppApi`.
+import { createLogger, type Logger } from "@nanobpm/urban/runtime";
+
+/** A `Logger` that silently discards every record (and whose `child()` does the same). */
+export function noopLog(): Logger {
+  return createLogger(() => {});
+}

package/workers/finalize/worker.test.ts

@@ -6,6 +6,7 @@
 // AND the request did not force convergence-only.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 import { MERGE_PROCESS_ID } from "../../app/service.ts";
 
@@ -48,7 +49,7 @@ function fakeApp() {
           return Promise.resolve({ processInstanceKey: "MERGE-1" });
         },
       },
-      log: () => undefined,
+      log: noopLog(),
     },
   };
 }

package/workers/finalize/worker.ts

@@ -83,10 +83,10 @@ const handler: AppJobHandler<In> = async (job, app) => {
       if (mergeProcessKey != null) {
         status = "waiting_deps";
       } else {
-        app.log("error", `finalize: merge-loop start returned no process key for ${prKey}; leaving PR converged`);
+        app.log.error(`finalize: merge-loop start returned no process key for ${prKey}; leaving PR converged`);
       }
     } catch (err) {
-      app.log("error", `finalize: could not start merge-loop for ${prKey}; leaving PR converged`, {
+      app.log.error(`finalize: could not start merge-loop for ${prKey}; leaving PR converged`, {
         err: String(err),
       });
     }

package/workers/merge/worker.test.ts

@@ -6,6 +6,7 @@
 // token transport and stubs `globalThis.fetch` so the single-PR GET reports `merged: true`.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 
 function fakeApp() {
@@ -36,7 +37,7 @@ function fakeApp() {
           };
         },
       },
-      log: () => undefined,
+      log: noopLog(),
       engine: {},
     } as any,
     stores,

package/workers/record-plan/worker.ts

@@ -83,7 +83,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     });
     waveOf = new Map();
     for (const t of tasks) waveOf.set(t.id, 0);
-    app.log("warn", `record-plan: ${planKey} plan not levelizable, running flat`, {
+    app.log.warn(`record-plan: ${planKey} plan not levelizable, running flat`, {
       err: err.message,
     });
   }

package/workers/record-plan-review/worker.test.ts

@@ -8,6 +8,7 @@
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
 import { BpmnError } from "@nanobpm/urban";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview } from "../../app/plan.ts";
 
@@ -28,7 +29,7 @@ function fakeApp(existing: PlanReview[] = []) {
         };
       },
     },
-    log: () => {},
+    log: noopLog(),
     _rows: rows,
   } as any;
 }

package/workers/record-plan-review/worker.ts

@@ -92,7 +92,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // `PLAN_REJECTED`, so the engine parks the instance on an incident rather than dispatching an
   // un-approved plan. The round is 0-based, so `round + 1 >= cap` is the last permitted round.
   if (round + 1 >= MAX_PLAN_REVIEW_ROUNDS) {
-    app.log("error", `record-plan-review: ${planKey} not approved after ${MAX_PLAN_REVIEW_ROUNDS} round(s)`, {
+    app.log.error(`record-plan-review: ${planKey} not approved after ${MAX_PLAN_REVIEW_ROUNDS} round(s)`, {
       round,
     });
     throw new BpmnError(
@@ -102,7 +102,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   }
 
   // Otherwise loop: the planner revises against this round's findings.
-  app.log("info", `record-plan-review: ${planKey} round ${round} — revise`, { approved: false });
+  app.log.info(`record-plan-review: ${planKey} round ${round} — revise`, { approved: false });
   return { planApproved: false, planFindings: roundFindings };
 };
 

package/workers/record-results/worker.test.ts

@@ -9,6 +9,7 @@
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
 import { BpmnError } from "@nanobpm/urban";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 import type { PlanTaskStatus } from "../../app/plan.ts";
 
@@ -45,7 +46,7 @@ function fakeApp(rows: Row[]) {
         };
       },
     },
-    log: () => {},
+    log: noopLog(),
     _plans: plans,
   } as any;
 }

package/workers/record-results/worker.ts

@@ -43,7 +43,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
       outcome,
       updated_at: ts,
     });
-    app.log("error", `record-results: ${planKey} finalized with 0 opened PRs`, {
+    app.log.error(`record-results: ${planKey} finalized with 0 opened PRs`, {
       taskCount: rows.length,
     });
     throw new BpmnError("NO_WORK_DISPATCHED", `${planKey}: ${outcome}`);

package/workers/record-trial-merge/worker.test.ts

@@ -1,5 +1,6 @@
 import { test } from "node:test";
 import { assertEquals, assertStringIncludes } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
 import handler, { parseResult } from "./worker.ts";
 
 function fakeApp() {
@@ -19,7 +20,7 @@ function fakeApp() {
         };
       },
     },
-    log: () => undefined,
+    log: noopLog(),
   };
   return { app, inserts };
 }

package/workers/record-trial-merge/worker.ts

@@ -67,7 +67,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       jobKey,
     });
   } catch (err) {
-    app.log("error", `record-trial-merge: audit persist failed for ${planKey} wave ${wave}`, { err: String(err) });
+    app.log.error(`record-trial-merge: audit persist failed for ${planKey} wave ${wave}`, { err: String(err) });
   }
 
   const trialMergeRed = trialMergeDecision(result) === "escalate";

package/workers/record-wave/worker.test.ts

@@ -3,6 +3,7 @@
 // finish the plan with a still-pending task.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 import type { PlanTaskStatus } from "../../app/plan.ts";
 import { _clearMergeProtocolCache } from "../../app/mergeProtocol.ts";
@@ -61,7 +62,7 @@ function fakeApp(rows: Row[]) {
           };
         },
       },
-      log: () => undefined,
+      log: noopLog(),
       engine: {
         createInstance: () => Promise.resolve({ processInstanceKey: "pi" }),
       },

package/workers/record-wave/worker.ts

@@ -164,7 +164,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
           });
         }
       } catch (err) {
-        app.log("error", `record-wave: recording delta for ${taskId} failed`, {
+        app.log.error(`record-wave: recording delta for ${taskId} failed`, {
           err: String(err),
         });
       }
@@ -194,7 +194,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       try {
         await submitPr(app.data, app.engine, parsed, depPrKeys);
       } catch (err) {
-        app.log("error", `record-wave: handoff failed for ${parsed.prKey}`, {
+        app.log.error(`record-wave: handoff failed for ${parsed.prKey}`, {
           err: String(err),
         });
       }
@@ -220,7 +220,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
         if (meta?.headRef) head.headRef = meta.headRef;
         if (meta?.headSha) head.headSha = meta.headSha;
       } catch (err) {
-        app.log("error", `record-wave: pr head fetch failed for ${head.repo}#${head.prNumber}`, { err: String(err) });
+        app.log.error(`record-wave: pr head fetch failed for ${head.repo}#${head.prNumber}`, { err: String(err) });
       }
       return head;
     }));
@@ -253,7 +253,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
           for (const f of files) set.add(f);
           touchesByTask.set(o.taskId, set);
         } catch (err) {
-          app.log("error", `record-wave: pr files fetch failed for ${o.repo}#${o.number}`, {
+          app.log.error(`record-wave: pr files fetch failed for ${o.repo}#${o.number}`, {
             err: String(err),
           });
         }
@@ -261,7 +261,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       const edges = deriveExclusions(touchesByTask);
       if (edges.length > 0) {
         const { inserted, updated } = await recordExclusions(app.data, planKey, edges);
-        app.log("info", `record-wave: merge-exclusion scan wave ${currentWave}`, {
+        app.log.info(`record-wave: merge-exclusion scan wave ${currentWave}`, {
           planKey,
           edges: edges.length,
           inserted,
@@ -269,7 +269,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
         });
       }
     } catch (err) {
-      app.log("error", `record-wave: merge-exclusion scan failed for ${planKey}`, {
+      app.log.error(`record-wave: merge-exclusion scan failed for ${planKey}`, {
         err: String(err),
       });
     }
@@ -291,7 +291,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       updated_at: ts,
     });
   } catch (err) {
-    app.log("error", `record-wave: arming wave gate failed for ${planKey}`, { err: String(err) });
+    app.log.error(`record-wave: arming wave gate failed for ${planKey}`, { err: String(err) });
   }
 
   return {

package/workers/retro-gather/worker.test.ts

@@ -1,6 +1,7 @@
 import { test } from "node:test";
 import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
+import { noopLog } from "../../test/log.ts";
 import { appendEntry } from "../../app/blackboard.ts";
 import handler from "./worker.ts";
 
@@ -38,7 +39,7 @@ test("retro-gather: emits a digest brief + learning count for the plan", async (
   await appendEntry(data, "o/r#3", { author_task: "t1", kind: "learning", body: "regen before build" });
   await appendEntry(data, "o/r#3", { author_task: "t2", kind: "learning", body: "use nextest" });
 
-  const app = { data, log: () => undefined };
+  const app = { data, log: noopLog() };
   const out = await handler(
     { variables: { planKey: "o/r#3" } } as any,
     app as any,
@@ -53,7 +54,7 @@ test("retro-gather: emits a digest brief + learning count for the plan", async (
 test("retro-gather: an epic with no learnings still renders a valid brief", async () => {
   const { data, stores } = memData();
   stores["plans"] = [{ plan_key: "o/r#4", repo: "o/r", issue_url: "", title: null }];
-  const app = { data, log: () => undefined };
+  const app = { data, log: noopLog() };
   const out = await handler(
     { variables: { planKey: "o/r#4" } } as any,
     app as any,

package/workers/retro-gather/worker.ts

@@ -18,7 +18,7 @@ interface Out extends Record<string, unknown> {
 const handler: AppJobHandler<In, Out> = async (job, app) => {
   const planKey = job.variables.planKey;
   const digest = await gatherRetro(app.data, planKey);
-  app.log("info", `retro-gather: ${planKey} — ${digest.counts.learnings} learnings, ${digest.counts.deltas} deltas`);
+  app.log.info(`retro-gather: ${planKey} — ${digest.counts.learnings} learnings, ${digest.counts.deltas} deltas`);
   return {
     retroDigest: renderRetroBrief(digest),
     retroLearnings: digest.counts.learnings,

package/workers/retro-record/worker.test.ts

@@ -1,5 +1,6 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 
 function fakeApp() {
@@ -29,7 +30,7 @@ function fakeApp() {
       },
     };
   }
-  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) }, log: () => undefined };
+  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) }, log: noopLog() };
   return { app, stores };
 }
 

package/workers/retro-record/worker.ts

@@ -53,7 +53,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
     report,
   });
 
-  app.log("info", `retro-record: ${planKey} — status=${status}${prKey ? ` pr=${prKey}` : ""}`);
+  app.log.info(`retro-record: ${planKey} — status=${status}${prKey ? ` pr=${prKey}` : ""}`);
   return {};
 };