@nanobpm/nano-workforce 0.37.0 → 0.38.0

package/operations/answerFeatureEscalation.test.ts

@@ -0,0 +1,100 @@
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+
+const hadSecret = Object.prototype.hasOwnProperty.call(process.env, "NANO_PR_WEBHOOK_SECRET");
+const previousSecret = process.env.NANO_PR_WEBHOOK_SECRET;
+let answerFeatureEscalation: typeof import("./answerFeatureEscalation.ts").default;
+try {
+  process.env.NANO_PR_WEBHOOK_SECRET = " test-secret ";
+  answerFeatureEscalation = (await import("./answerFeatureEscalation.ts")).default;
+} finally {
+  if (hadSecret && previousSecret !== undefined) process.env.NANO_PR_WEBHOOK_SECRET = previousSecret;
+  else delete process.env.NANO_PR_WEBHOOK_SECRET;
+}
+
+function memTable(rows: any[], key: string) {
+  return {
+    find: (where: Record<string, unknown>) =>
+      Promise.resolve(rows.filter((row) => Object.entries(where).every(([field, value]) => row[field] === value))),
+    update: (value: unknown, patch: Record<string, unknown>) => {
+      const row = rows.find((candidate) => candidate[key] === value);
+      if (row) Object.assign(row, patch);
+      return Promise.resolve(row);
+    },
+  };
+}
+
+function memApp(escalations: any[] = []) {
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: "owner/repo#9" }], key: "plan_key" },
+    plan_escalations: { rows: escalations, key: "id" },
+    plan_tasks: { rows: [{ id: 1, plan_key: "owner/repo#9", task_id: "task-1" }], key: "id" },
+  };
+  const published: Record<string, unknown>[] = [];
+  const app = {
+    data: {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    },
+    engine: {
+      publishMessage: (message: Record<string, unknown>) => {
+        published.push(message);
+        return Promise.resolve();
+      },
+    },
+  } as any as AppApi;
+  return { app, published };
+}
+
+function input(body: Record<string, unknown>, secret?: string) {
+  const headers = new Headers();
+  if (secret !== undefined) headers.set("x-hook-secret", secret);
+  return {
+    req: {
+      method: "POST",
+      path: "/app/api/hooks/feature-answer",
+      query: new URLSearchParams(),
+      headers,
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+test("rejects a request without the configured hook secret", async () => {
+  const { app } = memApp();
+  const result = await answerFeatureEscalation(input({ corrKey: "owner/repo#9:task-1", answer: "yes" }), app) as any;
+  assertEquals(result.status, 401);
+  assertEquals(result.body, { ok: false, error: "unauthorized" });
+});
+
+test("derives corrKey from plan + task and maps an answered escalation to 200", async () => {
+  const { app, published } = memApp([{
+    id: 1,
+    plan_key: "owner/repo#9",
+    task_id: "task-1",
+    corr_key: "owner/repo#9:task-1",
+    question: "Proceed?",
+    status: "open",
+  }]);
+  const result = await answerFeatureEscalation(
+    input({ plan: "owner/repo#9", task: "task-1", answer: " yes " }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 200);
+  assertEquals(result.body.ok, true);
+  assertEquals(published[0]?.correlationKey, "owner/repo#9:task-1");
+  assertEquals((published[0]?.variables as Record<string, unknown>).answer, "yes");
+});
+
+test("maps an unmatched corrKey to 404", async () => {
+  const { app } = memApp();
+  const result = await answerFeatureEscalation(
+    input({ corrKey: "owner/repo#9:missing", answer: "yes" }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 404);
+  assertEquals(result.body.ok, false);
+});

package/operations/answerFeatureEscalation.ts

@@ -0,0 +1,49 @@
+// POST /app/api/hooks/feature-answer → operationId `answerFeatureEscalation` (ADR 0059 webhook
+// operation; was the `/hooks/feature-answer` action). Answers an implementation-phase task
+// escalation out of band (optional shared-secret guard via X-Hook-Secret, enforced only when
+// NANO_PR_WEBHOOK_SECRET is set — mirrors the operator control surface), issue #25. Lets an
+// 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:
+//   { "corrKey": "owner/repo#12:task-3", "answer": "…" }
+//   { "plan": "owner/repo#12", "task": "task-3", "answer": "…" }
+import { defineOperation } from "@nanobpm/urban";
+import { answerTaskEscalation, featureCorrKey } from "../app/plan.ts";
+import { envVar } from "../app/version.ts";
+
+const WEBHOOK_SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+interface Body {
+  corrKey?: unknown;
+  plan?: unknown;
+  task?: unknown;
+  answer?: unknown;
+}
+
+export default defineOperation<
+  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
+  { ok: boolean } & Record<string, unknown>
+>("answerFeatureEscalation", async ({ req, body }, app) => {
+  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_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" } };
+
+  const corrKey = str(b.corrKey) || (str(b.plan) && str(b.task) ? featureCorrKey(str(b.plan), str(b.task)) : "");
+  if (!corrKey) {
+    return {
+      status: 400,
+      body: { ok: false, error: "provide corrKey, or both plan (owner/repo#N) and task" },
+    };
+  }
+
+  const r = await answerTaskEscalation(app.data, app.engine, corrKey, answer);
+  return { status: r.ok ? 200 : 404, body: r };
+});

package/operations/appendBlackboard.ts

@@ -0,0 +1,61 @@
+// POST /app/api/hooks/blackboard?token=<capabilityToken> → operationId `appendBlackboard` (ADR 0059
+// webhook operation; was the POST half of the `/hooks/blackboard` action; Tier 1, issues #51 / #49 D4).
+//
+// The per-plan capability token (query string) IS the credential (see readBlackboard). An unknown
+// token is a 404 (never leaks which plans exist).
+//
+//   POST → append one entry: { author_task?, kind?, files?, body, wave?, dedupe_key? }. Idempotent
+//          on (plan, dedupe_key). Returns { id, inserted, conflicts } — `conflicts` lists prior
+//          sibling `file-claim`s on the same file(s) (advisory first-writer-wins; never a lock).
+import { defineOperation } from "@nanobpm/urban";
+import type { ClaimConflict } from "../app/blackboard.ts";
+import {
+  appendEntry,
+  detectFileClaimConflicts,
+  normalizeKind,
+  planKeyForToken,
+} from "../app/blackboard.ts";
+
+export default defineOperation<
+  { params: Record<string, string>; query: { token?: string }; body: Record<string, unknown> },
+  { id: number; inserted: boolean; conflicts: ClaimConflict[] } | { error: string }
+>("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" } };
+
+  const b = body ?? {};
+  const text = typeof b.body === "string" ? b.body.trim() : "";
+  if (!text) return { status: 400, body: { error: "'body' (the note text) is required" } };
+  const kind = normalizeKind(b.kind);
+  const files = Array.isArray(b.files) ? b.files.map(String) : [];
+  // Normalize once (trim + default to "system") so the value we send to appendEntry matches the
+  // value we send to detectFileClaimConflicts. Otherwise an omitted/blank author_task is stored as
+  // "system" but conflict detection sees "", and the caller's own prior "system" claims are wrongly
+  // reported as sibling conflicts.
+  const author_task = (typeof b.author_task === "string" ? b.author_task.trim() : "") || "system";
+  const res = await appendEntry(app.data, planKey, {
+    author_task,
+    kind,
+    files,
+    body: text,
+    wave: typeof b.wave === "number" ? b.wave : null,
+    dedupe_key: typeof b.dedupe_key === "string" ? b.dedupe_key : undefined,
+  });
+  // Advisory conflict-of-intent: surface prior sibling claims on the same file(s). Computed AFTER
+  // the append and filtered to claims strictly before ours (id < res.id), so first-writer-wins is
+  // decided by insertion order — a sibling that raced a claim in between is still caught, and our
+  // own just-written row is never reported. Never blocks the append — the agent decides how to react.
+  const conflicts = kind === "file-claim"
+    ? await detectFileClaimConflicts(app.data, planKey, {
+      author_task,
+      files,
+      beforeId: Number(res.id),
+    })
+    : [];
+  return {
+    status: res.inserted ? 201 : 200,
+    body: { id: Number(res.id), inserted: res.inserted, conflicts },
+  };
+});

package/{actions → operations}/blackboard.test.ts

@@ -1,8 +1,10 @@
-// Tests for the /hooks/blackboard endpoint (Tier 1, issues #51 / #49 D4).
+// Tests for the /app/api/hooks/blackboard operations `readBlackboard` (GET) + `appendBlackboard`
+// (POST) (ADR 0059; Tier 1, issues #51 / #49 D4).
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
-import handler from "./blackboard.ts";
+import readBlackboard from "./readBlackboard.ts";
+import appendBlackboard from "./appendBlackboard.ts";
 
 function memApp(): { app: AppApi; stores: Record<string, any[]> } {
   const stores: Record<string, any[]> = {};
@@ -34,7 +36,7 @@ function memApp(): { app: AppApi; stores: Record<string, any[]> } {
 function req(method: string, query: Record<string, string>) {
   return {
     method,
-    path: "/hooks/blackboard",
+    path: "/app/api/hooks/blackboard",
     query: new URLSearchParams(query),
     headers: new Headers(),
     text: async () => "",
@@ -47,7 +49,17 @@ async function call(
   query: Record<string, string>,
   body?: unknown,
 ) {
-  const res = await handler({ req: req(method, query) as any, body }, app);
+  // Method routing is the runtime's job; here we dispatch to the delegate the spec mounts per verb.
+  // Be explicit so an unexpected method fails loudly rather than silently running the POST delegate.
+  const handler =
+    method === "GET"
+      ? readBlackboard
+      : method === "POST"
+        ? appendBlackboard
+        : (() => {
+            throw new Error(`blackboard test helper: unsupported method ${method}`);
+          })();
+  const res = await handler({ req: req(method, query) as any, params: {}, query: {}, body } as any, app);
   return res as any;
 }
 
@@ -179,9 +191,3 @@ test("POST a non-file-claim carries no conflicts", async () => {
   const res = await call(app, "POST", { token: "tok" }, { author_task: "t", kind: "note", body: "fyi" });
   assertEquals(res.body.conflicts, []);
 });
-
-test("unsupported method → 405", async () => {
-  const { app } = memApp();
-  await seedPlan(app, "o/r#1", "tok");
-  assertEquals((await call(app, "DELETE", { token: "tok" })).status, 405);
-});

package/{actions/abandon.test.ts → operations/checkAbandon.test.ts}

@@ -1,8 +1,8 @@
-// Tests for the GET /hooks/abandon endpoint (issue #76).
+// Tests for the GET /app/api/hooks/abandon operation `checkAbandon` (ADR 0059; issue #76).
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
-import handler from "./abandon.ts";
+import handler from "./checkAbandon.ts";
 
 function memApp(): { app: AppApi } {
   const stores: Record<string, any[]> = {};
@@ -25,7 +25,7 @@ function memApp(): { app: AppApi } {
 function req(method: string, query: Record<string, string>) {
   return {
     method,
-    path: "/hooks/abandon",
+    path: "/app/api/hooks/abandon",
     query: new URLSearchParams(query),
     headers: new Headers(),
     text: async () => "",
@@ -33,7 +33,7 @@ function req(method: string, query: Record<string, string>) {
 }
 
 async function call(app: AppApi, method: string, query: Record<string, string>) {
-  const res = await handler({ req: req(method, query) as any, body: undefined }, app);
+  const res = await handler({ req: req(method, query) as any, params: {}, query: {}, body: undefined }, app);
   return res as any;
 }
 
@@ -73,13 +73,7 @@ test("token via header is accepted", async () => {
   await seedPr(app, "o/r#1", "tok", "abandoned");
   const r = req("GET", {});
   r.headers.set("x-abandon-token", "tok");
-  const res = await handler({ req: r as any, body: undefined }, app) as any;
+  const res = await handler({ req: r as any, params: {}, query: {}, body: undefined }, app) as any;
   assertEquals(res.status, 200);
   assertEquals(res.body.abandoned, true);
 });
-
-test("non-GET → 405", async () => {
-  const { app } = memApp();
-  await seedPr(app, "o/r#1", "tok", "converging");
-  assertEquals((await call(app, "POST", { token: "tok" })).status, 405);
-});

package/{actions/abandon.ts → operations/checkAbandon.ts}

@@ -1,4 +1,5 @@
-// GET /hooks/abandon?token=<capabilityToken> — the cooperative abandon check (issue #76).
+// GET /app/api/hooks/abandon?token=<capabilityToken> → operationId `checkAbandon` (ADR 0059
+// webhook operation; was the `/hooks/abandon` action, issue #76).
 //
 // A DIRECT side-channel for a running `senior:*` agent to learn whether its run was cancelled
 // before it performs an irreversible side effect (push / open PR / request review / merge). The
@@ -8,16 +9,16 @@
 //
 //   GET → { prKey, status, abandoned }  — `abandoned` is derived from `pull_requests.status`,
 //          which Urban's cancel primitive sets to 'abandoned' on cancel. `true` ⇒ the agent must stop.
-import type { ActionHandler } from "@nanobpm/urban";
+import { defineOperation } from "@nanobpm/urban";
 import { abandonStatusForToken } from "../app/abandon.ts";
 
-const handler: ActionHandler = async ({ req }, app) => {
-  if (req.method !== "GET") return { status: 405, body: { error: "method not allowed (use GET)" } };
+export default defineOperation<
+  { params: Record<string, string>; query: { token?: string }; body: unknown },
+  { prKey: string; status: string; abandoned: boolean } | { error: string }
+>("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" } };
   return { status: 200, body: state };
-};
-
-export default handler;
+});

package/operations/listActivePrs.ts

@@ -3,7 +3,7 @@
 // external automation harness can see active work — and grab a `processKey` to cancel — without
 // opening the DB or the UI. Read-only projection over the datasource.
 //
-// The runtime validates the (empty) request against openapi.json; the optional shared-secret guard
+// The runtime validates the (empty) request against openapi.yaml; the optional shared-secret guard
 // stays HERE (the runtime does not enforce OpenAPI `security`): when NANO_PR_WEBHOOK_SECRET is set,
 // callers must present it via the x-hook-secret header. Unset → open (unchanged default).
 import { defineOperation } from "@nanobpm/urban";

package/operations/postMessage.ts

@@ -5,7 +5,7 @@
 // token, then re-surface the next open escalation. Any other message falls back to a plain
 // publishMessage.
 //
-// The runtime validates the body against openapi.json (`name` is required, so a missing name is a 400
+// The runtime validates the body against openapi.yaml (`name` is required, so a missing name is a 400
 // for free); this delegate keeps the message-name dispatch — the discriminator + downstream behavior
 // is app logic, not something the JSON schema can express.
 import { defineOperation } from "@nanobpm/urban";

package/operations/readBlackboard.ts

@@ -0,0 +1,29 @@
+// GET /app/api/hooks/blackboard?token=<capabilityToken> → operationId `readBlackboard` (ADR 0059
+// webhook operation; was the GET half of the `/hooks/blackboard` action; Tier 1, issues #51 / #49 D4).
+//
+// A DIRECT side-channel for agents, distinct from the c8ctl-nano activation/completion channel. The
+// per-plan capability token (query string) IS the credential: it scopes every read to exactly one
+// plan, so no shared secret is needed — the agent curls the exact URL it was handed in its prompt.
+// An unknown token is a 404 (never leaks which plans exist).
+//
+//   GET → { planKey, entries: [ { id, author_task, kind, files, body, wave, created_at } ], cursor }
+//          optional ?since=<id> returns only entries with id > since (incremental poll). `cursor` is
+//          the plan's current head id; pass it back as `since` on the next poll (Tier 2).
+import { defineOperation } from "@nanobpm/urban";
+import type { BlackboardPage } from "../app/blackboard.ts";
+import { planKeyForToken, readBlackboardPage } from "../app/blackboard.ts";
+
+export default defineOperation<
+  { params: Record<string, string>; query: { token?: string; since?: string }; body: unknown },
+  (BlackboardPage & { planKey: string }) | { error: string }
+>("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" } };
+
+  const rawSince = req.query.get("since");
+  const since = rawSince != null && /^\d+$/.test(rawSince) ? Number(rawSince) : undefined;
+  const { entries, cursor } = await readBlackboardPage(app.data, planKey, { since });
+  return { status: 200, body: { planKey, entries, cursor } };
+});

package/operations/startAndMessage.test.ts

@@ -1,6 +1,8 @@
 // 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 runtime's schema validation (required `variables`/`name`) is exercised by urban's
+// 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.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
@@ -21,14 +23,14 @@ function input(body: any) {
 }
 
 test("startConvergenceLoop → 400 on an unparseable PR reference", async () => {
-  const res = await startConvergenceLoop(input({ variables: { pr: "not a pr" } }), app);
+  const res = await startConvergenceLoop(input({ pr: "not a pr" }), app);
   const r = res as any;
   assertEquals(r.status, 400);
   assertEquals(typeof r.body.error, "string");
 });
 
 test("startPlanFanout → 400 on an unparseable issue reference", async () => {
-  const res = await startPlanFanout(input({ variables: { issue: "" } }), app);
+  const res = await startPlanFanout(input({ issue: "" }), app);
   const r = res as any;
   assertEquals(r.status, 400);
   assertEquals(typeof r.body.error, "string");

package/operations/startConvergenceLoop.ts

@@ -1,28 +1,34 @@
-// POST /app/api/actions/start/convergence-loop → operationId `startConvergenceLoop` (ADR 0058, base /app/api).
-// Replaces the hand-rolled action that overrode the generic "start process" palette action: parse the
-// PR reference and register/refresh the PR aggregate (idempotent on prKey) before starting the loop.
+// POST /app/api/actions/start/convergence-loop → operationId `startConvergenceLoop` (ADR 0058/0059,
+// base /app/api). The ONE door for starting a convergence loop — the page's "Start review" form, an
+// external webhook relay, a CI job, and Swagger all POST here. Parse the PR reference and
+// register/refresh the PR aggregate (idempotent on prKey) before starting the loop.
 //
-// The runtime validates the body against openapi.json (a `variables` object is required); 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.
+// The request body is FLAT (`{ pr | url, dependsOn?, maxRounds? }`), 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.
 import { defineOperation } from "@nanobpm/urban";
 import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
 
 interface Body {
-  variables?: { pr?: string; url?: string; dependsOn?: unknown; maxRounds?: unknown };
+  pr?: string;
+  url?: string;
+  dependsOn?: unknown;
+  maxRounds?: unknown;
 }
 
 export default defineOperation<
   { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
   { prKey: string; alreadyRunning?: boolean; processKey?: string | null } | { error: string }
 >("startConvergenceLoop", async ({ body }, app) => {
-  const vars = body?.variables ?? {};
-  const raw = String(vars.pr ?? vars.url ?? "").trim();
+  const b = body ?? {};
+  const raw = String(b.pr ?? b.url ?? "").trim();
   const parsed = parsePr(raw);
   if (!parsed) {
     return { status: 400, body: { error: "could not parse PR (use owner/repo#123 or a PR URL)" } };
   }
-  const dependsOn = Array.isArray(vars.dependsOn) ? vars.dependsOn.map((d) => String(d)) : [];
-  const maxRounds = clampRounds(vars.maxRounds, MAX_ROUNDS);
+  const dependsOn = Array.isArray(b.dependsOn) ? b.dependsOn.map((d) => String(d)) : [];
+  const maxRounds = clampRounds(b.maxRounds, MAX_ROUNDS);
   return { status: 202, body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds) };
 });

package/operations/startPlanFanout.ts

@@ -1,12 +1,18 @@
-// POST /app/api/actions/start/plan-fanout → operationId `startPlanFanout` (ADR 0058, base /app/api).
-// Replaces the hand-rolled action that overrode the generic "start process" palette action: parse the
-// issue reference and register/refresh the plan aggregate (idempotent on planKey) before starting the
-// planning fan-out. An unparseable reference is a 400; an already-running plan short-circuits.
+// POST /app/api/actions/start/plan-fanout → operationId `startPlanFanout` (ADR 0058/0059, base
+// /app/api). The ONE door for starting a planning fan-out — the epic page's "Plan & implement" form,
+// an external webhook relay (a GitHub relay on issue open/label), a CI job, and Swagger all POST
+// here. Parse the issue reference and register/refresh the plan aggregate (idempotent on planKey)
+// before starting the planning fan-out. An unparseable reference is a 400; an already-running plan
+// 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.
 import { defineOperation } from "@nanobpm/urban";
 import { parseIssue, startPlan } from "../app/plan.ts";
 
 interface Body {
-  variables?: { issue?: string; url?: string };
+  issue?: string;
+  url?: string;
 }
 
 type Res =
@@ -17,8 +23,8 @@ export default defineOperation<
   { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
   Res
 >("startPlanFanout", async ({ body }, app) => {
-  const vars = body?.variables ?? {};
-  const raw = String(vars.issue ?? vars.url ?? "").trim();
+  const b = body ?? {};
+  const raw = String(b.issue ?? b.url ?? "").trim();
   const parsed = parseIssue(raw);
   if (!parsed) {
     return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.37.0",
+  "version": "0.38.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",
@@ -40,11 +40,11 @@
     "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
     "dev": "urban dev",
     "test": "node --experimental-strip-types --test",
-    "lint": "biome check app operations actions workers pages components scripts main.ts",
-    "lint:fix": "biome check --write app operations actions workers pages components scripts main.ts"
+    "lint": "biome check app operations workers pages components scripts main.ts",
+    "lint:fix": "biome check --write app operations workers pages components scripts main.ts"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.33.0"
+    "@nanobpm/urban": "^0.35.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/pages/epic.page.json

@@ -33,7 +33,7 @@
       "props": {
         "title": "Hand an issue to the fleet",
         "submitLabel": "Plan & implement",
-        "action": { "path": "/app/api/actions/start/plan-fanout" },
+        "action": { "path": "/app/api/actions/start/plan-fanout", "body": "{{form}}" },
         "fields": [
           { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" }
         ]

package/pages/home.page.json

@@ -33,7 +33,7 @@
       "props": {
         "title": "Submit a pull request",
         "submitLabel": "Start review",
-        "action": { "path": "/app/api/actions/start/convergence-loop" },
+        "action": { "path": "/app/api/actions/start/convergence-loop", "body": "{{form}}" },
         "fields": [
           { "key": "pr", "label": "owner/repo#123 or a GitHub PR URL", "type": "text" },
           { "key": "maxRounds", "label": "Max review rounds (blank = fleet default)", "type": "number" }

package/workers/persist-task-escalation/worker.ts

@@ -9,7 +9,7 @@
 //
 // The process then parks the child at the `feature-escalation-answered` message
 // catch (correlationKey `<plan_key>:<task_id>`). Answering it (page form or
-// `/hooks/feature-answer`) resumes the child, which re-dispatches the SAME task.
+// `/app/api/hooks/feature-answer`) resumes the child, which re-dispatches the SAME task.
 //
 // Retry-safe: if an open escalation already exists for this corr key (a worker
 // re-activation before the wait subscription opened), it is UPDATED, not

package/actions/blackboard.ts

@@ -1,77 +0,0 @@
-// GET/POST /hooks/blackboard?token=<capabilityToken> — the epic coordination blackboard endpoint
-// (Tier 1, issues #51 / #49 D4).
-//
-// This is a DIRECT side-channel for agents, distinct from the c8ctl-nano activation/completion
-// channel. The per-plan capability token (query string) IS the credential: it scopes every read
-// and write to exactly one plan, so no shared secret is needed — the agent curls the exact URL it
-// was handed in its prompt. An unknown token is a 404 (never leaks which plans exist).
-//
-//   GET  → { planKey, entries: [ { id, author_task, kind, files, body, wave, created_at } ], cursor }
-//          optional ?since=<id> returns only entries with id > since (incremental poll). `cursor` is
-//          the plan's current head id; pass it back as `since` on the next poll (Tier 2).
-//   POST → append one entry: { author_task?, kind?, files?, body, wave?, dedupe_key? }. Idempotent
-//          on (plan, dedupe_key). Returns { id, inserted, conflicts } — `conflicts` lists prior
-//          sibling `file-claim`s on the same file(s) (advisory first-writer-wins; never a lock).
-import type { ActionHandler } from "@nanobpm/urban";
-import {
-  appendEntry,
-  detectFileClaimConflicts,
-  normalizeKind,
-  planKeyForToken,
-  readBlackboardPage,
-} from "../app/blackboard.ts";
-
-const handler: ActionHandler = 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 (req.method === "GET") {
-    const rawSince = req.query.get("since");
-    const since = rawSince != null && /^\d+$/.test(rawSince) ? Number(rawSince) : undefined;
-    const { entries, cursor } = await readBlackboardPage(app.data, planKey, { since });
-    return { status: 200, body: { planKey, entries, cursor } };
-  }
-
-  if (req.method === "POST") {
-    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const b = (body ?? {}) as Record<string, unknown>;
-    const text = typeof b.body === "string" ? b.body.trim() : "";
-    if (!text) return { status: 400, body: { error: "'body' (the note text) is required" } };
-    const kind = normalizeKind(b.kind);
-    const files = Array.isArray(b.files) ? b.files.map(String) : [];
-    // Normalize once (trim + default to "system") so the value we send to appendEntry matches the
-    // value we send to detectFileClaimConflicts. Otherwise an omitted/blank author_task is stored as
-    // "system" but conflict detection sees "", and the caller's own prior "system" claims are wrongly
-    // reported as sibling conflicts.
-    const author_task = (typeof b.author_task === "string" ? b.author_task.trim() : "") || "system";
-    const res = await appendEntry(app.data, planKey, {
-      author_task,
-      kind,
-      files,
-      body: text,
-      wave: typeof b.wave === "number" ? b.wave : null,
-      dedupe_key: typeof b.dedupe_key === "string" ? b.dedupe_key : undefined,
-    });
-    // Advisory conflict-of-intent: surface prior sibling claims on the same file(s). Computed AFTER
-    // the append and filtered to claims strictly before ours (id < res.id), so first-writer-wins is
-    // decided by insertion order — a sibling that raced a claim in between is still caught, and our
-    // own just-written row is never reported. Never blocks the append — the agent decides how to react.
-    const conflicts = kind === "file-claim"
-      ? await detectFileClaimConflicts(app.data, planKey, {
-        author_task,
-        files,
-        beforeId: Number(res.id),
-      })
-      : [];
-    return {
-      status: res.inserted ? 201 : 200,
-      body: { id: Number(res.id), inserted: res.inserted, conflicts },
-    };
-  }
-
-  return { status: 405, body: { error: "method not allowed (use GET or POST)" } };
-};
-
-export default handler;