@nanobpm/nano-workforce 0.36.0 → 0.38.0

package/operations/listActivePrs.ts

@@ -3,16 +3,15 @@
 // 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";
 import { type ActivePr, activePrs } from "../app/service.ts";
 import { envVar } from "../app/version.ts";
 
-// Cross-runtime env read (Node `process.env` OR Deno `Deno.env`): reading via `process.env` alone
-// would silently disable the guard under Deno/compiled runtimes where `process` is absent, leaving
-// the endpoint open even when NANO_PR_WEBHOOK_SECRET is set. Captured once, at module load.
+// The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
+// the x-hook-secret header. Captured once, at module load.
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
 type Res = { count: number; prs: ActivePr[] } | { error: string };

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,20 +1,20 @@
 // 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 { assertEquals } from "jsr:@std/assert@1";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import startConvergenceLoop from "./startConvergenceLoop.ts";
 import startPlanFanout from "./startPlanFanout.ts";
 import postMessage from "./postMessage.ts";
 
-// deno-lint-ignore no-explicit-any
 const app = {} as any as AppApi;
 
-// deno-lint-ignore no-explicit-any
 function input(body: any) {
   return {
-    // deno-lint-ignore no-explicit-any
     req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as any,
     params: {},
     query: {},
@@ -22,33 +22,29 @@ function input(body: any) {
   };
 }
 
-Deno.test("startConvergenceLoop → 400 on an unparseable PR reference", async () => {
-  const res = await startConvergenceLoop(input({ variables: { pr: "not a pr" } }), app);
-  // deno-lint-ignore no-explicit-any
+test("startConvergenceLoop → 400 on an unparseable PR reference", async () => {
+  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");
 });
 
-Deno.test("startPlanFanout → 400 on an unparseable issue reference", async () => {
-  const res = await startPlanFanout(input({ variables: { issue: "" } }), app);
-  // deno-lint-ignore no-explicit-any
+test("startPlanFanout → 400 on an unparseable issue reference", async () => {
+  const res = await startPlanFanout(input({ issue: "" }), app);
   const r = res as any;
   assertEquals(r.status, 400);
   assertEquals(typeof r.body.error, "string");
 });
 
-Deno.test("postMessage → 400 when name is blank", async () => {
+test("postMessage → 400 when name is blank", async () => {
   const res = await postMessage(input({ name: "" }), app);
-  // deno-lint-ignore no-explicit-any
   const r = res as any;
   assertEquals(r.status, 400);
   assertEquals(r.body.error, "name is required");
 });
 
-Deno.test("postMessage → 400 when escalation-answered lacks a correlationKey", async () => {
+test("postMessage → 400 when escalation-answered lacks a correlationKey", async () => {
   const res = await postMessage(input({ name: "escalation-answered", variables: { answer: "yes" } }), app);
-  // deno-lint-ignore no-explicit-any
   const r = res as any;
   assertEquals(r.status, 400);
   assertEquals(r.body.error, "correlationKey is required");

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,9 +1,12 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.36.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",
+  "imports": {
+    "#test-assert": "./test/assert.ts"
+  },
   "engines": {
     "node": ">=22.6"
   },
@@ -30,19 +33,18 @@
     "upgrade": "node --experimental-strip-types scripts/upgrade-from-pack.ts",
     "check": "urban check",
     "typecheck": "tsc --noEmit",
-    "check:prompts": "deno run -A scripts/check-agent-prompts.ts",
+    "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
     "gen": "urban gen",
     "gen:check": "urban gen --check",
     "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",
     "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
     "dev": "urban dev",
-    "compile": "deno task compile",
-    "test": "deno test -A",
-    "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"
+    "test": "node --experimental-strip-types --test",
+    "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/scripts/check-agent-prompts.test.ts

@@ -4,7 +4,11 @@
 // blank agent-prompt header — ships an effectively prompt-less agent (the root of the empty
 // "(no question provided)" escalations on Magikcraft/nano-bpm #597/#599). These cases assert it
 // fails on each of those shapes and passes on a well-formed app.
-import { assert, assertEquals } from "jsr:@std/assert@1";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
 import { checkAgentPrompts } from "./check-agent-prompts.ts";
 
 const MANIFEST = JSON.stringify({
@@ -16,17 +20,17 @@ function header(value: string): string {
 }
 
 // Build a throwaway app tree and return its root. Each entry maps a repo-relative path to content.
-async function fixture(files: Record<string, string>): Promise<string> {
-  const root = await Deno.makeTempDir({ prefix: "agent-prompts-" });
+function fixture(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "agent-prompts-"));
   for (const [rel, content] of Object.entries(files)) {
-    const abs = `${root}/${rel}`;
-    await Deno.mkdir(abs.slice(0, abs.lastIndexOf("/")), { recursive: true });
-    await Deno.writeTextFile(abs, content);
+    const abs = join(root, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
   }
   return root;
 }
 
-Deno.test("passes when every {{token}} resolves to a non-blank template", async () => {
+test("passes when every {{token}} resolves to a non-blank template", async () => {
   const root = await fixture({
     "nano.app.json": MANIFEST,
     "resources/processes/loop.bpmn": header("{{review-round}}"),
@@ -38,7 +42,7 @@ Deno.test("passes when every {{token}} resolves to a non-blank template", async
   assertEquals(res.resolved, ["review-round"]);
 });
 
-Deno.test("fails when a header references an undeclared template", async () => {
+test("fails when a header references an undeclared template", async () => {
   const root = await fixture({
     "nano.app.json": MANIFEST,
     "resources/processes/loop.bpmn": header("{{does-not-exist}}"),
@@ -49,7 +53,7 @@ Deno.test("fails when a header references an undeclared template", async () => {
   assert(res.errors.some((e) => e.includes("{{does-not-exist}}") && e.includes("no such template")));
 });
 
-Deno.test("fails when the referenced template file is blank (would substitute to nothing)", async () => {
+test("fails when the referenced template file is blank (would substitute to nothing)", async () => {
   const root = await fixture({
     "nano.app.json": MANIFEST,
     "resources/processes/loop.bpmn": header("{{review-round}}"),
@@ -60,7 +64,7 @@ Deno.test("fails when the referenced template file is blank (would substitute to
   assert(res.errors.some((e) => e.includes("empty") && e.includes("review-round")));
 });
 
-Deno.test("fails when a reserved agent-prompt header is blank", async () => {
+test("fails when a reserved agent-prompt header is blank", async () => {
   const root = await fixture({
     "nano.app.json": MANIFEST,
     "resources/processes/loop.bpmn": header(""),
@@ -71,7 +75,7 @@ Deno.test("fails when a reserved agent-prompt header is blank", async () => {
   assert(res.errors.some((e) => e.includes("is empty")));
 });
 
-Deno.test("checks the real repo: all committed agent prompts resolve", () => {
+test("checks the real repo: all committed agent prompts resolve", () => {
   // The guard must be green against the actual app it protects — this is the case CI relies on.
   const repoRoot = decodeURIComponent(new URL("../", import.meta.url).pathname);
   const res = checkAgentPrompts(repoRoot);

package/scripts/layout-bpmn.ts

@@ -1,4 +1,4 @@
-// npm run layout <file.bpmn ...> (or `deno task layout <file.bpmn ...>`) — (re)generate the
+// npm run layout <file.bpmn ...> — (re)generate the
 // bpmndi:BPMNDiagram for one or more BPMN models using the urban toolkit's `layoutBpmn`
 // (bpmn-auto-layout). The semantic model stays authoritative: author the process elements
 // (tasks, gateways, flows, zeebe extensions) and run this to derive an auto-laid-out diagram,
@@ -8,39 +8,18 @@
 // `--check` (npm run layout:check) regenerates the DI in memory and fails with a non-zero exit
 // if any committed diagram is stale, WITHOUT rewriting files — the CI freshness gate that stops
 // a BPMN flow change from merging with an un-regenerated diagram.
+import { readdir, readFile, writeFile } from "node:fs/promises";
 import { layoutBpmn } from "@nanobpm/urban";
 
-// Host-agnostic file I/O: Deno inside a compiled binary, else node:fs under Node — mirrors
-// app/plan.ts's readAsset seam so this runs the same under `npm run` and `deno task`.
-// biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-const g = globalThis as {
-  Deno?: {
-    args: string[];
-    exit(c: number): never;
-    readDir(p: string): AsyncIterable<{ name: string; isFile: boolean }>;
-    readTextFile(p: string): Promise<string>;
-    writeTextFile(p: string, s: string): Promise<void>;
-  };
-};
-
 async function readText(path: string): Promise<string> {
-  return g.Deno?.readTextFile
-    ? await g.Deno.readTextFile(path)
-    : await (await import("node:fs/promises")).readFile(path, "utf8");
+  return await readFile(path, "utf8");
 }
 async function writeText(path: string, text: string): Promise<void> {
-  if (g.Deno?.writeTextFile) return await g.Deno.writeTextFile(path, text);
-  await (await import("node:fs/promises")).writeFile(path, text, "utf8");
+  await writeFile(path, text, "utf8");
 }
 async function defaultProcessFiles(): Promise<string[]> {
   const dir = "resources/processes";
-  if (g.Deno?.readDir) {
-    const files: string[] = [];
-    for await (const e of g.Deno.readDir(dir)) if (e.isFile && e.name.endsWith(".bpmn")) files.push(`${dir}/${e.name}`);
-    return files.sort();
-  }
-  const fs = await import("node:fs/promises");
-  return (await fs.readdir(dir, { withFileTypes: true }))
+  return (await readdir(dir, { withFileTypes: true }))
     .filter((e) => e.isFile() && e.name.endsWith(".bpmn"))
     .map((e) => `${dir}/${e.name}`)
     .sort();
@@ -54,12 +33,11 @@ const countDi = (xml: string) => ({
 });
 
 function exit(code: number): never {
-  if (g.Deno) return g.Deno.exit(code);
   process.exit(code);
 }
 
 async function main() {
-  const argv = g.Deno?.args ?? process.argv.slice(2);
+  const argv = process.argv.slice(2);
   // `--check` mode: regenerate the DI in memory and fail (non-zero) if it differs from what's
   // committed, WITHOUT rewriting any file. This is the CI freshness gate — it catches a BPMN
   // flow change whose author forgot to re-run `npm run layout`, so a stale diagram can't merge.

package/scripts/pages-contract.test.ts

@@ -10,7 +10,9 @@
 // It also pins the issue #87 surfaces: the plan-review audit log (`plan_reviews`) — which is
 // persisted but was surfaced on no page — must appear on the epic page (flat grid) and inside the
 // home page's plan detail (child grid). Feature coverage so the trace can't silently regress out.
-import { assert } from "jsr:@std/assert@1";
+import { test } from "node:test";
+import { assert } from "#test-assert";
+import { readdirSync, readFileSync } from "node:fs";
 
 // Percent-decode the pathname: `new URL(..).pathname` can contain encoded characters (e.g. a space
 // as `%20`), which `Deno.readDir`/`readTextFile` would fail to resolve. Matches the repo convention
@@ -79,22 +81,21 @@ function splitTopLevel(body: string): string[] {
   return out;
 }
 
-async function loadSchema(): Promise<Map<string, Set<string>>> {
+function loadSchema(): Map<string, Set<string>> {
   const schema = new Map<string, Set<string>>();
   const files: string[] = [];
-  for await (const e of Deno.readDir(`${ROOT}db/migrations`)) {
-    if (e.isFile && e.name.endsWith(".sql")) files.push(e.name);
+  for (const e of readdirSync(`${ROOT}db/migrations`, { withFileTypes: true })) {
+    if (e.isFile() && e.name.endsWith(".sql")) files.push(e.name);
   }
   files.sort(); // migration order doesn't matter for the union, but keep it deterministic
   for (const f of files) {
-    parseSchema(await Deno.readTextFile(`${ROOT}db/migrations/${f}`), schema);
+    parseSchema(readFileSync(`${ROOT}db/migrations/${f}`, "utf8"), schema);
   }
   return schema;
 }
 
 // ---- pages -> datasource references -------------------------------------------------------------
 
-// deno-lint-ignore no-explicit-any
 type Json = any;
 
 interface Ref {
@@ -164,11 +165,11 @@ function collectRefs(page: string, node: Json, out: Ref[]): void {
   for (const v of Object.values(node)) collectRefs(page, v, out);
 }
 
-async function loadRefs(): Promise<Ref[]> {
+function loadRefs(): Ref[] {
   const refs: Ref[] = [];
-  for await (const e of Deno.readDir(`${ROOT}pages`)) {
-    if (!e.isFile || !e.name.endsWith(".page.json")) continue;
-    const page = JSON.parse(await Deno.readTextFile(`${ROOT}pages/${e.name}`));
+  for (const e of readdirSync(`${ROOT}pages`, { withFileTypes: true })) {
+    if (!e.isFile() || !e.name.endsWith(".page.json")) continue;
+    const page = JSON.parse(readFileSync(`${ROOT}pages/${e.name}`, "utf8"));
     collectRefs(e.name, page, refs);
   }
   return refs;
@@ -176,7 +177,7 @@ async function loadRefs(): Promise<Ref[]> {
 
 // ---- guards -------------------------------------------------------------------------------------
 
-Deno.test("every page datasource table exists in the migrations", async () => {
+test("every page datasource table exists in the migrations", async () => {
   const schema = await loadSchema();
   const refs = await loadRefs();
   assert(refs.length > 0, "no datasource references found — collector or pages are broken");
@@ -190,7 +191,7 @@ Deno.test("every page datasource table exists in the migrations", async () => {
   }
 });
 
-Deno.test("every page datasource column exists on its table", async () => {
+test("every page datasource column exists on its table", async () => {
   const schema = await loadSchema();
   const refs = await loadRefs();
   for (const r of refs) {
@@ -206,7 +207,7 @@ Deno.test("every page datasource column exists on its table", async () => {
   }
 });
 
-Deno.test("issue #87: plan_reviews is surfaced on the epic and home pages", async () => {
+test("issue #87: plan_reviews is surfaced on the epic and home pages", async () => {
   const refs = await loadRefs();
   const onEpic = refs.some((r) => r.page === "epic.page.json" && r.table === "plan_reviews");
   const onHome = refs.some((r) => r.page === "home.page.json" && r.table === "plan_reviews");

package/scripts/purge-db.ts

@@ -1,4 +1,4 @@
-// npm run purge (or `deno task purge`) — wipe the app's sqlite datasource so `npm start`
+// npm run purge — wipe the app's sqlite datasource so `npm start`
 // comes up against a fresh schema (the runtime re-applies db/migrations on boot). Deletes the
 // sqlite file and its WAL/SHM sidecars for the `app` source declared in nano.app.json.
 import { rmSync } from "node:fs";

package/scripts/upgrade-from-pack.ts

@@ -1,4 +1,4 @@
-// npm run upgrade (or `deno task upgrade`) — refresh THIS app's source from a newer
+// npm run upgrade — refresh THIS app's source from a newer
 // published pack of @nanobpm/nano-workforce, WITHOUT touching your data.
 //
 // Why this exists: a Console project stamped from the example pack is a one-time

package/test/assert.ts

@@ -0,0 +1,74 @@
+// Node-native test assertions, presenting the small `@std/assert` surface this repo's suite used
+// under Deno so the 35 ported `*.test.ts` files keep their call sites unchanged (only their import
+// line moved to `#test-assert`). Backed by `node:assert/strict`. Semantics intentionally mirror
+// Deno's std/assert (deep structural equality; the throw helpers return the caught error).
+import nodeAssert from "node:assert/strict";
+
+/** Deep structural equality (Deno `assertEquals`). */
+export function assertEquals<T>(actual: T, expected: T, msg?: string): void {
+  nodeAssert.deepStrictEqual(actual, expected, msg);
+}
+
+/** Deep structural inequality (Deno `assertNotEquals`). */
+export function assertNotEquals<T>(actual: T, expected: T, msg?: string): void {
+  nodeAssert.notDeepStrictEqual(actual, expected, msg);
+}
+
+/** Truthiness (Deno `assert`). */
+export function assert(expr: unknown, msg?: string): asserts expr {
+  nodeAssert.ok(expr, msg);
+}
+
+/** Substring containment (Deno `assertStringIncludes`). */
+export function assertStringIncludes(actual: string, expected: string, msg?: string): void {
+  nodeAssert.ok(
+    actual.includes(expected),
+    msg ?? `expected string to contain "${expected}" but got "${actual}"`,
+  );
+}
+
+// The constructor rest is `any[]` so error subclasses with required args (e.g. WaveError(message))
+// satisfy the type — param contravariance rejects a narrower `unknown[]`/`never[]` here.
+type ErrorClass = new (...args: any[]) => Error;
+
+function checkError(error: unknown, ErrorClass?: ErrorClass, msgIncludes?: string): Error {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const gotName = err.constructor.name;
+  if (ErrorClass && !(err instanceof ErrorClass)) {
+    nodeAssert.fail(`expected error to be instance of ${ErrorClass.name}, got ${gotName}`);
+  }
+  if (msgIncludes && !err.message.includes(msgIncludes)) {
+    nodeAssert.fail(`expected error message to include "${msgIncludes}", got "${err.message}"`);
+  }
+  return err;
+}
+
+/** Assert a sync fn throws; optionally check the error type/message. Returns the caught error
+ *  (Deno `assertThrows`). */
+export function assertThrows(
+  fn: () => unknown,
+  ErrorClass?: ErrorClass,
+  msgIncludes?: string,
+): Error {
+  try {
+    fn();
+  } catch (error) {
+    return checkError(error, ErrorClass, msgIncludes);
+  }
+  nodeAssert.fail("expected function to throw, but it did not");
+}
+
+/** Assert an async fn rejects; optionally check the error type/message. Returns the caught error
+ *  (Deno `assertRejects`). */
+export async function assertRejects(
+  fn: () => Promise<unknown>,
+  ErrorClass?: ErrorClass,
+  msgIncludes?: string,
+): Promise<Error> {
+  try {
+    await fn();
+  } catch (error) {
+    return checkError(error, ErrorClass, msgIncludes);
+  }
+  nodeAssert.fail("expected promise to reject, but it resolved");
+}

package/tsconfig.json

@@ -37,11 +37,14 @@
   },
   "include": [
     "main.ts",
+    "app/**/*.ts",
+    "operations/**/*.ts",
     "workers/**/*.ts",
     "lib/**/*.ts",
     "src/**/*.ts",
     "scripts/**/*.ts",
-    "actions/**/*.ts"
+    "actions/**/*.ts",
+    "test/**/*.ts"
   ],
   "exclude": [
     "node_modules",

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