@nanobpm/nano-workforce 0.162.1 → 0.163.0

package/e2e/plan-fanout.e2e.ts

@@ -241,6 +241,43 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     );
   });
 
+  // Empty-plan short-circuit (issue #623 — regression for Merlin instance-46 / epic #1067). A
+  // planner that legitimately emits `{tasks:[]}` (meta/tracking epic, or all sub-issues closed) must
+  // reach a terminal state WITHOUT entering the adversarial plan-review loop — feeding an empty plan
+  // into review caused a plan↔plan-review livelock (it can neither be approved nor produce findings).
+  test("empty plan short-circuits to the taskless-done end, never entering plan-review (issue #623)", async () => {
+    let reviewCalls = 0;
+    await withApp(
+      {
+        "senior:plan": () => ({ tasks: [], note: "all sub-issues closed" }),
+        // If this ever fires, the short-circuit failed and the empty plan entered the review loop.
+        "senior:plan-review": () => {
+          reviewCalls += 1;
+          return { approved: false, findings: "" };
+        },
+        "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
+      },
+      async ({ app, planKey }) => {
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-plan-empty->EndTasklessDone"),
+          `empty plan routed to the taskless-done end (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("gw-plan-empty->review-plan"),
+          "the has-tasks flow into plan-review was NOT taken",
+        );
+        assert.equal(reviewCalls, 0, "the plan-review agent must never run for an empty plan");
+
+        const plan = await app.db
+          .table<{ plan_key: string; status: string; outcome: string | null }>("plans", "plan_key")
+          .findOne({ plan_key: planKey });
+        assert.equal(plan?.status, "done", "the empty plan reached a terminal done state");
+        assert.equal(plan?.outcome, "all sub-issues closed", "the planner note was recorded as the outcome");
+      },
+    );
+  });
+
   // A two-task wave whose PRs both open triggers the D3 trial-merge gate; a suite-failed trial
   // parks on the trial-merge decision user task.
   const twoTaskPlan: Stub = () => ({

package/main.ts

@@ -22,6 +22,7 @@ import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urba
 import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
 import { makeElementInstanceResolver } from "./app/agentic/element-instance.ts";
 import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
+import { runEngineReconcile } from "./app/reconcile.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
 
@@ -102,6 +103,30 @@ if (httpServer instanceof Server) {
   app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
 }
 
+// Engine-reset reconciliation (issue #622). On boot, compare the engine's incarnation epoch against
+// the last-seen value; on a REGRESSION (the engine was reset/restored/rewound and re-minted its keys,
+// Magikcraft/nano-bpm#1065) drive every dangling engine-backed inflight row to the defined `orphaned`
+// terminal WITH PROVENANCE — BEFORE the pollers below start projecting off stale, dead instances.
+// Guarded: an unreachable engine is a no-op (it never orphans live work), and any failure degrades to
+// a warn so reconcile can never block boot.
+if (app.data) {
+  try {
+    const reconciled = await runEngineReconcile(
+      app.data,
+      { restAddress: engineAddress.restAddress, token: process.env.CAMUNDA_TOKEN },
+      { log: { info: (m) => app.log.info(m), warn: (m) => app.log.warn(m) } },
+    );
+    if (reconciled.orphanedCount > 0) {
+      app.log.warn(
+        `startup reconcile: engine reset detected — orphaned ${reconciled.orphanedCount} engine-backed ` +
+          `inflight row(s) [run ${reconciled.runId}].`,
+      );
+    }
+  } catch (err) {
+    app.log.warn(`startup reconcile skipped: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 // Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
 // overlap two passes (which could double-signal `readiness-ready`); the next pass is scheduled
 // only after the previous one settles.

package/openapi.yaml

@@ -844,6 +844,64 @@ components:
           type: string
         uptimeSeconds:
           type: integer
+    ReconcileReport:
+      type: object
+      description: The result of one engine-reset reconciliation pass (issue #622).
+      additionalProperties: false
+      required:
+        - runId
+        - reason
+        - observedEpoch
+        - recordedEpoch
+        - orphanedCount
+        - orphaned
+      properties:
+        runId:
+          type: string
+          description: The reconcile run id every orphaned transition's provenance is stamped with.
+        reason:
+          type: string
+          description: Why this pass acted (or did not).
+          enum:
+            - epoch-regression
+            - seed-epoch
+            - no-op
+            - engine-unreachable
+        observedEpoch:
+          type: integer
+          nullable: true
+          description: The engine incarnation epoch observed on this pass (null when the engine exposes
+            none, or was unreachable).
+        recordedEpoch:
+          type: integer
+          nullable: true
+          description: The previously-recorded epoch this pass compared against (null on the first run).
+        orphanedCount:
+          type: integer
+          description: How many engine-backed inflight rows were driven to `orphaned`.
+        orphaned:
+          type: array
+          description: The rows orphaned by this pass.
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - table
+              - pk
+              - key
+              - fromStatus
+            properties:
+              table:
+                type: string
+              pk:
+                type: string
+              key:
+                type: string
+                nullable: true
+                description: The engine instance key (e.g. process_key) the row projected.
+              fromStatus:
+                type: string
+                description: The non-terminal status the row carried before it was orphaned.
     AgentInstructions:
       type: object
       description: The agent operator guide — how to drive (submit PRs/epics, answer escalations)
@@ -3189,6 +3247,40 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /reconcile:
+    post:
+      operationId: reconcileEngineState
+      summary: Reconcile engine-backed inflight projections after an engine reset/rewind (issue #622).
+      description: >-
+        The explicit operator command for the app-side reconciliation surface. Probes the engine's
+        incarnation epoch (`/v2/topology`) and compares it to the last-seen value: on a REGRESSION (the
+        #1065 reset/rewind signature) every NON-terminal engine-backed app row (an instanceTracking
+        binding whose status is still active and whose engine key is populated) is driven to the
+        defined `orphaned` terminal WITH PROVENANCE. Terminal history and non-engine-backed surfaces
+        (presence, audit) are never touched. Idempotent — a second call with a matching epoch is a
+        no-op — and safe: an unreachable engine orphans nothing. Runs automatically on startup too.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The reconcile pass result (what it observed and orphaned).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReconcileReport"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "503":
+          description: The app has no data source configured, so there is nothing to reconcile.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /version:
     get:
       operationId: getVersion

package/operations/reconcileEngineState.test.ts

@@ -0,0 +1,81 @@
+// Delegate-level tests for POST /app/api/reconcile → operation `reconcileEngineState` (issue #622).
+// Covers the shared-secret guard (401), the no-data-source guard (503), and a happy-path 200 that
+// exercises the wiring to `runEngineReconcile` against the REAL shipping schema (the whole migration
+// set on an in-memory SQLite) with the engine `/topology` probe stubbed — so the operator command's
+// auth guard, status codes, and reconcile wiring are regression-covered by the Node test suite.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import { freshData } from "../test/reconcileDb.ts";
+import handler from "./reconcileEngineState.ts";
+
+function input(headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "POST",
+      path: "/app/api/reconcile",
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+/** Stub the global `/topology` probe so the delegate never touches the network; restore after. */
+async function withEngineEpoch<T>(epoch: number | null, fn: () => Promise<T>): Promise<T> {
+  const prev = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    ({
+      ok: true,
+      json: async () => (epoch == null ? {} : { nano: { incarnation: epoch } }),
+    }) as unknown as Response) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prev;
+  }
+}
+
+test("returns 503 when no data source is configured", async () => {
+  const app = { log: noopLog() } as any as AppApi;
+  const res = (await handler(input(), app)) as any;
+  assertEquals(res.status, 503);
+  assert("error" in res.body);
+});
+
+test("first observation seeds the epoch and returns 200 with a reconcile result", async () => {
+  const { data } = freshData();
+  const app = { data, log: noopLog() } as any as AppApi;
+  const res = await withEngineEpoch(7, async () => (await handler(input(), app)) as any);
+  assertEquals(res.status, 200);
+  assertEquals(res.body.reason, "seed-epoch");
+  assertEquals(res.body.orphanedCount, 0);
+  assert(typeof res.body.runId === "string" && res.body.runId.length > 0);
+});
+
+test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    // SECRET is bound at import time, so import a cache-busted copy to observe the guard.
+    const mod = await import(`./reconcileEngineState.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const { data } = freshData();
+    const app = { data, log: noopLog() } as any as AppApi;
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const wrong = (await guarded(input({ "x-hook-secret": "nope" }), app)) as any;
+    assertEquals(wrong.status, 401);
+    const ok = await withEngineEpoch(7, async () =>
+      (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any,
+    );
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/reconcileEngineState.ts

@@ -0,0 +1,44 @@
+// POST /app/api/reconcile → operationId `reconcileEngineState` (ADR 0058/0059, base /app/api).
+//
+// The explicit OPERATOR COMMAND for the app-side engine-reset reconciliation surface (issue #622) —
+// the on-demand twin of the startup pass in main.ts, sharing the one `runEngineReconcile` seam so the
+// two paths can never diverge. An operator (or a restore runbook) POSTs here after resetting /
+// restoring / rewinding the engine to converge `app.db`: it probes the engine incarnation epoch and,
+// on a regression, drives every dangling engine-backed inflight row to the defined `orphaned` terminal
+// with provenance. Idempotent (a matching epoch is a no-op) and safe (an unreachable engine orphans
+// nothing), so it is harmless to run at any time — a green "nothing to do" is the common case.
+//
+// The engine address is the canonical `resolveEngineAddress` (the same precedence the engine client
+// and startup preflight use), so the operator command talks to exactly the engine the app runs
+// against. 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.
+
+import { resolveEngineAddress } from "../app/enginePreflight.ts";
+import { runEngineReconcile } from "../app/reconcile.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("reconcileEngineState", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("reconcileEngineState rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  if (!app.data) {
+    app.log.warn("reconcileEngineState: no data source configured — nothing to reconcile");
+    return { status: 503, body: { error: "no data source configured" } };
+  }
+  const engineAddress = resolveEngineAddress();
+  const result = await runEngineReconcile(
+    app.data,
+    { restAddress: engineAddress.restAddress, token: envVar("CAMUNDA_TOKEN") ?? undefined },
+    { log: { info: (m) => app.log.info(m), warn: (m) => app.log.warn(m) } },
+  );
+  app.log.info("reconcileEngineState complete", {
+    reason: result.reason,
+    orphanedCount: result.orphanedCount,
+    runId: result.runId,
+  });
+  return { status: 200, body: result };
+});

package/package.json

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