@nanobpm/nano-workforce 0.102.1 → 0.104.0

package/openapi.yaml

@@ -386,6 +386,15 @@ components:
         instance:
           type: string
           description: The worker instance id, echoed back for provenance (optional).
+        durableResume:
+          type: boolean
+          description: >-
+            Whether this worker's harness advertises durable-resume (issue #325, ADR 0062 Slice 5/5)
+            — an ENROLMENT attribute, never a routing token. Recorded per instance so the app emits
+            the world-restore marker only to a fleet with a participant; a harness that omits it (or
+            sets false) redrives a re-leased round from scratch. Recorded only when `instance` is
+            a non-blank string — a missing, empty, or whitespace-only `instance` is echoed back for
+            provenance but the flag is not persisted.
     EnrolledRole:
       type: object
       description: One matched role in an enrolment resolution — provenance for the resolved SERVE set.
@@ -411,6 +420,14 @@ components:
         instance:
           type: string
           description: The worker instance id, echoed from the request when supplied.
+        durableResume:
+          type: boolean
+          description: >-
+            Echo of the request's durable-resume declaration (issue #325, ADR 0062 Slice 5/5).
+            Present only when the request supplied it. This reflects the value the worker sent, not a
+            guarantee of durable persistence — recording into the durable-resume registry is
+            best-effort (skipped when `instance` is absent/blank, and a registry write hiccup is
+            logged without failing enrolment).
         serve:
           type: array
           description: The SERVE token set — sorted, de-duplicated leaf tokens the worker may serve.
@@ -1153,12 +1170,65 @@ components:
             Accepted by the schema today but currently has no runtime effect. When implemented it
             will be the required acknowledgement when `baseBranch` names the repository default
             branch. See `PlanStartByIssue.confirmDefaultBase`.
+    ReadinessProbe:
+      description: >-
+        A single durable readiness probe (issue #258, #295) the feature run must satisfy before its
+        implementation agent is dispatched. `kind` selects the source; `target` + `match` are the
+        per-kind predicate. The `capability` kind resolves "which published `pkg@version` first
+        carries capability C?" from publish provenance and late-binds it into the run. See
+        `app/readiness.ts` for the full per-kind semantics.
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - target
+      properties:
+        kind:
+          type: string
+          enum: [http, command, npm, github-check, capability]
+          description: The readiness source. `command` is the escape hatch; `capability` resolves a cross-repo published-artifact edge.
+        target:
+          type: string
+          minLength: 1
+          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, or `github-releases:owner/repo`).
+        onTimeout:
+          type: string
+          enum: [escalate, fail, continue]
+          description: What the gate does when the bounded wait elapses (default `escalate`).
+        credentialEnv:
+          type: string
+          description: A declared env-contract key supplying a credential (http kind only). Names a key, never a secret value.
+        match:
+          type: object
+          additionalProperties: false
+          description: The per-kind readiness predicate; every field is optional and read only by the kinds that understand it.
+          properties:
+            status: { type: integer, description: "http: the exact status that means ready (default any 2xx)." }
+            bodyIncludes: { type: string, description: "http: a substring the response body must contain." }
+            exitCode: { type: integer, description: "command: the exit code that means ready (default 0)." }
+            stdoutIncludes: { type: string, description: "command/npm: a substring stdout must contain." }
+            version: { type: string, description: "npm: the version that must be published." }
+            conclusion: { type: string, description: "github-check: the conclusion that means ready (default success)." }
+            checkName: { type: string, description: "github-check: restrict to the named check run." }
+            capabilityRef: { type: string, description: "capability: the upstream issue/PR handle the resolved version must carry." }
+            package: { type: string, description: "capability: the package whose releases are scanned for provenance." }
+            verifyCommand: { type: string, description: "capability: optional empirical verifier run once at the gate boundary." }
+        poll:
+          type: object
+          additionalProperties: false
+          description: The poll cadence (how often to re-probe, how long to keep trying, and the backoff shape).
+          properties:
+            everyMs: { type: integer, description: Interval between poll attempts (ms). }
+            timeoutMs: { type: integer, description: Bounded budget (ms) before the gate escalates. }
+            backoff: { type: string, enum: [fixed, exponential], description: Backoff shape between attempts. }
     FeatureStart:
       description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
         by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a
         REQUIRED `baseBranch` (ADR 0003, same admission as the epic path), and the two optional
-        follow-on knobs `converge` / `autoMerge`. Modeled as `oneOf` named variants (Camunda REST v2
-        pattern) so an ambiguous or empty target is a 400 at the edge.
+        follow-on knobs `converge` / `autoMerge`. May also carry an intake-time readiness gate
+        (`readiness` and/or `blockedOn` + `consumerPackage`, per issue 295) that parks the run until
+        the declared upstreams land. Modeled as `oneOf` named variants (Camunda REST v2 pattern) so an
+        ambiguous or empty target is a 400 at the edge.
       oneOf:
         - $ref: "#/components/schemas/FeatureStartByIssue"
         - $ref: "#/components/schemas/FeatureStartByUrl"
@@ -1210,6 +1280,36 @@ components:
             OPTIONAL free-text steering appended to the implementation agent's prompt for this run
             (via the implement task's `appendPrompt`). Blank/whitespace is treated as absent. Persists
             on the instance, so it also applies to the agent's answer-loop redispatch.
+        readiness:
+          type: array
+          maxItems: 32
+          items:
+            $ref: "#/components/schemas/ReadinessProbe"
+          description: >-
+            OPTIONAL intake-time readiness gate (issue #295): one or more durable probes the run must
+            ALL satisfy before its implementation agent is dispatched. The run parks (durably, bounded
+            by the gate's escalating timer) at the leading readiness preflight until every probe goes
+            green. Absent/empty ⇒ the run implements immediately, unchanged.
+        blockedOn:
+          type: array
+          maxItems: 32
+          items:
+            type: string
+            minLength: 1
+          description: >-
+            OPTIONAL ergonomic shorthand for `readiness` (issue #295): a list of upstream
+            `owner/repo#123` issue/PR handles the run waits to land. With `consumerPackage` each
+            desugars to a `capability` probe (resolve which published `pkg@version` first carries the
+            handle, and late-bind it into the run); without it, to a `command` probe that goes green
+            once the referenced issue/PR is closed/merged.
+        consumerPackage:
+          type: string
+          minLength: 1
+          description: >-
+            OPTIONAL npm package name (e.g. `@nanobpm/engine-wasm`) the `blockedOn` shorthand resolves
+            its handles against — the consumer dependency whose published provenance must carry each
+            awaited upstream. When present, `blockedOn` desugars to `capability` probes and the
+            resolved `pkg@version` is late-bound into the implementation agent's brief.
     FeatureStartByUrl:
       type: object
       additionalProperties: false
@@ -1246,6 +1346,23 @@ components:
           description: >-
             OPTIONAL free-text steering appended to the implementation agent's prompt for this run.
             See `FeatureStartByIssue.customInstructions`.
+        readiness:
+          type: array
+          maxItems: 32
+          items:
+            $ref: "#/components/schemas/ReadinessProbe"
+          description: OPTIONAL intake-time readiness gate. See `FeatureStartByIssue.readiness`.
+        blockedOn:
+          type: array
+          maxItems: 32
+          items:
+            type: string
+            minLength: 1
+          description: OPTIONAL readiness shorthand — upstream `owner/repo#123` handles to wait on. See `FeatureStartByIssue.blockedOn`.
+        consumerPackage:
+          type: string
+          minLength: 1
+          description: OPTIONAL package the `blockedOn` handles resolve against. See `FeatureStartByIssue.consumerPackage`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/enrolAgenticWorker.test.ts

@@ -2,6 +2,8 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { memDataFor } from "../test/worldDb.ts";
+import { DurableResumeRegistry } from "../app/durableResume.ts";
 import { noopLog } from "../test/log.ts";
 import handler from "./enrolAgenticWorker.ts";
 
@@ -69,6 +71,68 @@ test("rejects non-finite capability.weight (NaN/Infinity) as 400", async () => {
   assertEquals(infWeight.status, 400);
 });
 
+// Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5).
+test("echoes durableResume back in the result when the worker declares it", async () => {
+  const on = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), app)) as any;
+  assertEquals(on.status, 200);
+  assertEquals(on.body.durableResume, true);
+  const off = (await handler(input({ capability: { cognition: "decide" }, instance: "w2", durableResume: false }), app)) as any;
+  assertEquals(off.body.durableResume, false);
+});
+
+test("omits durableResume from the result when the worker does not declare it", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), app)) as any;
+  assertEquals(res.status, 200);
+  assertEquals("durableResume" in res.body, false);
+});
+
+test("rejects a non-boolean durableResume as 400", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: "yes" }), app)) as any;
+  assertEquals(res.status, 400);
+});
+
+test("records durable-resume participation in the registry when a data layer + instance are present", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), true);
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), true);
+});
+
+test("a re-enrol omitting durableResume persists an explicit false, clearing a stale true (degrade to scratch)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  // First enrol advertises durable-resume.
+  await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), withData);
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), true);
+  // Re-enrol WITHOUT the field (downgrade/rollback/client bug) must clear the stale flag.
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals("durableResume" in res.body, false, "still omitted from the echo");
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), false, "stale true cleared");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false);
+});
+
+test("a declaration without an instance is echoed but not persisted (enrolment is per-instance)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.durableResume, true, "still echoed");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false, "nothing recorded without an instance key");
+});
+
+test("a blank/whitespace instance is echoed but not persisted (avoids a shared registry-row collision)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "   ", durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.instance, "   ", "still echoed verbatim");
+  assertEquals(res.body.durableResume, true, "still echoed");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false, "nothing recorded for a blank instance key");
+});
+
 test("enforces the shared secret when NANO_PR_WEBHOOK_SECRET is set", async () => {
   // The module captures the secret at load, so re-import a cache-busted copy with the env var set to
   // exercise the guarded 401 path and the authorized 200 path.

package/operations/enrolAgenticWorker.ts

@@ -12,13 +12,14 @@
 // NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
 import type { Capability } from "@nanobpm/agentic/protocol";
 import { resolveEnrolment } from "../app/agentic/vocab/enrol.ts";
+import { DurableResumeRegistry } from "../app/durableResume.ts";
 import { envVar } from "../app/version.ts";
 import type { EnrolResult } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
-export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
+export default defineOperation("enrolAgenticWorker", async ({ req, body }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     app.log.warn("enrolAgenticWorker rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
@@ -65,6 +66,13 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
       body: { error: "`capability.weight` must be a finite number when provided" },
     };
   }
+  // The durable-resume enrolment attribute (issue #325, ADR 0062 Slice 5/5) — a boolean the harness
+  // advertises. A directly-invoked delegate bypasses the OpenAPI runtime validation, so guard the type
+  // here (a non-boolean would corrupt the {0,1} enrolment flag the world-restore gate reads).
+  if (body.durableResume !== undefined && typeof body.durableResume !== "boolean") {
+    app.log.warn("enrolAgenticWorker rejected: non-boolean durableResume");
+    return { status: 400, body: { error: "`durableResume` must be a boolean when provided" } };
+  }
 
   // Fold a top-level `host` into the capability when the capability didn't carry its own — a worker
   // may declare its host either on the capability or beside it (ADR 0059 `{ capability, host }`).
@@ -74,6 +82,26 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
       : body.capability;
 
   const resolved = resolveEnrolment(capability);
+
+  // Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5): record whether this worker's
+  // harness advertises durable-resume so the world-restore marker is emitted only to a fleet with a
+  // participant. Recorded per instance (ADR 0056 §7 — an enrolment attribute, never a routing token),
+  // so it needs a non-blank `instance`; a declaration without one — or with a blank/whitespace
+  // string — is echoed but not persisted (a blank key would let unrelated workers collide on the
+  // same registry row and wrongly open/close the fleet-wide durable-resume gate). Omission of the
+  // field on a re-enrol persists an explicit `false` (degrade to scratch), so a harness that previously
+  // advertised durable-resume and later re-enrols without the field clears its stale `true` rather than
+  // leaving `fleetSupportsDurableResume()` true indefinitely. Best-effort — the enrolment resolution
+  // must not fail on a registry write hiccup.
+  const instanceKey = body.instance?.trim();
+  if (app.data && instanceKey) {
+    try {
+      await new DurableResumeRegistry(app.data).recordEnrolment(instanceKey, body.durableResume ?? false);
+    } catch (err) {
+      app.log.warn("enrolAgenticWorker: durable-resume record failed", { instance: instanceKey, err: String(err) });
+    }
+  }
+
   const result: EnrolResult = {
     serve: [...resolved.serve],
     roles: resolved.roles.map((role) => {
@@ -85,6 +113,7 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
     leaseTtl: resolved.leaseTtl,
   };
   if (body.instance !== undefined) result.instance = body.instance;
+  if (body.durableResume !== undefined) result.durableResume = body.durableResume;
 
   app.log.info("agentic enrol resolved", { instance: body.instance, serve: result.serve, family: capability.family });
   return { status: 200, body: result };

package/operations/startFeature.ts

@@ -13,6 +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 { BaseBranchMustExistError } from "../app/github.ts";
 import {
   admitPlan,
@@ -22,6 +23,7 @@ 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) => {
@@ -120,13 +122,39 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
     ? body.customInstructions
     : null;
-  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge, customInstructions);
+  // Intake-time readiness gate (issue #295): desugar the optional `readiness` descriptors and/or the
+  // `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 };
+  try {
+    readiness = parseFeatureReadiness({
+      readiness: "readiness" in body ? body.readiness : undefined,
+      blockedOn: "blockedOn" in body ? body.blockedOn : undefined,
+      consumerPackage: "consumerPackage" in body ? body.consumerPackage : undefined,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "invalid readiness gate";
+    app.log.warn("start-feature rejected: invalid readiness gate", { message });
+    return { status: 400, body: { error: message } };
+  }
+  const result = await startFeature(
+    app.data,
+    app.engine,
+    parsed,
+    normalizedBase,
+    converge,
+    autoMerge,
+    customInstructions,
+    { probes: readiness.probes, probeTimeout: readiness.probeTimeout },
+  );
   app.log.info("feature run started", {
     featureKey: parsed.planKey,
     requestedBaseBranch: normalizedBase,
     converge,
     autoMerge,
     hasCustomInstructions: typeof customInstructions === "string" && customInstructions.trim() !== "",
+    readinessProbes: readiness.probes.length,
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
   });
   return { status: 202, body: result };

package/package.json

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