@nanobpm/nano-workforce 0.144.0 → 0.145.1

package/app/service.ts

@@ -27,11 +27,12 @@ import {
   conformanceEscalationQuestion,
 } from "./conformance.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
-import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
 import { isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
+import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
 import { deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
@@ -53,6 +54,7 @@ import {
 import { activeStatusesFor, derivedTrackingTable } from "./instanceTracking.ts";
 import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
+import { mergeLandedWaitTimeout } from "./mergeLandedWait.ts";
 import {
   freshHeadRunAction,
   headRunPresenceCount,
@@ -155,6 +157,18 @@ export const AGENT_SLA_TIMEOUT = agentSlaTimeout(process.env.NANO_PR_AGENT_SLA_T
  * default so an uninterpretable timer is never deployed. */
 export const REVIEW_WAIT_TIMEOUT = reviewWaitTimeout(process.env.NANO_PR_REVIEW_WAIT_TIMEOUT);
 
+/** How long the merge loop waits for a `queued` PR to actually land before escalating to a human.
+ * Seeded as the `landedWaitTimeout` process variable at merge start and evaluated by the merge-loop's
+ * `wait-landed-timeout` timer catch (the timer arm of the `eg-landed` event-based gateway, racing the
+ * `merge-landed` / `merge-evicted` messages). `attempt-merge` classifies a merge as `queued` on an
+ * ambiguous "merge queue" signal without verifying a real enqueue, so on a repo that never actually
+ * queues a plain `gh pr merge` (e.g. Mergify) the loop would otherwise park at `wait-landed` forever
+ * (issue #556). ISO-8601 duration; a malformed `NANO_PR_MERGE_LANDED_WAIT_TIMEOUT` falls back to the
+ * default so an uninterpretable timer is never deployed. */
+export const MERGE_LANDED_WAIT_TIMEOUT = mergeLandedWaitTimeout(
+  process.env.NANO_PR_MERGE_LANDED_WAIT_TIMEOUT,
+);
+
 /** Cooldown (ms) between the poller's automatic Copilot re-request nudges for a single waiting PR.
  * Copilot dismisses re-requests, so the poller retries — but not on every tick; this throttles it
  * to one attempt per window. Set via `NANO_PR_REVIEW_NUDGE_MINUTES` (minutes). */
@@ -707,6 +721,7 @@ export async function startMerge(
       mergeRetryRound: 0,
       mergeRetryMax: MAX_MERGE_RETRIES,
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
+      landedWaitTimeout: MERGE_LANDED_WAIT_TIMEOUT,
       // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
       rootRequestKey,
       abandonUrl: abUrl,
@@ -2309,6 +2324,65 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
  * completed task's row is deleted (answered here, via the task inbox, or out-of-band) and `showCount`
  * reflects live pending work. Best-effort + idempotent — per-instance failures are isolated so one bad
  * instance never stalls the pass. */
+/** Poll pass (S8, #542 / ADR 0006 §4b): reconcile each LIVE epic's `plans.epic_phase` from the engine
+ * element-instance model — the PURE read-model derivation that RETIRES the write-time stamp the spine
+ * workers used to write. For each plan still live (`EPIC_LIVE_STATUSES`) with a running instance, read
+ * its element instances (`searchElementInstances`, nano-ide#473) and project the furthest-reached
+ * active spine element onto its domain phase (`deriveEpicPhaseLive`, app/epicPhase.ts — the SAME
+ * `ELEMENT_PHASE` structural map the stamp used). The wave label rides the `plan_wave_progress` rollup
+ * VIEW (the single wave-frontier source, 060/082), so the Implementing band reads `wave n/t` without a
+ * second wave derivation. Writes only on a real change (a steady-state pass is a no-op) and leaves the
+ * last phase untouched when nothing active marks one (`null`), so a plan parked on non-spine plumbing
+ * never clobbers to blank. The terminal `Dispatched` phase is a COMPLETION marker (no ACTIVE token to
+ * read once the instance ends), so a second pass derives it from the durable terminal status
+ * (`deriveTerminalEpicPhase` over `done` epics) rather than the fleeting ACTIVE `record-results` token
+ * a coarse poll would miss. Best-effort + idempotent — a per-plan failure is isolated. */
+export async function pollEpicPhase(
+  data: DataLayer,
+  engine: Pick<EngineClient, "searchElementInstances">,
+) {
+  const waveByPlan = new Map<string, { current: number | null; total: number | null }>();
+  for (const w of await data
+    .table<{ plan_key: string; wave_count: number | null; current_wave: number | null }>(
+      "plan_wave_progress",
+      "plan_key",
+    )
+    .all()) {
+    // Coerce SQL NULL to `null` so a missing `current_wave`/`wave_count` stays MISSING through the
+    // wave label — a wave number that coerced to `0` would otherwise mislabel an unknown wave as
+    // `wave 1/t` (the derivation guards this too, see `toWave`, which treats `null`/`undefined` alike).
+    waveByPlan.set(w.plan_key, {
+      current: w.current_wave ?? null,
+      total: w.wave_count ?? null,
+    });
+  }
+  for (const status of EPIC_LIVE_STATUSES) {
+    for (const plan of await plans(data).find({ status })) {
+      if (!plan.process_key) continue;
+      try {
+        const elements = await engine.searchElementInstances({ processInstanceKey: plan.process_key });
+        const phase = deriveEpicPhaseLive(elements, waveByPlan.get(plan.plan_key) ?? undefined);
+        if (phase !== null && phase !== plan.epic_phase) {
+          await plans(data).update(plan.plan_key, { epic_phase: phase, updated_at: now() });
+        }
+      } catch (err) {
+        console.error(`[poller] epic phase ${plan.plan_key}: ${err}`);
+      }
+    }
+  }
+  // Terminal "Fleet dispatched" phase: a COMPLETION marker, derived from the durable terminal status
+  // rather than a fleeting ACTIVE `record-results` token a coarse poll would miss (#542 review). A
+  // `done` epic that dispatched ≥1 slice freezes at Dispatched; a taskless `done` and any non-`done`
+  // terminal are left untouched (`deriveTerminalEpicPhase` returns null). Idempotent — writes only on
+  // a real change, so a steady-state pass over already-Dispatched rows is a no-op.
+  for (const plan of await plans(data).find({ status: "done" })) {
+    const phase = deriveTerminalEpicPhase(plan.status, plan.task_count);
+    if (phase !== null && phase !== plan.epic_phase) {
+      await plans(data).update(plan.plan_key, { epic_phase: phase, updated_at: now() });
+    }
+  }
+}
+
 /** Poll pass (ADR 0005 slice S5): reconcile each RUNNING delivery-graph run's derived phase from
  * engine truth, and complete it when its instance ends. A delivery graph is a DYNAMIC compiled
  * process with no happy-path host worker, so — unlike `plans`/`feature_runs`, whose spine workers
@@ -2316,22 +2390,25 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
  * transition (instanceTracking's `onTerminated` edge reconciles only TERMINATED, never COMPLETED, so
  * a graph that ends normally would otherwise stay `running` forever). Generalises the `epic_phase`
  * derived-phase machinery to a graph whose element ids aren't known ahead of time: the parked-node
- * label is derived from the run row's stamped `human_labels` + the instance's OPEN user tasks. Scoped
- * to `running` rows (an `awaiting-approval` run has no instance yet), so it stays O(in-flight). */
+ * label is derived from the run row's stamped `human_labels` + the instance's live USER_TASK parks.
+ * The parked node is now sourced from the unified element-instance wait-state channel
+ * (`searchElementInstanceWaitStates`, nano-ide#473) rather than a separate user-task search, folding
+ * this read onto the same live element-instance model the epic derivation uses (S8, #542). Scoped to
+ * `running` rows (an `awaiting-approval` run has no instance yet), so it stays O(in-flight). */
 export async function pollDeliveryGraphPhase(
   data: DataLayer,
-  engine: Pick<EngineClient, "searchProcessInstances" | "searchUserTasks">,
+  engine: Pick<EngineClient, "searchProcessInstances" | "searchElementInstanceWaitStates">,
 ) {
   for (const run of await deliveryGraphRuns(data).find({ status: "running" })) {
     if (!run.process_key) continue;
     const processKey = run.process_key;
     try {
-      const [snapshots, tasks] = await Promise.all([
+      const [snapshots, parks] = await Promise.all([
         engine.searchProcessInstances({ processInstanceKeys: [processKey] }),
-        engine.searchUserTasks({ processInstanceKey: processKey, state: "CREATED" }),
+        engine.searchElementInstanceWaitStates({ processInstanceKey: processKey, waitStateType: "USER_TASK" }),
       ]);
       const state = snapshots.find((s) => String(s.processInstanceKey) === processKey)?.state ?? null;
-      const projection = deriveDeliveryPhase(state, tasks, parseHumanLabels(run.human_labels));
+      const projection = deriveDeliveryPhase(state, parks, parseHumanLabels(run.human_labels));
       if (run.status !== projection.status || run.phase !== projection.phase || run.phase_node_id !== projection.phase_node_id) {
         await deliveryGraphRuns(data).update(run.run_key, {
           status: projection.status,
@@ -2538,6 +2615,7 @@ export async function pollOnce(
   await pollFeatureDelivery(data);
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
+  await pollEpicPhase(data, engine);
   await pollDeliveryGraphPhase(data, engine);
   await pollDeliveryProposals(data);
   if (engineRest) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.144.0",
+  "version": "0.145.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",
@@ -64,7 +64,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^0.13.1",
+    "@nanobpm/urban-testkit": "^0.14.0",
     "@nanobpm/workflow": "^0.14.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.0",