@nanobpm/nano-workforce 0.150.0 → 0.150.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.150.1](https://github.com/nanobpm/nano-workforce/compare/v0.150.0...v0.150.1) (2026-08-28)
+
+### Bug Fixes
+
+* **startFeature:** thread probePollEvery through the readiness gate ([#579](https://github.com/nanobpm/nano-workforce/issues/579)) ([#582](https://github.com/nanobpm/nano-workforce/issues/582)) ([d8f7739](https://github.com/nanobpm/nano-workforce/commit/d8f773907e1c66292fa6799f70e8d957f6f5f626)), closes [#295](https://github.com/nanobpm/nano-workforce/issues/295)
+
 ## [0.150.0](https://github.com/nanobpm/nano-workforce/compare/v0.149.0...v0.150.0) (2026-08-28)
 
 ### Features

package/operations/startFeature.readiness.integration.test.ts

@@ -0,0 +1,195 @@
+// Integration coverage for the intake READINESS gate (issue #295) driven through the operation EDGE —
+// `startFeature` → `parseFeatureReadiness` → the started run's variables. The unit tests in
+// app/featureReadiness.test.ts already prove the parser derives `probes`/`probeTimeout`/`probePollEvery`
+// correctly in isolation, and app/feature.test.ts proves `startFeature` seeds them onto the run. What
+// nothing asserted — and what regressed in issue #579 — is that the OPERATION threads the parser's
+// output through to `startFeature` intact: a too-narrow local dropped `probePollEvery` on the floor, so
+// every gated start (`blockedOn`/`readiness`) 500'd on startFeature's invariant. This file locks the
+// composed door behaviour: a gated start returns 202 and the run it fans out carries non-blank bounds.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { resetDefaultBranchCache } from "../app/github.ts";
+import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import startFeature from "./startFeature.ts";
+
+// ── in-memory github model (default branch = main, so `confirmDefaultBase` is required) ───────────
+function githubFetch(repo: string) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    const json = (obj: unknown, status = 200) =>
+      new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+    if (method === "GET" && path === `/repos/${repo}`) return Promise.resolve(json({ default_branch: "main" }));
+    const refPrefix = `/repos/${repo}/git/ref/heads/`;
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      if (branch !== "main") return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(json({ ref: `refs/heads/${branch}`, object: { sha: `${branch}-sha` } }));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(repo: string, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "tok";
+  resetDefaultBranchCache();
+  globalThis.fetch = githubFetch(repo) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    resetDefaultBranchCache();
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+}
+
+// ── in-memory app (data + engine) ────────────────────────────────────────────
+// `started` records each engine.createInstance call so a test can assert the run's seeded variables.
+function makeApp() {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  const started: { processDefinitionId?: string; variables?: Record<string, unknown> }[] = [];
+  const table = (name: string, key: string) => {
+    const rows = tables.get(name) ?? (() => {
+      const fresh: Record<string, unknown>[] = [];
+      tables.set(name, fresh);
+      return fresh;
+    })();
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      findOne: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const app = {
+    data: { table: withTrackingViews(table) },
+    engine: {
+      createInstance: (req: { processDefinitionId?: string; variables?: Record<string, unknown> }) => {
+        started.push(req);
+        return Promise.resolve({ processInstanceKey: "PI-F1" });
+      },
+    },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, started };
+}
+
+function input(body: unknown) {
+  return {
+    req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+const REPO = "owner/repo";
+const GATED_BASE = { baseBranch: "main", confirmDefaultBase: true } as const;
+
+// ── the #579 regression: a gated start must reach 202 AND thread the bounds through ───────────────
+
+test("blockedOn gate → 202 and the started run carries non-blank probeTimeout + probePollEvery", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [`${REPO}#578`] }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+    const v = started[0].variables as Record<string, unknown>;
+    // The regressed field: it was dropped by a too-narrow local, so the run seeded a blank cadence and
+    // startFeature's invariant threw → 500. Both bounds must arrive non-blank.
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+    assertEquals(Array.isArray(v.readinessProbes) && (v.readinessProbes as unknown[]).length === 1, true);
+  });
+});
+
+test("explicit readiness descriptor list → 202 with both bounds threaded to the run", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({
+        issue: `${REPO}#577`,
+        ...GATED_BASE,
+        readiness: [{ kind: "command", target: "gh api repos/owner/repo/issues/578 --jq .state", match: { stdoutIncludes: "closed" } }],
+      }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+  });
+});
+
+test("blockedOn + consumerPackage (capability edge) → 202 with both bounds threaded", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [`${REPO}#578`], consumerPackage: "@nanobpm/engine-wasm" }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+    const probes = v.readinessProbes as { kind?: string }[];
+    assertEquals(probes[0]?.kind, "capability");
+  });
+});
+
+// ── regression: an UNGATED start still passes null/absent for both bounds (gate skipped) ──────────
+
+test("no readiness ⇒ 202 and the run seeds null probeTimeout + probePollEvery (gate skipped)", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(input({ issue: `${REPO}#577`, ...GATED_BASE }), app)) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals(v.probeTimeout, null);
+    assertEquals(v.probePollEvery, null);
+    assertEquals(v.readinessProbes, null);
+  });
+});
+
+// ── a malformed gate is a caller-meaningful 400, never a 500 ──────────────────────────────────────
+
+test("malformed readiness descriptor → 400 at the edge (never a 500)", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [""] }),
+      app,
+    )) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+  });
+});

package/operations/startFeature.ts

@@ -13,7 +13,7 @@
 // confirm-default / shared-base rules, with the same typed-error → HTTP mapping.
 
 import { startFeature } from "../app/feature.ts";
-import { parseFeatureReadiness } from "../app/featureReadiness.ts";
+import { type FeatureReadiness, parseFeatureReadiness } from "../app/featureReadiness.ts";
 import { BaseBranchMustExistError } from "../app/github.ts";
 import {
   admitPlan,
@@ -23,7 +23,6 @@ import {
   parseIssue,
   SharedBaseError,
 } from "../app/plan.ts";
-import type { ReadinessProbe } from "../app/readiness.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startFeature", async ({ body }, app) => {
@@ -126,7 +125,12 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // `blockedOn` shorthand (resolved against `consumerPackage`) into the probes + bound the run parks
   // on before implementing. A malformed gate (bad descriptor, unparseable handle, blank package) is a
   // 400 at the edge — it must never wait forever at runtime.
-  let readiness: { probes: ReadinessProbe[]; probeTimeout: string | null };
+  // Type the local as the parser's OWN return type (not a hand-written subset): `parseFeatureReadiness`
+  // derives `probes`, `probeTimeout` AND `probePollEvery` together, and all three must be threaded to
+  // the run. A narrower local silently drops a field the parser produced (issue #579: `probePollEvery`
+  // was dropped, so every gated start 500'd on startFeature's invariant) without TypeScript flagging it,
+  // because the narrower shape is structurally assignable from the wider return.
+  let readiness: FeatureReadiness;
   try {
     readiness = parseFeatureReadiness({
       readiness: "readiness" in body ? body.readiness : undefined,
@@ -138,6 +142,31 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     app.log.warn("start-feature rejected: invalid readiness gate", { message });
     return { status: 400, body: { error: message } };
   }
+  // Validate the gate's timing bounds at the EDGE, before dispatch: a non-empty probe set is
+  // load-bearing together with a non-blank `probeTimeout` (preflight escalation timers + pr.readiness-probe)
+  // and `probePollEvery` (preflight retry cadence). `parseFeatureReadiness` always derives all three
+  // together, so this only fires for a mis-derived/hand-seeded gate — but validating here turns that
+  // into a caller-meaningful 400 rather than a bare-Error 500 from startFeature's internal invariant.
+  if (readiness.probes.length > 0) {
+    const missingBounds: string[] = [];
+    if ((readiness.probeTimeout ?? "").trim() === "") missingBounds.push("a timeout");
+    if ((readiness.probePollEvery ?? "").trim() === "") missingBounds.push("a poll cadence");
+    if (missingBounds.length > 0) {
+      app.log.warn("start-feature rejected: readiness gate missing timing bound", {
+        missing: missingBounds,
+        probes: readiness.probes.length,
+      });
+      return {
+        status: 400,
+        body: {
+          error:
+            `readiness gate is malformed: ${readiness.probes.length} probe(s) but the request did not ` +
+            `resolve to ${missingBounds.join(" and ")}. A gated start (readiness/blockedOn) must resolve ` +
+            `to a non-blank timeout and poll cadence`,
+        },
+      };
+    }
+  }
   const result = await startFeature(
     app.data,
     app.engine,
@@ -146,7 +175,7 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     converge,
     autoMerge,
     customInstructions,
-    { probes: readiness.probes, probeTimeout: readiness.probeTimeout },
+    { probes: readiness.probes, probeTimeout: readiness.probeTimeout, probePollEvery: readiness.probePollEvery },
   );
   app.log.info("feature run started", {
     featureKey: parsed.planKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.150.0",
+  "version": "0.150.1",
   "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",