@nanobpm/nano-workforce 0.171.7 → 0.171.8

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.171.8](https://github.com/nanobpm/nano-workforce/compare/v0.171.7...v0.171.8) (2026-09-01)
+
+### Bug Fixes
+
+* **agentic:** release job⇄worker correlation on terminal lifecycle event ([#688](https://github.com/nanobpm/nano-workforce/issues/688)) ([58dde6c](https://github.com/nanobpm/nano-workforce/commit/58dde6cf1c91f75828c8a38de52fef9409e3484c)), closes [#661](https://github.com/nanobpm/nano-workforce/issues/661) [#544](https://github.com/nanobpm/nano-workforce/issues/544) [#661](https://github.com/nanobpm/nano-workforce/issues/661)
+
 ## [0.171.7](https://github.com/nanobpm/nano-workforce/compare/v0.171.6...v0.171.7) (2026-09-01)
 
 ### Bug Fixes

package/app/agentic/families/relay.family.test.ts

@@ -16,16 +16,19 @@ import { fileURLToPath } from "node:url";
 import { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
-import { type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
-import { assert, assertEquals } from "#test-assert";
+import { encodeTranscriptEvent, type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
+import { assert, assertEquals, assertThrows } from "#test-assert";
 import { noopLog } from "../../../test/log.ts";
 import { CorrelationRegistry, jobStream } from "../correlation.ts";
 import { AgenticCorrelationStore } from "../correlation-store.ts";
+import { createPresenceStore, PresenceRegistry } from "./presence.family.ts";
 import {
   type CorrelationLink,
   createRelayFamily,
   currentRelayTranscriptService,
+  engineReconcileMs,
   family as relayFamily,
+  guardOverlappingPasses,
   RELAY_FAMILY_NAME,
   RelayTranscriptService,
   sweepIntervalMs,
@@ -542,6 +545,227 @@ test("#544 element-instance enrichment: an unresolved job (never parked) leaves
   service.teardown();
 });
 
+/** A `produce` frame whose chunk is a typed transcript LIFECYCLE event at `phase` (#661). */
+const lifecycle = (stream: string, incarnation: number, phase: "open" | "completed" | "exited"): Frame =>
+  produce(stream, incarnation, encodeTranscriptEvent({ kind: "lifecycle", phase, offset: 0 }));
+
+test("#661 primary release: a terminal lifecycle event clears an idle-but-connected worker's finished job", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  // The worker relays its job's terminal → linked as active.
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job is active while it runs");
+  assertEquals(correlation.count(), 1);
+
+  // The job ends: the worker emits the terminal `lifecycle` event on the SAME live connection and then
+  // goes idle — it does NOT disconnect and does NOT take a new job (no supersede). Before this fix that
+  // finished job lingered forever as a phantom active job; now the terminal event releases it.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "completed"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the finished job is released on the terminal event");
+  assertEquals(correlation.count(), 0, "count() drops — no phantom active job");
+
+  // Assert the RENDERED supply row clears too (not just the registry): the presence snapshot seeds
+  // per-worker jobKeys from the correlation registry, so an idle-but-connected worker shows no job.
+  const store = createPresenceStore(memoryDb());
+  store.ensureSchema();
+  store.register({ instance: "worker-A", connectionId: "prod", identity: "leaf", capability: {} });
+  const presence = new PresenceRegistry(store, () => new Set(["prod"]));
+  const row = presence.snapshot({ jobKeysFor: (i) => correlation.jobKeysFor(i) }).workers[0];
+  assertEquals(row.jobKeys, [], "the supply row shows no active job for the idle worker");
+  assert(row.live, "the worker is still connected — the connection persists across jobs");
+
+  // The terminal event itself is captured in the flushed transcript (release runs AFTER the ring append).
+  const meta = service.transcriptOf(jobStream("k1"));
+  assertEquals(meta?.status, "completed", "the finished job becomes a completed past session");
+  assertEquals(service.reattach(jobStream("k1"), 0)?.entries.length, 2, "the terminal event is part of the transcript");
+  service.teardown();
+});
+
+test("#661 primary release: an `exited` lifecycle also releases; a non-terminal `open` does not", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  // A `phase: "open"` lifecycle is NOT terminal — a genuinely active job must not be cleared.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "open"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "an open lifecycle keeps the active job");
+  assertEquals(correlation.count(), 1);
+
+  // An `exited` lifecycle (a crash/kill the worker still managed to report) IS terminal → released.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "exited"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "an exited lifecycle releases the job");
+  assertEquals(correlation.count(), 0);
+  service.teardown();
+});
+
+test("#661 no-regression: an ordinary (non-lifecycle) chunk never clears a genuinely active job", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  // Ordinary terminal output (raw bytes, not a typed envelope) must NOT be read as a job-end signal.
+  for (let i = 0; i < 5; i++) hub.handler?.(produce(jobStream("k1"), 1, `output ${i}`), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a running job stays active across ordinary output");
+  assertEquals(correlation.count(), 1);
+  assertEquals(service.transcriptOf(jobStream("k1")), undefined, "the live job is not completed");
+  service.teardown();
+});
+
+test("#661 defensive reconcile: an unclean exit (no lifecycle) whose engine job is gone is dropped by the reconcile pass", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine reports job k1 as a live JOB park (element instance ei-1) — until the worker exits
+  // UNCLEANLY (crash/kill): it emits no terminal lifecycle event, keeps no connection to reconcile,
+  // and the engine park is gone → the resolver returns undefined.
+  let parked = true;
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(parked && jobKey === "k1" ? "ei-1" : undefined);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job links while it runs");
+
+  // While the engine still parks the job, the reconcile pass leaves a genuinely active job alone.
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a genuinely active job is NOT cleared by the safety net");
+  assertEquals(correlation.count(), 1);
+
+  // The worker exits uncleanly (no lifecycle event) — its engine park vanishes. The next reconcile
+  // pass drops the stale correlation even though nothing on the wire signalled job end.
+  parked = false;
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the reconcile pass drops the stale correlation");
+  assertEquals(correlation.count(), 0, "no phantom active job survives an unclean exit");
+  service.teardown();
+});
+
+test("#661 defensive reconcile: a transient engine read failure never falsely releases a job", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine read throws (unavailable) — a transient fault must be treated as "unknown, keep it",
+  // NEVER as "job gone", or a live job would be wrongly cleared on every engine blip.
+  const resolveElementInstance = () => Promise.reject(new Error("engine unavailable"));
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a transient engine failure leaves the job linked");
+  assertEquals(correlation.count(), 1);
+  service.teardown();
+});
+
+test("#661 defensive reconcile: a no-op when no engine resolver is wired", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+
+  // With no element-instance resolver (engine-less host), the safety net cannot query the engine —
+  // it must be an inert no-op, leaving the correlation exactly as the primary path manages it.
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "no resolver → the reconcile pass is inert");
+  service.teardown();
+});
+
+test("#661 engineReconcileMs: defaults, disables on a non-positive/non-finite value, caps at the timer max", () => {
+  assertEquals(engineReconcileMs(), 30_000, "an omitted config uses the default cadence");
+  assertEquals(engineReconcileMs(5_000), 5_000, "a finite positive value is honoured");
+  assertEquals(engineReconcileMs(0), undefined, "zero disables the pass");
+  assertEquals(engineReconcileMs(-1), undefined, "a negative value disables the pass");
+  assertEquals(engineReconcileMs(Number.NaN), undefined, "a non-finite value disables the pass");
+  assertEquals(engineReconcileMs(Number.POSITIVE_INFINITY), undefined, "infinity disables the pass");
+  assertEquals(engineReconcileMs(2 ** 32), 2_147_483_647, "a huge value is capped at the Node timer ceiling");
+  assertEquals(engineReconcileMs(0.5), 1, "a sub-millisecond positive value floors to 1ms, never 0 (no busy setInterval(0))");
+});
+
+test("#661 guardOverlappingPasses: a tick while a pass is in flight is skipped; only one pass runs at a time", async () => {
+  let starts = 0;
+  let active = 0;
+  let maxActive = 0;
+  let release!: () => void;
+  // A pass that blocks until we release it, so we can hold one "in flight" while further ticks fire.
+  const pass = () => {
+    starts++;
+    active++;
+    maxActive = Math.max(maxActive, active);
+    return new Promise<void>((resolve) => {
+      release = () => {
+        active--;
+        resolve();
+      };
+    });
+  };
+  const tick = guardOverlappingPasses(pass);
+
+  tick(); // first tick starts a pass — now in flight
+  tick(); // skipped while the first pass is still pending
+  tick(); // skipped
+  assertEquals(starts, 1, "overlapping ticks are dropped while a pass is in flight");
+  assertEquals(maxActive, 1, "never more than one pass runs concurrently");
+
+  release(); // let the first pass settle
+  await new Promise((r) => setImmediate(r)); // flush the `finally` that clears the in-flight flag
+
+  tick(); // a tick after the previous pass settled starts a fresh pass
+  assertEquals(starts, 2, "a tick after the in-flight pass settles starts a new pass");
+  assertEquals(maxActive, 1, "still only ever one pass at a time");
+  release();
+});
+
+test("#661 guardOverlappingPasses: a pass whose work rejects but is self-caught still re-arms the guard", async () => {
+  // The guard clears its in-flight flag via `.finally`, so it re-arms whether the pass resolves OR
+  // rejects — a rejection does NOT wedge the guard. The real hazard of a rejecting pass is an
+  // *unhandled rejection* (the tick voids the returned promise), which is why the mount wraps
+  // `reconcileEngineCorrelations()` in `.catch`. Here the pass's work rejects but is self-caught
+  // (mirroring that wrapper), so there is no unhandled rejection, and we assert the guard re-arms.
+  let starts = 0;
+  const tick = guardOverlappingPasses(() => {
+    starts++;
+    // Work that rejects but settles its own error — exactly like the mount's `.catch` wrapper.
+    return Promise.reject(new Error("pass work failed")).catch(() => {});
+  });
+  tick();
+  await new Promise((r) => setImmediate(r));
+  tick();
+  await new Promise((r) => setImmediate(r));
+  assertEquals(starts, 2, "a self-caught rejecting pass settles and re-arms the guard for the next tick");
+});
+
+test("#661 guardOverlappingPasses: a pass that throws SYNCHRONOUSLY re-arms the guard (no wedge) and stays loud", () => {
+  // A synchronous throw from `pass` escapes before `.finally` is attached, so the guard must catch it,
+  // re-arm, and re-throw — otherwise a future non-`async` caller/refactor would wedge the guard
+  // permanently in-flight. We assert both: the throw propagates (stays loud, not swallowed) AND the
+  // next tick starts a fresh pass (the guard re-armed rather than sticking at in-flight).
+  let starts = 0;
+  const tick = guardOverlappingPasses(() => {
+    starts++;
+    throw new Error("synchronous boom"); // violates the "must not throw synchronously" contract
+  });
+  assertThrows(() => tick(), Error, "synchronous boom");
+  assertThrows(() => tick(), Error, "synchronous boom");
+  assertEquals(starts, 2, "the guard re-armed after a synchronous throw, so the next tick ran the pass");
+});
+
 /**
  * A {@link CorrelationLink} wrapper that delegates to a real registry but can be flipped to throw on
  * `link()`/`releaseJob()`, exercising the advisory-resilience contract: `#link`/`#unlink` are

package/app/agentic/families/relay.family.ts

@@ -24,6 +24,7 @@ import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
 import {
+  parseTranscriptEvent,
   type SqliteDb,
   type TranscriptLifecycle,
   type TranscriptRing,
@@ -50,6 +51,14 @@ const SWEEP_DIVISOR = 4;
  * 32-bit timer and Node silently clamps it to 1ms — turning a slow periodic tick into a busy loop. */
 const MAX_TIMER_MS = 2_147_483_647;
 
+/**
+ * Default cadence (ms) of the defensive engine-reconcile pass (#661) — the safety net that releases a
+ * correlation whose engine JOB park is gone but whose terminal `lifecycle` event never arrived (an
+ * unclean worker exit). 30s trades a small staleness bound for a light engine-read load; the precise,
+ * immediate release stays the terminal-lifecycle path, so this only ever mops up unclean exits.
+ */
+const DEFAULT_ENGINE_RECONCILE_MS = 30_000;
+
 /**
  * The retention-sweep cadence (ms) for a given ephemeral-retention window: a fraction of the window,
  * floored at 1ms and — crucially — capped at {@link MAX_TIMER_MS} so a large retention config (e.g.
@@ -64,12 +73,75 @@ export function sweepIntervalMs(ephemeralRetentionMs: number): number {
   return Math.min(MAX_TIMER_MS, Math.max(1, interval));
 }
 
+/**
+ * The defensive engine-reconcile cadence (ms) for a given config (#661), or `undefined` to DISABLE the
+ * pass. An omitted config uses {@link DEFAULT_ENGINE_RECONCILE_MS}; a non-finite or non-positive value
+ * (a broken config, or a deliberate opt-out) disables the pass rather than degrading into a 1ms busy
+ * loop; a finite positive value is floored at 1ms (so a sub-millisecond config like 0.5 cannot floor
+ * to 0 and degrade into a busy `setInterval(0)`) and capped at {@link MAX_TIMER_MS} so a large window
+ * cannot overflow Node's 32-bit timer.
+ */
+export function engineReconcileMs(configuredMs?: number): number | undefined {
+  const value = configuredMs ?? DEFAULT_ENGINE_RECONCILE_MS;
+  if (!Number.isFinite(value) || value <= 0) return undefined;
+  return Math.min(MAX_TIMER_MS, Math.max(1, Math.floor(value)));
+}
+
+/**
+ * Wrap an async pass in an in-flight guard so a periodic `setInterval` never fires OVERLAPPING runs
+ * (#661). A single pass of {@link RelayTranscriptService.reconcileEngineCorrelations} awaits an engine
+ * read per linked job, so a pass can outlast its interval (a small configured cadence, or a slow/large
+ * engine read-model); an unguarded `setInterval` would then stack concurrent passes, piling up engine
+ * reads and log volume. While a pass is still pending, every subsequent tick is skipped; the next tick
+ * after it settles — whether it resolves OR rejects, since the guard clears via `.finally` — starts a
+ * fresh pass. The guard clears on BOTH failure modes so it can never wedge in-flight: (1) a
+ * *synchronous* throw from `pass` escapes before `.finally` is attached, so it is caught here — the
+ * guard is re-armed and the fault is re-thrown so it stays loud rather than being silently swallowed;
+ * (2) an async rejection is cleared by `.finally`, but the tick `void`s (does not await) the returned
+ * promise, so `pass` must still settle its own rejections or an unhandled rejection results — which is
+ * why the mount wraps `reconcileEngineCorrelations()` in `.catch`. Making the guard resilient to (1)
+ * removes a subtle footgun for a future caller (or refactor) that returns a non-`async` `pass`. Mirrors
+ * the "one pass at a time" discipline the main poll loop enforces by self-scheduling. Returns the tick
+ * callback to hand to `setInterval`.
+ */
+export function guardOverlappingPasses(pass: () => Promise<void>): () => void {
+  let inFlight = false;
+  return () => {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      void pass().finally(() => {
+        inFlight = false;
+      });
+    } catch (err) {
+      // A synchronous throw never attaches the `.finally`; re-arm the guard so it does not wedge,
+      // then re-throw so a contract violation still surfaces instead of being silently swallowed.
+      inFlight = false;
+      throw err;
+    }
+  };
+}
+
 /** Read a property off an unknown value without an unsafe `as` cast (mirrors the loader's helper). */
 function readProp(value: unknown, key: string): unknown {
   if (!value || typeof value !== "object") return undefined;
   return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
 }
 
+/**
+ * Decode a single relay chunk through the ONE canonical transcript parser and report whether it is a
+ * TERMINAL `lifecycle` event (`phase` `completed`/`exited`) — the authoritative "job end" signal a
+ * clean agent run emits on its transcript stream (#661). Anything else — raw terminal bytes, a
+ * non-envelope JSON value, a `phase: "open"` lifecycle, any other event kind — is not terminal.
+ * Reusing {@link parseTranscriptEvent} keeps transcript-vocab knowledge out of the content-agnostic
+ * relay ring and off any forked decoder (Derivation Over Duplication): the ring still sees opaque
+ * bytes; only this narrow seam classifies them.
+ */
+function isTerminalLifecycleChunk(chunk: string): boolean {
+  const event = parseTranscriptEvent({ offset: 0, chunk });
+  return event.kind === "lifecycle" && (event.phase === "completed" || event.phase === "exited");
+}
+
 /**
  * A resume-from-offset source with no retained chunks — used to flush/complete a stream that a
  * producer opened logically but never wrote to, so its transcript is still stamped `completed`
@@ -424,11 +496,41 @@ export class RelayTranscriptService {
     this.#streams.clear();
   }
 
-  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, then delegate. */
+  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, delegate, then
+   * release on a terminal `lifecycle` event (#661 — AFTER the hub appended the chunk, so the terminal
+   * event itself is captured in the flushed transcript). */
   #onFrame(frame: Frame, conn: RelayConnectionCtx): void {
     this.#reconcile();
     this.#observe(frame, conn);
     this.relay.handle(frame, conn);
+    this.#observeTerminalLifecycle(frame);
+  }
+
+  /**
+   * Primary job-end release (#661): when a `produce` frame carries the terminal `lifecycle` event
+   * (`phase` `completed`/`exited`), complete its stream so the worker's job⇄instance correlation is
+   * released the moment the job ends — even though the worker's relay connection stays open across jobs
+   * (the disconnect/supersede release paths miss that idle-after-last-job tail, so an idle worker's
+   * finished job would otherwise linger as a phantom active job on its supply row). Runs AFTER the hub
+   * appends the chunk to the ring, so the terminal event is part of the flushed transcript. A narrow,
+   * self-contained decode at the correlation seam that reuses the ONE canonical
+   * {@link parseTranscriptEvent} — the content-agnostic relay ring keeps treating chunks as opaque
+   * bytes, and no transcript-vocab knowledge is forked into it. Non-terminal chunks (raw bytes, a
+   * `phase: "open"` lifecycle, any other event kind) never complete a live stream, so a genuinely
+   * active job is never cleared. Advisory — never throws into the frame handler.
+   */
+  #observeTerminalLifecycle(frame: Frame): void {
+    if (readProp(frame.payload, "op") !== "produce") return;
+    const stream = readProp(frame.payload, "stream");
+    if (typeof stream !== "string" || stream === "") return;
+    const chunk = readProp(frame.payload, "chunk");
+    if (typeof chunk !== "string" || chunk === "") return;
+    const state = this.#streams.get(stream);
+    // Idempotent: an unknown or already-completed stream needs no (further) release — a second terminal
+    // event, or a late one after the disconnect/supersede path already completed the stream, is a no-op.
+    if (state === undefined || state.completed) return;
+    if (!isTerminalLifecycleChunk(chunk)) return;
+    this.completeStream(stream);
   }
 
   /** Record `produce` ownership so a producer disconnect can drive ephemeral completion. */
@@ -624,6 +726,61 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * Defensive engine-reconcile safety net (#661): release any linked jobKey whose engine JOB park is
+   * no longer live. The precise, fast release is the terminal `lifecycle` event
+   * ({@link #observeTerminalLifecycle}), but an UNCLEAN worker exit (crash/kill) can skip that event —
+   * and because the worker's relay connection is persistent across jobs, the disconnect release never
+   * fires either, so the finished job would linger as a phantom active job on the worker's supply row.
+   * This periodic pass asks the engine read model (the same {@link ElementInstanceResolver} the link
+   * path uses at #544) whether each linked job is still parked; a job the engine no longer parks
+   * (resolver returns `undefined`) is released and its transcript completed. Bounds staleness regardless
+   * of whether the worker emitted a clean terminal event — and also covers a worker that emitted nothing
+   * and merely went quiet.
+   *
+   * Advisory and best-effort: a no-op with no resolver wired, and a resolver THROW / REJECTION for a
+   * given job is treated as "unknown — keep it linked" (never a false release of a genuinely active
+   * job). The linked set is snapshotted before any await so a concurrent completion (a terminal
+   * lifecycle event landing mid-pass) cannot corrupt iteration, and each release re-checks the current
+   * stream state so a job already released between snapshot and resolution is not double-completed.
+   */
+  async reconcileEngineCorrelations(): Promise<void> {
+    const resolve = this.#resolveElementInstance;
+    if (resolve === undefined) return;
+    const linked: { stream: string; jobKey: string; processInstanceKey?: string }[] = [];
+    for (const [stream, state] of this.#streams) {
+      if (!state.linked || state.completed) continue;
+      const jobKey = jobKeyOfStream(stream);
+      if (jobKey === undefined) continue;
+      const processInstanceKey = this.#correlation()?.resolve?.(jobKey)?.processInstanceKey;
+      linked.push({ stream, jobKey, processInstanceKey });
+    }
+    for (const { stream, jobKey, processInstanceKey } of linked) {
+      let activeKey: string | undefined;
+      try {
+        activeKey = await resolve(jobKey, processInstanceKey);
+      } catch (err) {
+        // A transient engine read failure must NOT be read as "job gone" — leave the job linked; a
+        // later pass (or the terminal lifecycle event) releases it. Advisory, never a false release.
+        this.#log.warn("agentic relay engine-reconcile read failed — leaving correlation linked", {
+          stream,
+          jobKey,
+          err: String(err),
+        });
+        continue;
+      }
+      // A live JOB park (a resolved element-instance key) means the job is genuinely active — keep it.
+      if (activeKey !== undefined) continue;
+      // The engine no longer parks this job → it ended (possibly via an unclean exit that skipped the
+      // terminal lifecycle event). Re-check the current state — a concurrent completion may already
+      // have released it — then release its correlation and flush its transcript.
+      const current = this.#streams.get(stream);
+      if (current === undefined || current.completed || !current.linked) continue;
+      this.#log.info("agentic relay engine-reconcile released a stale correlation", { stream, jobKey });
+      this.completeStream(stream);
+    }
+  }
+
   /**
    * The still-live relay ring for a stream, for the read path to serve BEFORE a durable flush (#486).
    *
@@ -670,11 +827,18 @@ export function createRelayFamily(options: {
   readonly relay?: RelayHubOptions;
   readonly transcript?: TranscriptStoreOptions;
   readonly ensureSchema?: boolean;
+  /**
+   * Cadence (ms) of the defensive engine-reconcile pass (#661). Defaults to
+   * {@link DEFAULT_ENGINE_RECONCILE_MS}. Clamped to Node's 32-bit timer ceiling; a non-positive /
+   * non-finite value disables the pass (the terminal-lifecycle release path still runs).
+   */
+  readonly engineReconcileIntervalMs?: number;
   /** Called with the live service once mounted, so a driver can drive completion/reattach. */
   readonly onMounted?: (service: RelayTranscriptService) => void;
 } = {}): AgenticFamily {
   let service: RelayTranscriptService | undefined;
   let sweepTimer: ReturnType<typeof setInterval> | undefined;
+  let engineReconcileTimer: ReturnType<typeof setInterval> | undefined;
   return {
     name: RELAY_FAMILY_NAME,
     mount(ctx: AgenticContext): void {
@@ -729,6 +893,31 @@ export function createRelayFamily(options: {
         tick();
       }
 
+      // Defensive engine-reconcile safety net (#661): periodically release any linked correlation
+      // whose engine JOB park is gone but whose terminal `lifecycle` event never arrived (an unclean
+      // worker exit), so a crashed worker's finished job stops showing as a phantom active job. Only
+      // useful when an element-instance resolver is wired (engine read-model access); harmless no-op
+      // otherwise. Advisory — a reconcile fault is logged, never thrown, and never keeps the process
+      // alive on its own.
+      if (ctx.resolveElementInstance !== undefined) {
+        const reconcileInterval = engineReconcileMs(options.engineReconcileIntervalMs);
+        if (reconcileInterval !== undefined) {
+          // In-flight guard: `reconcileEngineCorrelations()` is async and awaits an engine read per
+          // linked job, so a pass can outlast `reconcileInterval` (a small interval, or a slow/large
+          // engine read-model). Without a guard, `setInterval` would fire overlapping passes that pile
+          // up concurrent engine reads and log volume. {@link guardOverlappingPasses} skips a tick while
+          // the previous pass is still running so only one reconcile runs at a time — the same "one pass
+          // at a time" discipline the main poll loop enforces by self-scheduling.
+          const reconcileTick = guardOverlappingPasses(() =>
+            (service?.reconcileEngineCorrelations() ?? Promise.resolve()).catch((err: unknown) => {
+              ctx.log.warn("agentic relay engine-reconcile failed", { err: String(err) });
+            }),
+          );
+          engineReconcileTimer = setInterval(reconcileTick, reconcileInterval);
+          engineReconcileTimer.unref?.();
+        }
+      }
+
       options.onMounted?.(service);
     },
     teardown(): void {
@@ -736,6 +925,10 @@ export function createRelayFamily(options: {
         clearInterval(sweepTimer);
         sweepTimer = undefined;
       }
+      if (engineReconcileTimer !== undefined) {
+        clearInterval(engineReconcileTimer);
+        engineReconcileTimer = undefined;
+      }
       service?.teardown();
       if (currentService === service) setCurrentRelayTranscriptService(undefined);
       service = undefined;

package/package.json

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