@nanobpm/nano-workforce 0.162.2 → 0.163.1

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.2",
+  "version": "0.163.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",

package/resources/forms/empty-plan-escalation.form

@@ -0,0 +1,31 @@
+{
+  "id": "empty-plan-escalation",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "text",
+      "text": "The planner produced an **empty plan** (no tasks) for this epic. This can be a legitimate no-op (a meta/tracking epic, or one whose sub-issues are all closed) or a planning failure. It is parked here for an operator to decide — it does NOT auto-terminate and does NOT re-enter the adversarial plan-review loop."
+    },
+    {
+      "type": "select",
+      "key": "directive",
+      "label": "Directive",
+      "values": [
+        { "label": "Accept — a legitimate no-op epic; complete the run", "value": "accept" },
+        { "label": "Revise — send it back to the planner to re-plan", "value": "revise" }
+      ],
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "notes",
+      "label": "Revision guidance for the planner",
+      "conditional": {
+        "hide": "=directive != \"revise\""
+      }
+    }
+  ]
+}

package/resources/processes/plan-fanout.bpmn

@@ -293,8 +293,25 @@
       <bpmn:outgoing>f_plan_empty</bpmn:outgoing>
       <bpmn:outgoing>f_toReviewPlan</bpmn:outgoing>
     </bpmn:exclusiveGateway>
-    <bpmn:endEvent id="EndTasklessDone" name="Taskless done (no-op epic)">
+    <bpmn:userTask id="empty-plan-escalation" name="Empty plan — operator attention (human)">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="empty-plan-escalation" />
+        <zeebe:userTask />
+        <zeebe:assignmentDefinition candidateGroups="operators" assignee="=escalationAssignee" />
+        <zeebe:ioMapping>
+          <zeebe:output source="=(if planFindings = null then &#34;&#34; else planFindings) + (if (notes = null or notes = &#34;&#34;) then &#34;&#34; else &#34;&#10;&#10;Human guidance:&#10;&#34; + notes)" target="planFindings" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
       <bpmn:incoming>f_plan_empty</bpmn:incoming>
+      <bpmn:outgoing>f_toGwEmptyAnswer</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:exclusiveGateway id="gw-empty-plan-answer" name="accept no-op?" default="f_empty_revise">
+      <bpmn:incoming>f_toGwEmptyAnswer</bpmn:incoming>
+      <bpmn:outgoing>f_empty_accept</bpmn:outgoing>
+      <bpmn:outgoing>f_empty_revise</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
+    <bpmn:endEvent id="EndTasklessDone" name="Taskless done (no-op epic)">
+      <bpmn:incoming>f_empty_accept</bpmn:incoming>
     </bpmn:endEvent>
     <bpmn:serviceTask id="review-plan" name="Review plan (agent)">
       <bpmn:extensionElements>
@@ -622,9 +639,14 @@
     <bpmn:sequenceFlow id="f_toPlan" sourceRef="ensure-base-branch" targetRef="plan" />
     <bpmn:sequenceFlow id="f_toRecordPlan" sourceRef="plan" targetRef="record-plan" />
     <bpmn:sequenceFlow id="f_toPlanEmptyGw" sourceRef="record-plan" targetRef="gw-plan-empty" />
-    <bpmn:sequenceFlow id="f_plan_empty" name="no tasks" sourceRef="gw-plan-empty" targetRef="EndTasklessDone">
+    <bpmn:sequenceFlow id="f_plan_empty" name="no tasks" sourceRef="gw-plan-empty" targetRef="empty-plan-escalation">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=taskCount = 0</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_toGwEmptyAnswer" sourceRef="empty-plan-escalation" targetRef="gw-empty-plan-answer" />
+    <bpmn:sequenceFlow id="f_empty_accept" name="accept (no-op)" sourceRef="gw-empty-plan-answer" targetRef="EndTasklessDone">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=directive = "accept"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_empty_revise" name="revise" sourceRef="gw-empty-plan-answer" targetRef="plan" />
     <bpmn:sequenceFlow id="f_toReviewPlan" name="has tasks" sourceRef="gw-plan-empty" targetRef="review-plan" />
     <bpmn:sequenceFlow id="f_toRecordPlanReview" sourceRef="review-plan" targetRef="record-plan-review" />
     <bpmn:sequenceFlow id="f_toGwPlanReview" sourceRef="record-plan-review" targetRef="gw-plan-review" />
@@ -700,13 +722,22 @@
       <bpmndi:BPMNShape id="BPMNShape_gw-plan-empty" bpmnElement="gw-plan-empty" isMarkerVisible="true">
         <dc:Bounds x="1166" y="284" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1123" y="339" width="57" height="28" />
+          <dc:Bounds x="1163" y="359" width="57" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_empty-plan-escalation" bpmnElement="empty-plan-escalation">
+        <dc:Bounds x="1316" y="589" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-empty-plan-answer" bpmnElement="gw-empty-plan-answer" isMarkerVisible="true">
+        <dc:Bounds x="1541" y="604" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1543" y="571" width="46" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_EndTasklessDone" bpmnElement="EndTasklessDone">
-        <dc:Bounds x="1348" y="451" width="36" height="36" />
+        <dc:Bounds x="1723" y="611" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1327" y="492" width="78" height="42" />
+          <dc:Bounds x="1702" y="652" width="78" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_review-plan" bpmnElement="review-plan">
@@ -718,7 +749,7 @@
       <bpmndi:BPMNShape id="BPMNShape_gw-plan-review" bpmnElement="gw-plan-review" isMarkerVisible="true">
         <dc:Bounds x="1716" y="284" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1668" y="339" width="67" height="28" />
+          <dc:Bounds x="1668" y="359" width="67" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_plan-review-decision" bpmnElement="plan-review-decision">
@@ -727,7 +758,7 @@
       <bpmndi:BPMNShape id="BPMNShape_gw-plan-answer" bpmnElement="gw-plan-answer" isMarkerVisible="true">
         <dc:Bounds x="2066" y="444" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="2121" y="455" width="67" height="28" />
+          <dc:Bounds x="2058" y="411" width="67" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_select-wave" bpmnElement="select-wave">
@@ -844,7 +875,7 @@
         <di:waypoint x="1766" y="309" />
         <di:waypoint x="2216" y="309" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1899" y="287" width="60" height="14" />
+          <dc:Bounds x="1961" y="287" width="60" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toImplement" bpmnElement="f_toImplement">
@@ -877,6 +908,15 @@
         <di:waypoint x="6004" y="309" />
         <di:waypoint x="6104" y="309" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_empty_revise" bpmnElement="f_empty_revise">
+        <di:waypoint x="1566" y="654" />
+        <di:waypoint x="1566" y="689" />
+        <di:waypoint x="816" y="689" />
+        <di:waypoint x="816" y="349" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1168" y="667" width="46" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_plan_revise" bpmnElement="f_plan_revise">
         <di:waypoint x="1741" y="284" />
         <di:waypoint x="1741" y="249" />
@@ -892,7 +932,7 @@
         <di:waypoint x="816" y="549" />
         <di:waypoint x="816" y="349" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1431" y="557" width="46" height="14" />
+          <dc:Bounds x="1431" y="527" width="46" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toRecordTrialMerge" bpmnElement="f_toRecordTrialMerge">
@@ -930,10 +970,14 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_plan_empty" bpmnElement="f_plan_empty">
         <di:waypoint x="1191" y="334" />
-        <di:waypoint x="1191" y="469" />
-        <di:waypoint x="1348" y="469" />
+        <di:waypoint x="1191" y="354" />
+        <di:waypoint x="2136" y="354" />
+        <di:waypoint x="2136" y="558" />
+        <di:waypoint x="1296" y="558" />
+        <di:waypoint x="1296" y="609" />
+        <di:waypoint x="1316" y="609" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1196" y="395" width="57" height="14" />
+          <dc:Bounds x="2141" y="489" width="57" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_plan_escalate" bpmnElement="f_plan_escalate">
@@ -945,11 +989,11 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_plan_answer_proceed" bpmnElement="f_plan_answer_proceed">
-        <di:waypoint x="2091" y="444" />
-        <di:waypoint x="2091" y="309" />
-        <di:waypoint x="2216" y="309" />
+        <di:waypoint x="2116" y="469" />
+        <di:waypoint x="2266" y="469" />
+        <di:waypoint x="2266" y="349" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="2096" y="370" width="53" height="14" />
+          <dc:Bounds x="2165" y="447" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_runTrialMerge" bpmnElement="f_runTrialMerge">
@@ -1005,6 +1049,17 @@
         <di:waypoint x="616" y="469" />
         <di:waypoint x="616" y="349" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toGwEmptyAnswer" bpmnElement="f_toGwEmptyAnswer">
+        <di:waypoint x="1416" y="629" />
+        <di:waypoint x="1541" y="629" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_empty_accept" bpmnElement="f_empty_accept">
+        <di:waypoint x="1591" y="629" />
+        <di:waypoint x="1723" y="629" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1631" y="596" width="53" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toGwPlanAnswer" bpmnElement="f_toGwPlanAnswer">
         <di:waypoint x="1966" y="469" />
         <di:waypoint x="2066" y="469" />
@@ -1029,7 +1084,7 @@
         <di:waypoint x="816" y="547" />
         <di:waypoint x="816" y="349" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1426" y="514" width="81" height="28" />
+          <dc:Bounds x="1326" y="514" width="81" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_trial_sla" bpmnElement="f_trial_sla">

package/test/reconcileDb.ts

@@ -0,0 +1,61 @@
+// A test-only DataLayer over a real in-memory `node:sqlite` db with the WHOLE migration set applied,
+// for exercising the engine-reset reconciliation surface (`app/reconcile.ts`, issue #622) and its
+// operator-command delegate (`operations/reconcileEngineState.ts`) against the REAL shipping schema —
+// so the tables/columns/indexes reconcile reads and writes are exactly what deploys, not a fake.
+//
+// Canonical harness shared by `app/reconcile.test.ts` and `operations/reconcileEngineState.test.ts`
+// (derivation over duplication: one in-memory DataLayer builder, not two divergent copies).
+import { readdirSync, readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach } from "node:test";
+import { fileURLToPath } from "node:url";
+import { type DataLayer, makeGateway, type SqliteDb } from "@nanobpm/urban";
+import { applyMigrationSet } from "#test-migrations";
+
+const MIGRATIONS_DIR = fileURLToPath(new URL("../db/migrations", import.meta.url));
+
+// Every raw handle `freshData()` opens is tracked here and released after each test, so call sites
+// (all of them) don't leak native SQLite handles across the run. Mirrors `test/worldDb.ts` and
+// `test/blackboardDb.ts` (derivation over duplication: the same auto-close idiom, not a new one).
+const openDbs = new Set<DatabaseSync>();
+afterEach(() => {
+  for (const raw of openDbs) {
+    if (openDbs.delete(raw)) raw.close();
+  }
+});
+
+/** Adapt a raw `node:sqlite` handle to urban's tiny `SqliteDb` seam so `makeGateway` yields the real
+ *  record-oriented `DataSource` reconcile binds to (no fakes — the shipping gateway). */
+export function sqliteDb(raw: DatabaseSync): SqliteDb {
+  return {
+    exec: (sql) => raw.exec(sql),
+    run: (sql, params = []) => {
+      const r = raw.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      raw.prepare(sql).all(...(params as never[])) as T[],
+    close: () => raw.close(),
+  };
+}
+
+export function readMigrationFiles(): { name: string; sql: string }[] {
+  return readdirSync(MIGRATIONS_DIR)
+    .filter((n) => n.endsWith(".sql"))
+    .map((name) => ({ name, sql: readFileSync(`${MIGRATIONS_DIR}/${name}`, "utf8") }));
+}
+
+/** A DataLayer over a fresh in-memory DB with the whole migration set applied. The raw handle is
+ *  tracked and auto-closed after each test (see `openDbs`), and FK enforcement is enabled so the
+ *  migrations are exercised under the real constraints they ship with. */
+export function freshData(): { data: DataLayer; raw: DatabaseSync } {
+  const raw = new DatabaseSync(":memory:");
+  openDbs.add(raw);
+  // SQLite disables FK enforcement by default; enable it so migrations with foreign keys are
+  // exercised (and any FK violations surface) exactly as they would on the shipping schema.
+  raw.exec("PRAGMA foreign_keys = ON;");
+  applyMigrationSet(raw, readMigrationFiles());
+  const gw = makeGateway(sqliteDb(raw));
+  const data = { open: () => gw } as unknown as DataLayer;
+  return { data, raw };
+}

package/workers/record-plan/worker.test.ts

@@ -84,15 +84,19 @@ test("record-plan dispatches a taskful plan and levelizes its tasks (wave progre
   assertEquals(plans[0].wave_label, undefined);
 });
 
-test("record-plan marks a taskless plan done (no wave-progress columns written)", async () => {
+test("record-plan keeps a taskless plan NON-terminal (planning) with an outcome note (issue #624)", async () => {
   const { app, plans } = fakeApp();
   const out = await handler(
     { variables: { planKey: "owner/repo#137", tasks: [], note: "planner emitted no tasks" } } as any,
     app,
   );
-  assertEquals(plans[0].status, "done");
-  // taskCount 0 routes the plan-fanout gateway (`gw-plan-empty`) to the terminal taskless-done arm,
-  // short-circuiting the adversarial plan-review loop that would otherwise livelock (issue #623).
+  // A taskless plan is INTERMEDIATE, not terminal: the plan-fanout instance is still live (may
+  // re-plan / escalate / be cancelled). Terminal `done` follows engine liveness (reconciled by the
+  // poller), never this empty-plan heuristic, so the status stays non-terminal here (issue #624).
+  assertEquals(plans[0].status, "planning");
+  assertEquals(plans[0].task_count, 0);
+  // `taskCount` still drives the plan-fanout gateway (`gw-plan-empty`): zero routes to the operator
+  // empty-plan escalation instead of the adversarial plan-review loop (issues #623/#624).
   assertEquals((out as any).taskCount, 0);
   assertEquals(plans[0].outcome, "planner emitted no tasks");
   assertEquals(plans[0].wave_count, undefined);

package/workers/record-plan/worker.ts

@@ -10,6 +10,13 @@
 //   • records the task count, moves the plan to `dispatched`, and emits `currentWave = 0`
 //     plus `waveCount` so the wave loop (`select-wave → implement → record-wave`) can run.
 //
+// A TASKLESS plan (the planner emitted no tasks) is NOT terminal here (issue #624): "the planner
+// produced nothing this pass" is an intermediate state, not an ended process — the plan-fanout
+// instance is still live and may re-plan, escalate, or be cancelled. The plan stays NON-terminal
+// (`planning`, with an `outcome` note for observability); terminal `plans.status` follows ENGINE
+// instance liveness, reconciled by the poller (COMPLETED → `done`; TERMINATED → `abandoned`), never
+// this empty-plan heuristic.
+//
 // If the planner emits a malformed DAG (cycle / unknown or self dependency / duplicate id),
 // levelization can't order the tasks. Rather than dead-lock the plan we DEGRADE to the old
 // flat behaviour — a single wave (wave 0) of all tasks, run fully in parallel — and log a
@@ -38,10 +45,13 @@ interface NormalTask {
 interface Out extends Record<string, unknown> {
   currentWave: number;
   waveCount: number;
-  // Task count of the recorded plan. The plan-fanout gateway (`gw-plan-empty`) reads this to
-  // SHORT-CIRCUIT an intentionally-empty plan (`{tasks:[]}`) to a terminal taskless-done arm
-  // BEFORE the adversarial plan-review gate (issue #623). Feeding an empty plan into review
-  // caused a plan↔plan-review livelock — it can neither be approved nor produce findings.
+  // Task count of the recorded plan. The plan-fanout gateway (`gw-plan-empty`) reads this to route
+  // an intentionally-empty plan (`{tasks:[]}`) to the OPERATOR empty-plan escalation
+  // (`empty-plan-escalation`) — a human decides Accept (no-op done) or Revise (re-plan) — instead of
+  // the adversarial plan-review gate (issues #623/#624). Feeding an empty plan into review caused a
+  // plan↔plan-review livelock (it can neither be approved nor produce findings), and auto-terminating
+  // it (issue #625) reached a terminal verdict from an intermediate signal while the instance was
+  // still live; escalating for operator attention resolves both.
   taskCount: number;
 }
 
@@ -143,7 +153,6 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   }
 
   const patch: Record<string, unknown> = {
-    status: tasks.length > 0 ? "dispatched" : "done",
     task_count: tasks.length,
     // Operator-visibility wave progress (wave_count / current_wave / wave_label) was RETIRED as a
     // stored projection (epic #412) — the epics-index reads it from the `plan_wave_label` /
@@ -151,11 +160,25 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     // denormalises it onto the `plans` row.
     updated_at: ts,
   };
-  if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
+  if (tasks.length > 0) {
+    patch.status = "dispatched";
+  } else {
+    // Taskless plan: DO NOT collapse to terminal `done` (issue #624). "The planner produced nothing
+    // this pass" is an INTERMEDIATE state, NOT an ended process — the plan-fanout instance is still
+    // live and may re-plan, escalate, or be cancelled. Terminal `plans.status` must follow ENGINE
+    // instance liveness, not this per-pass empty-plan heuristic, or the epic renders "Done" over a
+    // still-active (in fact looping) instance. So the plan stays NON-terminal (`planning`) until the
+    // poller sees the instance actually end: COMPLETED → `done` (pollTasklessPlanTermination,
+    // app/service.ts — the same poller that owns the delivery-graph COMPLETED→done transition) or
+    // TERMINATED → `abandoned` (instanceTracking's `onTerminated` derived edge). The outcome note is
+    // still recorded for observability; it is phase/label copy, not a terminal-status signal.
+    patch.status = "planning";
+    patch.outcome = note ? str(note) : "planner emitted no tasks";
+  }
   await plans(app.data).update(planKey, patch);
 
-  // Kick off the wave loop at wave 0. `taskCount` lets the BPMN gateway terminate an empty plan
-  // before the review loop (issue #623).
+  // Kick off the wave loop at wave 0. `taskCount` lets the BPMN gateway (`gw-plan-empty`) route an
+  // empty plan to the operator empty-plan escalation instead of the review loop (issues #623/#624).
   return { currentWave: 0, waveCount, taskCount: tasks.length };
 };