@nanobpm/nano-workforce 0.126.0 → 0.128.0

package/e2e/readiness-gate.e2e.ts

@@ -23,34 +23,7 @@ import { dirname, join, resolve } from "node:path";
 import { after, before, describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
-import type { CommandResult, ProbeExec } from "../app/readiness.ts";
-import { __setProbeExecForTest } from "../workers/readiness-probe/worker.ts";
-
-// A synchronous, in-memory ProbeExec so the probe resolves WITHIN the testkit's virtual-clock drain
-// fixpoint instead of spawning a REAL subprocess (real-time work `settle()` cannot deterministically
-// await — issue #450). It maps the hermetic shell builtins these scenarios use to a deterministic
-// `CommandResult` — `true` → exit 0 (green), `false` → exit 1 (never green) — mirroring the real
-// commands' semantics exactly, but with zero real time. Any OTHER command, or any HTTP call, is an
-// unintended probe escape: because `probeSingleShot` catches a thrown/rejected probe error and folds
-// it into a silent "not ready", an escape would otherwise be INVISIBLE and could let a bounded
-// not-ready scenario still pass, masking a regression (reviewer note). So we record every escape and
-// assert none occurred in teardown, failing the suite loudly instead of swallowing it.
-const unexpectedProbeIO: string[] = [];
-const deterministicExec: ProbeExec = {
-  run(command: string): Promise<CommandResult> {
-    const cmd = command.trim();
-    if (cmd !== "true" && cmd !== "false") {
-      unexpectedProbeIO.push(`command: ${cmd}`);
-      return Promise.resolve({ code: 127, stdout: "", stderr: "" });
-    }
-    const code = cmd === "true" ? 0 : 1;
-    return Promise.resolve({ code, stdout: "", stderr: "" });
-  },
-  httpGet(url: string): Promise<never> {
-    unexpectedProbeIO.push(`http: ${url}`);
-    return Promise.reject(new Error(`readiness-gate e2e: unexpected real HTTP probe (command probes only)`));
-  },
-};
+import { deterministicProbeSeam } from "./support/probe-exec.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 let dbSeq = 0;
@@ -60,7 +33,7 @@ const GITHUB_ENV_OVERRIDES: Record<string, string> = {
   GITHUB_TOKEN: "",
 };
 const savedEnv = new Map<string, string | undefined>();
-let savedProbeExec: ProbeExec | undefined;
+const probeSeam = deterministicProbeSeam("readiness-gate e2e");
 
 interface TakenFlow {
   from: string;
@@ -94,7 +67,7 @@ describe("nano-workforce artifact-readiness wait-gate (readiness-gate.bpmn)", ()
     // clock (issue #450). Scenario-agnostic: it maps each scenario's command by string. Capture the
     // prior override and restore exactly that in teardown, so the seam is restored to its real prior
     // state rather than assuming production.
-    savedProbeExec = __setProbeExecForTest(deterministicExec);
+    probeSeam.install();
   });
 
   after(() => {
@@ -102,13 +75,11 @@ describe("nano-workforce artifact-readiness wait-gate (readiness-gate.bpmn)", ()
       if (v === undefined) delete process.env[k];
       else process.env[k] = v;
     }
-    // Restore the prior exec — the seam must never outlive this suite.
-    __setProbeExecForTest(savedProbeExec);
-    // Fail loudly if the probe ever escaped the hermetic `true`/`false` builtins (an unexpected
-    // command or any HTTP call). `probeSingleShot` folds a probe error into a silent "not ready", so
-    // without this assertion an escape would be invisible and could let a bounded not-ready scenario
-    // still pass, masking a regression.
-    assert.deepEqual(unexpectedProbeIO, [], `readiness-gate e2e saw unexpected probe I/O: ${unexpectedProbeIO.join(", ")}`);
+    // Restore the prior exec (the seam must never outlive this suite) and fail loudly if the probe
+    // ever escaped the hermetic `true`/`false` builtins — `probeSingleShot` folds a probe error into
+    // a silent "not ready", so without this an escape would be invisible and could let a bounded
+    // not-ready scenario still pass, masking a regression.
+    probeSeam.restoreAndAssertHermetic();
   });
 
   test("READY: a green probe publishes readiness-ready and the gate releases through wait-ready → gate-ready", async () => {

package/e2e/support/probe-exec.test.ts

@@ -0,0 +1,78 @@
+// Negative-path coverage for the deterministic probe seam (e2e/support/probe-exec.ts).
+//
+// The wired readiness-gate suites only ever route the hermetic `true`/`false` builtins through the
+// seam, so a regression in RECORDING or REJECTING an unexpected command/HTTP call — the seam's whole
+// reason to exist — would leave every one of them green while silently swallowing an escape. This
+// exercises the escape contract directly: a non-hermetic command or a real HTTP probe must be
+// recorded and make `restoreAndAssertHermetic()` fail, and the recorded escape must never leak the
+// raw command or a URL's credential material into the teardown assertion (ADR 0004 pinned
+// decision 2 — mirrors production `redactTarget`).
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { __setProbeExecForTest } from "../../workers/readiness-probe/worker.ts";
+import { deterministicProbeSeam } from "./probe-exec.ts";
+
+/** Install the seam, then hand back the exact `ProbeExec` it wired into the worker so a test can
+ *  route probes through the real installed seam (not a private copy). Uses the documented
+ *  set-returns-previous contract of `__setProbeExecForTest` to read the current override, then puts
+ *  it straight back so the seam's own restore still returns the DB to the prior exec. */
+function installAndCaptureExec(seam: ReturnType<typeof deterministicProbeSeam>) {
+  seam.install();
+  const installed = __setProbeExecForTest(undefined);
+  assert.ok(installed, "install() must have wired a ProbeExec into the worker");
+  __setProbeExecForTest(installed);
+  return installed;
+}
+
+test("hermetic true/false probes leave the seam clean", async () => {
+  const seam = deterministicProbeSeam("hermetic");
+  const exec = installAndCaptureExec(seam);
+
+  assert.deepEqual(await exec.run("true", {}), { code: 0, stdout: "", stderr: "" });
+  assert.deepEqual(await exec.run("false", {}), { code: 1, stdout: "", stderr: "" });
+
+  // No escape recorded — teardown passes.
+  seam.restoreAndAssertHermetic();
+});
+
+test("a non-hermetic command escapes, fails teardown, and never leaks the raw command", async () => {
+  const seam = deterministicProbeSeam("cmd-escape");
+  const exec = installAndCaptureExec(seam);
+
+  const secret = "curl https://user:supersecret@host/health?token=abc123";
+  const result = await exec.run(secret, {});
+  // The escaping command still resolves to a non-green result so a bounded not-ready scenario holds.
+  assert.equal(result.code, 127);
+
+  assert.throws(
+    () => seam.restoreAndAssertHermetic(),
+    (err: unknown) => {
+      const msg = String(err);
+      assert.match(msg, /cmd-escape saw unexpected probe I\/O/);
+      assert.doesNotMatch(msg, /supersecret/, "the credential must never reach teardown output");
+      assert.doesNotMatch(msg, /abc123/, "the token must never reach teardown output");
+      return true;
+    },
+  );
+});
+
+test("a real HTTP probe escapes, fails teardown, and redacts the URL's credential material", async () => {
+  const seam = deterministicProbeSeam("http-escape");
+  const exec = installAndCaptureExec(seam);
+
+  await assert.rejects(
+    exec.httpGet("https://user:tok@host/ready?apikey=zzz999", {}),
+    /http-escape: unexpected real HTTP probe/,
+  );
+
+  assert.throws(
+    () => seam.restoreAndAssertHermetic(),
+    (err: unknown) => {
+      const msg = String(err);
+      assert.match(msg, /http-escape saw unexpected probe I\/O/);
+      assert.doesNotMatch(msg, /zzz999/, "the query token must never reach teardown output");
+      assert.doesNotMatch(msg, /user:tok/, "the userinfo credential must never reach teardown output");
+      return true;
+    },
+  );
+});

package/e2e/support/probe-exec.ts

@@ -0,0 +1,69 @@
+// Deterministic readiness-probe exec for e2es driven by the testkit's VIRTUAL clock (issue #450).
+//
+// Production `defaultProbeExec` (app/readiness.ts) runs a `command` probe as a REAL
+// `node:child_process` subprocess. That subprocess resolves on the wall clock, spanning macrotasks
+// the urban-testkit's virtual-clock `settle()`/`drain()` fixpoint cannot deterministically await —
+// so `settle()` can return BEFORE the probe publishes `readiness-ready`, and a gate-flow assertion
+// (e.g. `pf_gw->pf_end`) races the subprocess. That race is the flake behind feature-preflight /
+// plan-fanout-preflight failing intermittently (green probe logged, gate flow not yet taken).
+//
+// This seam injects a synchronous, in-memory `ProbeExec` (via the worker's `__setProbeExecForTest`)
+// so the probe resolves WITHIN the drain fixpoint — no real spawn, no wall-clock race. It maps the
+// hermetic shell builtins the gate e2es use to a deterministic `CommandResult` — `true` → exit 0
+// (green), `false` → exit 1 (never green) — mirroring the real commands exactly, with zero real time.
+//
+// Any OTHER command, or any HTTP call, is an unintended probe escape: `probeSingleShot` folds a
+// thrown/rejected probe error into a silent "not ready", so an escape would be INVISIBLE and could
+// let a bounded not-ready scenario still pass, masking a regression. Every escape is recorded and
+// asserted-none in teardown, failing the suite loudly instead of swallowing it.
+//
+// Single source of truth shared by every readiness-gate e2e (readiness-gate, feature-preflight,
+// plan-fanout-preflight, delivery-graph, inter-epic-dependency) so the deterministic-exec contract
+// can never drift between them.
+import assert from "node:assert/strict";
+import { type CommandResult, type ProbeExec, redactString } from "../../app/readiness.ts";
+import { __setProbeExecForTest } from "../../workers/readiness-probe/worker.ts";
+
+export interface DeterministicProbeSeam {
+  /** Install the deterministic exec — call once in the suite's `before`. */
+  install(): void;
+  /** Restore the prior exec and assert no probe escaped the hermetic `true`/`false` builtins — call
+   *  once in the suite's `after`. */
+  restoreAndAssertHermetic(): void;
+}
+
+/** Build a deterministic probe seam scoped to one suite. `label` is used in the escape assertion
+ *  message and the unexpected-HTTP error, so a failure names the offending suite. */
+export function deterministicProbeSeam(label: string): DeterministicProbeSeam {
+  const escapes: string[] = [];
+  const exec: ProbeExec = {
+    run(command: string): Promise<CommandResult> {
+      const cmd = command.trim();
+      if (cmd !== "true" && cmd !== "false") {
+        // A `command` target is an arbitrary shell snippet that can embed a secret, so — exactly as
+        // production `redactTarget` does (app/readiness.ts, ADR 0004 pinned decision 2) — record only
+        // a fixed placeholder, never the raw command, so an escape can't leak credentials into the
+        // teardown assertion at `restoreAndAssertHermetic()`.
+        escapes.push("command: <redacted>");
+        return Promise.resolve({ code: 127, stdout: "", stderr: "" });
+      }
+      return Promise.resolve({ code: cmd === "true" ? 0 : 1, stdout: "", stderr: "" });
+    },
+    httpGet(url: string): Promise<never> {
+      // A probe URL can carry a token in its userinfo or query string; strip those before recording.
+      escapes.push(`http: ${redactString(url)}`);
+      return Promise.reject(new Error(`${label}: unexpected real HTTP probe (command probes only)`));
+    },
+  };
+  let saved: ProbeExec | undefined;
+  return {
+    install() {
+      saved = __setProbeExecForTest(exec);
+    },
+    restoreAndAssertHermetic() {
+      // Restore the prior exec first — the seam must never outlive this suite.
+      __setProbeExecForTest(saved);
+      assert.deepEqual(escapes, [], `${label} saw unexpected probe I/O: ${escapes.join(", ")}`);
+    },
+  };
+}

package/e2e/support/time.test.ts

@@ -0,0 +1,42 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { advancePastTimer } from "./time.ts";
+
+// Guards the defect class behind issue #474: a long BPMN business-wait must be crossed by advancing
+// the ENGINE clock (fire the boundary timer) + one reconcile settle — NOT by `app.advanceTime`,
+// which steps the scheduler in lockstep and replays every 5s runtime-cadence poll across the window
+// (~18,000× for a 25h jump; ~123s of no-op churn). This pins the mechanism so a regression back to
+// the lockstep path — or an added `scheduler.advance` — fails here instead of silently re-slowing CI.
+test("advancePastTimer advances the engine clock then settles once, never replaying scheduler cadence", async () => {
+  const PAST_SLA_MS = 25 * 60 * 60 * 1000;
+  const calls: string[] = [];
+  let engineMs: number | undefined;
+
+  const app = {
+    engine: {
+      advanceTime: async (ms: number) => {
+        engineMs = ms;
+        calls.push("engine.advanceTime");
+      },
+    },
+    settle: async () => {
+      calls.push("settle");
+    },
+    // Present only to catch a regression: touching the scheduler's own `advance` is the slow
+    // lockstep replay path the helper exists to avoid, so it must never be called.
+    scheduler: {
+      advance: async () => {
+        calls.push("scheduler.advance");
+      },
+    },
+  } as unknown as Parameters<typeof advancePastTimer>[0];
+
+  await advancePastTimer(app, PAST_SLA_MS);
+
+  assert.deepEqual(
+    calls,
+    ["engine.advanceTime", "settle"],
+    "the engine boundary fires, then exactly one reconcile settle — the scheduler cadence is never replayed",
+  );
+  assert.equal(engineMs, PAST_SLA_MS, "the full business-wait window is applied to the engine clock");
+});

package/e2e/support/time.ts

@@ -0,0 +1,33 @@
+import type { TestApp } from "@nanobpm/urban-testkit";
+
+/**
+ * Advance a long BPMN **business-wait** boundary timer and reconcile once.
+ *
+ * A business wait — "park at this task until the 24h SLA elapses, then auto-escalate" — is
+ * modelled as a BPMN interrupting boundary timer on the ENGINE clock: durable, engine-owned, and
+ * already virtual under the engine clock. This is the line camunda/orchestration-cluster-api-js#450
+ * draws: *"Long/business waits are BPMN timer events … not [runtime-cadence] `sleep`/poll."* To
+ * cross such a wait we advance the ENGINE clock so the boundary fires, then {@link TestApp.settle}
+ * once to drain the follow-on token flow.
+ *
+ * This deliberately does **not** call {@link TestApp.advanceTime}, which steps the virtual-clock
+ * scheduler in lockstep with the engine and therefore REPLAYS every short runtime-cadence poll —
+ * the 5s `instanceTracking` reconcilers — once per interval across the whole window. A 25h jump
+ * replays each poller ~18,000× (measured: ~123s of pure no-op reconcile churn *per call*, which is
+ * essentially the entire e2e wall-clock). Those replays are runtime cadence, not the business wait,
+ * and #450 treats such busy-replays as a bug to *surface*, not to coalesce away in the scheduler.
+ * Advancing engine time + one settle fires the same boundary in ~2ms.
+ *
+ * Use ONLY when the assertions target **engine state** — taken sequence-flows (`app.snapshot()`) or
+ * instance state — which is populated by `engine.advanceTime` + `engine.drain` (run inside
+ * `settle`). Do NOT use it when an assertion depends on a **read model the reconcile pollers
+ * project**: for that the pollers must actually run, so use {@link TestApp.advanceTime}. The
+ * scheduler's virtual clock intentionally does not track this jump.
+ */
+export async function advancePastTimer(
+  app: Pick<TestApp, "engine" | "settle">,
+  ms: number,
+): Promise<void> {
+  await app.engine.advanceTime(ms);
+  await app.settle();
+}

package/openapi.yaml

@@ -646,6 +646,16 @@ components:
         planKey:
           type: string
           description: The plan / epic key this job was part of (e.g. owner/repo#142), when still known (advisory).
+        instance:
+          type: string
+          description: The worker instance that ran the session, recovered from durable attribution — present even
+            after the worker exited or the process restarted (advisory).
+        identity:
+          type: string
+          description: The worker's durable identity (presence identity), when recorded (advisory).
+        host:
+          type: string
+          description: The worker's host, when recorded (advisory).
     AgenticTranscriptList:
       type: object
       description: The list of captured agent sessions (past + open) — the cockpit "past sessions" feed.
@@ -742,6 +752,15 @@ components:
         planKey:
           type: string
           description: The plan / epic key, when still known (advisory).
+        instance:
+          type: string
+          description: The worker instance that ran the session, from durable attribution (advisory).
+        identity:
+          type: string
+          description: The worker's durable identity, when recorded (advisory).
+        host:
+          type: string
+          description: The worker's host, when recorded (advisory).
         entries:
           type: array
           description: The retained chunks with `offset >= from`, in offset order.
@@ -2448,6 +2467,13 @@ paths:
           schema:
             type: string
           description: Return only transcripts whose (still-known) correlation names this plan / epic key.
+        - name: instance
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only sessions run by this worker instance (durable attribution) — powers the
+            per-worker history view. Survives worker exit / process restart.
         - name: since
           in: query
           required: false

package/operations/getAgenticTranscript.ts

@@ -28,13 +28,14 @@ export default defineOperation("getAgenticTranscript", async ({ params, query, r
     return { status: 400, body: { error: "invalid from: expected a non-negative integer offset" } };
   }
 
-  const store = currentRelayTranscriptService()?.store;
+  const service = currentRelayTranscriptService();
+  const store = service?.store;
   if (!store) {
     // No transcript store mounted (relay unmounted or unpersisted) - nothing to replay.
     return { status: 404, body: { error: "no transcript for stream" } };
   }
 
-  const data = readTranscriptFrom(params.stream, from, store, currentCorrelation());
+  const data = readTranscriptFrom(params.stream, from, store, currentCorrelation(), service?.correlationStore);
   if (data === undefined) {
     return { status: 404, body: { error: "no transcript for stream" } };
   }

package/operations/listAgenticTranscripts.ts

@@ -47,10 +47,11 @@ export default defineOperation("listAgenticTranscripts", async ({ query, req },
     ...(query.jobKey !== undefined ? { jobKey: query.jobKey } : {}),
     ...(query.processInstanceKey !== undefined ? { processInstanceKey: query.processInstanceKey } : {}),
     ...(query.planKey !== undefined ? { planKey: query.planKey } : {}),
+    ...(query.instance !== undefined ? { instance: query.instance } : {}),
     ...(query.since !== undefined ? { since: query.since } : {}),
     ...(query.until !== undefined ? { until: query.until } : {}),
   };
-  const transcripts = listTranscripts(store, currentCorrelation(), filter);
+  const transcripts = listTranscripts(store, currentCorrelation(), filter, service?.correlationStore);
   const body: AgenticTranscriptList = {
     count: transcripts.length,
     generatedAt: new Date().toISOString(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.126.0",
+  "version": "0.128.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",
@@ -58,13 +58,13 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.1.0",
+    "@nanobpm/agentic": "^0.4.0",
     "@nanobpm/urban": "^0.80.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^0.11.0",
+    "@nanobpm/urban-testkit": "^0.12.16",
     "@nanobpm/workflow": "^0.14.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",

package/pages/cockpit/cockpit.css

@@ -119,7 +119,10 @@
 .cockpit-dot[data-liveness="stale"] { background: var(--cockpit-amber); }
 .cockpit-dot[data-liveness="down"] { background: var(--cockpit-red); }
 
-.cockpit-worker {
+.cockpit-worker,
+.cockpit-worker-drill,
+.cockpit-worker-detail-back,
+.cockpit-worker-current-job {
   background: none;
   border: none;
   color: var(--cockpit-text);
@@ -130,7 +133,15 @@
   text-underline-offset: 2px;
 }
 
-.cockpit-worker:hover { color: #58a6ff; }
+.cockpit-worker-drill {
+  color: var(--cockpit-muted);
+  font-size: 12px;
+}
+
+.cockpit-worker:hover,
+.cockpit-worker-drill:hover,
+.cockpit-worker-detail-back:hover,
+.cockpit-worker-current-job:hover { color: #58a6ff; }
 
 .cockpit-supply-process { color: var(--cockpit-muted); }
 
@@ -220,6 +231,58 @@
   padding: 8px 0;
 }
 
+/* ── Worker detail route (#/cockpit/worker/<instance>): header + current job + filtered history. ── */
+
+.cockpit-worker-detail {
+  display: grid;
+  gap: 12px;
+}
+
+.cockpit-worker-detail-back {
+  justify-self: start;
+  color: var(--cockpit-muted);
+}
+
+.cockpit-worker-detail-header {
+  display: grid;
+  gap: 8px;
+}
+
+.cockpit-worker-detail-meta {
+  display: grid;
+  gap: 8px;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  margin: 0;
+}
+
+.cockpit-worker-detail-meta-item {
+  border: 1px solid rgba(34, 48, 65, 0.7);
+  border-radius: 6px;
+  padding: 8px;
+}
+
+.cockpit-worker-detail-meta-item dt {
+  color: var(--cockpit-muted);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.cockpit-worker-detail-meta-item dd {
+  margin: 2px 0 0;
+  overflow-wrap: anywhere;
+}
+
+.cockpit-worker-current {
+  border-top: 1px solid rgba(34, 48, 65, 0.7);
+  padding-top: 10px;
+}
+
+.cockpit-worker-current-empty,
+.cockpit-worker-detail-empty {
+  color: var(--cockpit-muted);
+}
+
 /* Distinguish a live terminal from a replayed (static) past session at a glance. */
 .cockpit-terminal[data-terminal-mode="replay"] {
   border-color: #8957e5;