@nanobpm/nano-workforce 0.80.0 → 0.82.0

package/workers/readiness-probe/worker.ts

@@ -0,0 +1,146 @@
+// pr.readiness-probe — the ReadinessProbe executor (ADR 0001 §2, issue #258).
+//
+// The service-task half of the durable wait-gate (`resources/processes/readiness-gate.bpmn`). It is
+// handed a declared `ReadinessProbe` descriptor + a `gateKey` correlation key, and polls the probe
+// with backoff until it goes green — at which point it publishes the `readiness-ready` message the
+// gate's event-based gateway correlates, releasing the wait. It does NOT own the timeout: the gate's
+// timer arm is the authoritative bound (a hung or forever-red probe is escalated by the engine, not
+// by a poller-side sentinel — ADR 0001 §2 pinned decision 3). Because the probe only *reads*
+// readiness, a worker restart simply re-activates this job and re-probes (idempotent / resumable).
+//
+// Secrets never appear in the descriptor, a process variable, or a log line: a credential is read at
+// execution time from the typed env-contract (`credentialEnv` → `readEnv`) and the probe's
+// target/output is redacted before logging (ADR 0004 pinned decision 2).
+import type { AppJobHandler } from "@nanobpm/urban";
+import { readEnvOr } from "../../app/contracts.ts";
+import {
+  DEFAULT_EVERY_MS,
+  defaultProbeExec,
+  nextDelay,
+  normalizePoll,
+  type ProbeExec,
+  type ProbePoll,
+  type ProbeResult,
+  parseProbe,
+  probeBudgetMs,
+  probeOnce,
+  type ReadinessProbe,
+  redactTarget,
+} from "../../app/readiness.ts";
+import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input/output typed off the model data envelopes (`ReadinessProbeIn` / `ReadinessProbeOut` in
+// readiness-gate.bpmn), the single source of truth for this worker's wire contract (ADR 0040).
+// `probe` is a `nano:reference` to the nested `ReadinessProbe` shape, so it derives to the descriptor.
+type In = WorkerInputs["pr.readiness-probe"];
+type Out = WorkerOutputs["pr.readiness-probe"];
+
+/** The message the gate's event-based gateway correlates on `=gateKey` to release the wait. */
+export const READINESS_READY_MESSAGE = "readiness-ready";
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** The effective poll cadence: the descriptor's values, with `everyMs` defaulting through the env
+ * contract (`NANO_READINESS_POLL_EVERY_MS`) when the descriptor omits it, then the built-in
+ * defaults/clamps in {@link normalizePoll}. Reads the env value from the injected `env` (not the
+ * ambient `process.env`) so the loop is deterministic under test. */
+function effectivePoll(
+  poll: ProbePoll | undefined,
+  env: Record<string, string | undefined>,
+): ReturnType<typeof normalizePoll> {
+  const envEvery = Number(readEnvOr("NANO_READINESS_POLL_EVERY_MS", String(DEFAULT_EVERY_MS), env));
+  const everyMs = poll?.everyMs ?? (Number.isFinite(envEvery) && envEvery >= 1 ? envEvery : DEFAULT_EVERY_MS);
+  return normalizePoll({ everyMs, timeoutMs: poll?.timeoutMs, backoff: poll?.backoff });
+}
+
+/** The core poll loop, factored out with injectable I/O + clock + publisher so it is unit-testable
+ * without a network, a subprocess, or a real timer. Polls until ready (publishes, returns ready) or
+ * the local budget is exhausted (returns not-ready — the engine timer then bounds the wait). */
+export async function pollUntilReady(deps: {
+  probe: ReadinessProbe;
+  gateKey: string;
+  probeTimeout?: string;
+  exec: ProbeExec;
+  env: Record<string, string | undefined>;
+  now: () => number;
+  wait: (ms: number) => Promise<void>;
+  publish: (detail: string) => Promise<void>;
+  log?: (msg: string) => void;
+}): Promise<ProbeResult> {
+  const poll = effectivePoll(deps.probe.poll, deps.env);
+  // The local budget is bound to the gate PER INSTANCE: it adopts the same seeded `probeTimeout`
+  // process variable the gate's engine timers fire off (`=probeTimeout`), falling back to the env-
+  // derived twin only when it's absent. Recomputing from the ambient env would let the worker go
+  // silent while the engine timer is still waiting if the env changed after the instance was seeded.
+  const deadline = deps.now() + probeBudgetMs(deps.probeTimeout, deps.probe, deps.env);
+  const label = redactTarget(deps.probe);
+  let attempt = 0;
+  for (;;) {
+    const res: ProbeResult = await probeOnce(deps.probe, deps.exec, deps.env).catch((err) => ({
+      ready: false,
+      // Never surface the raw error message: a fetch/subprocess error can embed the target URL
+      // (with query tokens), command fragments, or other secrets. Log only the error class name.
+      detail: `probe error: ${err instanceof Error ? err.name : "Error"}`,
+    }));
+    deps.log?.(`readiness probe ${label} attempt ${attempt + 1}: ${res.detail}`);
+    if (res.ready) {
+      await deps.publish(res.detail);
+      return res;
+    }
+    attempt += 1;
+    const wait = nextDelay(attempt, poll);
+    if (deps.now() + wait >= deadline) {
+      return { ready: false, detail: "probe budget exhausted; engine timer bounds the wait" };
+    }
+    await deps.wait(wait);
+  }
+}
+
+/** Normalize the two required process variables the gate seeds, failing fast when either is unusable.
+ *
+ * Both are load-bearing for the worker↔gate binding, so a bad value must surface immediately rather
+ * than silently degrade:
+ *  • `gateKey` is returned **raw** (only validated on a trimmed view). The gate's message subscription
+ *    binds `correlationKey="=gateKey"` — the *untrimmed* process variable — so the publish key must
+ *    match it byte-for-byte. Trimming the key we publish on would desync a whitespace-seeded `gateKey`
+ *    from the gate's subscription, leaving a green probe to release the wait only via the timeout arm.
+ *  • `probeTimeout` is required by the typed input envelope and drives BOTH the gate's engine timers
+ *    (`=probeTimeout`). A missing/blank value used to fall back silently to the env-derived twin,
+ *    breaking the per-instance bound (and masking a mis-seeded instance until it escalates); fail fast
+ *    instead and pass the raw string through so worker and engine share one seeded bound. */
+export function readGateVars(vars: { gateKey?: unknown; probeTimeout?: unknown }): {
+  gateKey: string;
+  probeTimeout: string;
+} {
+  const gateKey = String(vars.gateKey ?? "");
+  if (gateKey.trim() === "") throw new Error("readiness-probe: 'gateKey' is required (blank correlation key)");
+  const { probeTimeout } = vars;
+  if (typeof probeTimeout !== "string" || probeTimeout.trim() === "")
+    throw new Error("readiness-probe: 'probeTimeout' is required (per-instance timer bound)");
+  return { gateKey, probeTimeout };
+}
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const probe = parseProbe(job.variables.probe);
+  const { gateKey, probeTimeout } = readGateVars(job.variables);
+  const result = await pollUntilReady({
+    probe,
+    gateKey,
+    probeTimeout,
+    exec: defaultProbeExec(),
+    env: process.env,
+    now: () => Date.now(),
+    wait: sleep,
+    publish: async (detail) => {
+      await app.engine.publishMessage({
+        name: READINESS_READY_MESSAGE,
+        correlationKey: gateKey,
+        variables: { ready: true, detail },
+      });
+    },
+    log: (msg) => app.log.info(msg),
+  });
+  return { ready: result.ready, detail: result.detail };
+};
+
+export default handler;

package/workers/record-plan/worker.ts

@@ -16,6 +16,7 @@
 // warning; the ordering is lost but every task still runs. No `plan_task_deps` are recorded
 // in that case (the edges were invalid).
 import type { AppJobHandler } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { planTaskDeps, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
@@ -127,6 +128,11 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     wave_label: tasks.length > 0 ? `1/${waveCount}` : null,
     updated_at: ts,
   };
+  // Domain-phase projection (#261): recording the plan hands the epic to the `review-plan` agent,
+  // so it enters the Reviewing phase (derived structurally from this worker's BPMN element id).
+  // Guard against a null derivation (element id absent) clobbering the genesis phase.
+  const epicPhase = deriveEpicPhase(job.elementId);
+  if (epicPhase) patch.epic_phase = epicPhase;
   if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
   await app.data.table("plans", "plan_key").update(planKey, patch);
 

package/workers/record-results/worker.ts

@@ -13,6 +13,7 @@
 
 import type { AppJobHandler } from "@nanobpm/urban";
 import { BpmnError } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -49,9 +50,16 @@ const handler: AppJobHandler<In> = async (job, app) => {
     throw new BpmnError("NO_WORK_DISPATCHED", `${planKey}: ${outcome}`);
   }
 
+  // Domain-phase projection (#261): the finalizer landed with opened PRs — the epic reaches its
+  // terminal "Fleet dispatched" phase (derived structurally from this worker's BPMN element id).
+  // The failed/no-work path above leaves epic_phase untouched: its terminal signal is status +
+  // outcome, and stamping "Dispatched" against a failed epic would misread. A null derivation
+  // (element id absent) must not clobber the last implementing phase.
+  const epicPhase = deriveEpicPhase(job.elementId);
   await app.data.table("plans", "plan_key").update(planKey, {
     status: "done",
     outcome: `${opened} PR(s) dispatched to convergence`,
+    ...(epicPhase ? { epic_phase: epicPhase } : {}),
     updated_at: ts,
   });
 

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

@@ -144,6 +144,8 @@ test("record-wave retries the same wave when a task is still pending", async ()
   assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, 1);
   // Retry keeps the projection on the same (still-pending) wave.
   assertEquals((planUpdates[0].patch as Record<string, unknown>).current_wave, 1);
+  // Domain-phase projection (#261): more waves remain, so the epic stays Implementing (wave n/t).
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).epic_phase, "Implementing (wave 2/2)");
 });
 
 test("record-wave pins current_wave to the last index and clears gate_wave on the final wave", async () => {
@@ -174,6 +176,9 @@ test("record-wave pins current_wave to the last index and clears gate_wave on th
   assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, null);
   assertEquals((planUpdates[0].patch as Record<string, unknown>).current_wave, 2);
   assertEquals((planUpdates[0].patch as Record<string, unknown>).wave_label, "3/3");
+  // Domain-phase projection (#261): the final wave landed with no successor and no trial merge, so
+  // the epic enters Finalizing (record-results then advances to the Dispatched terminal).
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).epic_phase, "Finalizing");
 });
 
 test("record-wave keeps all wave-progress fields NULL for a taskless plan (waveCount 0)", async () => {

package/workers/record-wave/worker.ts

@@ -15,6 +15,7 @@
 // and, crucially, so a later wave's `dependsOn` can reference the PR keys earlier waves produced.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { appendEntry } from "../../app/blackboard.ts";
+import { EPIC_PHASE, implementingPhase } from "../../app/epicPhase.ts";
 import { fetchPrFiles, fetchPrHead } from "../../app/github.ts";
 import { deriveExclusions, recordExclusions } from "../../app/mergeExclusion.ts";
 import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
@@ -280,6 +281,16 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const currentWaveProjection = waveCount > 0 ? projectedCurrentWave : null;
   const waveLabel = waveCount > 0 ? `${projectedCurrentWave + 1}/${waveCount}` : null;
 
+  // Domain-phase projection (#261): the wave landed — stamp the phase the epic is ENTERING next,
+  // which is data-dependent here (unlike the structural spine writers). A trial merge runs → Trial
+  // merging; another wave follows → Implementing (next wave n/t); otherwise the finalizer runs →
+  // Finalizing (record-results then advances to the Dispatched terminal).
+  const epicPhase = runTrialMerge
+    ? EPIC_PHASE.TRIAL_MERGING
+    : hasMoreWaves
+      ? implementingPhase(projectedCurrentWave, waveCount)
+      : EPIC_PHASE.FINALIZING;
+
   // Wave-merge barrier: when another wave follows, park the plan-fanout instance at the
   // `wait-wave-merged` catch event until THIS wave's opened PRs have MERGED (not merely opened).
   // `gate_wave` is that durable marker; the poller (`pollWaveGates`) clears it and publishes
@@ -292,6 +303,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       gate_wave: hasMoreWaves ? currentWave : null,
       current_wave: currentWaveProjection,
       wave_label: waveLabel,
+      epic_phase: epicPhase,
       updated_at: ts,
     });
   } catch (err) {

package/workers/select-wave/worker.test.ts

@@ -67,7 +67,7 @@ test("select-wave projects the active wave onto plans.current_wave", async () =>
   ];
   const plans: Record<string, unknown>[] = [{ plan_key: "owner/repo#63", current_wave: 0 }];
   const out = await handler(
-    { variables: { planKey: "owner/repo#63", currentWave: 1 } } as any,
+    { variables: { planKey: "owner/repo#63", currentWave: 1 }, elementId: "select-wave" } as any,
     fakeApp(rows, [], plans),
   );
   assertEquals((out as { waveTasks: unknown[] }).waveTasks.length, 1);
@@ -76,6 +76,9 @@ test("select-wave projects the active wave onto plans.current_wave", async () =>
   // is pre-formatted for the epics-index at-a-glance column.
   assertEquals(plans[0].wave_count, 2);
   assertEquals(plans[0].wave_label, "2/2");
+  // Domain-phase projection (#261): dispatching the wave marks the epic Implementing (wave n/t),
+  // derived from this worker's BPMN element id + the levelize records.
+  assertEquals(plans[0].epic_phase, "Implementing (wave 2/2)");
 });
 
 test("select-wave nulls all three progress fields when there are no levelized rows", async () => {

package/workers/select-wave/worker.ts

@@ -15,6 +15,7 @@
 // Emitting an empty `waveTasks` is fine: the MI activity over an empty collection completes
 // immediately (the same 0-task path the flat fan-out already relied on).
 import type { AppJobHandler } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -53,6 +54,13 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // display-only — it must never gate control flow, which stays driven by the process
   // `currentWave`/`waveCount`/`gate_wave` state.
   const waveCount = rows.reduce((m, r) => Math.max(m, r.wave ?? 0), -1) + 1;
+  // Domain-phase projection (#261): select-wave dispatches this wave and is the last host write
+  // before the write-silent `implement` MI, so it durably marks the implementation phase for the
+  // wave it launches — `Implementing (wave n/t)` from the levelize records (job.elementId +
+  // current/total waves). A null derivation (element id absent) must not clobber the phase.
+  const epicPhase = waveCount > 0
+    ? deriveEpicPhase(job.elementId, { current: currentWave, total: waveCount })
+    : null;
   try {
     await plans(app.data).update(planKey, {
       // Keep the three progress fields consistent: with no levelized rows (waveCount 0) there is
@@ -60,6 +68,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       current_wave: waveCount > 0 ? currentWave : null,
       wave_count: waveCount > 0 ? waveCount : null,
       wave_label: waveCount > 0 ? `${currentWave + 1}/${waveCount}` : null,
+      ...(epicPhase ? { epic_phase: epicPhase } : {}),
       updated_at: ts,
     });
   } catch (err) {