@nanobpm/nano-workforce 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.44.0](https://github.com/nanobpm/nano-workforce/compare/v0.43.0...v0.44.0) (2026-08-11)
+
+
+### Features
+
+* **merge-loop:** wait on a blocking PR instead of escalating to a human ([#122](https://github.com/nanobpm/nano-workforce/issues/122)) ([aec738f](https://github.com/nanobpm/nano-workforce/commit/aec738f165df5a216b9094b4eb9b5b6d4a7ac419))
+
+# [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/SPEC.md

@@ -368,11 +368,21 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   exhausted, the agent reports `blocked`, or the branch is in `conflict` does it fall
   through to the human escalation path.
 
+- **Discovered dependency** — a `senior:fix-ci` or `senior:rebase` agent may find that
+  the PR cannot land because **another PR must merge first** (a required linked-issue
+  gate a sibling PR will close, a stacked base PR, or a `Depends-on:` the agent read
+  from the PR/issue text). That is an ordering **wait, not a human decision**: the
+  agent returns `status: "waiting-on-pr"` with a `dependsOn` list of `owner/repo#N`
+  refs. `pr.record-dependency` appends those edges to `pr_dependencies` and parks the
+  PR back at *wait: deps merged*, so the same poller pass lands it automatically once
+  the named PRs merge — no escalation is opened.
+
 - **Dependencies** — `pr_dependencies(pr_key, depends_on_key)` (migration 004).
-  Declared two ways: a `Depends-on: owner/repo#N` line in the PR body (parsed on
-  submit) and/or a `dependsOn` array on the submit request. `merge-loop` parks at
-  *wait: deps merged*; the poller checks each dependency (own tracked row first,
-  else GitHub `merged` state) and publishes `deps-cleared` once all have landed.
+  Declared three ways: a `Depends-on: owner/repo#N` line in the PR body (parsed on
+  submit), a `dependsOn` array on the submit request, and/or **discovered at merge
+  time** by a `fix-ci`/`rebase` agent (`status: "waiting-on-pr"`, above). `merge-loop`
+  parks at *wait: deps merged*; the poller checks each dependency (own tracked row
+  first, else GitHub `merged` state) and publishes `deps-cleared` once all have landed.
 - **Mergeability** — the poller classifies GitHub's `mergeStateStatus`:
   `CLEAN`/`HAS_HOOKS`/`UNSTABLE`/`BEHIND` → `ready`; `DIRTY` → `conflict`;
   `BLOCKED` → `blocked` if a required check is failing, else keep waiting;

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/nano.app.json

@@ -87,6 +87,10 @@
       "taskType": "pr.mark-merged",
       "handler": "workers/mark-merged/worker.ts"
     },
+    {
+      "taskType": "pr.record-dependency",
+      "handler": "workers/record-dependency/worker.ts"
+    },
     {
       "taskType": "pr.record-plan",
       "handler": "workers/record-plan/worker.ts"

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;